ether-docs/_archive/domains-old/REVERSE-OPS.md

运维工单域功能详细设计文档（代码反推版）

文档来源: 基于 module-wo 模块实际代码反推
生成日期: 2026-04-23
代码基线: ether-pms/module-wo, ether-admin
对照文档: 02-OPERATIONS.md（运营调度领域技术方案）

---

一、领域概述

1.1 领域职责

运维工单域（module-wo）负责管理物业运维全生命周期，涵盖：

• 综合工单管理：多来源工单的创建、分配、执行、完成、验收全流程
• 维保计划管理：设备周期性维保计划的制定与调度
• 维保任务管理：维保工单的触发、执行、验收闭环
• 巡检模板管理：设备点检模板与检查项的配置
• 工单明细管理：工单下的备件/巡检项/检查点明细
• 统计看板：工单与维保任务的多维度统计

1.2 核心概念

概念	说明	对应实体	数据库表
工单	综合业务单据，支持6种来源6种类型	WorkOrder	ops_work_order
工单明细	工单下的备件/巡检项/检查点	WorkOrderItem	ops_work_order_item
维保计划	设备周期性维保计划	MaintenancePlan	ops_maintenance_plan
维保任务	维保工单（设备维保执行单元）	MaintenanceTask	ops_maintenance_task
巡检模板	设备点检模板	InspectionTemplate	ops_inspection_template
巡检项	模板下的检查项	InspectionItem	ops_inspection_item

1.3 领域边界

实际实现中，运维工单域与原需求文档的边界存在显著差异：

• 原需求：运营调度域（ether-ops）包含工单 + 消息通知系统
• 实际实现：module-wo 仅包含工单/维保/巡检，消息通知系统未实现
• 前端分裂：维保计划存在两套前端 API（maintenance.ts vs maintenance-plan.ts），巡检标准项归属 MDM 域

---

二、数据结构设计

2.1 WorkOrder（工单）

表名: ops_work_order

字段	类型	必填	默认值	说明
id	UUID	是	自动生成	主键
workNo	VARCHAR(50)	是	自动生成	工单编号，格式: WO-YYYYMMDD-XXXX
source	ENUM	是	-	工单来源
type	ENUM	是	-	工单类型
priority	ENUM	否	MEDIUM	优先级
status	ENUM	否	PENDING	工单状态
title	VARCHAR(200)	是	-	工单标题
description	VARCHAR(2000)	否	-	工单描述
projectId	UUID	是	-	所属项目
equipmentId	UUID	否	-	关联设备
spaceId	UUID	否	-	关联空间
planId	UUID	否	-	关联维保计划
triggerType	ENUM	否	-	触发类型
assignedTo	VARCHAR(200)	否	-	负责人
assignedVendor	VARCHAR(200)	否	-	服务商
assignedDate	DATE	否	-	派单日期
actualStart	TIMESTAMP	否	-	实际开始时间
actualEnd	TIMESTAMP	否	-	实际结束时间
actualHours	DECIMAL(6,2)	否	-	实际工时（小时）
faultCause	VARCHAR(2000)	否	-	故障原因
solution	VARCHAR(5000)	否	-	解决方案
result	VARCHAR(2000)	否	-	处理结果
laborCost	DECIMAL(12,2)	否	-	人工费
partsCost	DECIMAL(12,2)	否	-	备件费
totalCost	DECIMAL(12,2)	否	-	总费用
completedBy	VARCHAR(200)	否	-	完成人
completedDate	DATE	否	-	完成日期
verifiedBy	VARCHAR(200)	否	-	验收人
verifiedDate	DATE	否	-	验收日期
rating	INTEGER	否	-	评分（1-5星）
remark	VARCHAR(1000)	否	-	备注
photos	JSONB	否	-	照片URL列表
signature	VARCHAR(2000)	否	-	签名
createdAt	TIMESTAMP	是	now()	创建时间
updatedAt	TIMESTAMP	是	now()	更新时间
createdBy	VARCHAR(200)	否	-	创建人

枚举定义：

枚举	值	中文
Source	OWNER	业主报修
	MAINTENANCE	维保计划
	INSPECTION	巡检触发
	FAULT	故障触发
	REGULATORY	法规巡检
	MANUAL	手动创建
Type	REPAIR	维修
	INSPECTION	巡检
	SECURITY	安保
	CLEANING	保洁
	PROPERTY	物业
	CONSULTATION	咨询
Priority	LOW / MEDIUM / HIGH / URGENT	低/中/高/紧急
Status	PENDING / ASSIGNED / IN_PROGRESS / COMPLETED / VERIFIED / CANCELLED	见状态机
TriggerType	PLAN / INSPECTION / FAULT / MANUAL	计划/巡检/故障/手动

