# 运营调度领域技术方案

**领域编号**: 4.2  
**微服务**: ether-ops  
**最后更新**: 2026-04-26

> **更新记录**:
> - 2026-04-26: 反向同步实际代码实现到文档。主要变更：工单状态机更新为PENDING→ASSIGNED→IN_PROGRESS→COMPLETED→VERIFIED/CANCELLED（标注TODO: 增加SUSPENDED/RETURNED）；工单类型枚举更新（REPAIR/INSPECTION/SECURITY/CLEANING/PROPERTY/CONSULTATION）；工单来源枚举更新（OWNER/MAINTENANCE/INSPECTION/FAULT/REGULATORY/MANUAL）；新增实体（WorkOrderItem/MaintenancePlan/MaintenanceTask/InspectionTemplate/InspectionItem）；新增字段（planId/triggerType/assignedVendor/laborCost/partsCost/totalCost/signature）；字段拆分（resultDescription→result+faultCause+solution）；新增业务规则（优先级自动判定/设备联动更新/维保任务双完成接口）；API路径从/api/v1/ops改为/api/wo；标注TODO: 工单列表需改为分页查询。

---

## 一、领域概述

### 1.1 领域职责

运营调度领域是 Ether 平台的核心业务领域，负责管理：
- 综合工单管理（创建、分配、处理、关闭）
- 工单流转记录与状态机
- 消息通知系统（模板、规则、渠道）
- 工单统计与分析

### 1.2 核心概念

| 概念 | 说明 | 对应实体 |
|------|------|----------|
| **工单** | 综合业务单据，支持多种类型 | WorkOrder |
| **工单明细** | 工单下的处理项目清单 | WorkOrderItem |
| **工单流转** | 工单状态变更记录 | WorkOrderFlow |
| **维保计划** | 定期保养计划 | MaintenancePlan |
| **维保任务** | 维保执行工单 | MaintenanceTask |
| **巡检模板** | 巡检检查项模板 | InspectionTemplate |
| **巡检项目** | 巡检模板中的检查项 | InspectionItem |
| **通知渠道** | 消息发送通道 | NotificationChannel |
| **通知模板** | 消息内容模板 | NotificationTemplate |
| **通知规则** | 触发条件和发送策略 | NotificationRule |
| **通知历史** | 已发送消息记录 | NotificationHistory |

---

## 二、领域模型

### 2.1 聚合根设计

#### WorkOrder（综合工单）

```java
@Entity
@Table(name = "ops_work_order")
@Data
public class WorkOrder {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String orderNo;        // 工单编号: WO2024021000001
    
    // 工单类型
    private WorkOrderType orderType; // REPAIR/INSPECTION/SECURITY/CLEANING/PROPERTY/CONSULTATION
    private WorkOrderStatus status;  // 状态机
    private WorkOrderPriority priority; // URGENT/HIGH/MEDIUM/LOW
    private WorkOrderSource source;   // OWNER/MAINTENANCE/INSPECTION/FAULT/REGULATORY/MANUAL
    
    // 基本信息
    private String title;
    private String description;
    
    // 报修人信息
    private UUID reporterId;
    private String reporterName;
    private String reporterPhone;
    private String reporterAddress;
    
    // 关联信息
    private UUID spaceNodeId;      // 关联空间
    private UUID equipmentId;      // 关联设备
    
    // 维保关联（新增）
    private UUID planId;           // 关联维保计划ID
    private String triggerType;    // 触发类型: MANUAL/AUTO/SCHEDULED
    
    // 处理人信息
    private UUID assigneeId;
    private String assigneeName;
    private UUID assignedVendor;   // 指派供应商ID（新增）
    private LocalDateTime assignedAt;
    private LocalDateTime acceptedAt;
    private LocalDateTime startedAt;
    private LocalDateTime completedAt;
    private LocalDateTime closedAt;
    
    // 费用（拆分细化）
    private BigDecimal laborCost;  // 人工费（新增）
    private BigDecimal partsCost;  // 材料费（新增）
    private BigDecimal totalCost;  // 总费用（新增，替代原actualCost）
    
    // 结果（拆分：原resultDescription → result + faultCause + solution）
    private String result;         // 处理结果
    private String faultCause;     // 故障原因
    private String solution;       // 解决方案
    private Integer satisfactionScore;
    private String satisfactionComment;
    
    // 签名确认（新增）
    private String signature;      // 签名图片URL
    
    // 附件
    private String images;
    private String attachments;
    
    // 扩展属性
    private String attributes;
    
    // 审计字段
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
    private UUID createdBy;
}
```

