430 lines
15 KiB
Markdown
430 lines
15 KiB
Markdown
# Part 1: 架构总<E69E84><E680BB>
|
||
|
||
## 1.1 业务背景
|
||
|
||
### 1.1.1 物业管理行业现状
|
||
|
||
传统物业管理面临的核心挑战：
|
||
|
||
| 问题 | 具体表现 | 影响 |
|
||
|------|----------|------|
|
||
| **调度低效** | 依赖人工派单，电话沟通 | 响应慢，客户体验差 |
|
||
| **资源浪费** | 保洁员/维修工闲置或过载 | 人力成本高，效率低 |
|
||
| **信息滞后** | 无法实时掌握现场情况 | 问题发现晚，处理慢 |
|
||
| **质量不稳定** | 依赖人工经验，缺乏标准 | 服务质量参差不齐 |
|
||
| **数据孤岛** | 各业务系统独立 | 难以统筹决策，数据价值低 |
|
||
|
||
### 1.1.2 万物梁行的数字化目标
|
||
|
||
**短期目标**：
|
||
- 实<><E5AE9E>工单智能调度，提升响应速度
|
||
- 实时监控人员状态，优化资源分配
|
||
- 记录服务数据，支撑绩效评价
|
||
|
||
**中期目标**：
|
||
- 四大业务线一体化运营
|
||
- 数据驱动决策，优化运营策略
|
||
- 提升客户满意度，降低运营成本
|
||
|
||
**长期目标**：
|
||
- 打造行业领先的智能运营平台
|
||
- 输出数字化解决方案
|
||
- 支持规模化复制
|
||
|
||
---
|
||
|
||
## 1.2 系统架构
|
||
|
||
### 1.2.1 模块结构
|
||
|
||
```
|
||
viewsh-module-ops/
|
||
├── viewsh-module-ops-api/ # [契约层] DTO、Feign 接口
|
||
├── viewsh-module-ops-biz/ # [核心层] 工单引擎、公共逻辑
|
||
├── viewsh-module-environment-biz/ # [业务层] 保洁条线
|
||
├── viewsh-module-security-biz/ # [业务层] 安保条线
|
||
├── viewsh-module-facilities-biz/ # [业务层] 工程条线
|
||
├── viewsh-module-service-biz/ # [业务层] 客服条线
|
||
└── viewsh-module-ops-server/ # [宿主层] 微服务入口
|
||
```
|
||
|
||
### 1.2.2 分层架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 宿主层 (Server) │
|
||
│ Ops Server Application │
|
||
│ - REST API │
|
||
│ - 配置管理 │
|
||
└──────────────────────────┬──────────────────────────────────┘
|
||
│
|
||
┌─────────────────┼─────────────────┐
|
||
│ │ │
|
||
┌────────▼────────┐ ┌──────▼──────┐ ┌───────▼────────┐
|
||
│ 保洁业务层 │ │ 安保业务层 │ │ 工程业务层 │
|
||
│ (Environment) │ │ (Security) │ │(Facilities) │
|
||
│ - 排班 │ │ - 巡更 │ │ - 维保 │
|
||
│ - 巡检 │ │ - 报警 │ │ - 巡检 │
|
||
│ - 耗材 │ │ - 岗位 │ │ - 备件 │
|
||
└────────┬────────┘ └──────┬──────┘ └───────┬────────┘
|
||
│ │ │
|
||
└─────────────────┼─────────────────┘
|
||
│
|
||
┌─────────────────▼─────────────────┐
|
||
│ 核心业务层 (Ops Biz) │
|
||
│ - 工单引擎 │
|
||
│ - 状态机 │
|
||
│ - 队列管理 │
|
||
│ - 派单引擎 │
|
||
└─────────────────┬─────────────────┘
|
||
│
|
||
┌─────────────────▼─────────────────┐
|
||
│ 契约层 (Ops API) │
|
||
│ - DTO 定义 │
|
||
│ - 枚举定义 │
|
||
│ - 服务接口 │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
**设计原则**：
|
||
- **依赖倒置**：高层不依赖低层，都依赖抽象
|
||
- **单一职责**：每层专注自己的职责
|
||
- **开闭原则**：对扩展开放，对修改关闭
|
||
- **接口隔离**：业务线通过接口扩展核心引擎
|
||
|
||
### 1.2.3 技术栈
|
||
|
||
| 层次 | 技术选型 |
|
||
|------|----------|
|
||
| 应用框架 | Spring Boot 3.5.9 |
|
||
| ORM 框架 | MyBatis Plus 3.5+ |
|
||
| 数据库 | MySQL 8.0+ |
|
||
| 缓存 | Redis 6.x/7.x |
|
||
| 消息队列 | RocketMQ 5.x |
|
||
| 定时任务 | Spring @Scheduled / XXL-Job |
|
||
| 单元测试 | JUnit 5 + Mockito |
|
||
|
||
---
|
||
|
||
## 1.3 核心业务流程
|
||
|
||
### 1.3.1 保洁工单完整流程
|
||
|
||
```
|
||
┌──────────────┐
|
||
│ 系统定时任务 │ 每5分钟生成日常保洁工单
|
||
│ 或巡检员创建 │ 手动创建临时工单
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 智能派单引擎 │ 推荐最合适的保洁员
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 工单入队 │ 加入优先级队列
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 工牌语音播报 │ "2楼电梯厅有水渍"
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 保洁员接单 │ 确认接单，状态变更为 ARRIVED
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 到岗打卡 │ 自动记录位置和时间
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 作业进行中 │ 暂停：临时离开
|
||
│ │ 恢复：回来继续作业
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 完成工单 │ 上传照片，记录作业时长
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 自动派发 │ 自动派发下一个任务
|
||
│ 下一个任务 │ 或恢复被中断的任务
|
||
└──────────────┘
|
||
```
|
||
|
||
### 1.3.2 P0 紧急任务打断流程
|
||
|
||
```
|
||
┌──────────────┐
|
||
│ 巡检员创建P0 │ 2楼电梯厅有严重水渍，紧急处理！
|
||
│ 紧急工单 │
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 查找附近 │ 500米范围内
|
||
│ 保洁员 │ 状态为 IDLE 或 BUSY
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 目标保洁员 │ 张师傅（正在执行P2任务）
|
||
│ 当前状态 │ BUSY
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 打断当前任务 │ 暂停P2任务
|
||
│ │ - 工单状态：ARRIVED → PAUSED
|
||
│ │ - 队列状态：PROCESSING → PAUSED
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 紧急插队 │ P0任务加入队列首位
|
||
│ │ 立即派单
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 高分贝警报 │ 工牌最大音量 + 震动
|
||
│ + 语音播报 │ "紧急插队：2楼电梯厅"
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 张师傅接单 │ 立即处理P0任务
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 完成P0任务 │
|
||
└──────┬───────┘
|
||
│
|
||
▼
|
||
┌──────────────┐
|
||
│ 自动恢复 │ 恢复被中断的P2任务
|
||
│ P2任务 │ 工牌语音播报："恢复任务"
|
||
└──────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 1.4 四大业务线
|
||
|
||
### 1.4.1 保洁条线（环境管理）
|
||
|
||
**业务范围**：
|
||
- 日常保洁（定时生成工单）
|
||
- 临时保洁（巡检员手动创建）
|
||
- 排班管理（保洁员班次）
|
||
- 巡检管理（巡检计划、巡检记录）
|
||
- 耗材管理（消耗品、库存）
|
||
|
||
**核心功能**：
|
||
- ✅ 智能调度系统（自动派单、优先级队列、紧急插队）
|
||
- ✅ 保洁员状态管理（IDLE、BUSY、PAUSED、OFFLINE）
|
||
- ✅ 工牌语音播报（自动去重）
|
||
- ✅ 绩效统计（响应时间、作业时长、质量评分）
|
||
|
||
**技术<E68A80><E69CAF><EFBFBD>现**：
|
||
- 代码模块：`viewsh-module-environment-biz`
|
||
- 服务类：`CleanOrderService`、`CleanerStatusService`
|
||
- 派单策略：`CleanerAreaAssignStrategy`、`CleanerPriorityScheduleStrategy`
|
||
|
||
### 1.4.2 安保条线
|
||
|
||
**业务范围**：
|
||
- 巡更管理（路线规划、点位打卡）
|
||
- 报警管理（异常上报、报警联动）
|
||
- 岗位管理（岗位值守、交接班）
|
||
- 人员管理（保安档案、考勤）
|
||
|
||
**核心功能**：
|
||
- 巡更轨迹追踪（GPS + 信标）
|
||
- 异常报警联动（自动创建工单）
|
||
- 实时监控（巡更进度可视化）
|
||
|
||
**技术实现**：
|
||
- 代码模块：`viewsh-module-security-biz`
|
||
- 计划实现：2026 Q2
|
||
|
||
### 1.4.3 工程条线（设施管理）
|
||
|
||
**业务范围**：
|
||
- 维保管理（设备维保计划）
|
||
- 巡检管理（设备巡检）
|
||
- 备件管理（库存、领用）
|
||
- 故障维修（报修、派单、维修、验收）
|
||
|
||
**核心功能**：
|
||
- 设备档案管理
|
||
- 维保计划自动生成
|
||
- 备件库存预警
|
||
- 故障统计分析
|
||
|
||
**技术实现**：
|
||
- 代码模块：`viewsh-module-facilities-biz`
|
||
- 计划实现：2026 Q3
|
||
|
||
### 1.4.4 客服条线
|
||
|
||
**业务范围**：
|
||
- 投诉处理（客户投诉、分类、处理）
|
||
- 建议管理（客户建议、采纳）
|
||
- 满意度调查（服务评价、统计分析）
|
||
|
||
**核心功能**：
|
||
- 多渠道接入（小程序、电话、公众号）
|
||
- 智能分类（AI 分类）
|
||
- 满意度评价
|
||
- 服务数据分析
|
||
|
||
**技术实现**：
|
||
- 代码模块：`viewsh-module-service-biz`
|
||
- 计划实现：2026 Q4
|
||
|
||
---
|
||
|
||
## 1.5 核心概念
|
||
|
||
### 1.5.1 工单（Work Order）
|
||
|
||
工单是 Ops 模块的核心业务对象，代表一个需要处理的任务。
|
||
|
||
**工单类型（WorkOrderTypeEnum）**：
|
||
```java
|
||
CLEAN("CLEAN", "保洁") // 保洁工单
|
||
REPAIR("REPAIR", "维修") // 维修工单
|
||
SECURITY("SECURITY", "安保") // 安保工单
|
||
SERVICE("SERVICE", "客服") // 客服工单
|
||
```
|
||
|
||
**工单状态（WorkOrderStatusEnum）**：
|
||
```java
|
||
PENDING("待接单") // 工单已创建，等待分配
|
||
ASSIGNED("已分配") // 已分配给执行人
|
||
ARRIVED("已到岗") // 执行人已到岗
|
||
PAUSED("已暂停") // 任务暂停（临时离开或被P0打断）
|
||
COMPLETED("已完成") // 任务完成
|
||
CANCELLED("已取消") // 工单取消
|
||
```
|
||
|
||
**工单优先级（PriorityEnum）**：
|
||
```java
|
||
P0("P0", "紧急") // 可打断当前任务，立即处理
|
||
P1("P1", "重要") // 优先处理
|
||
P2("P2", "普通") // 正常排队
|
||
```
|
||
|
||
### 1.5.2 保洁员状态（CleanerStatus）
|
||
|
||
**状态定义（CleanerStatusEnum）**：
|
||
```java
|
||
IDLE("空闲") // 可接新单
|
||
BUSY("忙碌") // 正在执行工单
|
||
PAUSED("暂停") // 临时离开
|
||
OFFLINE("离线") // 工牌离线
|
||
```
|
||
|
||
**状态转换规则**：
|
||
```
|
||
OFFLINE → IDLE: 工牌上线，心跳恢复
|
||
IDLE → BUSY: 接单成功
|
||
BUSY → PAUSED: 任务暂停（手动或被P0打断）
|
||
PAUSED → BUSY: 任务恢复
|
||
BUSY → IDLE: 完成所有任务
|
||
IDLE/OFFLINE: 工牌离线超时（30分钟无心跳）
|
||
```
|
||
|
||
### 1.5.3 队列状态（OrderQueueStatus）
|
||
|
||
**状态定义（OrderQueueStatusEnum）**：
|
||
```java
|
||
WAITING("等待中") // 工单已进入队列，等待派单
|
||
PROCESSING("处理中") // 任务已下发，正在处理
|
||
PAUSED("暂停中") // 任务被暂停
|
||
REMOVED("已移除") // 任务已完成或已取消
|
||
```
|
||
|
||
### 1.5.4 服务职责划分
|
||
|
||
**DispatchEngine（派单引擎）**：
|
||
- 职责：根据策略推荐最合适的执行人员
|
||
- 不负责：状态管理、设备通知、业务逻辑
|
||
|
||
**OrderLifecycleManager（生命周期管理器）**：
|
||
- 职责：统一管理工单状态和队列状态的同步变更
|
||
- 核心方法：`pauseOrder()`, `resumeOrder()`, `interruptOrder()`
|
||
|
||
**OrderStateMachine（状态机）**：
|
||
- 职责：验证状态转换规则、记录事件
|
||
- 不触发：任何业务逻辑
|
||
|
||
**OrderEventPublisher（事件发布器）**：
|
||
- 职责：发布工单状态变更事件
|
||
- 实现业务解耦
|
||
|
||
---
|
||
|
||
## 1.6 当前实施状态
|
||
|
||
### 已完成 ✅
|
||
|
||
**阶段1：基础数据层**（2025.12）
|
||
- ✅ 枚举类（10个）
|
||
- ✅ DO 实体类（10个）
|
||
- ✅ Mapper 接口（10个）
|
||
- ✅ 数据库表结构
|
||
|
||
**阶段2：工单引擎**（2026.01）
|
||
- ✅ 状态机实现
|
||
- ✅ 事件溯源机制
|
||
- ✅ 监听器模式
|
||
- ✅ 工单 CRUD
|
||
- ✅ 工单暂停/恢复
|
||
- ✅ REST API（11个）
|
||
- ✅ 单元测试（26个）
|
||
|
||
**阶段3：智能调度（部分）**
|
||
- ✅ 队列状态管理
|
||
- ✅ 派单引擎实现
|
||
- ✅ P0 紧急任务打断
|
||
- ✅ 保洁员状态管理
|
||
|
||
**架构重构**（2026.01.06）
|
||
- ✅ 重新定义组件职责
|
||
- ✅ 引入 OrderLifecycleManager
|
||
- ✅ 创建 OrderEventPublisher
|
||
- ✅ 事件处理器替代监听器
|
||
|
||
### 进行中 ⏳
|
||
|
||
**阶段3：智能调度（剩余工作）**
|
||
- ⏳ 工牌通知服务集成
|
||
- ⏳ 消息队列集成（MQ）
|
||
- ⏳ 定时任务（自动生成工单、绩效计算）
|
||
|
||
### 待实施 📋
|
||
|
||
**阶段4：绩效评价系统**
|
||
- ⏳ 响应时间统计
|
||
- ⏳ 质量评分
|
||
- ⏳ 绩效计算
|
||
|
||
**阶段5：其他业务线**
|
||
- ⏳ 安保条线（2026 Q2）
|
||
- ⏳ 工程条线（2026 Q3）
|
||
- ⏳ 客服条线（2026 Q4）
|
||
|
||
---
|
||
|
||
**下一章**：[Part 2: 架构演进史](./part2-架构演进史.md)
|