索引：

索引名	字段	用途
idx_wo_project_status	project_id, status	项目+状态查询
idx_wo_priority_status	priority, status	优先级+状态查询
idx_wo_plan_createdat	plan_id, created_at	计划关联查询
idx_wo_status_createdat	status, created_at	状态+时间查询
idx_wo_createdat_desc	created_at DESC	时间倒序

2.2 WorkOrderItem（工单明细）

表名: ops_work_order_item

字段	类型	必填	默认值	说明
id	UUID	是	自动生成	主键
workOrderId	UUID	是	-	所属工单ID
itemType	ENUM	是	-	明细类型
itemName	VARCHAR(200)	是	-	明细名称
quantity	DECIMAL(10,2)	否	1	数量
unit	VARCHAR(50)	否	-	单位
unitPrice	DECIMAL(12,2)	否	-	单价
totalPrice	DECIMAL(12,2)	否	-	总价
isNormal	BOOLEAN	否	-	是否正常
observation	VARCHAR(2000)	否	-	观察记录
suggestion	VARCHAR(2000)	否	-	建议
sortOrder	INTEGER	否	0	排序序号
createdAt	TIMESTAMP	否	now()	创建时间

枚举定义：

枚举	值	中文
ItemType	PART	备件
	INSPECTION_ITEM	巡检项
	CHECKPOINT	检查点

2.3 MaintenanceTask（维保任务）

表名: ops_maintenance_task

字段	类型	必填	默认值	说明
id	UUID	是	自动生成	主键
taskNo	VARCHAR(50)	否	自动生成	任务编号，格式: EQ-YYYYMMDD-XXXX
planId	UUID	否	-	关联维保计划ID
equipmentId	UUID	是	-	关联设备ID
projectId	UUID	否	-	所属项目
taskType	ENUM	否	-	任务类型
triggerType	ENUM	否	-	触发类型
priority	ENUM	否	自动判定	优先级
status	ENUM	否	PENDING	任务状态
title	VARCHAR(200)	否	-	任务标题
description	VARCHAR(2000)	否	-	任务描述
assignedTo	VARCHAR(200)	否	-	负责人
assignedVendor	VARCHAR(200)	否	-	服务商
assignedDate	DATE	否	-	派单日期
actualStart	TIMESTAMP	否	-	实际开始时间
actualEnd	TIMESTAMP	否	-	实际结束时间
actualHours	DECIMAL(6,2)	否	-	实际工时
faultCause	VARCHAR(2000)	否	-	故障原因
solution	VARCHAR(5000)	否	-	解决方案
result	VARCHAR(2000)	否	-	处理结果
partsUsed	JSONB	否	-	使用备件列表
laborCost	DECIMAL(12,2)	否	-	人工费
partsCost	DECIMAL(12,2)	否	-	备件费
totalCost	DECIMAL(12,2)	否	-	总费用
completedBy	VARCHAR(200)	否	-	完成人
completedDate	DATE	否	-	完成日期
verifiedBy	VARCHAR(200)	否	-	验收人
verifiedDate	DATE	否	-	验收日期
rating	INTEGER	否	-	评分（1-5）
remark	VARCHAR(1000)	否	-	备注
photos	JSONB	否	-	照片URL列表
signature	VARCHAR(2000)	否	-	签名
createdAt	TIMESTAMP	否	now()	创建时间
updatedAt	TIMESTAMP	否	now()	更新时间
createdBy	VARCHAR(200)	否	-	创建人

枚举定义：

枚举	值	中文
TaskType	PREVENTIVE	预防性维护
	CORRECTIVE	纠正性维护
	EMERGENCY	紧急维修
TriggerType	PLAN	计划触发
	INSPECTION	巡检触发
	FAULT	故障触发
	MANUAL	手动创建
Priority	LOW / MEDIUM / HIGH / URGENT	低/中/高/紧急
Status	PENDING / ASSIGNED / IN_PROGRESS / COMPLETED / VERIFIED / CANCELLED	见状态机

partsUsed JSONB 结构：

[
  {
    "partsId": "uuid",
    "partsName": "备件名称",
    "quantity": 2,
    "unitPrice": 100.00,
    "totalPrice": 200.00
  }
]

索引：

索引名	字段	用途
idx_mt_equipment_status	equipment_id, status	设备+状态查询
idx_mt_project_status	project_id, status	项目+状态查询
idx_mt_plan_createdat	plan_id, created_at	计划关联查询
idx_mt_status_assigneddate	status, assigned_date	状态+派单日期查询

2.4 MaintenancePlan（维保计划）

表名: ops_maintenance_plan

