# 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)
2. 阅读 [Part 2 系统架构](./02-系统架构.md)
3. 搭建环境（[Part 8](./08-开发指南.md)） |
| **Day 2** | **深入核心** | 1. 阅读 [Part 3 核心模块](./03-核心模块详解.md)（关注 Ops/IoT）
2. 阅读 [Part 7 接口文档](./07-接口文档.md) |
| **Day 3** | **动手实践** | 1. 运行项目
2. 阅读 [Part 5 数据设计](./05-数据存储设计.md)
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。