**工单类型枚举（更新）**:

```java
public enum WorkOrderType {
    REPAIR("报修"),
    INSPECTION("巡检"),
    SECURITY("安全"),
    CLEANING("保洁"),
    PROPERTY("物业"),
    CONSULTATION("咨询");
}
```

**工单来源枚举（更新）**:

```java
public enum WorkOrderSource {
    OWNER("业主报修"),
    MAINTENANCE("维保触发"),
    INSPECTION("巡检发现"),
    FAULT("设备故障"),
    REGULATORY("监管要求"),
    MANUAL("手动创建");
}
```

**业务规则**:
- orderNo 自动生成，格式: WO + yyyyMMdd + 5位序号
- 状态流转必须通过合法的业务操作
- 关闭工单时必须填写处理结果
- **优先级自动判定**（新增）：根据工单类型和来源自动设置优先级（如安全类默认HIGH，设备故障默认HIGH）
- **设备联动更新**（新增）：工单完成时自动更新关联设备状态

#### WorkOrderFlow（工单流转记录）

```java
@Entity
@Table(name = "ops_work_order_flow")
@Data
public class WorkOrderFlow {
    @Id
    private UUID id;
    private UUID workOrderId;
    
    // 流转信息
    private WorkOrderStatus fromStatus;
    private WorkOrderStatus toStatus;
    private String action;         // 操作: ASSIGN/START/COMPLETE/VERIFY/CANCEL
    
    // 操作人
    private UUID operatorId;
    private String operatorName;
    private LocalDateTime operateTime;
    
    // 备注
    private String remark;
    
    // 附件
    private String images;
}
```

#### WorkOrderItem（工单明细，新增）

```java
@Entity
@Table(name = "ops_work_order_item")
@Data
public class WorkOrderItem {
    @Id
    private UUID id;
    private UUID workOrderId;
    private UUID projectId;
    
    private String itemName;       // 明细名称
    private String itemType;       // 明细类型
    private String description;    // 明细描述
    private Integer quantity;      // 数量
    private BigDecimal unitPrice;  // 单价
    private BigDecimal amount;     // 金额
    private String remark;         // 备注
    
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}
```

#### MaintenancePlan（维保计划，新增）

```java
@Entity
@Table(name = "ops_maintenance_plan")
@Data
public class MaintenancePlan {
    @Id
    private UUID id;
    private UUID projectId;
    private UUID equipmentId;
    
    private String name;
    private MaintenanceType type;  // DAILY/WEEKLY/MONTHLY/QUARTERLY/YEARLY
    private Integer cycleDays;
    private String cronExpression;
    private String content;
    private String checkItems;     // JSON
    
    private UUID maintainerId;
    private String maintainerName;
    private Integer remindDays;
    private Boolean enabled;
    
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}
```

#### MaintenanceTask（维保任务，新增）

```java
@Entity
@Table(name = "ops_maintenance_task")
@Data
public class MaintenanceTask {
    @Id
    private UUID id;
    private UUID projectId;
    private UUID equipmentId;
    private UUID planId;
    
    private String taskCode;
    private MaintenanceTaskStatus status; // PENDING/IN_PROGRESS/COMPLETED/CANCELLED
    private LocalDate maintenanceDate;
    private MaintenanceType type;
    private String content;
    
    private UUID maintainerId;
    private String maintainerName;
    private MaintenanceResult result;
    private String remark;
    private String images;
    private String checkResults;   // JSON
    
    private BigDecimal laborCost;
    private BigDecimal partsCost;
    private BigDecimal totalCost;
    private String signature;
    
    private LocalDate nextMaintenanceDate;
    
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}

public enum MaintenanceTaskStatus {
    PENDING, IN_PROGRESS, COMPLETED, CANCELLED;
}
```

> **维保任务双完成接口**（新增业务规则）: 维保任务提供两个完成接口：
> 1. `POST /api/wo/maintenance-tasks/{id}/complete` - 维保人员完成
> 2. `POST /api/wo/maintenance-tasks/{id}/verify` - 主管验证确认