字段	类型	必填	默认值	说明
id	UUID	是	自动生成	主键
planCode	VARCHAR(50)	是	自动生成	计划编码（唯一）
planName	VARCHAR(200)	是	-	计划名称
planContent	VARCHAR(5000)	否	-	计划内容
projectId	UUID	否	-	所属项目
equipmentId	UUID	是	-	关联设备
planType	ENUM	是	-	计划类型
cycleDays	INTEGER	否	-	周期天数
estimatedHours	DECIMAL(6,2)	否	-	预估工时
assignedVendor	VARCHAR(200)	否	-	指定服务商
status	ENUM	否	ACTIVE	计划状态
lastDate	DATE	否	-	上次执行日期
nextDate	DATE	否	-	下次执行日期
createdAt	TIMESTAMP	否	now()	创建时间
updatedAt	TIMESTAMP	否	now()	更新时间
createdBy	VARCHAR(200)	否	-	创建人

枚举定义：

枚举	值	中文
PlanType	PREVENTIVE	预防性维护
	CORRECTIVE	纠正性维护
PlanStatus	ACTIVE	启用
	INACTIVE	停用
	SUSPENDED	暂停

2.5 InspectionTemplate（巡检模板）

表名: ops_inspection_template

字段	类型	必填	默认值	说明
id	UUID	是	自动生成	主键
templateCode	VARCHAR(50)	是	自动生成	模板编码（唯一）
templateName	VARCHAR(200)	是	-	模板名称
description	VARCHAR(2000)	否	-	描述
projectId	UUID	否	-	所属项目
spaceId	UUID	否	-	关联空间
category	VARCHAR(50)	否	-	分类
status	ENUM	否	ACTIVE	模板状态
createdAt	TIMESTAMP	否	now()	创建时间
updatedAt	TIMESTAMP	否	now()	更新时间
createdBy	VARCHAR(200)	否	-	创建人
items	List<InspectionItem>	-	-	检查项列表（@Transient，非持久化）

枚举定义：

枚举	值	中文
TemplateStatus	ACTIVE	启用
	INACTIVE	停用

2.6 InspectionItem（巡检项）

表名: ops_inspection_item

字段	类型	必填	默认值	说明
id	UUID	是	自动生成	主键
templateId	UUID	是	-	所属模板ID
itemName	VARCHAR(200)	是	-	检查项名称
description	VARCHAR(2000)	否	-	描述
checkMethod	VARCHAR(2000)	否	-	检查方法
standard	VARCHAR(2000)	否	-	检查标准
isMandatory	BOOLEAN	否	true	是否必检
isNormalRequired	BOOLEAN	否	true	是否需要正常判定
sortOrder	INTEGER	否	0	排序序号
createdAt	TIMESTAMP	否	now()	创建时间

2.7 实体关系图

MaintenancePlan ──1:N──> MaintenanceTask
       │                      │
       │ planId               │ equipmentId
       ▼                      ▼
  WorkOrder ──1:N──> WorkOrderItem
       │
       │ (关联)
       ▼
InspectionTemplate ──1:N──> InspectionItem

关系说明：

• WorkOrder.planId → MaintenancePlan.id（工单可关联维保计划）
• WorkOrderItem.workOrderId → WorkOrder.id（工单明细属于工单）
• MaintenanceTask.planId → MaintenancePlan.id（维保任务由计划触发）
• InspectionItem.templateId → InspectionTemplate.id（检查项属于模板）
• WorkOrder 与 MaintenanceTask 为独立实体，无直接外键关联

---

三、API 接口设计

3.1 WorkOrderController

基础路径: /api/wo/work-orders

方法	路径	说明	请求体	响应
POST	/	创建工单	WorkOrder	WorkOrder
GET	/	查询工单列表	QueryParams	List<WorkOrder>
GET	/{id}	获取工单详情	-	WorkOrder
PUT	/{id}	更新工单	WorkOrder	WorkOrder
DELETE	/{id}	删除工单	-	Void
POST	/{id}/assign	派单	AssignRequest	WorkOrder
POST	/{id}/start	开始执行	-	WorkOrder
POST	/{id}/complete	完成工单	WorkOrder	WorkOrder
POST	/{id}/verify	验收工单	VerifyRequest	WorkOrder
POST	/{id}/cancel	取消工单	-	WorkOrder
GET	/stats	工单统计	-	WorkOrderStatsDTO
GET	/{id}/items	获取工单明细	-	List<WorkOrderItem>
POST	/{id}/items	批量添加工单明细	List<WorkOrderItem>	WorkOrder

查询参数（GET /）：

参数	类型	必填	说明
projectId	UUID	否	按项目筛选
equipmentId	UUID	否	按设备筛选
source	Enum	否	按来源筛选
type	Enum	否	按类型筛选
status	Enum	否	按状态筛选
assignedTo	String	否	按负责人筛选

