From abd15d842b4a0842175671f712489f7dc39abae5 Mon Sep 17 00:00:00 2001 From: lzh Date: Mon, 6 Apr 2026 22:47:42 +0800 Subject: [PATCH] =?UTF-8?q?docs(architecture):=20=E9=87=8D=E5=86=99?= =?UTF-8?q?=E6=80=BB=E4=BD=93=E6=8A=80=E6=9C=AF=E6=9E=B6=E6=9E=84=E5=9B=BE?= =?UTF-8?q?=EF=BC=8C=E6=96=B0=E5=A2=9E=E4=B8=9A=E5=8A=A1=E6=9E=B6=E6=9E=84?= =?UTF-8?q?=E4=B8=8E=E6=95=B0=E6=8D=AE=E6=B5=81=E8=BD=AC=E9=93=BE=E8=B7=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 开发者文档/01-业务与架构/01-总体架构设计.md | 300 +++++++----------- 开发者文档/01-业务与架构/01-架构设计说明.md | 8 - .../01-业务与架构/02-业务架构与数据流转.md | 109 +++++++ 3 files changed, 226 insertions(+), 191 deletions(-) delete mode 100644 开发者文档/01-业务与架构/01-架构设计说明.md create mode 100644 开发者文档/01-业务与架构/02-业务架构与数据流转.md diff --git a/开发者文档/01-业务与架构/01-总体架构设计.md b/开发者文档/01-业务与架构/01-总体架构设计.md index 01b9f6b..f46fecd 100644 --- a/开发者文档/01-业务与架构/01-总体架构设计.md +++ b/开发者文档/01-业务与架构/01-总体架构设计.md @@ -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 管理后台
(Vue3 + Vben)"] + MobileApp["移动端
(uni-app)"] + IoTDevice["IoT 设备
(MQTT/HTTP)"] + end + + %% 网关层 + subgraph GatewayLayer ["网关层 (API Gateway)"] + Gateway["viewsh-gateway
(Spring Cloud Gateway)"] + end + + %% 微服务层 + subgraph ServiceLayer ["后端微服务集群 (viewsh-server)"] + direction TB + subgraph BizModules ["业务领域模块"] + ModSystem["module-system
(系统管理)"] + ModOps["module-ops
(运维/工单)"] + ModIoT["module-iot
(设备/规则)"] + ModInfra["module-infra
(基础支撑)"] + end + Framework["viewsh-framework
(安全/缓存/工具组件)"] + BizModules --> Framework + end + + %% 数据层 + subgraph DataLayer ["数据与中间件层 (Data & Infra)"] + direction LR + MySQL[(MySQL 8.0)] + Redis[(Redis)] + Nacos[Nacos
注册配置中心] + 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` 类型。 \ No newline at end of file diff --git a/开发者文档/01-业务与架构/01-架构设计说明.md b/开发者文档/01-业务与架构/01-架构设计说明.md deleted file mode 100644 index c7f6f3d..0000000 --- a/开发者文档/01-业务与架构/01-架构设计说明.md +++ /dev/null @@ -1,8 +0,0 @@ -# 01-架构设计说明 - -## 目标与面向读者 -介绍系统整体的微服务架构、网络边界与技术选型，主要面向系统架构师与后端开发者。 - -## 核心内容占位 -- 待补充：系统物理架构图。 -- 待补充：`aiot-platform-cloud` 的微服务划分说明。 diff --git a/开发者文档/01-业务与架构/02-业务架构与数据流转.md b/开发者文档/01-业务与架构/02-业务架构与数据流转.md new file mode 100644 index 0000000..ff93815 --- /dev/null +++ b/开发者文档/01-业务与架构/02-业务架构与数据流转.md @@ -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["人工上报
(巡检异常/主动报修)"] + IoTEvent["设备感知
(阈值告警/离线预警)"] + end + + subgraph 调度环 ["调度环 (Brain)"] + direction TB + RuleEngine["规则引擎
(过滤/转化)"] + Dispatch["派单引擎
(抢单/派单/排班)"] + RuleEngine --> Dispatch + end + + subgraph 执行环 ["执行环 (Action)"] + direction TB + OpsTask["人工执行
(工单/保洁/安保)"] + IoTAction["设备控制
(反向指令下发)"] + 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 \ No newline at end of file