121 lines
5.5 KiB
Markdown
121 lines
5.5 KiB
Markdown
# Part 3: 核心模块详解
|
||
|
||
> **文档定位**：详细拆解系统各核心模块的功能定位、技术实现与关键业务逻辑，辅助开发人员深入理解系统内部运作机制。
|
||
|
||
## 3.1 Gateway 网关体系
|
||
|
||
平台采用双网关架构，分别处理 HTTP 业务流量与 IoT 设备连接流量，实现 **“管理控制流”** 与 **“设备数据流”** 的物理隔离。
|
||
|
||
### 3.1.1 API Gateway (`viewsh-gateway`)
|
||
基于 **Spring Cloud Gateway** 构建，端口 `48080`，核心职责是流量分发与安全防护。
|
||
* **统一鉴权**：作为 OAuth2 Resource Server，通过 `GlobalFilter` 解析 JWT 令牌。透传 `User-Id` 和 `Tenant-Id` 到下游微服务。
|
||
* **动态路由**：集成 Nacos Config，支持无需重启服务的路由规则变更，便于灰度发布。
|
||
* **流量防护**：集成 **Sentinel**，针对突发流量（如大屏刷新接口）配置 QPS 限流，保障后端服务稳定性。
|
||
|
||
### 3.1.2 IoT Gateway (`viewsh-module-iot-gateway`)
|
||
基于 **Netty** (TCP) 和 **Vert.x** (MQTT) 构建的高性能异步 I/O 网关。
|
||
|
||
| 协议 | 端口 | 实现类/组件 | 特性 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **TCP** | 8091 | `NettyServer` + `Jt808ProtocolHandler` | 支持 JT808 交通部标协议，自定义 `ByteToMessageDecoder` 处理粘包拆包。 |
|
||
| **MQTT** | 1883 | `VertxMqttServer` | 支持 MQTT v3.1.1，QoS 0/1/2，支持百万级长连接。 |
|
||
| **HTTP** | 8092 | `VertxHttpServer` | 用于低功耗设备（NB-IoT）无连接状态下的数据直接上报。 |
|
||
|
||
---
|
||
|
||
## 3.2 System 系统服务 (`viewsh-module-system`)
|
||
|
||
作为“中台底座”，管理核心元数据与权限体系。
|
||
|
||
* **多租户架构**：
|
||
* **字段隔离**：全表预置 `tenant_id` 字段，MyBatis Plus 插件自动注入过滤条件的 SaaS 模式。
|
||
* **套餐管理**：控制租户可创建的账号数量、设备数量及功能模块开关。
|
||
* **RBAC 权限模型**：
|
||
* 支持 标准 RBAC (User-Role-Permission) 模型。
|
||
* **数据权限**：支持按“本人”、“本部门”、“本部门及以下”等 5 种粒度的数据范围管控。
|
||
|
||
---
|
||
|
||
## 3.3 IoT 物联网服务 (`viewsh-module-iot`)
|
||
|
||
### 3.3.1 JT808 协议深度实现
|
||
针对车载/定位类设备，平台完整实现了 **JT808-2019** 标准的认证与交互流程：
|
||
1. **分步认证机制**：
|
||
* **注册 (0x0100)**：设备上报手机号与车牌，网关验证通过后生成临时 `AuthToken` 并缓存至 Redis (5分钟有效期)。
|
||
* **鉴权 (0x0102)**：设备携带 `AuthToken` 发起鉴权，校验通过后建立正式会话。
|
||
2. **通用应答 (0x8001)**：
|
||
* 对于位置汇报 (0x0200)、心跳 (0x0002) 等高频消息，`Jt808ProtocolHandler` 会自动回复通用应答，确保设备端确认数据已送达。
|
||
|
||
### 3.3.2 规则引擎 (Rule Engine)
|
||
核心类 `RuleEngineService`，负责将设备数据转化为业务价值。
|
||
|
||
#### 1. 处理流程图
|
||
```mermaid
|
||
graph LR
|
||
A[设备上报消息] --> B{规则过滤器 Filter}
|
||
B -- 满足条件 --> C[动作执行器 Action]
|
||
B -- 不满足 --> D[丢弃/仅存储]
|
||
|
||
subgraph 规则逻辑
|
||
B -->|SQL-like| B1["temp > 40 AND hum < 20"]
|
||
end
|
||
|
||
subgraph 动作类型
|
||
C --> C1[发送告警]
|
||
C --> C2[设备反控]
|
||
C --> C3[消息转发]
|
||
end
|
||
```
|
||
|
||
#### 2. 场景示例
|
||
当 `sensor_01` 上报 `humidity < 20%` 且持续 5 分钟：
|
||
1. **触发指令**：自动下发“加湿器开启”指令到关联设备。
|
||
2. **推送告警**：向 Ops 服务发送“环境干燥告警”事件。
|
||
|
||
---
|
||
|
||
## 3.4 Ops 业务运营服务 (`viewsh-module-ops`)
|
||
|
||
### 3.4.1 核心业务条线
|
||
* **环境 (Cleaning)**：智能排班与公厕传感器联动。
|
||
* **设施 (Facilities)**：设备全生命周期台账与预防性维保。
|
||
* **安保 (Security)**：电子巡更轨迹追踪与岗位管理。
|
||
|
||
### 3.4.2 智能工单引擎 (Order FSM)
|
||
为了应对复杂的工单流转（如：待派单 -> 待接单 -> 维修中 -> 挂起 -> 待验收 -> 完成），Ops 模块引入了有限状态机 (FSM)。
|
||
|
||
#### 1. 状态流转图
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> PENDING: 创建工单
|
||
PENDING --> ASSIGNED: 派单(Dispatch)
|
||
ASSIGNED --> ARRIVED: 签到(Check-in)
|
||
ARRIVED --> PROCESSING: 开始作业
|
||
|
||
state PROCESSING {
|
||
[*] --> WORKING
|
||
WORKING --> PAUSED: 暂停/打断
|
||
PAUSED --> WORKING: 恢复
|
||
}
|
||
|
||
PROCESSING --> COMPLETED: 完成(Finish)
|
||
PENDING --> CANCELLED: 取消
|
||
ASSIGNED --> CANCELLED: 取消
|
||
|
||
COMPLETED --> [*]
|
||
CANCELLED --> [*]
|
||
```
|
||
|
||
#### 2. 实现机制
|
||
* **状态定义**：`OrderStateMachine` 统一管理所有工单状态枚举。
|
||
* **事件驱动**：状态流转必须由明确的 Event 触发（如 `EVENT_DISPATCH` 触发 `PENDING -> ACCEPTING`）。
|
||
* **可靠性**：状态机结合数据库事务，确保状态变更与操作日志记录的原子性，避免工单状态“卡死”或“跳变”。
|
||
* **自动派单**：系统内置派单算法，可根据**人员忙闲状态**、**当前位置**及**技能标签**，自动将工单分配给最优的服务人员。
|
||
|
||
---
|
||
|
||
## 3.5 Infra 基础设施服务 (`viewsh-module-infra`)
|
||
|
||
* **分布式任务**：集成 **XXL-JOB**，负责跨服务的定时任务调度（如每晚 0 点生成日报表、定时清理过期临时文件）。
|
||
* **文件服务**：通过 Factory 模式适配 MinIO/S3，提供统一接口。支持文件预签名上传，减轻服务端流量压力。
|