注意：查询参数互斥，按优先级 projectId > equipmentId > source > type > status > assignedTo 依次判断

请求体定义：

// 派单请求
AssignRequest {
    String assignedTo;       // 负责人
    String assignedVendor;   // 服务商
    LocalDate assignedDate;  // 派单日期
}

// 验收请求
VerifyRequest {
    String verifiedBy;  // 验收人
    String remark;      // 备注
    Integer rating;     // 评分（1-5）
}

WorkOrderStatsDTO：

字段	类型	说明
total	long	工单总数
pending	long	待分配数
assigned	long	已派单数
inProgress	long	执行中数
completed	long	已完成数
verified	long	已验收数
cancelled	long	已取消数
completedToday	long	今日完成数
createdToday	long	今日创建数
overdue	long	逾期数
avgCompleteHours	BigDecimal	平均完成工时
avgRating	BigDecimal	平均评分
bySource	Map<String, Long>	按来源分布
byType	Map<String, Long>	按类型分布
byPriority	Map<String, Long>	按优先级分布

3.2 MaintenanceTaskController

基础路径: /api/ops/maintenance-tasks

方法	路径	说明	请求体	响应
POST	/	创建维保任务	MaintenanceTask	MaintenanceTask
GET	/	查询维保任务列表	QueryParams	List<MaintenanceTask>
GET	/{id}	获取任务详情	-	MaintenanceTask
PUT	/{id}	更新任务	MaintenanceTask	MaintenanceTask
DELETE	/{id}	删除任务	-	Void
POST	/{id}/assign	分配任务	AssignRequest	MaintenanceTask
POST	/{id}/start	开始执行	-	MaintenanceTask
POST	/{id}/complete	完成任务（简版）	CompleteRequest	MaintenanceTask
POST	/{id}/complete-details	完成任务（详版）	MaintenanceTask	MaintenanceTask
POST	/{id}/verify	验收任务	VerifyRequest	MaintenanceTask
POST	/{id}/cancel	取消任务	-	MaintenanceTask
POST	/{id}/rate	评分	rating (query)	MaintenanceTask
GET	/stats	任务统计	-	MaintenanceTaskStatsDTO

查询参数（GET /）：

参数	类型	必填	说明
equipmentId	UUID	否	按设备筛选
planId	UUID	否	按计划筛选
status	Enum	否	按状态筛选
priority	Enum	否	按优先级筛选
assignedTo	String	否	按负责人筛选
overdueDate	LocalDate	否	逾期截止日期

同样互斥优先级：equipmentId > planId > status > priority > assignedTo > overdueDate

请求体定义：

// 分配请求
AssignRequest {
    String assignedTo;       // 负责人
    LocalDate assignedDate;  // 派单日期
}

// 完成请求（简版）
CompleteRequest {
    String result;            // 处理结果
    BigDecimal actualHours;   // 实际工时
    BigDecimal cost;          // 总费用
    String completedBy;       // 完成人
}

// 验收请求
VerifyRequest {
    String verifiedBy;  // 验收人
    String remark;      // 备注
    Integer rating;     // 评分
}

MaintenanceTaskStatsDTO：

字段	类型	说明
total	long	任务总数
pending	long	待分配数
assigned	long	已派单数
inProgress	long	执行中数
completed	long	已完成数
verified	long	已验收数
cancelled	long	已取消数
completedToday	long	今日完成数
createdToday	long	今日创建数
overdue	long	逾期数
avgCompleteHours	BigDecimal	平均完成工时
avgRating	BigDecimal	平均评分
byPriority	Map<String, Long>	按优先级分布
byTriggerType	Map<String, Long>	按触发类型分布
totalLaborCost	BigDecimal	人工费总计
totalPartsCost	BigDecimal	备件费总计
totalCost	BigDecimal	费用总计

3.3 前端独立 API（无后端 Controller 对应）

以下前端 API 存在但后端无对应 Controller 实现：

前端文件	API 路径	说明
maintenance-plan.ts	/api/mdm/maintenance-plans	维保计划 CRUD（归属 MDM 域）
maintenance.ts	/api/ops/maintenance-plans	维保计划 CRUD（另一套，含 accept 操作）
maintenance.ts	/api/ops/maintenance-tasks	维保任务（含 accept 操作，状态含 ACCEPTED）
inspection-template.ts	/api/ops/inspection-templates	巡检模板 CRUD
inspection-item.ts	/api/mdm/inspection-items	巡检标准项 CRUD（归属 MDM 域）
inspection-record.ts	/api/mdm/inspection-records	巡检记录 CRUD（归属 MDM 域）

---

四、业务规则

4.1 工单状态机

