XW-AIOT/aiot-platform-cloud
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ops): update cleaner status and assignment logic

Browse Source
This commit is contained in:
lzh
2026-01-19 14:56:31 +08:00
parent 73bc3b299f
commit b71558ae07
169 changed files with 57972 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
docs/technical-overview/01-项目概述.md Normal file
View File

@@ -0,0 +1,78 @@
# Part 1: 项目概述
> **文档定位**：本章节旨在为新加入团队的开发人员、架构师及运维人员提供项目的宏观视图，快速理解项目的业务背景、核心价值及技术底座。
## 1.1 项目背景与业务价值
### 1.1.1 项目背景
在企业数字化转型的浪潮下，**AIoT Platform (ViewSh)** 应运而生。该平台旨在解决传统园区、楼宇管理中“设备孤岛”、“数据割裂”和“人工效率低”的三大痛点。通过构建统一的物联网接入层和业务中台，实现对海量智能设备的集中管控，并基于设备数据驱动上层业务流程（如安保、保洁、工程），打造全场景的智慧空间解决方案。
### 1.1.2 核心业务价值
1. **设备全生命周期管理**：提供跨协议（TCP/MQTT/HTTP）、跨厂商设备的统一接入能力，实现设备状态实时监控与远程指令下发。
2. **业务流程数字化**：将线下的巡检、维修、保洁等作业流程线上化，结合 IoT 告警自动触发工单，实现“人机协同”。
3. **数据驱动决策**：汇聚设备运行数据与业务运营数据，为管理层提供能耗分析、人员效能评估等决策依据。
---
## 1.2 核心业务场景
平台核心业务覆盖**智慧物业**的四大核心条线，形成了“IoT感知 + Ops运营”的业务闭环。
### 1.2.1 智能 Ops 运营体系
* **保洁条线 (Cleaning)**
* **场景**：智能排班、耗材管理、巡检打卡。
* **联动**：公厕异味传感器自动触发保洁工单。
* **安保条线 (Security)**
* **场景**：电子巡更、岗位管理、应急报警。
* **联动**：门禁异常或视频分析（AI）自动触发安保报警事件。
* **工程条线 (Engineering)**
* **场景**：设施维保、巡检计划、备件库存管理。
* **联动**：设备故障信号（如电梯故障）自动生成维修工单。
* **客服条线 (Service)**
* **场景**：投诉建议处理、客户满意度调查、报事报修。
### 1.2.2 IoT 物联网连接
* **设备接入**：支持海量异构设备接入，包括摄像头、门禁、道闸、环境传感器、楼宇BA系统等。
* **规则引擎**：基于设备上报属性或事件，配置灵活的规则（如：温度 > 30℃ -> 触发报警）。
---
## 1.3 技术栈总览
本项目采用当前主流的 **Spring Cloud Alibaba** 微服务架构，结合 **IoT** 特性引入了时序数据库和高性能网络框架。
| 分层 | 关键技术 | 版本 (当前) | 说明 |
| :--- | :--- | :--- | :--- |
| **应用层** | **Spring Boot** | 3.5.9 | 基础应用框架 |
| **微服务** | **Spring Cloud Alibaba** | 2023.0.3.3 | 服务治理 (Nacos, Sentinel, Seata) |
| | **Spring Cloud** | 2025.0.0 | 微服务标准实现 |
| **IoT 接入** | **Netty / Vert.x** | 4.2.9 / 4.5.22 | 高性能网络通信，支持 TCP/MQTT |
| **数据存储** | **MySQL** / Domestic DBs | 8.x / DM8 | 关系型业务数据存储 |
| | **TDengine** | 3.7.9 | 时序数据库，存储设备遥测数据 |
| | **Redis** | 7.x (Redisson 3.52) | 缓存与分布式锁 |
| **消息中间件** | **RocketMQ** | 5.x (Starter 2.3.5) | 高吞吐消息削峰填谷，事件解耦 |
| **工作流** | **Flowable** | 7.2.0 | 复杂业务流程引擎 (工单、审批) |
| **运维监控** | **SkyWalking** | 9.5.0 | 分布式链路追踪与 APM |
| | **XXL-JOB** | 2.4.0 | 分布式任务调度 |
> **💡 架构特点**：
> * **读写分离**：业务数据走 MySQL，海量设备日志走 TDengine。
> * **事件驱动**：核心业务解耦，基于 RocketMQ 实现“设备 -> 消息 -> 业务”的异步处理。
> * **多租户**：支持 SaaS 模式，数据层面做租户隔离。
---
## 1.4 版本演进历史
| 版本号 | 发布日期 | 里程碑内容 | 状态 |
| :--- | :--- | :--- | :--- |
| **v0.1.0** | 2026-01-14 | **MVP 验证阶段**。<br>1. 验证核心业务逻辑闭环（设备接入 -> 数据上报 -> 工单触发）。<br>2. 确立微服务基础架构与技术选型。<br>3. 完成系统服务、网关及保洁条线基础功能。 | 🔄 In Progress |
---
## 1.5 快速上手建议
对于初次接触本项目的开发人员，建议按以下顺序进行深入：
1. **环境准备**：参考 [Part 8: 开发指南](../08-开发指南.md) 完成本地 JDK 17、Maven、Docker 环境搭建。
2. **架构理解**：阅读 [Part 2: 系统架构](../02-系统架构.md) 理解服务分层。
3. **代码运行**：优先启动 `Gateway` 和 `System` 服务，体验基础的用户登录与菜单功能。

120
docs/technical-overview/02-系统架构.md Normal file
View File

