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

docs(architecture): 重写总体技术架构图，新增业务架构与数据流转链路

Browse Source
This commit is contained in:
lzh
2026-04-06 22:47:42 +08:00
parent 63886a4e76
commit abd15d842b
3 changed files with 226 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files

300
开发者文档/01-业务与架构/01-总体架构设计.md
View File

@@ -1,188 +1,122 @@
# AIOT 系统架构
# 01-总体架构设计
本文档描述 AIOT 平台的整体系统架构和模块划分。
本文档是 AIOT 平台的顶层架构蓝图，涵盖技术架构、端到端数据流与物理拓扑。在阅读具体的业务模块设计前，请先通读本文档建立全局认知。
## 高层架构
```
┌──────────────────────────────────────────────────────────────┐
│ 客户端 │
├─────────────┬────────────────────┬───────────────────────────┤
│ Web 管理后台 │ 移动端（多端） │ IoT 设备 │
│ Vue 3 │ uni-app │ MQTT / HTTP │
│ Vben Admin │ 小程序/H5/App │ 传感器/执行器 │
└──────┬───────┴─────────┬──────────┴──────────┬───────────────┘
│ HTTPS │ HTTPS │ MQTT / HTTP
│ │ │
┌──────▼──────────────────▼─────────────────────▼──────────────┐
│ viewsh-gateway │
│ Spring Cloud Gateway（API 网关） │
│ 路由转发 · 鉴权 · 限流 · 负载均衡 │
└──────────────────────────┬───────────────────────────────────┘
│
┌──────────────────────────▼───────────────────────────────────┐
│ 后端微服务集群 │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ viewsh-server（主服务） │ │
│ │ 聚合启动各业务模块 │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────┐ ┌───────────────┐ ┌──────────────────┐ │
│ │ module-system │ │ module-infra │ │ module-iot │ │
│ │ 用户·角色·权限 │ │ 文件·配置·代码 │ │ 设备·数据·协议 │ │
│ │ 菜单·部门·岗位 │ │ 生成·日志·监控 │ │ 采集·告警·联动 │ │
│ └───────────────┘ └───────────────┘ └──────────────────┘ │
│ │
│ ┌───────────────┐ ┌──────────────────────────────────────┐ │
│ │ module-ops │ │ viewsh-framework │ │
│ │ 工单·巡检 │ │ 公共层：安全、缓存、日志、工具类 │ │
│ │ 告警·维保 │ │ MyBatis-Plus · MapStruct · Lombok │ │
│ └───────────────┘ └──────────────────────────────────────┘ │
└──────────────────────────┬───────────────────────────────────┘
│
┌──────────────────────────▼───────────────────────────────────┐
│ 数据层 │
│ ┌───────────────┐ ┌───────────────┐ ┌──────────────────┐ │
│ │ MySQL 8.0 │ │ Redis │ │ Nacos │ │
│ │ 业务数据 │ │ 缓存·会话 │ │ 注册中心·配置 │ │
│ └───────────────┘ └───────────────┘ └──────────────────┘ │
└──────────────────────────────────────────────────────────────┘
│
┌──────────────────────────▼───────────────────────────────────┐
│ 基础设施 │
│ Docker · Jenkins · Nginx │
└──────────────────────────────────────────────────────────────┘
```
## 后端模块职责
### viewsh-gateway
API 网关，所有客户端请求的统一入口。
- 路由转发：根据路径前缀将请求分发到对应服务
- 认证鉴权：统一的 Token 校验
- 限流熔断：保护后端服务
- 跨域处理：统一 CORS 配置
### viewsh-framework
公共框架层，被所有业务模块依赖。
- 安全框架：JWT 认证、权限校验
- 数据访问：MyBatis-Plus 封装、分页、多租户
- 缓存封装：Redis 操作工具类
- 日志切面：操作日志、访问日志
- 工具类库：Lombok、MapStruct、通用响应体
### viewsh-server
主服务启动模块，聚合加载各业务模块。
- 统一启动入口
- 模块扫描与加载
- 全局异常处理
- Swagger/OpenAPI 文档聚合
### viewsh-module-system
系统管理模块，提供基础的管理功能。
- 用户管理：增删改查、密码重置
- 角色管理：角色分配、数据权限
- 权限管理：菜单权限、按钮权限
- 部门管理：组织架构树
- 岗位管理
- 字典管理
- 通知公告
### viewsh-module-infra
基础设施模块，提供平台底层能力。
- 文件管理：上传、下载、存储
- 配置管理：系统参数配置
- 代码生成：根据表结构自动生成 CRUD 代码
- 数据源管理
- API 日志：访问日志、错误日志
- 定时任务
### viewsh-module-iot
IoT 核心模块，AIOT 平台的核心业务。
- 设备管理：设备注册、分组、状态监控
- 数据采集：设备上报数据接收和存储
- 协议适配：MQTT、HTTP 等协议接入
- 告警规则：阈值告警、离线告警
- 设备联动：规则引擎、场景联动
- 数据可视化：实时数据展示
### viewsh-module-ops
运维管理模块，面向运维人员的管理功能。
- 工单管理：创建、分配、流转、关闭
- 巡检管理：巡检计划、巡检记录
- 告警处理：告警确认、告警统计
- 维保管理：设备维保计划和记录
## 前端架构
```
yudao-ui-admin-vben/
├── apps/ # 应用层
│ └── admin/ # 管理后台主应用
├── packages/ # 共享包
│ ├── components/ # 通用业务组件
│ ├── utils/ # 工具函数
│ └── types/ # TypeScript 类型定义
├── internal/ # 内部构建配置
│ ├── lint-configs/ # ESLint、Prettier 规则
│ └── vite-config/ # Vite 构建配置
└── scripts/ # 构建和发布脚本
```
**核心技术选型**：Vue 3 + TypeScript + Vben Admin + Ant Design Vue + Pinia + pnpm monorepo + Turborepo
## 移动端架构
```
aiot-uniapp/
├── src/
│ ├── pages/ # 页面
│ ├── components/ # 组件
│ ├── api/ # 后端 API 调用
│ ├── store/ # Pinia 状态管理
│ ├── utils/ # 工具函数
│ └── static/ # 静态资源
├── env/ # 多环境配置
└── vite-plugins/ # 自定义 Vite 插件
```
**核心技术选型**：Vue 3 + TypeScript + uni-app + Pinia + UnoCSS + wot-design-uni
**构建目标**：微信小程序、H5、Android App、iOS App
## 通信方式
| 通信链路 | 协议 | 说明 |
|----------|------|------|
| 前端 ↔ 网关 | HTTPS | REST API 调用 |
| 移动端 ↔ 网关 | HTTPS | REST API 调用 |
| 网关 ↔ 后端服务 | HTTP | 内部服务转发 |
| 设备 ↔ 后端 | MQTT | 设备数据上报、指令下发 |
| 设备 ↔ 后端 | HTTP | 设备注册、固件升级 |
| 服务 ↔ Nacos | HTTP | 服务注册与配置拉取 |
## 关键设计原则
1. **模块化** — 业务按领域拆分为独立模块，各模块职责清晰
2. **网关统一入口** — 所有外部请求通过 Gateway 进入，统一鉴权和路由
3. **配置集中管理** — Nacos 管理所有服务配置，支持动态刷新
4. **前后端分离** — 前端独立部署，通过 API 与后端交互
5. **多端复用** — 移动端通过 uni-app 一套代码编译多个平台
> **🔗 关联阅读**：
> - 了解代码仓具体分配，请看：[[../00-导航与总览/03-代码仓与协作边界.md]]
> - 了解后端基本规约，请看：[[../07-协作规范/01-不同项目的基本规范.md]]
---
最后更新时间：2026-03-26
## 1. 高层技术架构 (Mermaid)
AIOT 平台采用经典的前后端分离与微服务架构。下面是全局系统的高层视图：
```mermaid
flowchart TB
%% 客户端层
subgraph ClientLayer ["客户端层 (Clients)"]
direction LR
WebAdmin["Web 管理后台<br/>(Vue3 + Vben)"]
MobileApp["移动端<br/>(uni-app)"]
IoTDevice["IoT 设备<br/>(MQTT/HTTP)"]
end
%% 网关层
subgraph GatewayLayer ["网关层 (API Gateway)"]
Gateway["viewsh-gateway<br/>(Spring Cloud Gateway)"]
end
%% 微服务层
subgraph ServiceLayer ["后端微服务集群 (viewsh-server)"]
direction TB
subgraph BizModules ["业务领域模块"]
ModSystem["module-system<br/>(系统管理)"]
ModOps["module-ops<br/>(运维/工单)"]
ModIoT["module-iot<br/>(设备/规则)"]
ModInfra["module-infra<br/>(基础支撑)"]
end
Framework["viewsh-framework<br/>(安全/缓存/工具组件)"]
BizModules --> Framework
end
%% 数据层
subgraph DataLayer ["数据与中间件层 (Data & Infra)"]
direction LR
MySQL[(MySQL 8.0)]
Redis[(Redis)]
Nacos[Nacos<br/>注册配置中心]
end
%% 交互链路
WebAdmin == HTTPS ==> Gateway
MobileApp == HTTPS ==> Gateway
IoTDevice == MQTT/HTTP ==> Gateway
Gateway == 路由分发 ==> ServiceLayer
ServiceLayer == 持久化 ==> MySQL
ServiceLayer -. 缓存/会话 .-> Redis
ServiceLayer -. 服务发现/配置 .-> Nacos
```
---
## 2. 后端模块职责 (aiot-platform-cloud)
后端不采用过于碎片化的微服务拆分，而是采用**单体聚合启动、模块化隔离（Modulith）**的设计。
### 核心引擎
- **`viewsh-gateway`**：API 网关。负责统一路由转发、全局 Token 校验、限流熔断及 CORS 跨域处理。
- **`viewsh-server`**：主服务。聚合加载所有的业务 module，提供统一启动入口、全局异常处理和 OpenAPI（Swagger）文档聚合。
- **`viewsh-framework`**：公共基座。被所有模块依赖，提供 MyBatis-Plus 封装、JWT 安全、Redis 模板、AOP 日志切面及全局工具类。
### 业务领域模块（Domain Modules）
各业务模块必须保持 Service 层的代码隔离，禁止循环依赖。
| 模块名 | 核心职责 | 关联领域文档 |
|--------|----------|--------------|
| **`module-system`** | 用户、角色、权限（RBAC）、菜单、部门、岗位、字典及通知公告。 | 系统公共基座 |
| **`module-infra`** | 文件上传/存储、系统参数、定时任务、操作/访问日志、代码生成。 | [[../06-平台支撑/00-支撑平台总览.md]] |
| **`module-ops`** | 工单生命周期流转、保洁排班、安保巡检、告警确认及维保任务。 | [[../02-Ops领域/00-Ops领域总览.md]] |
| **`module-iot`** | 设备接入认证、物模型解析、MQTT指令下发、数据上报存储、规则联动。 | [[../03-IoT领域/00-IoT领域总览.md]] |
---
## 3. 前端与移动端架构
### Web 管理后台 (yudao-ui-admin-vben)
采用 `pnpm monorepo` 结构管理。
- **核心选型**：Vue 3 + TypeScript + Vben Admin + Ant Design Vue + Pinia。
- **目录设计**：
- `apps/admin/`：主应用层。
- `packages/components/`：跨页面共享的 dumb 组件。
- `packages/utils/` 与 `packages/types/`：统一的基础类与接口定义。
### 移动端作业工具 (aiot-uniapp)
面向一线人员（保安、保洁、维修）的便携式作业流终端。
- **核心选型**：Vue 3 + TypeScript + uni-app + Pinia + UnoCSS。
- **编译目标**：同一套代码可输出为微信小程序、H5 及原生 App。
- **页面分域**：按照业务域严格切分 `pages-ops`、`pages-system`、`pages-infra`，确保分包体积最优。
---
## 4. 全局通信协议矩阵
开发联调与部署排障时，请认准以下网络边界契约：
| 通信链路 | 传输协议 | 报文格式 | 说明与场景 |
|----------|----------|----------|------------|
| Web端 ↔ 网关 | `HTTPS` | JSON | 浏览器 RESTful 请求。 |
| 移动端 ↔ 网关 | `HTTPS` | JSON | 小程序/App 业务请求。 |
| 网关 ↔ 业务服务 | `HTTP` | JSON | 网关鉴权后的内部路由（内网转发）。 |
| IoT设备 ↔ 网关 | `MQTT` / `HTTP` | 二进制/JSON | 设备端侧上报遥测数据及订阅云端指令。 |
| 业务服务 ↔ Nacos | `HTTP` / `gRPC` | - | 服务注册与配置动态刷新。 |
---
## 5. 核心架构设计原则
1. **领域隔离优先于复用**：`module-ops` 与 `module-iot` 在演进初期，允许部分实体的冗余，禁止在 Controller 层直接相互调用。如果需要联动，通过 Service 层依赖或内部事件总线（EventBus）解耦。
2. **统一网关入口**：绝不允许绕过 Gateway 直接请求后端节点，所有权限校验和限流必须在 Gateway 层统一收口。
3. **配置外置化**：环境变量、中间件地址、特征开关等，必须统一配置在 Nacos 中，禁止硬编码或随代码提交 `application-local.yml` 敏感信息。
4. **强契约驱动**：后端 API 变动前必须更新 Swagger，前端基于契约（Types）进行严格约束，杜绝随意使用 `any` 类型。