┌─────────────┐
│   PENDING   │ ← 创建工单（默认状态）
│   (待分配)   │
└──────┬──────┘
       │ 派单 (assign)
       ▼
┌─────────────┐
│  ASSIGNED   │ ← 分配负责人/服务商
│   (已派单)   │
└──────┬──────┘
       │ 开始执行 (start)
       ▼
┌─────────────┐
│ IN_PROGRESS │ ← 记录实际开始时间
│   (执行中)   │
└──────┬──────┘
       │ 完成 (complete)
       ▼
┌─────────────┐
│  COMPLETED  │ ← 记录故障原因/解决方案/费用
│   (已完成)   │
└──────┬──────┘
       │ 验收 (verify)
       ▼
┌─────────────┐
│  VERIFIED   │ ← 记录验收人/评分/备注
│   (已验收)   │
└─────────────┘

特殊状态:
- CANCELLED (已取消): PENDING/ASSIGNED/IN_PROGRESS 可转入

状态流转规则：

当前状态	允许操作	下一状态	前置条件	自动处理
PENDING	派单	ASSIGNED	-	设置 assignedTo/assignedVendor/assignedDate
ASSIGNED	开始执行	IN_PROGRESS	-	设置 actualStart = now()
IN_PROGRESS	完成	COMPLETED	-	设置 actualEnd = now()，自动计算 actualHours
COMPLETED	验收	VERIFIED	-	设置 verifiedBy/verifiedDate/rating
PENDING/ASSIGNED/IN_PROGRESS	取消	CANCELLED	-	-
COMPLETED/VERIFIED	取消	❌ 不允许	-	抛出异常"无法取消已完成的工单"

工单编号生成规则：WO-YYYYMMDD-XXXX（4位序号，按日期递增）

完成工单自动计算工时：

actualHours = Duration.between(actualStart, actualEnd).toMinutes() / 60.0

4.2 维保任务状态机

┌─────────────┐
│   PENDING   │ ← 创建任务（默认状态）
│   (待分配)   │
└──────┬──────┘
       │ 分配 (assign)
       ▼
┌─────────────┐
│  ASSIGNED   │ ← 指定负责人
│   (已派单)   │
└──────┬──────┘
       │ 开始执行 (start)
       ▼
┌─────────────┐
│ IN_PROGRESS │ ← 记录实际开始时间
│   (执行中)   │
└──────┬──────┘
       │ 完成 (complete / complete-details)
       ▼
┌─────────────┐
│  COMPLETED  │ ← 记录执行详情/费用/备件
│   (已完成)   │
└──────┬──────┘
       │ 验收 (verify)
       ▼
┌─────────────┐
│  VERIFIED   │ ← 记录验收人/评分
│   (已验收)   │
└─────────────┘

特殊状态:
- CANCELLED (已取消): PENDING/ASSIGNED/IN_PROGRESS 可转入

与工单状态机的差异：

差异点	WorkOrder	MaintenanceTask
完成方式	仅一种 complete	两种：complete（简版）+ complete-details（详版）
评分方式	验收时评分	验收时评分 + 独立 rate 接口
取消条件	COMPLETED/VERIFIED 不可取消	同
删除行为	物理删除	逻辑删除（设为 CANCELLED）
完成后联动	无	自动更新设备维保记录（maintenanceVendor/nextInspectionDate）

任务编号生成规则：EQ-YYYYMMDD-XXXX（4位序号，按日期递增）

4.3 维保任务触发机制

触发类型	枚举值	说明	优先级自动判定规则
计划触发	PLAN	由维保计划周期性触发	MEDIUM
巡检触发	INSPECTION	巡检发现异常时触发	HIGH
故障触发	FAULT	设备故障时触发	HIGH（含紧急关键词时 URGENT）
手动创建	MANUAL	人工手动创建	MEDIUM

自动优先级判定规则（MaintenanceTaskServiceImpl.autoDeterminePriority）：

1. 紧急维修类型(EMERGENCY) → URGENT
2. 故障触发(FAULT) + 紧急关键词 → URGENT
   紧急关键词: 困人/漏水/停电/火灾/爆炸/漏电/冒烟/故障停机
3. 故障触发(FAULT) 无紧急关键词 → HIGH
4. 巡检触发(INSPECTION) → HIGH
5. 计划触发(PLAN) → MEDIUM
6. 其他 → MEDIUM

4.4 维保计划管理规则

规则	说明
计划状态	ACTIVE（启用）/ INACTIVE（停用）/ SUSPENDED（暂停）
删除行为	逻辑删除，将状态设为 INACTIVE
周期调度	通过 cycleDays 计算下次执行日期（nextDate）
计划类型	PREVENTIVE（预防性）/ CORRECTIVE（纠正性）

4.5 巡检模板管理规则

