# 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)