@@ -0,0 +1,120 @@
# Part 2: 系统架构
> **文档定位**：从宏观视角阐述 AIoT 平台的顶层设计，涵盖逻辑架构、业务架构、技术架构及数据架构，为系统建设提供全景蓝图。
## 2.1 总体架构蓝图 (Logical Architecture)
本平台遵循标准的物联网四层架构模型，自下而上构建“感知-连接-平台-应用”的完整生态闭环。
```mermaid
graph TD
subgraph AppLayer [应用层 Application]
A1[智慧物业<br>Smart Property]
A2[智慧园区<br>Smart Campus]
A3[数据大屏<br>Dashboard]
A4[移动端<br>Mobile App]
end
subgraph PlatformLayer [平台层 Platform]
P1[<b>业务中台</b><br>用户/权限/流程/消息]
P2[<b>IoT中台</b><br>设备/规则/告警/指令]
P3[<b>数据中台</b><br>时序存储/数据清洗/分析]
end
subgraph NetworkLayer [网络层 Network]
N1[IoT Gateway<br>协议适配]
N2[API Gateway<br>流量分发]
N3[Edge Node<br>边缘计算节点]
end
subgraph PerceptionLayer [感知层 Perception]
S1[传感器<br>Sensors]
S2[智能设备<br>Smart Devices]
S3[控制器<br>Controllers]
S4[工控机<br>IPC]
end
PerceptionLayer -->|MQTT/TCP/HTTP| NetworkLayer
NetworkLayer -->|RPC/MQ| PlatformLayer
PlatformLayer -->|REST/WS| AppLayer
```
### 核心分层定义
1. **感知层 (Perception)**：物理世界的数字触角，包含各类环境传感器、视频监控、门禁闸机及边缘网关。
2. **网络层 (Network)**：连接物理与数字的桥梁，负责多协议（TCP/MQTT/HTTP）的统一接入与边缘协同。
3. **平台层 (Platform)**：系统的核心大脑，提供设备管理、规则引擎、业务逻辑编排及数据治理能力。
4. **应用层 (Application)**：面向最终用户的业务场景，如安保巡更、保洁排班、设施维保等 SaaS 应用。
---
## 2.2 业务架构 (Business Architecture)
平台采用 **“以台促用”** 的建设思路，概括为 **“一个底座，两大中心，N个应用”**。
### 2.2.1 两大核心中心
1. **IoT 连接中心 (IoT Center)**
* **核心能力**：解决设备“连得入、存得下、管得住”的问题。
* **功能模块**：物模型定义、设备生命周期管理、规则引擎、OTA 升级。
2. **业务运营中心 (Business Center / Ops)**
* **核心能力**：解决业务“流程化、标准化、智能化”的问题。
* **功能模块**：
* **保洁条线**：智能排班、耗材管理、公厕异味监测。
* **安保条线**：电子巡更、应急报警、视频 AI 联动。
* **工程条线**：设备台账、预防性维保、工单流转。
---
## 2.3 技术架构 (Technical Architecture)
基于 **Spring Cloud Alibaba** 微服务体系，采用存算分离与读写分离设计，确保系统的高可用与高扩展。
### 2.3.1 微服务分层实现
| 分层 | 服务组件 (Service) | 关键技术 | 职责说明 |
| :--- | :--- | :--- | :--- |
| **网关层** | `viewsh-gateway` | Spring Cloud Gateway | HTTP 流量入口，鉴权、限流、路由。 |
| | `viewsh-module-iot-gateway` | Netty / Vert.x | **以及高性能设备接入**，支持 TCP/MQTT 长连接。 |
| **业务层** | `viewsh-module-system` | Spring Boot | 统一认证 (OAuth2)、RBAC 权限、多租户管理。 |
| | `viewsh-module-ops` | Spring Boot + Flowable | 业务逻辑处理，集成工作流引擎处理复杂工单。 |
| | `viewsh-module-iot` | Spring Boot | 设备元数据管理，指令下发，规则计算。 |
| **支撑层** | `viewsh-module-infra` | MinIO / XXL-Job | 文件存储、定时任务、通知服务 (SMS/Mail)。 |
### 2.3.2 关键技术决策
* **通信框架**：采用 **Netty/Vert.x** 构建高性能物联网关，解决百万级设备并发连接问题。
* **异步解耦**：引入 **RocketMQ**，将设备上报数据与业务处理逻辑解耦，实现削峰填谷。
* **分布式事务**：使用 **Seata** 保证跨服务的业务数据一致性。
---
## 2.4 数据架构 (Data Architecture)
数据是 AIoT 平台的资产核心，采用 **“冷热分离 + 时序优化”** 的混合存储策略。
### 2.4.1 数据流向图
```text
[设备 Device]
↓ (Telemetry Data)
[IoT Gateway]
↓ (MQ Message)
[数据清洗/规则引擎]
│
├─(实时热数据/告警)─> [Redis] ──> [实时大屏/Web推送]
│
├─(设备历史日志)───> [TDengine] (时序数据库)
│
└─(业务状态/元数据)─> [MySQL] (关系型数据库)
```
### 2.4.2 存储选型
1. **时序数据 (Time-Series)**：使用 **TDengine** 存储设备上报的高频遥测数据（如温度、电压），利用其超级表特性实现高性能写入与聚合查询。
2. **业务数据 (Relational)**：使用 **MySQL** (或国产达梦/人大金仓) 存储用户、设备档案、工单记录等强一致性业务数据。
3. **缓存数据 (Cache)**：使用 **Redis** 存储设备在线状态、Token 令牌及高频配置，保障低延迟访问。
---
## 2.5 部署架构
支持纯容器化 (Docker-Compose) 与云原生 (K8s) 两种部署模式，具备良好的云中立性。
* **接入层**：支持多节点负载均衡 (SLB -> Nginx -> Gateways)。
* **服务层**：无状态节点，支持 HPA 弹性伸缩。
* **数据层**：支持主从/集群部署，保障数据可靠性。

120
docs/technical-overview/03-核心模块详解.md Normal file
View File

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

145
docs/technical-overview/04-技术架构设计.md Normal file
View File