规则	说明
模板状态	ACTIVE（启用）/ INACTIVE（停用）
检查项关联	InspectionItem 通过 templateId 关联模板
必检项	isMandatory = true 的检查项不可跳过
正常判定	isNormalRequired = true 的检查项需要判定正常/异常
排序	通过 sortOrder 控制检查项顺序

4.6 工单明细管理规则

规则	说明
明细类型	PART（备件）/ INSPECTION_ITEM（巡检项）/ CHECKPOINT（检查点）
批量添加	支持批量添加，受 BatchOperationValidator 限制
费用计算	前端计算：totalPrice = quantity × unitPrice，partsCost = Σ totalPrice
总费用	totalCost = laborCost + partsCost

4.7 维保任务完成后联动

维保任务完成（completeTaskWithDetails）时自动更新设备信息：

1. 更新设备维保商: equipment.maintenanceVendor = task.assignedVendor
2. 更新下次巡检日期（仅预防性维护）:
   equipment.nextInspectionDate = now() + equipment.inspectionCycle
   默认周期: 30天
3. 异常容错: 更新设备失败不影响工单完成

---

五、前端操作流程

5.1 工单管理（WorkOrder.vue）

页面路径: /ops/work-order

操作流程：

1. 选择项目 → 加载工单列表
2. 筛选: 项目/来源/类型/状态/优先级/关键词
3. 查看统计卡片: 总工单/待分配/执行中/今日完成/逾期/平均评分
4. 工单操作:
   ├─ 新建工单 → 填写来源/类型/优先级/标题/描述/负责人/服务商
   ├─ 查看详情 → 抽屉展示: 基本信息/问题描述/派单信息/执行信息/工单项/费用/验收
   ├─ 编辑工单 → 修改基本信息
   ├─ 派单 → 指定负责人/服务商/派单日期（PENDING → ASSIGNED）
   ├─ 开始执行 → 确认弹窗（ASSIGNED → IN_PROGRESS）
   ├─ 完成工单 → 填写工时/故障原因/解决方案/结果/工单项/费用（IN_PROGRESS → COMPLETED）
   ├─ 验收工单 → 填写验收人/评分/备注（COMPLETED → VERIFIED）
   ├─ 取消工单 → 确认弹窗（PENDING/ASSIGNED/IN_PROGRESS → CANCELLED）
   └─ 删除工单 → 确认弹窗

完成工单时的工单项录入：

添加工单项:
  ├─ 选择类型: 备件/巡检项/检查点
  ├─ 输入名称
  ├─ 输入数量 + 单价 → 自动计算 totalPrice
  └─ 自动汇总: partsCost = Σ(各工单项totalPrice)
                 totalCost = laborCost + partsCost

前端状态颜色映射：

状态	颜色	优先级	颜色
PENDING	default (灰)	LOW	green
ASSIGNED	blue	MEDIUM	blue
IN_PROGRESS	orange	HIGH	orange
COMPLETED	green	URGENT	red
VERIFIED	cyan
CANCELLED	red

5.2 维保计划（PlanList.vue）

页面路径: /maintenance/plans

注意：此页面使用 maintenance.ts API（/api/ops/maintenance-plans），与后端 MaintenancePlan 实体对应的是 maintenance-plan.ts API（/api/mdm/maintenance-plans），存在两套前端实现

操作流程：

1. 选择项目 → 加载维保计划列表
2. 筛选: 项目/触发类型
3. 计划操作:
   ├─ 新建计划 → 填写名称/项目/触发类型/Cron表达式/描述/启用状态
   ├─ 编辑计划 → 修改计划信息
   └─ 停用计划 → 确认弹窗（逻辑删除）

前端触发类型（与后端不一致）：

前端枚举	中文	后端枚举	差异
MANUAL	手动	-	前端独有
SCHEDULED	定时	-	前端独有
AUTOMATIC	自动	-	前端独有
-	-	PLAN	后端独有
-	-	INSPECTION	后端独有
-	-	FAULT	后端独有
-	-	MANUAL	后端有但含义不同

5.3 维保任务（TaskList.vue）

页面路径: /maintenance/tasks

注意：此页面使用 maintenance.ts API，状态包含 ACCEPTED，与后端 MaintenanceTaskController 的6状态不一致

操作流程：

1. 选择项目 → 加载维保任务列表
2. 筛选: 项目/状态/负责人
3. 任务操作:
   ├─ 接受任务 → PENDING → ACCEPTED（前端独有状态）
   ├─ 开始任务 → ACCEPTED → IN_PROGRESS
   ├─ 完成任务 → 弹窗输入完成备注 → IN_PROGRESS → COMPLETED
   └─ 取消任务 → 确认弹窗

前端状态映射（与后端不一致）：