#### InspectionTemplate（巡检模板，新增）

```java
@Entity
@Table(name = "ops_inspection_template")
@Data
public class InspectionTemplate {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String name;
    private String description;
    private String category;       // 模板分类
    private Boolean enabled;
    
    @OneToMany(mappedBy = "templateId", fetch = FetchType.LAZY)
    private List<InspectionItem> items;
    
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}
```

#### InspectionItem（巡检项目，新增）

```java
@Entity
@Table(name = "ops_inspection_item")
@Data
public class InspectionItem {
    @Id
    private UUID id;
    private UUID templateId;
    
    private String itemName;       // 检查项名称
    private String checkStandard;  // 检查标准
    private String checkMethod;    // 检查方法
    private Integer sortOrder;     // 排序
    private Boolean required;      // 是否必检
    
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}
```

### 2.2 状态机设计

```
┌─────────────┐
│   PENDING   │ ← 创建工单
│   (待处理)   │
└──────┬──────┘
       │ 分配
       ▼
┌─────────────┐
│  ASSIGNED   │ ← 分配给处理人
│   (已分配)   │
└──────┬──────┘
       │ 开始处理
       ▼
┌─────────────┐
│ IN_PROGRESS │ ← 开始处理
│   (处理中)   │
└──────┬──────┘
       │ 完成
       ▼
┌─────────────┐
│  COMPLETED  │ ← 处理完成
│   (已完成)   │
└──────┬──────┘
       │ 验证
       ▼
┌─────────────┐
│   VERIFIED  │ ← 验证通过
│   (已验证)   │
└─────────────┘

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

> **TODO**: 当前状态机缺少 SUSPENDED(已挂起) 和 RETURNED(已退回) 状态，需后续补充：
> - SUSPENDED: 任意状态可转入，可恢复到原状态
> - RETURNED: ASSIGNED状态可转入，需重新分配

**状态流转规则**:

| 当前状态 | 允许操作 | 下一状态 | 权限 |
|---------|---------|---------|------|
| PENDING | 分配 | ASSIGNED | 管理员/调度员 |
| ASSIGNED | 开始 | IN_PROGRESS | 被指派人 |
| IN_PROGRESS | 完成 | COMPLETED | 被指派人 |
| COMPLETED | 验证 | VERIFIED | 管理员/创建人 |
| PENDING/ASSIGNED | 取消 | CANCELLED | 管理员 |

---

## 三、消息通知系统

### 3.1 聚合根设计

#### NotificationChannel（通知渠道）

```java
@Entity
@Table(name = "ops_notification_channel")
@Data
public class NotificationChannel {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String name;
    private ChannelType type;      // SITE_MESSAGE/SMS/EMAIL/PUSH/WECHAT_WORK
    
    // 配置(JSONB)
    private String config;         // 渠道配置参数
    // SITE_MESSAGE: {}
    // SMS: {provider, apiKey, apiSecret, templateCode}
    // EMAIL: {host, port, username, password}
    // PUSH: {appKey, appSecret}
    // WECHAT_WORK: {corpId, agentId, secret}
    
    private Boolean enabled;
    private Integer priority;      // 优先级，数字越小优先级越高
    private Integer dailyLimit;    // 日发送限制
    private Integer sentToday;     // 今日已发送
    
    // 审计字段
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}
```

#### NotificationTemplate（消息模板）

```java
@Entity
@Table(name = "ops_notification_template")
@Data
public class NotificationTemplate {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String name;
    private String code;           // 模板编码，唯一
    
    // 模板内容
    private String titleTemplate;
    private String contentTemplate;
    
    // 变量定义
    private String variables;      // ["orderNo", "title", "assigneeName"]
    
    // 适用渠道
    private String channels;       // ["SITE_MESSAGE", "SMS"]
    
    // 示例
    private String example;        // 渲染后的示例
    
    // 审计字段
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}

// 模板示例:
// titleTemplate: "新工单通知: {{title}}"
// contentTemplate: "您有一个新的{{orderType}}工单待处理，工单号: {{orderNo}}，请尽快处理。"
```

#### NotificationRule（通知规则）

```java
@Entity
@Table(name = "ops_notification_rule")
@Data
public class NotificationRule {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String name;
    private String eventType;      // 事件类型: WORK_ORDER_CREATED/ASSIGNED/COMPLETED
    