@@ -0,0 +1,145 @@
# Part 4: 技术架构设计
> **文档定位**：深入剖析系统关键技术组件的选型策略、实现原理及落地实践，为解决高并发、分布式一致性等复杂工程问题提供标准方案。
## 4.1 服务治理体系 (Service Governance)
基于 **Alibaba Nacos 2.x** 构建统一的注册中心与配置中心，解决微服务架构下的服务发现与配置管理难题。
### 4.1.1 动态配置管理
* **设计原则**：配置即代码，环境隔离。
* **命名空间 (Namespace)**：严格按照环境划分（Dev/Test/Prod），确保环境间配置物理隔离。
* **配置共享**：
* **通用配置**：`application-common.yaml`（Redis、MyBatis Plus、Swagger 等基础中间件配置）。
* **应用配置**：`viewsh-module-{app}-{profile}.yaml`（业务专属配置）。
* **热更新机制**：基于 Spring Cloud `@RefreshScope` 注解，实现日志级别调整、限流阈值变更等场景的**零停机动态刷新**。
### 4.1.2 服务注册与发现
* **领域模型隔离**：微服务实例启动时自动注册至 Nacos，通过 `Group` 区分子略（如 `DEFAULT_GROUP`），支持基于元数据（Metadata）的版本灰度路由。
* **健康检查**：开启 Nacos 临时实例模式（Ephemeral=true），基于心跳机制（5s/次）自动剔除亚健康实例。
---
## 4.2 异步消息体系 (Messaging Architecture)
采用 **Apache RocketMQ 5.x** 作为核心消息总线，承担**削峰填谷**与**领域解耦**重任。
### 4.2.1 Topic 规划设计
遵循“业务域.类型.动作”的命名规范：
* **IoT 遥测数据**：`IOT_DEVICE_UP` (Tag: `Telemetry`, `Event`)
* *特征*：高吞吐，允许少量丢失，使用普通消息。
* **业务状态变更**：`OPS_WORK_ORDER` (Tag: `Create`, `Complete`)
* *特征*：低延迟，强一致性，使用事务消息或同步重试机制。
### 4.2.2 可靠性保证
1. **生产端**：开启同步发送模式（Sync Send），配置重试次数 `retryTimesWhenSendFailed=2`。
```java
// 消息发送示例
@Resource
private RocketMQTemplate rocketMQTemplate;
public void sendDeviceEvent(DeviceEvent event) {
// 构建消息
Message<DeviceEvent> message = MessageBuilder.withPayload(event)
.setHeader(RocketMQHeaders.KEYS, event.getEventId()) // 设置 Key 方便检索
.build();
// 同步发送，等待结果
SendResult result = rocketMQTemplate.syncSend("IOT_DEVICE_UP:Telemetry", message);
log.info("Send result: {}", result.getSendStatus());
}
```
2. **消费端**：
* **幂等处理**：在消费者业务逻辑中必须校验 `BizKey`（如工单号、消息ID）是否已处理。
* **死信队列 (DLQ)**：消费失败重试 16 次后自动进入 DLQ，需人工介入排查。
---
## 4.3 高并发防护 (System Resilience)
引入 **Sentinel** 实现全方位的流量控制与熔断降级。
### 4.3.1 网关层防护
* **流量清洗**：针对 API Gateway 设置集群限流规则（Cluster Flow Control），限制单 IP 或单用户的 QPS，防止恶意刷接口。
* **热点参数限流**：针对 SKU ID、Device ID 等热点参数配置特例化限流规则。
### 4.3.2 服务层熔断
* **微服务调用**：Feign Client 集成 Sentinel 熔断器，当调用错误率超过 50% 或响应时间 > 1s 时自动熔断，快速失败，防止雪崩效应。
**配置示例 (bootstrap.yaml)**：
```yaml
feign:
sentinel:
enabled: true # 开启 Feign Sentinel 支持
spring:
cloud:
sentinel:
transport:
dashboard: localhost:8080 # Sentinel 控制台地址
scg:
fallback:
mode: response
response-body: '{"code": 429, "msg": "服务繁忙，请稍后重试"}'
```
* **降级策略**：核心业务（如登录）必须配置 `fallback` 降级逻辑，返回友好的兜底数据。
---
## 4.4 分布式锁与幂等性 (Distributed Lock & Idempotency)
针对分布式环境下的并发竞争问题，提供标准化的解决方案组件。
### 4.4.1 分布式锁 (`Lock4j`)
集成 `Lock4j` 框架，基于 **Redis (Redisson)** 实现。
**使用示例**：
```java
@Service
public class OrderService {
@Autowired
private OrderMapper orderMapper;
// 锁住 orderId，防止并发修改
// expire: 锁过期时间 60s
// acquireTimeout: 获取锁超时时间 1s
@Lock4j(keys = {"#orderId"}, expire = 60000, acquireTimeout = 1000)
public void updateOrderStatus(Long orderId, String status) {
OrderDO order = orderMapper.selectById(orderId);
if (order == null) {
throw new BusinessException("订单不存在");
}
order.setStatus(status);
orderMapper.updateById(order);
}
}
```
* **看门狗机制**：对于长耗时业务，Redisson Watchdog 自动续期锁过期时间，防止业务未执行完锁被释放。
* **应用场景**：定时任务防重、库存扣减、设备指令下发。
### 4.4.2 幂等性组件 (`@Idempotent`)
自研幂等性切面 `com.viewsh.framework.idempotent`。
* **实现原理**：
1. **Key 生成**：支持多种策略，包括 HTTP Header 值、SpEL 表达式、请求参数 MD5。
2. **原子操作**：利用 Redis `setNX` 指令占位，设置较短的过期时间（默认 1s）。
3. **异常处理**：重复请求直接抛出 `IdempotentException`，全局异常处理器统一拦截返回 `429 Too Many Requests`。
* **应用场景**：表单重复提交、支付回调接口。
---
## 4.5 数据一致性设计 (Data Consistency)
### 4.5.1 最终一致性 (Saga/MQ)
绝大多数业务场景采用基于 MQ 的最终一致性方案。
* **本地事务表**：核心业务（如工单）执行本地事务时，记录“待发送消息”至本地表。
* **异步投递**：通过定时任务扫描本地表，投递至 MQ，确保消息不丢失。
* **消费确认**：下游服务消费成功后，回调更新状态。
### 4.5.2 强一致性 (Seata)
对于资金转账等极其敏感的跨库场景，预留 **Seata AT** 模式支持。
* *注*：当前核心业务流（IoT设备上报、Ops工单流转）设计上规避了强一致性需求，优先保障高可用与吞吐量。

126
docs/technical-overview/05-数据存储设计.md Normal file
View File