前端状态	中文	后端状态	差异
PENDING	待接受	PENDING (待分配)	含义不同
ACCEPTED	已接受	-	前端独有
IN_PROGRESS	进行中	IN_PROGRESS	一致
COMPLETED	已完成	COMPLETED	一致
CANCELLED	已取消	CANCELLED	一致
-	-	ASSIGNED	后端独有
-	-	VERIFIED	后端独有

5.4 点检模板管理（TemplateList.vue）

页面路径: /inspection/templates

操作流程：

1. 选择项目 → 加载模板列表
2. 模板操作:
   ├─ 新建模板 → 填写名称/设备类型/项目/启用状态 + 添加点检项目
   ├─ 编辑模板 → 修改模板信息 + 编辑点检项目
   ├─ 复制模板 → 创建副本（名称加"_副本"后缀）
   └─ 删除模板 → 确认弹窗

添加点检项目:
  ├─ 输入项目名称
  ├─ 输入检查方法
  ├─ 输入检查标准
  ├─ 设置是否必检
  └─ 添加到列表

前端设备类型选项（中文，与后端 category 字段不一致）：

电梯/消防设备/空调/给排水/配电/安防/其他

5.5 前端页面与 API 对照表

页面	前端文件	API 文件	后端 Controller	API 基础路径
工单管理	WorkOrder.vue	work-order.ts	WorkOrderController	/api/wo/work-orders
维保计划	PlanList.vue	maintenance.ts	❌ 无对应	/api/ops/maintenance-plans
维保任务	TaskList.vue	maintenance.ts	MaintenanceTaskController	/api/ops/maintenance-tasks
点检模板	TemplateList.vue	inspection-template.ts	❌ 无对应	/api/ops/inspection-templates

---

六、与原需求文档 02-OPERATIONS.md 的差异对比

6.1 状态机差异（核心差异）

对比项	需求文档	实际实现	差异分析
工单初始状态	CREATED（已创建）	PENDING（待分配）	实现简化，合并创建与待分配
接单状态	ACCEPTED（已接单）	❌ 不存在	实现中 ASSIGNED 直接进入 IN_PROGRESS，省略接单环节
关闭状态	CLOSED（已关闭）	❌ 不存在	实现用 VERIFIED（已验收）替代关闭
验收状态	❌ 不存在	VERIFIED（已验收）	实现新增，强调验收确认环节
挂起状态	SUSPENDED（已挂起）	❌ 不存在	实现未支持挂起/恢复
退回状态	RETURNED（已退回）	❌ 不存在	实现未支持退回重分配
取消状态	❌ 未提及	CANCELLED（已取消）	实现新增，支持工单取消

状态机对比图：

需求文档:  CREATED → ASSIGNED → ACCEPTED → IN_PROGRESS → COMPLETED → CLOSED
           + SUSPENDED（任意状态可挂起）
           + RETURNED（ASSIGNED 可退回）

实际实现:  PENDING → ASSIGNED → IN_PROGRESS → COMPLETED → VERIFIED
           + CANCELLED（PENDING/ASSIGNED/IN_PROGRESS 可取消）

6.2 实体差异

对比项	需求文档	实际实现	差异分析
WorkOrderFlow	有（工单流转记录）	❌ 不存在	实现未记录流转历史
NotificationChannel	有（通知渠道）	❌ 不存在	消息通知系统未实现
NotificationTemplate	有（消息模板）	❌ 不存在	消息通知系统未实现
NotificationRule	有（通知规则）	❌ 不存在	消息通知系统未实现
NotificationHistory	有（通知历史）	❌ 不存在	消息通知系统未实现
WorkOrderItem	❌ 不存在	有（工单明细）	实现新增，支持备件/巡检项/检查点
MaintenancePlan	❌ 不存在	有（维保计划）	实现新增，支持周期性维保调度
MaintenanceTask	❌ 不存在	有（维保任务）	实现新增，独立于 WorkOrder 的维保工单
InspectionTemplate	❌ 不存在	有（巡检模板）	实现新增，支持点检模板管理
InspectionItem	❌ 不存在	有（巡检项）	实现新增，模板下的检查项

6.3 字段差异（WorkOrder）