    // 触发条件(JSONB)
    private String conditions;     // {"orderType": "REPAIR", "priority": "HIGH"}
    
    // 延迟发送
    private Integer delayMinutes;  // 延迟分钟数，0为立即发送
    
    // 通知配置
    private String templateCode;   // 关联模板
    private String receivers;      // 接收人: ["CREATOR", "ASSIGNEE", "MANAGER"]
    private String channels;       // 通知渠道优先级: ["SITE_MESSAGE", "SMS"]
    
    // 免打扰
    private String quietHours;     // 免打扰时段: "22:00-08:00"
    private Boolean enabled;
    
    // 审计字段
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}
```

#### NotificationHistory（通知历史）

```java
@Entity
@Table(name = "ops_notification_history")
@Data
public class NotificationHistory {
    @Id
    private UUID id;
    private UUID projectId;
    
    // 通知内容
    private String title;
    private String content;
    private String eventType;
    
    // 接收人
    private UUID receiverId;
    private String receiverName;
    private String receiverPhone;
    private String receiverEmail;
    
    // 渠道信息
    private ChannelType channel;
    private String channelMsgId;   // 渠道消息ID
    
    // 状态
    private NotificationStatus status; // PENDING/SENT/FAILED/READ
    private String failReason;     // 失败原因
    
    private LocalDateTime sendTime;
    private LocalDateTime readTime;
    
    // 关联业务
    private String businessType;   // WORK_ORDER/INSPECTION/FEE
    private String businessId;
    
    // 审计字段
    private LocalDateTime createdAt;
}
```

### 3.2 通知事件类型

| 事件类型 | 触发时机 | 默认接收人 | 默认渠道 |
|---------|---------|-----------|---------|
| WORK_ORDER_CREATED | 工单创建 | 创建人 | 站内信 |
| WORK_ORDER_ASSIGNED | 工单分配 | 处理人 | 站内信+推送 |
| WORK_ORDER_ACCEPTED | 工单接单 | 创建人 | 站内信 |
| WORK_ORDER_COMPLETED | 工单完成 | 创建人 | 站内信+推送 |
| WORK_ORDER_CLOSED | 工单关闭 | - | - |
| INSPECTION_TODAY | 当天巡检提醒 | 巡检人 | 站内信+推送 |
| INSPECTION_OVERDUE | 巡检逾期 | 巡检人+管理员 | 站内信+短信 |
| FEE_UPCOMING_DUE | 费用即将到期 | 业主 | 站内信+推送 |
| FEE_OVERDUE | 费用逾期 | 业主 | 站内信+短信 |

### 3.3 通知流程

```
1. 业务事件触发
   ↓
2. 查询匹配的通知规则
   ↓
3. 渲染消息模板
   ↓
4. 确定接收人列表
   ↓
5. 选择通知渠道
   ↓
6. 检查免打扰设置
   ↓
7. 发送消息
   ↓
8. 记录发送历史
   ↓
9. 更新站内信未读数
```

---

## 四、工单统计

### 4.1 统计维度

```java
// 工单统计服务
@Service
public class WorkOrderStatisticsService {

    // 概览统计
    public WorkOrderOverviewVO getOverview(UUID projectId, LocalDate startDate, LocalDate endDate) {
        // 工单总数
        // 待处理数
        // 今日新增
        // 今日完成
        // 平均处理时长
        // 满意度评分
    }

    // 趋势统计
    public List<TrendVO> getTrend(UUID projectId, StatisticsType type, LocalDate startDate, LocalDate endDate) {
        // 按日/周/月统计工单量
        // 创建趋势
        // 完成趋势
    }

    // 类型分布
    public List<DistributionVO> getTypeDistribution(UUID projectId, LocalDate startDate, LocalDate endDate) {
        // 按工单类型统计
    }

    // 处理人排行
    public List<RankingVO> getAssigneeRanking(UUID projectId, LocalDate startDate, LocalDate endDate) {
        // 处理人工作量排行
        // 处理人满意度排行
    }