@@ -0,0 +1,126 @@
# Part 5: 数据存储设计
> **文档定位**：详细阐述平台的混合存储架构，明确不同类型数据的存储选型、模型设计及数据流转策略。
## 5.1 存储选型策略
AIoT 平台的数据呈现出明显的**冷热分层**与**结构差异**，因此采用“一主多从、动静分离”的混合存储策略。
| 数据类型 | 典型特征 | 选型方案 | 选型理由 |
| :--- | :--- | :--- | :--- |
| **业务元数据** | 强事务一致性、关联查询多、数据量中等 | **MySQL 8.0** | 关系型数据库事实标准，生态成熟，支持复杂事务。 |
| **设备遥测数据** | 数据量极巨大、写多读少、时序性强、无需事务 | **TDengine 3.0** | 专为物联网设计的时序数据库，写入性能是传统 DB 的 10 倍以上，支持超级表聚合查询。 |
| **热点/缓存数据** | 读多写多、对延迟极度敏感 (ms级) | **Redis 7.0** | 内存数据库，用于缓存设备在线状态、Token、分布式锁。 |
| **非结构化数据** | 图片、视频片段、Excel 报表 | **MinIO** | S3 兼容的对象存储，支持分布式部署与纠删码容错。 |
---
## 5.2 关系型数据库设计 (MySQL)
核心业务数据存储于 MySQL，采用 `aiot_platform` 库（逻辑上可拆分）。
### 5.2.1 核心 ER 关系图
* **多租户模型**：`system_tenant` (租户) 1:N `system_users` (用户) / `iot_device` (设备)。
* **业务闭环**：`iot_device` (设备) 1:N `iot_device_event` (告警) 1:1 `ops_work_order` (工单)。
### 5.2.2 关键表结构说明
#### 1. 设备表 (`iot_device`)
设备的“户口本”，存储设备的静态属性与认证信息。
| 字段名 | 类型 | 说明 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | BIGINT | 设备主键 | 分布式 ID |
| `product_id` | BIGINT | 产品ID | 关联产品物模型 |
| `device_name` | VARCHAR | 设备编码 | 唯一标识（如 IMEI、SN） |
| `auth_type` | VARCHAR | 认证方式 | Secret / Certificate / None |
| `device_secret` | VARCHAR | 设备密钥 | 一机一密模式下使用 |
| `status` | TINYINT | 启用状态 | 0-禁用，1-启用 |
| `tenant_id` | BIGINT | 租户ID | 多租户隔离键 |
#### 2. 工单表 (`ops_work_order`)
业务运营的核心载体，与 Flowable 流程实例绑定。
| 字段名 | 类型 | 说明 | 备注 |
| :--- | :--- | :--- | :--- |
| `id` | BIGINT | 工单主键 | |
| `work_order_no` | VARCHAR | 工单编号 | 业务唯一，带日期前缀 |
| `type` | VARCHAR | 工单类型 | REPAIR(维修), CLEAN(保洁), PATROL(巡逻) |
| `priority` | INT | 优先级 | 1-低, 2-中, 3-高 |
| `status` | VARCHAR | 状态 | PENDING, PROCESSING, FINISHED |
| `process_instance_id`| VARCHAR | 流程实例ID | 关联 Flowable 流程 |
| `device_id` | BIGINT | 关联设备 | 可为空（非设备类工单） |
---
## 5.3 时序数据库设计 (TDengine)
用于存储海量的设备上报消息与日志，采用 **“超级表 (Super Table)”** 设计模式。
### 5.3.1 模型设计思路
* **一个超级表**：定义同一类数据（如“设备消息”）的通用 Schema。
* **一个设备一张子表**：每个设备对应超级表下的一个子表，子表名通常为 `d_{deviceId}`。
* **标签 (Tags)**：将设备的元数据（`device_id`, `product_id`, `tenant_id`）作为 Tag，便于按维度聚合查询（例如：查询某租户下所有设备的平均温度）。
### 5.3.2 消息超级表 (`iot_device_message`)
存储所有从 Gateway 流入的原始消息及解析后的 Payload。
**Schema 定义 (Fields):**
| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `ts` | TIMESTAMP | 消息上报时间（主键） |
| `method` | NCHAR(64) | 消息类型 (jt808.loc.report) |
| `params` | JSON | 消息体（JSON 格式存储） |
| `code` | INT | 响应码 |
| `data` | JSON | 响应数据 |
**Tags 定义:**
| 标签名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `device_id` | BIGINT | 设备 ID |
| `product_id` | BIGINT | 产品 ID |
| `tenant_id` | BIGINT | 租户 ID |
**建表语句示例:**
```sql
CREATE STABLE iot_device_message (
ts TIMESTAMP,
method NCHAR(64),
params JSON,
code INT
) TAGS (
device_id BIGINT,
product_id BIGINT,
tenant_id BIGINT
);
```
---
## 5.4 缓存设计 (Redis)
### 5.4.1 Key 命名规范
遵循 `模块:业务:ID` 的格式，例如 `iot:device:online:1001`。
### 5.4.2 核心缓存场景
1. **设备在线状态**
* **Key**: `iot:device:online:{deviceId}`
* **Value**: String ("ONLINE" / "OFFLINE")
* **TTL**: 动态续期（心跳间隔 * 1.5）
2. **鉴权 Token**
* **Key**: `iot:auth:{token}`
* **Value**: DeviceDetail JSON
* **TTL**: 2 小时
3. **防重锁**
* **Key**: `lock:device:cmd:{deviceId}:{cmdId}`
* **Value**: Timestamp
* **TTL**: 5 秒（防止指令短时重复下发）
---
## 5.5 数据归档与清理
* **MySQL**: 业务数据原则上**永久存储**。对于极早期（3年以上）的历史工单，可迁移至历史库。
* **TDengine**: 利用其 TTL 特性，配置数据保留策略（例如保留 180 天）。
```sql
ALTER DATABASE aiot_db KEEP 180;
```

73
docs/technical-overview/06-公共组件与工具.md Normal file
View File

