2. 系统架构概览：数字工地平台整体架构、许可服务模块位置、看板服务模块位置
在进入许可工作流接口调试之前，必须理解数字工地平台的宏观架构。本章从分层视角拆解平台整体结构，并精准定位许可服务模块与看板服务模块在架构中的层级与交互关系。
2.1 数字工地平台整体架构（四层模型）
数字工地平台采用经典的四层微服务架构，从上至下依次为：展示层、业务服务层、基础服务层、数据与设备层。各层职责清晰，通过 API 网关统一路由。
架构设计要点： 业务服务层采用领域驱动设计（DDD）拆分，许可服务与看板服务分属不同领域，通过事件总线异步通信，避免强耦合。
2.2 许可服务模块位置与职责
许可服务位于业务服务层，是现场作业安全管控的核心领域。它负责电子作业许可（PTW）的全生命周期管理，包括申请、审批、签发、执行、关闭等环节。
| 维度 | 说明 |
|---|---|
| 所属层级 | 业务服务层（Business Service Layer） |
| 核心职责 | 许可流程编排、安全条件校验、审批链路由、电子签名、许可状态管理 |
| 依赖基础服务 | 认证鉴权服务、消息队列、人员组织服务 |
| 对外接口 | RESTful API（许可申请/审批/查询）、WebSocket（状态推送） |
| 关键数据 | 许可单、审批记录、安全措施清单、关联设备/人员 |
调试切入点： 许可服务的接口调试重点在于“流程状态机”的边界条件，例如：已签发许可不允许重复审批、过期许可自动关闭等。后续章节将针对这些接口进行详细调试。
2.3 看板服务模块位置与职责
看板服务同样位于业务服务层，负责将现场数据（包括许可状态、设备运行数据、告警事件等）实时聚合，并以图表、卡片、列表等形式呈现于现场大屏或管理端。
| 维度 | 说明 |
|---|---|
| 所属层级 | 业务服务层（Business Service Layer） |
| 核心职责 | 看板配置管理、数据聚合查询、图表渲染数据组装、定时刷新/实时推送 |
| 依赖基础服务 | 消息队列（消费许可状态变更事件）、时序数据库、配置中心 |
| 对外接口 | RESTful API（看板配置/数据查询）、SSE（服务端推送） |
| 关键数据 | 看板配置模板、图表数据集、实时指标快照 |
注意： 看板服务不直接操作许可数据库，而是通过消息队列订阅许可状态变更事件，实现数据最终一致性。调试时需关注事件消费延迟与数据聚合准确性。
2.4 许可服务与看板服务的协作关系
两个模块在业务上紧密协作，但架构上保持解耦。协作流程如下：
- 许可服务 完成许可审批或状态变更后，发布领域事件到消息队列。
- 看板服务 订阅相关事件，更新本地缓存或实时指标。
- 前端看板页面通过 SSE 或 WebSocket 从看板服务获取最新数据，渲染图表。
2.5 架构视角下的接口调试范围
本课程聚焦于许可服务对外暴露的 RESTful API 调试，同时涉及看板服务对许可数据的消费接口验证。调试范围界定如下：
- 许可服务接口：许可申请、审批流提交、安全措施确认、许可签发、许可关闭、许可查询（列表/详情）。
- 看板服务接口：看板配置获取、许可状态聚合数据查询、实时指标 SSE 端点。
- 不涉及：设备管理服务、告警服务、基础服务层的配置中心与消息队列内部运维。
架构启示： 理解模块位置有助于在调试时快速定位问题边界。例如，看板数据不更新时，应优先检查看板服务是否正常消费了许可服务发出的事件，而非直接排查许可数据库。