    // 超时分析
    public List<OvertimeVO> getOvertimeAnalysis(UUID projectId, LocalDate startDate, LocalDate endDate) {
        // 超时工单列表
        // 超时原因分析
    }
}
```

### 4.2 统计指标

| 指标 | 说明 | 计算方式 |
|------|------|---------|
| 工单总数 | 指定时间范围内的工单总数 | COUNT(*) |
| 待处理数 | 状态为CREATED/ASSIGNED/ACCEPTED/IN_PROGRESS的工单数 | COUNT(*) WHERE status IN (...) |
| 今日新增 | 今日创建的工单数 | COUNT(*) WHERE created_at >= today |
| 今日完成 | 今日完成的工单数 | COUNT(*) WHERE completed_at >= today |
| 平均处理时长 | 从创建到完成的平均时间 | AVG(completed_at - created_at) |
| 按时完成率 | 在SLA时间内完成的工单比例 | COUNT(on_time) / COUNT(completed) |
| 满意度评分 | 业主评价的平均分 | AVG(satisfaction_score) |

---

## 五、API 接口

### 5.1 WorkOrder API

> **注意**: API路径已从 `/api/v1/ops` 改为 `/api/wo`。

```java
@RestController
@RequestMapping("/api/wo/work-orders")
@Tag(name = "工单管理")
public class WorkOrderController {

    @PostMapping
    @Operation(summary = "创建工单")
    public Result<WorkOrderVO> create(@RequestBody @Valid WorkOrderCreateRequest request);

    @GetMapping("/{id}")
    @Operation(summary = "获取工单详情")
    public Result<WorkOrderVO> getById(@PathVariable UUID id);

    @GetMapping
    @Operation(summary = "查询工单列表")
    public Result<List<WorkOrderVO>> list(WorkOrderQueryRequest request);

    @PutMapping("/{id}")
    @Operation(summary = "更新工单")
    public Result<WorkOrderVO> update(@PathVariable UUID id, 
                                       @RequestBody @Valid WorkOrderUpdateRequest request);

    @DeleteMapping("/{id}")
    @Operation(summary = "删除工单")
    public Result<Void> delete(@PathVariable UUID id);

    // 业务操作
    @PostMapping("/{id}/assign")
    @Operation(summary = "分配工单")
    public Result<WorkOrderVO> assign(@PathVariable UUID id,
                                       @RequestBody @Valid WorkOrderAssignRequest request);

    @PostMapping("/{id}/start")
    @Operation(summary = "开始处理")
    public Result<WorkOrderVO> start(@PathVariable UUID id);

    @PostMapping("/{id}/complete")
    @Operation(summary = "完成工单")
    public Result<WorkOrderVO> complete(@PathVariable UUID id,
                                         @RequestBody @Valid WorkOrderCompleteRequest request);

    @PostMapping("/{id}/verify")
    @Operation(summary = "验证工单")
    public Result<WorkOrderVO> verify(@PathVariable UUID id,
                                       @RequestBody @Valid WorkOrderVerifyRequest request);

    @PostMapping("/{id}/cancel")
    @Operation(summary = "取消工单")
    public Result<WorkOrderVO> cancel(@PathVariable UUID id,
                                       @RequestBody WorkOrderCancelRequest request);

    // 流转记录
    @GetMapping("/{id}/flows")
    @Operation(summary = "获取流转记录")
    public Result<List<WorkOrderFlowVO>> getFlows(@PathVariable UUID id);
}
```

> **TODO**: 工单列表接口（GET /api/wo/work-orders）当前返回 List，需改为分页查询（返回 Page<WorkOrderVO>）。

### 5.2 Notification API

```java
@RestController
@RequestMapping("/api/wo/notifications")
@Tag(name = "消息通知")
public class NotificationController {

    // 渠道管理
    @PostMapping("/channels")
    @Operation(summary = "创建通知渠道")
    public Result<NotificationChannelVO> createChannel(@RequestBody @Valid ChannelCreateRequest request);

    @GetMapping("/channels")
    @Operation(summary = "查询渠道列表")
    public Result<List<NotificationChannelVO>> listChannels();

    // 模板管理
    @PostMapping("/templates")
    @Operation(summary = "创建消息模板")
    public Result<NotificationTemplateVO> createTemplate(@RequestBody @Valid TemplateCreateRequest request);

    @GetMapping("/templates")
    @Operation(summary = "查询模板列表")
    public Result<List<NotificationTemplateVO>> listTemplates();