@@ -0,0 +1,73 @@
# Part 6: 公共组件与工具
> **文档定位**：介绍平台核心的公共技术组件与通用工具类，指导业务开发人员如何高效复用现有能力，避免重复造轮子。
## 6.1 框架组件概览 (`viewsh-framework`)
项目基于 Spring Boot Starters 机制封装了一套开箱即用的技术组件库，业务模块仅需引入对应依赖即可获得能力。
| 组件 artifactId | 功能描述 | 核心依赖 |
| :--- | :--- | :--- |
| `viewsh-common` | **通用工具包** | Hutool, Jackson, Guava |
| `viewsh-spring-boot-starter-web` | **Web 基础** | Spring MVC, Swagger, Global Exception |
| `viewsh-spring-boot-starter-security` | **安全组件** | Spring Security, OAuth2 Resource Server |
| `viewsh-spring-boot-starter-mybatis` | **数据库组件** | MyBatis Plus, Druid, Dynamic Datasource |
| `viewsh-spring-boot-starter-redis` | **缓存组件** | Redisson, Spring Data Redis |
| `viewsh-spring-boot-starter-mq` | **消息队列** | RocketMQ, Kafka (可选) |
| `viewsh-spring-boot-starter-job` | **定时任务** | XXL-JOB |
| `viewsh-spring-boot-starter-protection` | **服务保障** | Sentinel, Lock4j, Idempotent |
| `viewsh-spring-boot-starter-biz-tenant` | **多租户业务** | MyBatis Plus Plugin |
---
## 6.2 核心组件使用指南
### 6.2.1 统一响应结构 (`CommonResult`)
所有 HTTP 接口必须返回 `CommonResult<T>` 包装对象。
```java
@GetMapping("/get")
public CommonResult<UserVO> getUser(@RequestParam("id") Long id) {
UserVO user = userService.get(id);
return CommonResult.success(user);
}
```
### 6.2.2 异常处理 (`GlobalExceptionHandler`)
框架自动拦截所有未捕获异常：
* **业务异常 (`ServiceException`)**：返回对应业务错误码。
* **参数校验异常 (`MethodArgumentNotValidException`)**：即 `@Valid` 校验失败，返回 400 错误。
* **系统异常 (`Exception`)**：返回 500 “系统内部错误”，并打印堆栈日志。
### 6.2.3 多租户隔离
业务模块引入 `viewsh-spring-boot-starter-biz-tenant` 后，无需手动编写 `WHERE tenant_id = ?`。
* **忽略隔离**：如需查询全局数据（如系统管理员），使用 `@TenantIgnore` 注解。
### 6.2.4 数据权限
支持注解式数据权限控制：
```java
@DataPermission(deptAlias = "d", userAlias = "u") // 自动拼接 AND (d.id = ? OR u.id = ?)
public List<Order> selectList() { ... }
```
---
## 6.3 常用工具类
基于 `Hutool` 进行了二次封装，推荐优先使用 `viewsh-common` 中的工具类。
| 工具类 | 路径 | 用途 |
| :--- | :--- | :--- |
| **JsonUtils** | `com.viewsh.framework.common.util.json` | JSON 序列化/反序列化 (Jackson) |
| **DateUtils** | `com.viewsh.framework.common.util.date` | 日期时间格式化与计算 |
| **CollUtils** | `com.viewsh.framework.common.util.collection` | 集合操作 (Map/List) |
| **ValidationUtils** | `com.viewsh.framework.common.util.validation` | 手动触发 Bean Validation |
| **ServletUtils** | `com.viewsh.framework.common.util.servlet` | 获取当前 Request/Response/UserAgent |
---
## 6.4 开发规范
1. **禁止 System.out**：必须使用 `log.info/error`。
2. **禁止魔法值**：状态值等必须定义枚举或常量。
3. **Lombok 使用**：推荐使用 `@Data`, `@Slf4j`, `@Builder` 简化代码。
4. **对象转换**：使用 `MapStruct` 进行 DO/DTO/VO 之间的转换，禁止手动 set。

105
docs/technical-overview/07-接口文档.md Normal file
View File

@@ -0,0 +1,105 @@
# Part 7: 接口文档
> **文档定位**：明确前后端交互的接口标准 (RESTful API)，介绍 API 文档的自动生成与聚合访问方式，以及网关层的路由转发规则。
## 7.1 RESTful API 规范
平台所有 HTTP 接口严格遵循 RESTful 设计风格，HTTP Status Code 与业务 Error Code 分离。
### 7.1.1 URL 设计
* **版本控制**：`/admin-api/system/user/v1/page`
* **动词使用**：
* `GET`：查询资源（幂等）
* `POST`：创建资源（非幂等）
* `PUT`：更新资源（全量）
* `DELETE`：删除资源
### 7.1.2 响应结构
HTTP Status Code 标识网络层状态，Response Body 中的 `code` 标识业务状态。
```json
{
"code": 0, // 0 表示成功，非 0 表示业务异常
"msg": "success", // 错误提示信息
"data": { // 业务数据
"id": 1001,
"username": "admin"
}
}
```
### 7.1.3 常用错误码
| Code | 类型 | 说明 |
| :--- | :--- | :--- |
| **0** | Success | 请求成功 |
| **400** | Client Error | 参数校验失败 |
| **401** | Unauthorized | 未登录或 Token 过期 |
| **403** | Forbidden | 无权限访问该资源 |
| **429** | Too Many Requests | 请求过于频繁（触发限流） |
| **500** | Server Error | 系统内部未知错误 |
| **100xxx** | Biz Error | [100001] 系统模块异常 |
| **200xxx** | Biz Error | [200001] IoT 模块异常 |
---
## 7.2 接口文档聚合 (Knife4j)
项目采用 **Knife4j** (Swagger 的增强版) 实现接口文档的自动生成与微服务聚合。
### 7.2.1 访问地址
* **统一入口**：`http://{gateway-ip}:48080/doc.html`
* **原理**：Gateway 服务集成 `knife4j-gateway-spring-boot-starter`，自动发现并聚合所有 Nacos 中注册的微服务 Swagger 文档。
### 7.2.2 开发注解规范
后端开发必须使用 Swagger 注解描述接口含义：
* `@Tag(name = "管理后台 - 用户管理")`：标记 Controller。
* `@Operation(summary = "获得用户分页")`：标记接口方法。
* `@Schema(description = "用户编号")`：标记 VO/DTO 字段。
---
## 7.3 Gateway 路由规则
网关根据请求 Path 前缀将流量转发至对应的微服务。
| 请求前缀 (Prefix) | 目标服务 (Target Service) | 说明 |
| :--- | :--- | :--- |
| `/admin-api/system/**` | `viewsh-module-system-server` | 系统/租户/权限相关 |
| `/admin-api/infra/**` | `viewsh-module-infra-server` | 文件/定时任务相关 |
| `/admin-api/iot/**` | `viewsh-module-iot-server` | 设备管理/规则引擎 |
| `/admin-api/ops/**` | `viewsh-module-ops-server` | 运营工单/报修 |
| `/app-api/**` | `viewsh-module-system-server` | 移动端 App 接口（部分复用） |
---
## 7.4 核心接口示例
### 7.4.1 设备遥测数据上报 (HTTP)
* **URL**: `http://{gateway}:8092/iot/device/report`
* **Method**: `POST`
* **Body**:
```json
{
"productKey": "a1B2c3D4",
"deviceName": "sn-0001",
"ts": 1678888888000,
"params": {
"temperature": 25.6,
"humidity": 60
}
}
```
### 7.4.2 创建维修工单 (Admin)
* **URL**: `http://{gateway}:48080/admin-api/ops/work-order/create`
* **Method**: `POST`
* **Header**: `Authorization: Bearer {token}`
* **Body**:
```json
{
"type": "REPAIR",
"deviceId": 10001,
"desc": "空调异响，需检查风扇",
"priority": 2
}
```

