# 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，提供统一接口。支持文件预签名上传，减轻服务端流量压力。