    // 规则管理
    @PostMapping("/rules")
    @Operation(summary = "创建通知规则")
    public Result<NotificationRuleVO> createRule(@RequestBody @Valid RuleCreateRequest request);

    @GetMapping("/rules")
    @Operation(summary = "查询规则列表")
    public Result<List<NotificationRuleVO>> listRules();

    // 消息历史
    @GetMapping("/history")
    @Operation(summary = "分页查询消息历史")
    public Result<Page<NotificationHistoryVO>> pageHistory(NotificationHistoryQueryRequest request);

    // 个人消息
    @GetMapping("/my")
    @Operation(summary = "获取我的消息列表")
    public Result<Page<NotificationVO>> getMyNotifications(@RequestParam(required = false) Boolean unread);

    @GetMapping("/my/unread-count")
    @Operation(summary = "获取未读消息数量")
    public Result<Long> getUnreadCount();

    @PostMapping("/{id}/read")
    @Operation(summary = "标记已读")
    public Result<Void> markAsRead(@PathVariable UUID id);

    @PostMapping("/read-all")
    @Operation(summary = "全部已读")
    public Result<Void> markAllAsRead();
}
```

### 5.3 Statistics API

```java
@RestController
@RequestMapping("/api/wo/statistics")
@Tag(name = "工单统计")
public class WorkOrderStatisticsController {

    @GetMapping("/overview")
    @Operation(summary = "概览统计")
    public Result<WorkOrderOverviewVO> getOverview(
            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate startDate,
            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate endDate);

    @GetMapping("/trend")
    @Operation(summary = "趋势统计")
    public Result<List<TrendVO>> getTrend(
            @RequestParam StatisticsType type,
            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate startDate,
            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate endDate);

    @GetMapping("/type-distribution")
    @Operation(summary = "类型分布")
    public Result<List<DistributionVO>> getTypeDistribution(
            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate startDate,
            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate endDate);