80
docs/technical-overview/08-开发指南.md Normal file
View File

@@ -0,0 +1,80 @@
# Part 8: 开发指南
> **文档定位**：为新入职开发人员提供从环境搭建、代码规范、分支管理到本地调试的保姆级教程，确保开发环境与生产环境的一致性。
## 8.1 本地开发环境搭建
### 8.1.1 基础软件要求
| 软件 | 版本要求 | 说明 |
| :--- | :--- | :--- |
| **JDK** | **17** | 必须 JDK 17 (Spring Boot 3.x 硬性要求) |
| **Maven** | 3.8+ | 建议配置阿里云镜像源 |
| **IntelliJ IDEA** | 2023.2+ | 需安装 Lombok, MapStruct 插件 |
| **Git** | 2.30+ | 代码版本管理 |
| **Docker** | 24.0+ | 用于本地启动中间件 (MySQL, Redis 等) |
### 8.1.2 中间件快速启动
项目根目录下提供了 `docker-compose.core.yml`，用于一键拉起依赖的中间件。
```bash
cd aiot-platform-cloud
docker-compose -f docker-compose.core.yml up -d mysql redis nacos rocketmq tdengine
```
* **MySQL 初始化**：首次启动后，需导入 `sql/mysql/` 下的 SQL 脚本。
* **Nacos 配置**：访问 `http://localhost:8848/nacos`，导入 `config/nacos_config_export.zip`（假定存在导出配置）。
---
## 8.2 代码规范 (Code Style)
### 8.2.1 命名规范
* **类名**：`UpperCamelCase`，如 `IotDeviceService`。
* **应用名**：`lower-kebab-case`，如 `viewsh-module-system`。
* **包名**：`com.viewsh.module.{模块}.{层级}`，如 `com.viewsh.module.iot.controller`。
### 8.2.2 异常与日志
* **日志**：统一使用 `@Slf4j`。禁止使用 `System.out.println`。
* INFO: 关键流程节点、状态变更。
* ERROR: 异常堆栈，必须包含 `e`。
* **异常**：业务逻辑错误抛出 `ServiceException(ErrorCode)`，不要吞掉异常。
---
## 8.3 分支管理策略 (Git Flow)
采用简化的 Git Flow 模型：
* **master**：主分支，对应生产环境 (Prod)，仅允许从 release 合并。
* **release**：发布分支，对应预发布环境 (Staging)，进行集成测试。
* **dev**：开发主分支，对应开发环境 (Dev)。
* **feat/xxx**：功能分支，从 dev 切出，开发完成后通过 Pull Request (PR) 合并回 dev。
**提交规范 (Commit Message):**
```text
feat(iot): 新增设备批量导入功能
fix(ops): 修复工单状态流转死锁 bug
docs: 更新部署文档
style: 代码格式化
```
---
## 8.4 如何新增一个微服务
1. **创建 Module**：在 `viewsh-module-xxx` 下创建 Maven 子模块。
2. **依赖配置**：引入 `viewsh-common` 及相关 starter。
3. **配置文件**：在 `resources` 下创建 `bootstrap.yaml`，配置 Nacos 地址。
4. **启动类**：添加 `@SpringBootApplication` 和 `@EnableDiscoveryClient`。
5. **网关路由**：在 Nacos 配置中心的 `viewsh-gateway` 路由配置中添加转发规则。
---
## 8.5 常见问题排查 (FAQ)
**Q: 启动报 `Connection refused: no further information`?**
A: 检查 Nacos 是否启动成功，且 8848 端口未被防火墙拦截。
**Q: Maven 依赖下载失败?**
A: 检查 `pom.xml` 中的 Maven 仓库配置，确认 settings.xml 中 mirror 设置正确。
**Q: MapStruct 转换对象时属性为 null?**
A: 确保编译顺序：Lombok 必须在 MapStruct 之前执行（参考父工程 `pom.xml` 的 `maven-compiler-plugin` 配置）。

62
docs/technical-overview/09-部署与运维.md Normal file
View File

@@ -0,0 +1,62 @@
# Part 9: 部署与运维
> **文档定位**：详细描述系统的自动化构建流程、容器化部署架构及生产环境的运维监控策略。
## 9.1 CI/CD 流水线 (Jenkins Pipeline)
平台采用声明式 Jenkins Pipeline 实现全自动化的持续集成与部署，支持**自动回滚**与**智能并发构建**。
### 9.1.1 流水线阶段概览
1. **Detect Changes**: 智能检测代码变更，仅构建受影响的微服务模块（Optimization 2）。
2. **Build Services**:
* **动态并行**：根据构建机 CPU/内存动态计算并行度 (`MAX_PARALLEL_BUILDS`)。
* **Maven 缓存**：挂载 `jenkins-maven-cache` 卷加速依赖下载。
3. **Deploy**:
* **备份**：记录当前运行的镜像 TAG 到 `deployment-state-xxx.txt`。
* **部署**：更新镜像并重启服务，支持 `StrictHostKeyChecking=no` 免交互 SSH。
4. **Health Check**: 循环检测 `/actuator/health` 端点，超时或失败则自动触发回滚。
### 9.1.2 自动回滚机制
* **触发条件**：部署失败或健康检查未通过。
* **执行逻辑**：
1. 读取 `PREV_IMAGE_TAG`（上一次成功部署的版本）。
2. 执行 `rollbackDeployment`，强制拉取旧镜像并重启。
3. 保留最近 5 个版本的镜像 Tag，避免 `dangling` 清理误删。
---
## 9.2 容器化部署架构
基于 **Docker Compose** 的微服务编排方案，适用于私有化交付场景。
### 9.2.1 核心服务清单
| 服务名称 | 端口 | 内存限制 | 依赖关系 |
| :--- | :--- | :--- | :--- |
| `viewsh-gateway` | 48080 | 1536m | Nacos, Redis |
| `viewsh-module-system` | 48081 | 1536m | Gateway, MySQL |
| `viewsh-module-iot` | 48091 | 2560m | RocketMQ, TDengine |
| `viewsh-module-iot-gateway` | 8091/1883 | 2560m | IoT-Server |
### 9.2.2 网络与存储
* **网络**：使用外部网络 `1panel-network` (External)，便于与 1Panel 面板管理的 MySQL/Redis 互通。
* **日志挂载**：所有服务日志统一映射至 `app-logs` 卷 (`/app/logs`)，便于 Filebeat 采集。
* **环境变量**：通过 `.env` 文件或 Jenkins 注入 `REGISTRY_HOST` 和 `IMAGE_TAG`，实现版本控制。
---
## 9.3 监控与运维
### 9.3.1 应用监控 (SkyWalking)
* **探针注入**：在 `Dockerfile` 中集成 SkyWalking Agent。
```dockerfile
JAVA_OPTS="-javaagent:/agent/skywalking-agent.jar -Dskywalking.agent.service_name=aiot-gateway"
```
* **全链路追踪**：通过 `TraceId` 串联 HTTP 请求 -> 网关 ->微服务 -> 数据库/MQ 的完整调用链。
### 9.3.2 日志管理
* **规范**：JSON 格式输出，包含 `traceId`、`spanId`。
* **采集**：Filebeat -> Logstash -> Elasticsearch -> Kibana (ELK 栈)。
### 9.3.3 告警策略
* **系统级**：CPU > 80%, 内存 > 90%, 磁盘 > 85%。
* **业务级**：IoT 设备离线率 > 10%, 工单处理超时 > 30min (通过 XXL-JOB 检测)。