8
开发者文档/01-业务与架构/01-架构设计说明.md
View File

@@ -1,8 +0,0 @@
# 01-架构设计说明
## 目标与面向读者
介绍系统整体的微服务架构、网络边界与技术选型，主要面向系统架构师与后端开发者。
## 核心内容占位
- 待补充：系统物理架构图。
- 待补充：`aiot-platform-cloud` 的微服务划分说明。

109
开发者文档/01-业务与架构/02-业务架构与数据流转.md Normal file
View File

@@ -0,0 +1,109 @@
# 02-业务架构与数据流转
相比于 [01-总体架构设计](./01-总体架构设计.md) 关注“代码和技术组件怎么堆叠”，本文档重点阐述“**业务数据如何在这个系统里流动**”。
在 AIOT 这个同时具备人工作业（Ops）和硬件交互（IoT）属性的系统中，搞懂业务架构，就是搞懂这两者怎么联动。
> **🔗 关联阅读**：
> - 具体 Ops 流转细节，请看：[[../02-Ops领域/01-工单生命周期与状态机.md]]
> - 具体 IoT 数据处理，请看：[[../03-IoT领域/00-IoT领域总览.md]]
---
## 1. 业务高层视图 (Business Architecture)
整个平台的业务可以抽象为「三环模型」：感知环、调度环、执行环。
```mermaid
flowchart LR
subgraph 感知环 ["感知环 (Trigger)"]
direction TB
ManualEvent["人工上报<br/>(巡检异常/主动报修)"]
IoTEvent["设备感知<br/>(阈值告警/离线预警)"]
end
subgraph 调度环 ["调度环 (Brain)"]
direction TB
RuleEngine["规则引擎<br/>(过滤/转化)"]
Dispatch["派单引擎<br/>(抢单/派单/排班)"]
RuleEngine --> Dispatch
end
subgraph 执行环 ["执行环 (Action)"]
direction TB
OpsTask["人工执行<br/>(工单/保洁/安保)"]
IoTAction["设备控制<br/>(反向指令下发)"]
end
ManualEvent --> Dispatch
IoTEvent --> RuleEngine
Dispatch --> OpsTask
RuleEngine --> IoTAction
```
### 为什么这样拆分？
- **触发源可以是人，也可以是设备**：保安巡逻发现水管爆裂（人工上报），或者水压传感器触发阈值（设备感知）。
- **调度是统一的大脑**：平台接收到事件后，需要决定是派人去修（生成工单发给移动端），还是直接给另外一台设备发指令关阀门（控制指令下发）。
- **执行方式隔离**：人的闭环在 `Ops领域`（抢单、拍照、核验）；设备的闭环在 `IoT领域`（发指令、等 ACK 报文）。
---
## 2. 核心数据流转链路
理解了三环模型后，以下是系统最核心的三条数据数据链路（Data Flow）。开发人员在写代码或联调时，必须清楚自己的接口位于哪条链路上。
### 链路 A：纯人工业务闭环 (The Ops Flow)
这是目前阶段最成熟的基本盘链路。
1. **发起**：Web 后台运营人员创建一个【保洁任务】，或者保安在移动端上报一个【异常工单】。
2. **分配**：后端根据配置的抢单规则或固定排班规则，将任务分配给特定的移动端账号。
3. **触达**：移动端通过轮询或消息推送收到任务。
4. **执行与完工**：现场人员到达位置（上传定位），完成工作（上传照片），并在移动端点击【完工】。
5. **归档**：数据流回后端，触发工单状态变更为【已完成】，可供数据看板进行绩效统计。
### 链路 B：纯设备数据闭环 (The IoT Flow)
这是下一阶段的建设重点。
1. **采集**：传感器设备通过 MQTT 协议将遥测数据（Telemetry）推送到网关。
2. **解析**：后端 `module-iot` 获取 payload，根据设备绑定的【物模型】解析出具体的属性值（如温度=25℃）。
3. **存储与判断**：数据落地到时序数据库或 MySQL 中，并经过【规则引擎】判断是否触发预设的告警规则。
4. **控制**：如果无需人工介入，Web 控制台或规则引擎可以直接向设备下发控制指令（如【打开风扇】），等待设备回复执行结果。
### 链路 C：设备与人工的交叉联动 (The Hybrid Flow)
这是本系统最终要达成的终极壁垒，即打破软硬件孤岛。
```mermaid
sequenceDiagram
participant Device as IoT设备
participant Rule as 规则引擎 (IoT)
participant Ticket as 工单系统 (Ops)
participant Worker as 移动端 (员工)
Device->>Rule: 1. 上报烟雾超标告警 (MQTT)
activate Rule
Rule->>Ticket: 2. 触发联动，调用内部接口生成紧急工单
deactivate Rule
activate Ticket
Ticket->>Worker: 3. 推送紧急【安保巡查工单】
deactivate Ticket
activate Worker
Worker->>Device: 4. 员工现场确认并可通过 App 强切设备电源
Worker->>Ticket: 5. 提交工单处理结果，拍照留存
deactivate Worker
```
---
## 3. 跨域业务边界准则
为了防止后期代码变成一团乱麻，业务边界必须死守以下红线：
1. **工单系统不关心具体是什么硬件**：`module-ops` 只能看到一个通用的“事件源 ID”和“故障描述”，它不需要去解析 MQTT 报文。解析的工作必须在 `module-iot` 内完成，转化成通用事件后再推给 Ops。
2. **设备系统不关心是谁在排班**：`module-iot` 触发告警后，只负责抛出“设备异常事件”，由 `module-ops` 决定这个事件是派给保洁张三还是安保李四。
3. **数据冗余的容忍度**：为了解耦，允许在工单表里冗余存储当时的设备名称和位置信息，而不是每次查询工单都去 join 设备表。
---
**更新时间**：2026-04-06