    @GetMapping("/assignee-ranking")
    @Operation(summary = "处理人排行")
    public Result<List<RankingVO>> getAssigneeRanking(
            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate startDate,
            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate endDate);
}
```

---

## 六、实现状态与差异

### 6.1 实现状态

| 功能模块 | 实现状态 | 备注 |
|---------|---------|------|
| WorkOrder | 🟢 已实现 | 完整状态机(PENDING→ASSIGNED→IN_PROGRESS→COMPLETED→VERIFIED/CANCELLED) |
| WorkOrderItem | 🟢 已实现 | 工单明细 |
| WorkOrderFlow | 🟢 已实现 | 自动记录流转 |
| MaintenancePlan | 🟢 已实现 | 维保计划 |
| MaintenanceTask | 🟢 已实现 | 维保任务，双完成接口 |
| InspectionTemplate | 🟢 已实现 | 巡检模板 |
| InspectionItem | 🟢 已实现 | 巡检项目 |
| NotificationChannel | 🟢 已实现 | 基础CRUD |
| NotificationTemplate | 🟢 已实现 | 基础CRUD |
| NotificationRule | 🟢 已实现 | 基础CRUD |
| NotificationHistory | 🟢 已实现 | 基础CRUD |
| 工单与通知集成 | 🟢 已实现 | 事件驱动 |
| 工单统计 | 🟢 已实现 | 多维度统计 |
| 优先级自动判定 | 🟢 已实现 | 根据类型/来源自动设置 |
| 设备联动更新 | 🟢 已实现 | 工单完成时更新设备状态 |
| SLA监控 | 🔴 未实现 | 超时预警 |
| 智能派单 | 🔴 未实现 | 自动分配 |
| SUSPENDED/RETURNED状态 | 🔴 未实现 | TODO: 需增加挂起和退回状态 |
| 工单分页查询 | 🔴 未实现 | TODO: 列表接口需改为分页查询 |

### 6.2 与设计方案的差异

| 设计项 | 设计方案 | 现有实现 | 差异分析 |
|--------|----------|----------|----------|
| **工单状态机** | CREATED→ASSIGNED→ACCEPTED→IN_PROGRESS→COMPLETED→CLOSED | PENDING→ASSIGNED→IN_PROGRESS→COMPLETED→VERIFIED/CANCELLED | 已更新：简化流程，增加验证环节 |
| **工单类型** | REPAIR/COMPLAINT/CLEANING/SECURITY/OTHER | REPAIR/INSPECTION/SECURITY/CLEANING/PROPERTY/CONSULTATION | 已更新：更贴合物业场景 |
| **工单来源** | APP/PHONE/INSPECTION/IOT/SYSTEM | OWNER/MAINTENANCE/INSPECTION/FAULT/REGULATORY/MANUAL | 已更新：按业务角色区分 |
| **结果字段** | resultDescription单字段 | result+faultCause+solution三字段 | 已拆分：更细粒度的结果记录 |
| **费用字段** | actualCost/materialCost/laborCost | laborCost/partsCost/totalCost | 已更新：更清晰的费用分类 |
| **通知渠道** | 多渠道支持 | 仅站内信实现 | 其他渠道待扩展 |
| **API路径** | /api/v1/ops | /api/wo | 已更新：路径简化 |
| **巡检归属** | ether-ops | ether-mdm | 领域边界模糊 |

### 6.3 待改进项

| 优先级 | 改进项 | 说明 |
|--------|--------|------|
| P0 | 工单分页查询 | 列表接口需改为分页查询 |
| P0 | 增加SUSPENDED/RETURNED状态 | 挂起和退回是常见业务需求 |
| P1 | 实现SLA监控 | 工单超时预警和自动升级 |
| P2 | 扩展通知渠道 | 短信、邮件、推送渠道 |
| P3 | 智能派单算法 | 基于负载、技能、位置的自动分配 |

---

## 七、数据库表结构

```sql
-- 工单表
CREATE TABLE ops_work_order (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    order_no VARCHAR(32) NOT NULL,
    order_type VARCHAR(20) NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
    priority VARCHAR(20) NOT NULL DEFAULT 'MEDIUM',
    source VARCHAR(20) NOT NULL,
    title VARCHAR(200) NOT NULL,
    description TEXT,
    reporter_id UUID,
    reporter_name VARCHAR(100),
    reporter_phone VARCHAR(20),
    reporter_address VARCHAR(255),
    space_node_id UUID,
    equipment_id UUID,
    plan_id UUID,
    trigger_type VARCHAR(20),
    assignee_id UUID,
    assignee_name VARCHAR(100),
    assigned_vendor UUID,
    assigned_at TIMESTAMP,
    accepted_at TIMESTAMP,
    started_at TIMESTAMP,
    completed_at TIMESTAMP,
    closed_at TIMESTAMP,
    labor_cost NUMERIC(12,2),
    parts_cost NUMERIC(12,2),
    total_cost NUMERIC(12,2),
    result TEXT,
    fault_cause TEXT,
    solution TEXT,
    satisfaction_score INTEGER,
    satisfaction_comment VARCHAR(500),
    signature VARCHAR(255),
    images TEXT,
    attachments TEXT,
    attributes JSONB,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    created_by UUID,
    updated_by UUID,
    UNIQUE(project_id, order_no)
);