80
docs/technical-overview/10-安全设计.md Normal file
View File

@@ -0,0 +1,80 @@
# Part 10: 安全设计
> **文档定位**：全景式阐述系统的安全防御体系，涵盖身份认证、权限控制、数据保护及网络防护四大维度。
## 10.1 身份认证架构 (Authentication)
采用标准 **OAuth2 Resource Server** 架构，实现端到端的无状态身份验证。
### 10.1.1 认证流程
1. **登录 (Login)**：
* 客户端调用 `/admin-api/system/auth/login`。
* 服务端校验账号密码，生成 JWT (JSON Web Token)，包含 `uid`, `tenant_id`, `scopes`。
2. **验签 (Verify)**：
* 网关层校验 `Authorization: Bearer {token}`。
* 解析 JWT 签名，若无效直接返回 401。
* 校验 Token 是否在 Redis 白名单中（支持服务端主动踢下线）。
3. **透传 (Pass-through)**：
* 网关将 `login-user-id` 等用户信息放入 HTTP Header，透传给下游微服务。
### 10.1.2 多端认证体系
* **管理端 (Admin)**：用户名/密码，支持图形验证码。
* **移动端 (App)**：手机号/验证码，微信一键登录。
* **设备端 (IoT)**：
* 一机一密：DeviceSecret 签名。
* 一型一密：ProductSecret 动态注册。
---
## 10.2 权限控制体系 (Authorization)
### 10.2.1 功能权限 (RBAC)
基于 **Spring Security** 的动态权限控制：
* **模型**：用户 -> 角色 -> 菜单/按钮 (Permission Identifier)。
* **鉴权**：
```java
@PreAuthorize("@ss.hasPermission('system:user:create')")
public CommonResult create() { ... }
```
* **动态加载**：服务启动时扫描 Controller 注解，上报权限标识至数据库。
### 10.2.2 数据权限
解决“同角色的不同用户只能看自己数据”的问题。
* **原理**：MyBatis Plus 拦截器 (`DataPermissionInterceptor`)。
* **策略**：
1. 全部数据
2. 本部门及以下
3. 本部门
4. 仅本人
5. 自定义部门
---
## 10.3 数据安全 (Data Security)
### 10.3.1 敏感数据脱敏
对手机号、身份证、银行卡等敏感字段传输进行掩码处理。
* **注解实现**：`@Desensitization(type = MOBILE)`，Jackson 序列化时自动处理为 `138****0000`。
### 10.3.2 密码存储
* **哈希算法**：BCrypt (Spring Security 默认)。
* **加盐**：每个用户随机 Salt，防止彩虹表攻击。
### 10.3.3 日志审计
* **操作日志**：记录 `UserID`, `IP`, `Module`, `Operation`, `Duration`。
* **异常监控**：拦截 SQL 注入攻击日志，记录异常堆栈。
---
## 10.4 网络防护
### 10.4.1 防重放攻击 (Replay Attack)
针对关键接口（如支付、设备控制）：
* Header 携带 `Timestamp` 和 `Nonce`。
* 服务端校验 Timestamp 偏差 < 5分钟。
* Redis 缓存 Nonce，5分钟内禁止重复使用。
### 10.4.2 接口签名 (API Signature)
对于开放给第三方的 API：
* 算法：`Sign = MD5(Sort(Params) + AppSecret)`。
* 作用：防止参数在传输过程中被篡改。

38
docs/technical-overview/11-附录.md Normal file
View File