字段	需求文档	实际实现	差异分析
orderNo	WO2024021000001	workNo: WO-YYYYMMDD-XXXX	编号格式不同，实现用连字符分隔
orderType	REPAIR/COMPLAINT/CLEANING/SECURITY/OTHER	type: REPAIR/INSPECTION/SECURITY/CLEANING/PROPERTY/CONSULTATION	枚举值完全不同
source	APP/PHONE/INSPECTION/IOT/SYSTEM	OWNER/MAINTENANCE/INSPECTION/FAULT/REGULATORY/MANUAL	枚举值完全不同
reporterId/reporterName/reporterPhone/reporterAddress	有	❌ 不存在	实现无报修人信息
assigneeId/assigneeName	UUID引用	assignedTo: String	实现用字符串而非用户ID引用
acceptedAt/startedAt/completedAt/closedAt	有	actualStart/actualEnd/completedDate/verifiedDate	字段名和粒度不同
materialCost	有	partsCost	字段名不同
resultDescription	有	result + faultCause + solution	实现拆分为3个字段
satisfactionScore/satisfactionComment	有	rating + remark	实现简化，无评论字段
images/attachments	String	photos: JSONB (List<String>)	实现用JSONB数组
attributes	JSONB	❌ 不存在	实现无扩展属性
spaceNodeId	有	spaceId	字段名不同
planId/triggerType	❌ 不存在	有	实现新增，关联维保计划
assignedVendor	❌ 不存在	有	实现新增，支持服务商
laborCost/partsCost/totalCost	❌ 不存在	有	实现新增，费用明细
signature	❌ 不存在	有	实现新增，签名确认

6.4 API 差异

对比项	需求文档	实际实现	差异分析
API 版本	/api/v1/ops/work-orders	/api/wo/work-orders	路径不同，实现无版本号
分页查询	Page<WorkOrderVO>	List<WorkOrder>	实现无分页，全量返回
接单接口	POST /{id}/accept	❌ 不存在	无 ACCEPTED 状态
关闭接口	POST /{id}/close	❌ 不存在	用 verify 替代
挂起/恢复	POST /{id}/suspend, /{id}/resume	❌ 不存在	未实现
退回	❌ 不存在	❌ 不存在	需求有但实现无
流转记录	GET /{id}/flows	❌ 不存在	未实现 WorkOrderFlow
通知 API	完整的渠道/模板/规则/历史	❌ 不存在	消息通知系统未实现
统计 API	独立 Controller，多维度	GET /stats（嵌入工单 Controller）	实现简化
工单明细	❌ 不存在	GET/POST /{id}/items	实现新增
维保任务 API	❌ 不存在	完整的 CRUD + 状态流转	实现新增

6.5 业务规则差异

对比项	需求文档	实际实现	差异分析
工单编号格式	WO + yyyyMMdd + 5位序号	WO-YYYYMMDD-XXXX（4位）	格式不同
通知触发	工单状态变更自动触发通知	❌ 无通知	消息通知未实现
SLA 监控	提及但未实现	❌ 未实现	均未实现
智能派单	提及但未实现	❌ 未实现	均未实现
维保优先级自动判定	❌ 未提及	有（基于触发类型+关键词）	实现新增
设备联动更新	❌ 未提及	有（完成维保后更新设备记录）	实现新增
维保任务双完成接口	❌ 未提及	complete + complete-details	实现新增，简版/详版
删除策略	未明确	WorkOrder 物理删除，MaintenanceTask 逻辑删除	不一致

6.6 前端实现差异

对比项	需求文档	实际实现	差异分析
维保计划 API	单一	两套（maintenance.ts + maintenance-plan.ts）	前端分裂
维保计划触发类型	-	MANUAL/SCHEDULED/AUTOMATIC vs PLAN/INSPECTION/FAULT/MANUAL	前后端不一致
维保任务状态	-	前端含 ACCEPTED，后端含 ASSIGNED/VERIFIED	前后端不一致
巡检模板	❌ 未提及	有（inspection-template.ts + TemplateList.vue）	实现新增
巡检标准项	❌ 未提及	有（inspection-item.ts，归属 MDM 域）	实现新增
巡检记录	❌ 未提及	有（inspection-record.ts，归属 MDM 域）	实现新增

6.7 差异总结

类别	需求文档有/实现无	实现有/需求文档无	说明
状态	CREATED, ACCEPTED, CLOSED, SUSPENDED, RETURNED	VERIFIED, CANCELLED	状态机完全重构
实体	WorkOrderFlow, NotificationChannel/Template/Rule/History	WorkOrderItem, MaintenancePlan/Task, InspectionTemplate/Item	实体体系完全不同
功能	消息通知系统, 工单流转记录	维保计划/任务, 巡检模板, 工单明细	功能重心偏移
字段	报修人信息, 扩展属性	服务商, 费用明细, 签名, 触发类型	字段侧重不同

核心结论: 实际实现与需求文档是两套不同的设计方案。需求文档侧重"运营调度+消息通知"，实际实现侧重"运维工单+维保管理+巡检模板"。状态机从7状态简化为6状态，去掉了接单/挂起/退回环节，新增了验收/取消环节。消息通知系统完全未实现，但新增了维保计划/任务/巡检模板等需求文档未涵盖的功能。