-- 工单明细表（新增）
CREATE TABLE ops_work_order_item (
    id UUID PRIMARY KEY,
    work_order_id UUID NOT NULL REFERENCES ops_work_order(id),
    project_id UUID NOT NULL,
    item_name VARCHAR(200) NOT NULL,
    item_type VARCHAR(50),
    description TEXT,
    quantity INTEGER,
    unit_price NUMERIC(12,2),
    amount NUMERIC(12,2),
    remark VARCHAR(500),
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 工单流转表
CREATE TABLE ops_work_order_flow (
    id UUID PRIMARY KEY,
    work_order_id UUID NOT NULL,
    from_status VARCHAR(20),
    to_status VARCHAR(20) NOT NULL,
    action VARCHAR(50) NOT NULL,
    operator_id UUID,
    operator_name VARCHAR(100),
    operate_time TIMESTAMP NOT NULL DEFAULT NOW(),
    remark VARCHAR(500),
    images TEXT
);

-- 维保计划表（新增）
CREATE TABLE ops_maintenance_plan (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    equipment_id UUID NOT NULL,
    name VARCHAR(100) NOT NULL,
    type VARCHAR(20) NOT NULL,
    cycle_days INTEGER,
    cron_expression VARCHAR(50),
    content TEXT,
    check_items JSONB,
    maintainer_id UUID,
    maintainer_name VARCHAR(100),
    remind_days INTEGER DEFAULT 3,
    enabled BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 维保任务表（新增）
CREATE TABLE ops_maintenance_task (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    equipment_id UUID NOT NULL,
    plan_id UUID,
    task_code VARCHAR(50),
    status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
    maintenance_date DATE NOT NULL,
    type VARCHAR(20) NOT NULL,
    content TEXT,
    maintainer_id UUID,
    maintainer_name VARCHAR(100),
    result VARCHAR(20),
    remark VARCHAR(500),
    images TEXT,
    check_results JSONB,
    labor_cost NUMERIC(12,2),
    parts_cost NUMERIC(12,2),
    total_cost NUMERIC(12,2),
    signature VARCHAR(255),
    next_maintenance_date DATE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 巡检模板表（新增）
CREATE TABLE ops_inspection_template (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    name VARCHAR(100) NOT NULL,
    description TEXT,
    category VARCHAR(50),
    enabled BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 巡检项目表（新增）
CREATE TABLE ops_inspection_item (
    id UUID PRIMARY KEY,
    template_id UUID NOT NULL REFERENCES ops_inspection_template(id),
    item_name VARCHAR(200) NOT NULL,
    check_standard TEXT,
    check_method VARCHAR(100),
    sort_order INTEGER DEFAULT 0,
    required BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 通知渠道表
CREATE TABLE ops_notification_channel (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    name VARCHAR(100) NOT NULL,
    type VARCHAR(20) NOT NULL,
    config JSONB,
    enabled BOOLEAN DEFAULT TRUE,
    priority INTEGER DEFAULT 0,
    daily_limit INTEGER,
    sent_today INTEGER DEFAULT 0,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 消息模板表
CREATE TABLE ops_notification_template (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    name VARCHAR(100) NOT NULL,
    code VARCHAR(50) NOT NULL,
    title_template VARCHAR(200),
    content_template TEXT NOT NULL,
    variables JSONB,
    channels JSONB,
    example TEXT,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(project_id, code)
);

-- 通知规则表
CREATE TABLE ops_notification_rule (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    name VARCHAR(100) NOT NULL,
    event_type VARCHAR(50) NOT NULL,
    conditions JSONB,
    delay_minutes INTEGER DEFAULT 0,
    template_code VARCHAR(50) NOT NULL,
    receivers JSONB,
    channels JSONB,
    quiet_hours VARCHAR(20),
    enabled BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 通知历史表
CREATE TABLE ops_notification_history (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    title VARCHAR(200),
    content TEXT,
    event_type VARCHAR(50),
    receiver_id UUID,
    receiver_name VARCHAR(100),
    receiver_phone VARCHAR(20),
    receiver_email VARCHAR(100),
    channel VARCHAR(20) NOT NULL,
    channel_msg_id VARCHAR(100),
    status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
    fail_reason VARCHAR(500),
    send_time TIMESTAMP,
    read_time TIMESTAMP,
    business_type VARCHAR(50),
    business_id VARCHAR(50),
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 创建索引
CREATE INDEX idx_work_order_project ON ops_work_order(project_id);
CREATE INDEX idx_work_order_status ON ops_work_order(status);
CREATE INDEX idx_work_order_assignee ON ops_work_order(assignee_id);
CREATE INDEX idx_work_order_created ON ops_work_order(created_at);
CREATE INDEX idx_work_order_type ON ops_work_order(order_type);
CREATE INDEX idx_work_order_flow_order ON ops_work_order_flow(work_order_id);
CREATE INDEX idx_work_order_item_order ON ops_work_order_item(work_order_id);
CREATE INDEX idx_maintenance_plan_equipment ON ops_maintenance_plan(equipment_id);
CREATE INDEX idx_maintenance_task_equipment ON ops_maintenance_task(equipment_id);
CREATE INDEX idx_maintenance_task_status ON ops_maintenance_task(status);
CREATE INDEX idx_inspection_item_template ON ops_inspection_item(template_id);
CREATE INDEX idx_notification_history_receiver ON ops_notification_history(receiver_id);
CREATE INDEX idx_notification_history_status ON ops_notification_history(status);
```

---

**文档维护**: 本领域技术方案由 ether-ops 服务负责人维护