@@ -0,0 +1,38 @@
# Part 11: 附录
> **文档定位**：提供文档中涉及的专业术语表、技术栈版本清单及参考资料链接，作为全文的补充索引。
## 11.1 术语表 (Glossary)
| 术语 | 全称 | 解释 |
| :--- | :--- | :--- |
| **TSL** | Thing Specification Language | 物模型，描述设备是什么、能做什么的数字化模板。 |
| **RBAC** | Role-Based Access Control | 基于角色的访问控制，标准的权限管理模型。 |
| **SaaS** | Software as a Service | 软件即服务，平台支持多租户独立使用。 |
| **FSM** | Finite State Machine | 有限状态机，用于管理复杂的工单状态流转。 |
| **APM** | Application Performance Management | 应用性能管理，指代 SkyWalking 等监控系统。 |
| **DLQ** | Dead Letter Queue | 死信队列，存储消费失败无法重试的消息。 |
---
## 11.2 核心依赖版本清单
| 组件 | 版本 | 说明 |
| :--- | :--- | :--- |
| **Java** | 17 | LTS 版本 |
| **Spring Boot** | 3.5.9 | 基础框架 |
| **Spring Cloud** | 2025.0.0 | 微服务治理 |
| **Spring Cloud Alibaba** | 2023.0.3.3 | Nacos/Sentinel/RocketMQ 适配 |
| **MyBatis Plus** | 3.5.x | ORM 框架 |
| **TDengine Driver** | 3.1.x | 时序数据库驱动 |
| **Lombok** | 1.18.30 | 代码简化工具 |
| **Redisson** | 3.24.x | Redis 高级客户端 |
---
## 11.3 参考资料
* **Spring Cloud Alibaba**: [https://github.com/alibaba/spring-cloud-alibaba](https://github.com/alibaba/spring-cloud-alibaba)
* **Ruoyi Vue Pro**: [https://gitee.com/zhijiantianya/ruoyi-vue-pro](https://gitee.com/zhijiantianya/ruoyi-vue-pro) (参考基础架构)
* **TDengine 官网**: [https://www.taosdata.com/](https://www.taosdata.com/)
* **JT808 协议文档**: [https://jt808.io/](https://jt808.io/)

182
docs/technical-overview/README.md Normal file
View File

@@ -0,0 +1,182 @@
# AIoT Platform 技术全景文档
> **文档定位**：项目的技术文档，全面覆盖整个 AIoT 平台
> **维护策略**：版本化管理，持续更新，支持多人协作
> **最后更新**：2026-01-14
> **文档版本**：v1.0.0
---
## 🗺️ 文档全景图
```mermaid
graph TD
Root[技术全景] --> P1[Part 1: 项目概述]
Root --> P2[Part 2: 系统架构]
Root --> P3[Part 3: 核心模块]
Root --> P4[Part 4: 技术架构]
P1 --> P1_1(背景/场景/技术栈)
P2 --> P2_1(业务/应用/数据架构)
P3 --> P3_1(Gateway/IoT/Ops/System)
P4 --> P4_1(服务治理/消息/存储)
style Root fill:#f9f,stroke:#333,stroke-width:2px
```
## 📖 文档导航
本文档采用模块化结构，各部分内容相对独立，支持按需查阅。
### [Part 1: 项目概述](./01-项目概述.md)
- 项目背景与业务价值
- 核心业务场景
- 技术栈总览
- 版本演进历史
### [Part 2: 系统架构](./02-系统架构.md)
- 微服务架构总览
- 服务分层设计
- 模块依赖关系
- 部署架构
- 技术选型与决策
### [Part 3: 核心模块详解](./03-核心模块详解.md)
#### 3.1 Gateway 网关服务
- 路由配置、负载均衡、统一认证、限流熔断
#### 3.2 System 系统服务
- 用户管理、权限管理、租户管理、字典管理
#### 3.3 Infra 基础设施服务
- 文件存储、消息通知、定时任务、数据字典
#### 3.4 IoT 物联网服务
- IoT 设备管理、IoT Gateway 设备网关、设备状态同步、设备事件发布、时序数据存储
#### 3.5 Ops 业务运营服务 ⭐
- **四大条线**：保洁、安保、工程、客服
- **核心引擎**：工单状态机、智能派单算法、优先级队列
### [Part 4: 技术架构设计](./04-技术架构设计.md)
- 服务注册与发现（Nacos）
- 配置中心（Nacos Config）
- 消息队列（RocketMQ）
- 分布式事务
- 缓存策略（Redis）
- 数据一致性保证
- 并发控制（分布式锁）
### [Part 5: 数据存储设计](./05-数据存储设计.md)
- MySQL 数据库设计
- Redis 缓存设计
- TDengine 时序数据库
- 数据迁移与同步
### [Part 6: 公共组件与工具](./06-公共组件与工具.md)
- 状态机框架
- 事件驱动框架
- 分布式锁组件
- 幂等性组件
- 限流组件
- 通用工具类
### [Part 7: 接口文档](./07-接口文档.md)
- REST API 规范
- Gateway 路由配置
- 核心接口清单
- 调用示例
### [Part 8: 开发指南](./08-开发指南.md)
- 本地环境搭建
- 代码规范
- 分支管理策略
- 提交规范
- 单元测试规范
- 如何新增服务
- 如何扩展业务类型
- 常见问题排查
### [Part 9: 部署与运维](./09-部署与运维.md)
- CI/CD 流程（Jenkins Pipeline）
- Docker 容器化部署
- 服务监控
- 日志管理
- 性能优化
- 故障处理流程
### [Part 10: 安全设计](./10-安全设计.md)
- 认证与授权
- 数据加密
- 接口安全
- 安全审计
### [Part 11: 附录](./11-附录.md)
- 术语表
- 参考资料
- 相关文档链接
- 变更日志
---
## 🎯 快速开始
### 🚀 新成员入职推荐阅读路径
| 天数 | 目标 | 核心任务 |
| :--- | :--- | :--- |
| **Day 1** | **了解全貌** | 1. 阅读 [Part 1 项目概述](./01-项目概述.md)<br>2. 阅读 [Part 2 系统架构](./02-系统架构.md)<br>3. 搭建环境（[Part 8](./08-开发指南.md)） |
| **Day 2** | **深入核心** | 1. 阅读 [Part 3 核心模块](./03-核心模块详解.md)（关注 Ops/IoT）<br>2. 阅读 [Part 7 接口文档](./07-接口文档.md) |
| **Day 3** | **动手实践** | 1. 运行项目<br>2. 阅读 [Part 5 数据设计](./05-数据存储设计.md)<br>3. 尝试编写第一个单元测试 |
### 🤝 跨团队协作推荐路径
* **产品/设计**：阅读 [Part 1](./01-项目概述.md) 和 [Part 3](./03-核心模块详解.md) 了解业务逻辑。
* **前端开发**：阅读 [Part 7 接口文档](./07-接口文档.md) 和 [Part 3](./03-核心模块详解.md)。
* **运维人员**：重点阅读 [Part 2](./02-系统架构.md) 和 [Part 9](./09-部署与运维.md)。
---
## 📝 文档维护指南
### 版本管理
本文档采用语义化版本号：`主版本.次版本.修订版本`
- **主版本**：架构重大变更，不兼容旧版本
- **次版本**：新增功能模块，向下兼容
- **修订版本**：bug 修复、文档优化
### 变更记录
| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| v1.0.1 | 2026-01-18 | 优化文档结构，增加图表与代码示例 | AI Assistant |
| v1.0.0 | 2026-01-14 | 初始版本，建立文档框架 | LZH |
### 贡献指南
1. **新增内容**：在对应章节添加内容，更新目录和版本号
2. **修改内容**：标注修改位置和原因，更新版本号
3. **格式规范**：使用 Markdown 格式，遵循现有文档风格
4. **代码示例**：确保代码可以运行，添加注释说明
### 文档规范
- 标题层级：最多使用 4 级标题
- 代码块：标注语言类型
- 链接：使用相对路径
- 图片：存放在 `./images/` 目录
---
## 🔗 相关资源
- [部署指南](../deployment-guide.md) - 生产环境部署文档
- [Ops 模块架构文档](./ops-architecture/) - Ops 业务运营模块深度架构文档
- [OpenSpec 规范](../../openspec/) - 项目变更规范
---
## 📧 联系方式
如有疑问或建议，请联系技术负责人或提交 Issue。