175 lines
6.2 KiB
Markdown
175 lines
6.2 KiB
Markdown
# Ops 业务运营模块架构文档
|
||
|
||
> **文档定位**：Ops 模块的深度架构设计与演进文档
|
||
> **维护策略**：按架构演进版本记录，保留历史设计决策（ADR）
|
||
> **最后更新**：2026-01-14
|
||
> **文档版本**：v2.1.0
|
||
|
||
---
|
||
|
||
## 📖 文档说明
|
||
|
||
### Ops 模块简介
|
||
|
||
**Ops（Operations）业务运营模块**是 AIoT Platform 的核心业务模块，承载万物梁行的四大业务线：
|
||
|
||
| 业务线 | 代码模块 | 业务范围 |
|
||
|--------|----------|----------|
|
||
| **保洁** | `environment-biz` | 排班、巡检、耗材、智能调度 |
|
||
| **安保** | `security-biz` | 巡更、报警、岗位管理 |
|
||
| **工程** | `facilities-biz` | 维保、巡检、备件管理 |
|
||
| **客服** | `service-biz` | 投诉、建议、满意度 |
|
||
|
||
**核心能力**：
|
||
- 工单引擎（基于状态机）
|
||
- 智能调度系统（自动派单、优先级队列）
|
||
- IoT 设备集成（工牌、信标、传感器）
|
||
- 绩效评价系统
|
||
|
||
### 文档结构
|
||
|
||
本文档分为 10 个部分，从架构总览到具体实现，全方位记录 Ops 模块的设计与演进。
|
||
|
||
```
|
||
Part 1: [架构总览](./part1-架构总览.md) - 业务背景、系统架构、核心概念
|
||
Part 2: [架构演进史](./part2-架构演进史.md) - 从阶段1到阶段3的演进历程
|
||
Part 3: [核心架构设计](./part3-核心架构设计.md) - 服务职责、分层设计、技术方案
|
||
Part 4: [关键技术方案](./part4-关键技术方案.md) - 状态机、队列、派单、事件驱动、P0打断
|
||
Part 5: [架构重构实践](./part5-架构重构实践.md) - 问题识别、重构方案、实施过程
|
||
Part 6: [性能与可靠性](./part6-性能与可靠性.md) - 优化、并发、可靠性保障
|
||
Part 7: [扩展性设计](./part7-扩展性设计.md) - 如何新增业务类型、扩展策略
|
||
Part 8: [测试指南](./part8-测试指南.md) - 单元测试、集成测试、性能测试
|
||
Part 9: [技术决策记录（ADR）](./part9-技术决策记录.md) - 记录重要技术决策
|
||
Part 10: [附录](./part10-附录.md) - 类图、时序图、术语表、变更日志
|
||
```
|
||
|
||
### 适用人群
|
||
|
||
- **Ops 模块开发者**：了解架构设计，参与功能开发
|
||
- **架构师**：理解设计决策，参与架构评审
|
||
- **技术负责人**：掌握技术债务，规划重构方向
|
||
- **新成员**：快速了解 Ops 模块的全貌
|
||
|
||
### 版本管理
|
||
|
||
| 版本 | 日期 | 主要内容 |
|
||
|------|------|----------|
|
||
| v1.0 | 2025-12 | 阶段2完成（工单引擎、状态机、事件溯源） |
|
||
| v2.0 | 2026-01 | 阶段3规划（智能调度系统） |
|
||
| v2.1 | 2026-01-06 | 架构重构方案（重新定义组件职责） |
|
||
|
||
---
|
||
|
||
## 🗂️ 快速导航
|
||
|
||
### 我想知道...
|
||
|
||
**业务相关**：
|
||
- [Ops 模块有哪些业务线？](./part1-架构总览.md#14-四大业务线)
|
||
- [保洁工单的完整流程是什么？](./part1-架构总览.md#13-核心业务流程)
|
||
- [如何处理紧急任务打断？](./part4-关键技术方案.md#45-p0-紧急任务打断)
|
||
|
||
**架构相关**：
|
||
- [Ops 模块的整体架构是什么？](./part1-架构总览.md#12-系统架构)
|
||
- [服务职责如何划分？](./part3-核心架构设计.md#31-服务职责划分)
|
||
- [为什么要重构 DispatchEngine？](./part5-架构重构实践.md#51-问题识别)
|
||
|
||
**技术实现**：
|
||
- [状态机如何实现？](./part4-关键技术方案.md#41-状态机实现详解)
|
||
- [Redis + MySQL 混合队列如何设计？](./part3-核心架构设计.md#33-redis--mysql-混合队列)
|
||
- [事件驱动架构如何实现？](./part4-关键技术方案.md#44-事件驱动架构)
|
||
|
||
**开发相关**：
|
||
- [如何新增一个业务类型？](./part7-扩展性设计.md#71-新增业务条线流程)
|
||
- [如何扩展派单策略？](./part7-扩展性设计.md#72-自定义派单策略)
|
||
- [如何编写单元测试？](./part8-测试指南.md#81-单元测试规范)
|
||
- [有哪些重大的技术决策？](./part9-技术决策记录.md)
|
||
- [如何查询术语定义？](./part10-附录.md#101-核心术语表)
|
||
|
||
---
|
||
|
||
## 📚 核心概念
|
||
|
||
### 工单（Work Order）
|
||
|
||
工单是 Ops 模块的核心业务对象，代表一个需要处理的任务。
|
||
|
||
**工单类型**：
|
||
- `CLEAN` - 保洁工单
|
||
- `REPAIR` - 维修工单
|
||
- `SECURITY` - 安保工单
|
||
- `SERVICE` - 客服工单
|
||
|
||
**工单状态**：
|
||
- `PENDING` - 待接单
|
||
- `ASSIGNED` - 已分配
|
||
- `ARRIVED` - 已到岗
|
||
- `PAUSED` - 已暂停
|
||
- `COMPLETED` - 已完成
|
||
- `CANCELLED` - 已取消
|
||
|
||
### 优先级（Priority）
|
||
|
||
**优先级等级**：
|
||
- `P0` - 紧急（可打断当前任务）
|
||
- `P1` - 重要（优先处理）
|
||
- `P2` - 普通（正常排队）
|
||
|
||
**关键特性**：
|
||
- P0 任务会打断保洁员当前正在执行的任务
|
||
- P0 任务完成后，自动恢复被中断的任务
|
||
|
||
### 队列（Queue）
|
||
|
||
每个保洁员/维修工都有一个优先级队列，存储待处理的任务。
|
||
|
||
**队列状态**：
|
||
- `WAITING` - 等待中
|
||
- `PROCESSING` - 处理中
|
||
- `PAUSED` - 暂停中
|
||
- `REMOVED` - 已移除
|
||
|
||
**技术实现**：Redis Sorted Set + MySQL 混合队列
|
||
|
||
### 派单引擎（Dispatch Engine）
|
||
|
||
根据策略自动推荐最合适的执行人员。
|
||
|
||
**派单策略**：
|
||
- 区域优先策略（就近分配）
|
||
- 负载均衡策略（考虑当前任务数）
|
||
- 技能匹配策略（维修工单需要相应技能）
|
||
|
||
### 状态机（State Machine）
|
||
|
||
管理工单的状态转换，保证状态一致性。
|
||
|
||
**核心能力**：
|
||
- 状态转换规则验证
|
||
- 事件记录（事件溯源）
|
||
- 监听器/事件处理器通知
|
||
|
||
---
|
||
|
||
## 🔗 相关文档
|
||
|
||
- [AIoT Platform 技术全景文档](../technical-overview/README.md)
|
||
- [部署指南](../deployment-guide.md)
|
||
- [工单调度系统技术实现汇报文档](../工单调度系统技术实现汇报文档.md)
|
||
- [阶段2实现总结](../phase2-implementation-summary.md)
|
||
|
||
---
|
||
|
||
## 📧 贡献指南
|
||
|
||
本文档是 Ops 模块的官方架构文档，欢迎团队成员贡献：
|
||
|
||
1. **新增内容**：在对应章节添加，更新目录和版本号
|
||
2. **修正错误**：标注修正位置和原因
|
||
3. **补充示例**：添加代码示例和图表
|
||
4. **记录决策**：使用 ADR 格式记录技术决策
|
||
|
||
---
|
||
|
||
**下一章**：[Part 1: 架构总览](./part1-架构总览.md)
|