1363 lines
52 KiB
Markdown
1363 lines
52 KiB
Markdown
# 运营与服务域 - 详细设计
|
||
|
||
**文档编号**: DETAIL-OPS
|
||
**版本**: v1.0
|
||
**模块**: module-wo + module-mdm（备件/能耗部分）
|
||
**生成日期**: 2026-05-18
|
||
**数据来源**: ether-pms/module-wo + module-mdm 实际代码 + REVERSE-OPS.md 反推文档
|
||
|
||
---
|
||
|
||
## 一、功能点清单
|
||
|
||
| 功能ID | 功能名称 | 优先级 | 实现状态 | 对应需求ID |
|
||
|--------|----------|--------|----------|------------|
|
||
| OPS-001 | 工单创建 | P0 | 已完成 | 02-OPERATIONS-001 |
|
||
| OPS-002 | 工单查询（分页） | P0 | 已完成 | 02-OPERATIONS-001 |
|
||
| OPS-003 | 工单详情 | P0 | 已完成 | 02-OPERATIONS-001 |
|
||
| OPS-004 | 工单更新 | P1 | 已完成 | 02-OPERATIONS-001 |
|
||
| OPS-005 | 工单删除（逻辑删除） | P1 | 已完成 | 02-OPERATIONS-001 |
|
||
| OPS-006 | 工单派单 | P0 | 已完成 | 02-OPERATIONS-002 |
|
||
| OPS-007 | 工单开始执行 | P0 | 已完成 | 02-OPERATIONS-002 |
|
||
| OPS-008 | 工单完成 | P0 | 已完成 | 02-OPERATIONS-002 |
|
||
| OPS-009 | 工单验收 | P0 | 已完成 | 02-OPERATIONS-002 |
|
||
| OPS-010 | 工单取消 | P1 | 已完成 | 02-OPERATIONS-002 |
|
||
| OPS-011 | 工单挂起 | P1 | 已完成 | 02-OPERATIONS-002 |
|
||
| OPS-012 | 工单恢复 | P1 | 已完成 | 02-OPERATIONS-002 |
|
||
| OPS-013 | 工单退回 | P1 | 已完成 | 02-OPERATIONS-002 |
|
||
| OPS-014 | 工单统计 | P1 | 已完成 | 02-OPERATIONS-003 |
|
||
| OPS-015 | 工单明细查询 | P1 | 已完成 | 02-OPERATIONS-004 |
|
||
| OPS-016 | 工单明细批量添加 | P1 | 已完成 | 02-OPERATIONS-004 |
|
||
| OPS-017 | 维保任务创建 | P0 | 已完成 | 02-OPERATIONS-005 |
|
||
| OPS-018 | 维保任务查询 | P0 | 已完成 | 02-OPERATIONS-005 |
|
||
| OPS-019 | 维保任务分配 | P0 | 已完成 | 02-OPERATIONS-005 |
|
||
| OPS-020 | 维保任务开始执行 | P0 | 已完成 | 02-OPERATIONS-005 |
|
||
| OPS-021 | 维保任务完成（简版） | P0 | 已完成 | 02-OPERATIONS-005 |
|
||
| OPS-022 | 维保任务完成（详版） | P0 | 已完成 | 02-OPERATIONS-005 |
|
||
| OPS-023 | 维保任务验收 | P0 | 已完成 | 02-OPERATIONS-005 |
|
||
| OPS-024 | 维保任务取消 | P1 | 已完成 | 02-OPERATIONS-005 |
|
||
| OPS-025 | 维保任务评分 | P2 | 已完成 | 02-OPERATIONS-005 |
|
||
| OPS-026 | 维保任务统计 | P1 | 已完成 | 02-OPERATIONS-006 |
|
||
| OPS-027 | 维保计划管理 | P1 | 已完成 | 02-OPERATIONS-007 |
|
||
| OPS-028 | 巡检模板管理 | P1 | 已完成 | 02-OPERATIONS-008 |
|
||
| OPS-029 | 巡检模板复制 | P2 | 已完成 | 02-OPERATIONS-008 |
|
||
| OPS-030 | 备件CRUD | P0 | 已完成 | 02-OPERATIONS-009 |
|
||
| OPS-031 | 备件分类管理 | P1 | 已完成 | 02-OPERATIONS-009 |
|
||
| OPS-032 | 备件入库 | P0 | 已完成 | 02-OPERATIONS-010 |
|
||
| OPS-033 | 备件出库 | P0 | 已完成 | 02-OPERATIONS-010 |
|
||
| OPS-034 | 备件低库存预警 | P1 | 已完成 | 02-OPERATIONS-010 |
|
||
| OPS-035 | 备件出入库记录 | P1 | 已完成 | 02-OPERATIONS-010 |
|
||
| OPS-036 | 能源计量点管理 | P1 | 已完成 | 02-OPERATIONS-011 |
|
||
| OPS-037 | 能耗抄表记录 | P0 | 已完成 | 02-OPERATIONS-012 |
|
||
| OPS-038 | 能耗按类型统计 | P1 | 已完成 | 02-OPERATIONS-013 |
|
||
| OPS-039 | 单位面积能耗 | P2 | 已完成 | 02-OPERATIONS-013 |
|
||
| OPS-040 | 消息通知系统 | P1 | 未实现 | 02-OPERATIONS-014 |
|
||
| OPS-041 | 工单流转记录 | P2 | 未实现 | 02-OPERATIONS-015 |
|
||
| OPS-042 | SLA监控 | P2 | 未实现 | 02-OPERATIONS-016 |
|
||
| OPS-043 | 智能派单 | P3 | 未实现 | 02-OPERATIONS-017 |
|
||
|
||
---
|
||
|
||
## 二、数据结构设计
|
||
|
||
### 2.1 WorkOrder（工单）
|
||
|
||
**表名**: `ops_work_order`
|
||
**实体类**: `com.ether.pms.ops.entity.WorkOrder`
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| id | UUID | 是 | 自动生成 | 主键 |
|
||
| workNo | VARCHAR(50) | 是 | 自动生成 | 工单编号，格式: WO-YYYYMMDD-XXXX，UNIQUE |
|
||
| source | ENUM | 是 | - | 工单来源（6种） |
|
||
| type | ENUM | 是 | - | 工单类型（6种） |
|
||
| priority | ENUM | 否 | MEDIUM | 优先级（4级） |
|
||
| status | ENUM | 否 | PENDING | 工单状态（8种） |
|
||
| previousStatus | ENUM | 否 | - | 前一状态（挂起恢复用） |
|
||
| title | VARCHAR(200) | 是 | - | 工单标题 |
|
||
| description | VARCHAR(2000) | 否 | - | 工单描述 |
|
||
| projectId | UUID | 是 | - | 所属项目 |
|
||
| equipmentId | UUID | 否 | - | 关联设备 |
|
||
| spaceId | UUID | 否 | - | 关联空间 |
|
||
| planId | UUID | 否 | - | 关联维保计划 |
|
||
| triggerType | ENUM | 否 | - | 触发类型（4种） |
|
||
| 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列表(List\<String\>) |
|
||
| signature | VARCHAR(2000) | 否 | - | 签名 |
|
||
| isDeleted | BOOLEAN | 否 | false | 逻辑删除标记 |
|
||
| 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 / SUSPENDED / RETURNED / 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`
|
||
**实体类**: `com.ether.pms.ops.entity.WorkOrderItem`
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| id | UUID | 是 | 自动生成 | 主键 |
|
||
| workOrderId | UUID | 是 | - | 所属工单ID |
|
||
| itemType | ENUM | 是 | - | 明细类型（3种） |
|
||
| 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 MaintenancePlan（维保计划）
|
||
|
||
**表名**: `ops_maintenance_plan`
|
||
**实体类**: `com.ether.pms.ops.entity.MaintenancePlan`
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| id | UUID | 是 | 自动生成 | 主键 |
|
||
| planCode | VARCHAR(50) | 是 | 自动生成 | 计划编码（UNIQUE） |
|
||
| planName | VARCHAR(200) | 是 | - | 计划名称 |
|
||
| planContent | VARCHAR(5000) | 否 | - | 计划内容 |
|
||
| projectId | UUID | 否 | - | 所属项目 |
|
||
| equipmentId | UUID | 是 | - | 关联设备 |
|
||
| planType | ENUM | 是 | - | 计划类型（2种） |
|
||
| cycleDays | INTEGER | 否 | - | 周期天数 |
|
||
| estimatedHours | DECIMAL(6,2) | 否 | - | 预估工时 |
|
||
| assignedVendor | VARCHAR(200) | 否 | - | 指定服务商 |
|
||
| status | ENUM | 否 | ACTIVE | 计划状态（3种） |
|
||
| lastDate | DATE | 否 | - | 上次执行日期 |
|
||
| nextDate | DATE | 否 | - | 下次执行日期 |
|
||
| createdAt | TIMESTAMP | 否 | now() | 创建时间 |
|
||
| updatedAt | TIMESTAMP | 否 | now() | 更新时间 |
|
||
| createdBy | VARCHAR(200) | 否 | - | 创建人 |
|
||
|
||
**枚举定义**:
|
||
|
||
| 枚举 | 值 | 中文 |
|
||
|------|-----|------|
|
||
| PlanType | PREVENTIVE | 预防性维护 |
|
||
| | CORRECTIVE | 纠正性维护 |
|
||
| PlanStatus | ACTIVE | 启用 |
|
||
| | INACTIVE | 停用 |
|
||
| | SUSPENDED | 暂停 |
|
||
|
||
### 2.4 MaintenanceTask（维保任务）
|
||
|
||
**表名**: `ops_maintenance_task`
|
||
**实体类**: `com.ether.pms.ops.entity.MaintenanceTask`
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| id | UUID | 是 | 自动生成 | 主键 |
|
||
| taskNo | VARCHAR(50) | 否 | 自动生成 | 任务编号，格式: EQ-YYYYMMDD-XXXX，UNIQUE |
|
||
| planId | UUID | 否 | - | 关联维保计划ID |
|
||
| equipmentId | UUID | 是 | - | 关联设备ID |
|
||
| projectId | UUID | 否 | - | 所属项目 |
|
||
| taskType | ENUM | 否 | - | 任务类型（3种） |
|
||
| triggerType | ENUM | 否 | - | 触发类型（4种） |
|
||
| priority | ENUM | 否 | 自动判定 | 优先级（4级） |
|
||
| status | ENUM | 否 | PENDING | 任务状态（6种） |
|
||
| 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 | 否 | - | 使用备件列表(List\<Map\>) |
|
||
| 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 结构**:
|
||
|
||
```json
|
||
[
|
||
{
|
||
"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.5 InspectionTemplate（巡检模板）
|
||
|
||
**表名**: `ops_inspection_template`
|
||
**实体类**: `com.ether.pms.mdm.entity.InspectionTemplate`（位于module-mdm）
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| id | UUID | 是 | 自动生成 | 主键 |
|
||
| templateCode | VARCHAR(50) | 是 | 自动生成 | 模板编码（UNIQUE） |
|
||
| templateName | VARCHAR(200) | 是 | - | 模板名称 |
|
||
| description | VARCHAR(2000) | 否 | - | 描述 |
|
||
| projectId | UUID | 否 | - | 所属项目 |
|
||
| spaceId | UUID | 否 | - | 关联空间 |
|
||
| category | VARCHAR(50) | 否 | - | 分类 |
|
||
| status | ENUM | 否 | ACTIVE | 模板状态（2种） |
|
||
| createdAt | TIMESTAMP | 否 | now() | 创建时间 |
|
||
| updatedAt | TIMESTAMP | 否 | now() | 更新时间 |
|
||
| createdBy | VARCHAR(200) | 否 | - | 创建人 |
|
||
| items | List\<InspectionItem\> | - | - | 检查项列表（@Transient，非持久化） |
|
||
|
||
**枚举定义**:
|
||
|
||
| 枚举 | 值 | 中文 |
|
||
|------|-----|------|
|
||
| TemplateStatus | ACTIVE | 启用 |
|
||
| | INACTIVE | 停用 |
|
||
|
||
### 2.6 InspectionItem（巡检项）
|
||
|
||
**表名**: `ops_inspection_item`
|
||
**实体类**: `com.ether.pms.mdm.entity.InspectionItem`（位于module-mdm）
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| 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 SparePart（备件）
|
||
|
||
**表名**: `ops_spare_part`
|
||
**实体类**: `com.ether.pms.mdm.entity.SparePart`（位于module-mdm）
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| id | UUID | 是 | 自动生成 | 主键 |
|
||
| projectId | UUID | 是 | - | 所属项目 |
|
||
| sparePartCode | VARCHAR | 是 | 自动生成 | 备件编码（UNIQUE），格式: SP+yyyyMMddHHmmss |
|
||
| sparePartName | VARCHAR | 是 | - | 备件名称 |
|
||
| categoryId | UUID | 否 | - | 分类ID |
|
||
| specification | VARCHAR(500) | 否 | - | 规格 |
|
||
| unit | VARCHAR(50) | 是 | - | 单位 |
|
||
| safeStock | INTEGER | 否 | 0 | 安全库存 |
|
||
| currentStock | INTEGER | 否 | 0 | 当前库存 |
|
||
| unitPrice | DECIMAL(10,2) | 否 | - | 单价 |
|
||
| supplier | VARCHAR(200) | 否 | - | 供应商 |
|
||
| supplierContact | VARCHAR | 否 | - | 供应商联系方式 |
|
||
| location | VARCHAR(200) | 否 | - | 存放位置 |
|
||
| remarks | VARCHAR(1000) | 否 | - | 备注 |
|
||
| status | ENUM | 是 | ACTIVE | 状态（2种） |
|
||
| createdAt | TIMESTAMP | 否 | now() | 创建时间 |
|
||
| updatedAt | TIMESTAMP | 否 | now() | 更新时间 |
|
||
|
||
**枚举定义**:
|
||
|
||
| 枚举 | 值 | 中文 |
|
||
|------|-----|------|
|
||
| Status | ACTIVE | 启用 |
|
||
| | INACTIVE | 停用 |
|
||
|
||
**索引**:
|
||
|
||
| 索引名 | 字段 | 用途 |
|
||
|--------|------|------|
|
||
| idx_sp_project_status | project_id, status | 项目+状态查询 |
|
||
|
||
### 2.8 SparePartCategory（备件分类）
|
||
|
||
**表名**: `ops_spare_part_category`
|
||
**实体类**: `com.ether.pms.mdm.entity.SparePartCategory`（位于module-mdm）
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| id | UUID | 是 | 自动生成 | 主键 |
|
||
| parentId | UUID | 否 | - | 父分类ID（支持树形结构） |
|
||
| categoryCode | VARCHAR | 是 | 自动生成 | 分类编码（UNIQUE），格式: CC+yyyyMMddHHmmss |
|
||
| categoryName | VARCHAR | 是 | - | 分类名称 |
|
||
| description | VARCHAR(500) | 否 | - | 描述 |
|
||
| sortOrder | INTEGER | 否 | - | 排序序号 |
|
||
| createdAt | TIMESTAMP | 否 | now() | 创建时间 |
|
||
|
||
### 2.9 SparePartRecord（备件出入库记录）
|
||
|
||
**表名**: `ops_spare_part_record`
|
||
**实体类**: `com.ether.pms.mdm.entity.SparePartRecord`（位于module-mdm）
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| id | UUID | 是 | 自动生成 | 主键 |
|
||
| recordCode | VARCHAR | 是 | 自动生成 | 记录编码（UNIQUE），格式: REC+类型+yyyyMMddHHmmss |
|
||
| recordType | ENUM | 是 | - | 记录类型（4种） |
|
||
| sparePartId | UUID | 是 | - | 备件ID |
|
||
| quantity | INTEGER | 是 | - | 数量 |
|
||
| balance | INTEGER | 是 | - | 操作后余额 |
|
||
| relatedOrderId | UUID | 否 | - | 关联工单ID |
|
||
| recordedBy | UUID | 否 | - | 操作人 |
|
||
| recordDate | TIMESTAMP | 否 | now() | 操作时间 |
|
||
| remarks | VARCHAR(1000) | 否 | - | 备注 |
|
||
|
||
**枚举定义**:
|
||
|
||
| 枚举 | 值 | 中文 | 说明 |
|
||
|------|-----|------|------|
|
||
| RecordType | IN | 入库 | 库存增加 |
|
||
| | OUT | 出库 | 库存减少，可关联工单 |
|
||
| | CHECK | 盘点 | 库存校准 |
|
||
| | ADJUST | 调整 | 库存调整 |
|
||
|
||
### 2.10 EnergyMeter（能源计量点）
|
||
|
||
**表名**: `ops_energy_meter`
|
||
**实体类**: `com.ether.pms.mdm.entity.EnergyMeter`（位于module-mdm）
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| id | UUID | 是 | 自动生成 | 主键 |
|
||
| projectId | UUID | 是 | - | 所属项目 |
|
||
| meterCode | VARCHAR | 是 | 自动生成 | 计量点编码（UNIQUE） |
|
||
| meterName | VARCHAR | 是 | - | 计量点名称 |
|
||
| energyType | ENUM | 是 | - | 能源类型（6种） |
|
||
| spaceNodeId | UUID | 否 | - | 关联空间节点 |
|
||
| installationLocation | VARCHAR | 否 | - | 安装位置 |
|
||
| ratedCapacity | DECIMAL(10,2) | 否 | - | 额定容量 |
|
||
| unitPrice | DECIMAL(10,4) | 否 | - | 单价 |
|
||
| status | ENUM | 是 | ACTIVE | 状态（2种） |
|
||
| createdAt | TIMESTAMP | 否 | now() | 创建时间 |
|
||
| updatedAt | TIMESTAMP | 否 | now() | 更新时间 |
|
||
|
||
**枚举定义**:
|
||
|
||
| 枚举 | 值 | 中文 | 说明 |
|
||
|------|-----|------|------|
|
||
| EnergyType | LIGHTING | 照明插座用电 | 建筑分项能耗分类 |
|
||
| | HVAC | 空调用电 | 建筑分项能耗分类 |
|
||
| | POWER | 动力用电 | 建筑分项能耗分类 |
|
||
| | SPECIAL | 特殊用电 | 建筑分项能耗分类 |
|
||
| | WATER | 给排水 | 水耗计量 |
|
||
| | GAS | 燃气 | 气耗计量 |
|
||
| Status | ACTIVE | 启用 | 可正常抄表 |
|
||
| | INACTIVE | 停用 | 不可抄表 |
|
||
|
||
### 2.11 EnergyConsumption（能耗记录）
|
||
|
||
**表名**: `ops_energy_consumption`
|
||
**实体类**: `com.ether.pms.mdm.entity.EnergyConsumption`（位于module-mdm）
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| id | UUID | 是 | 自动生成 | 主键 |
|
||
| projectId | UUID | 是 | - | 项目ID |
|
||
| meterId | UUID | 是 | - | 计量点ID |
|
||
| consumptionDate | DATE | 是 | - | 消耗日期 |
|
||
| previousReading | DECIMAL(12,2) | 否 | - | 上次读数 |
|
||
| currentReading | DECIMAL(12,2) | 否 | - | 当前读数 |
|
||
| consumption | DECIMAL(12,2) | 是 | - | 消耗量 = currentReading - previousReading |
|
||
| amount | DECIMAL(10,2) | 否 | - | 费用 = consumption x unitPrice |
|
||
| recordedBy | UUID | 否 | - | 抄表人 |
|
||
| recordMethod | ENUM | 否 | MANUAL | 抄表方式（2种） |
|
||
| remarks | VARCHAR(1000) | 否 | - | 备注 |
|
||
| createdAt | TIMESTAMP | 否 | now() | 创建时间 |
|
||
|
||
**枚举定义**:
|
||
|
||
| 枚举 | 值 | 中文 | 说明 |
|
||
|------|-----|------|------|
|
||
| RecordMethod | MANUAL | 手动录入 | 人工抄表 |
|
||
| | IOT | IoT自动采集 | 自动采集（预留） |
|
||
|
||
**索引**:
|
||
|
||
| 索引名 | 字段 | 用途 |
|
||
|--------|------|------|
|
||
| idx_ec_meter_date | meter_id, consumption_date | 计量点+日期查询 |
|
||
| idx_ec_project_date | project_id, consumption_date | 项目+日期查询 |
|
||
|
||
### 2.12 ER关系图
|
||
|
||
```mermaid
|
||
erDiagram
|
||
MaintenancePlan ||--o{ MaintenanceTask : "1:N planId"
|
||
MaintenancePlan }o--|| Equipment : "equipmentId"
|
||
WorkOrder ||--o{ WorkOrderItem : "1:N workOrderId"
|
||
WorkOrder }o--o| MaintenancePlan : "planId"
|
||
WorkOrder }o--o| Equipment : "equipmentId"
|
||
InspectionTemplate ||--o{ InspectionItem : "1:N templateId"
|
||
SparePartCategory ||--o{ SparePart : "1:N categoryId"
|
||
SparePart ||--o{ SparePartRecord : "1:N sparePartId"
|
||
EnergyMeter ||--o{ EnergyConsumption : "1:N meterId"
|
||
|
||
WorkOrder {
|
||
UUID id PK
|
||
String workNo UK
|
||
Source source
|
||
Type type
|
||
Priority priority
|
||
Status status
|
||
Status previousStatus
|
||
UUID projectId FK
|
||
UUID equipmentId FK
|
||
UUID planId FK
|
||
}
|
||
|
||
WorkOrderItem {
|
||
UUID id PK
|
||
UUID workOrderId FK
|
||
ItemType itemType
|
||
String itemName
|
||
BigDecimal quantity
|
||
BigDecimal totalPrice
|
||
}
|
||
|
||
MaintenancePlan {
|
||
UUID id PK
|
||
String planCode UK
|
||
String planName
|
||
PlanType planType
|
||
Integer cycleDays
|
||
PlanStatus status
|
||
UUID equipmentId FK
|
||
}
|
||
|
||
MaintenanceTask {
|
||
UUID id PK
|
||
String taskNo UK
|
||
UUID planId FK
|
||
UUID equipmentId FK
|
||
TaskType taskType
|
||
TriggerType triggerType
|
||
Priority priority
|
||
Status status
|
||
}
|
||
|
||
InspectionTemplate {
|
||
UUID id PK
|
||
String templateCode UK
|
||
String templateName
|
||
String category
|
||
TemplateStatus status
|
||
}
|
||
|
||
InspectionItem {
|
||
UUID id PK
|
||
UUID templateId FK
|
||
String itemName
|
||
String checkMethod
|
||
String standard
|
||
Boolean isMandatory
|
||
}
|
||
|
||
SparePart {
|
||
UUID id PK
|
||
String sparePartCode UK
|
||
String sparePartName
|
||
UUID categoryId FK
|
||
Integer currentStock
|
||
Integer safeStock
|
||
}
|
||
|
||
SparePartRecord {
|
||
UUID id PK
|
||
String recordCode UK
|
||
RecordType recordType
|
||
UUID sparePartId FK
|
||
Integer quantity
|
||
Integer balance
|
||
UUID relatedOrderId FK
|
||
}
|
||
|
||
EnergyMeter {
|
||
UUID id PK
|
||
String meterCode UK
|
||
String meterName
|
||
EnergyType energyType
|
||
BigDecimal unitPrice
|
||
}
|
||
|
||
EnergyConsumption {
|
||
UUID id PK
|
||
UUID meterId FK
|
||
LocalDate consumptionDate
|
||
BigDecimal consumption
|
||
BigDecimal amount
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、API设计
|
||
|
||
### 3.1 WorkOrderController
|
||
|
||
**基础路径**: `/api/wo/work-orders`
|
||
**控制器类**: `com.ether.pms.ops.controller.WorkOrderController`
|
||
|
||
#### 工单 CRUD
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| POST | `/` | 创建工单 | WorkOrder | ApiResponse\<WorkOrder\> | OPS-001 |
|
||
| GET | `/` | 查询工单列表（分页） | QueryParams | ApiResponse\<PageResponse\<WorkOrder\>\> | OPS-002 |
|
||
| GET | `/{id}` | 获取工单详情 | - | ApiResponse\<WorkOrder\> | OPS-003 |
|
||
| PUT | `/{id}` | 更新工单 | WorkOrder | ApiResponse\<WorkOrder\> | OPS-004 |
|
||
| DELETE | `/{id}` | 删除工单（逻辑删除） | - | ApiResponse\<Void\> | OPS-005 |
|
||
|
||
**查询参数**（GET /）:
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| projectId | UUID | 否 | - | 按项目筛选 |
|
||
| equipmentId | UUID | 否 | - | 按设备筛选 |
|
||
| source | Source | 否 | - | 按来源筛选 |
|
||
| type | Type | 否 | - | 按类型筛选 |
|
||
| status | Status | 否 | - | 按状态筛选 |
|
||
| priority | Priority | 否 | - | 按优先级筛选 |
|
||
| assignedTo | String | 否 | - | 按负责人筛选 |
|
||
| keyword | String | 否 | - | 关键词搜索 |
|
||
| page | int | 否 | 0 | 页码 |
|
||
| size | int | 否 | 20 | 每页大小 |
|
||
|
||
#### 工单状态流转
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| POST | `/{id}/assign` | 派单 | AssignRequest | ApiResponse\<WorkOrder\> | OPS-006 |
|
||
| POST | `/{id}/start` | 开始执行 | - | ApiResponse\<WorkOrder\> | OPS-007 |
|
||
| POST | `/{id}/complete` | 完成工单 | WorkOrder | ApiResponse\<WorkOrder\> | OPS-008 |
|
||
| POST | `/{id}/verify` | 验收工单 | VerifyRequest | ApiResponse\<WorkOrder\> | OPS-009 |
|
||
| POST | `/{id}/cancel` | 取消工单 | - | ApiResponse\<WorkOrder\> | OPS-010 |
|
||
| POST | `/{id}/suspend` | 挂起工单 | - | ApiResponse\<WorkOrder\> | OPS-011 |
|
||
| POST | `/{id}/resume` | 恢复工单 | - | ApiResponse\<WorkOrder\> | OPS-012 |
|
||
| POST | `/{id}/return` | 退回工单 | - | ApiResponse\<WorkOrder\> | OPS-013 |
|
||
|
||
**请求体定义**:
|
||
|
||
```java
|
||
// 派单请求
|
||
AssignRequest {
|
||
String assignedTo; // 负责人
|
||
String assignedVendor; // 服务商
|
||
LocalDate assignedDate; // 派单日期
|
||
}
|
||
|
||
// 验收请求
|
||
VerifyRequest {
|
||
String verifiedBy; // 验收人
|
||
String remark; // 备注
|
||
Integer rating; // 评分（1-5）
|
||
}
|
||
```
|
||
|
||
#### 工单统计与明细
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| GET | `/stats` | 工单统计 | - | ApiResponse\<WorkOrderStatsDTO\> | OPS-014 |
|
||
| GET | `/{id}/items` | 获取工单明细 | - | ApiResponse\<List\<WorkOrderItem\>\> | OPS-015 |
|
||
| POST | `/{id}/items` | 批量添加工单明细 | List\<WorkOrderItem\> | ApiResponse\<WorkOrder\> | OPS-016 |
|
||
|
||
**WorkOrderStatsDTO**:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| total | long | 工单总数 |
|
||
| pending | long | 待分配数 |
|
||
| assigned | long | 已派单数 |
|
||
| inProgress | long | 执行中数 |
|
||
| completed | long | 已完成数 |
|
||
| verified | long | 已验收数 |
|
||
| cancelled | long | 已取消数 |
|
||
| suspended | long | 已挂起数 |
|
||
| returned | long | 已退回数 |
|
||
| completedToday | long | 今日完成数 |
|
||
| createdToday | long | 今日创建数 |
|
||
| overdue | long | 逾期数 |
|
||
| bySource | Map\<String, Long\> | 按来源分布 |
|
||
| byType | Map\<String, Long\> | 按类型分布 |
|
||
| byPriority | Map\<String, Long\> | 按优先级分布 |
|
||
|
||
### 3.2 MaintenanceTaskController
|
||
|
||
**基础路径**: `/api/ops/maintenance-tasks`
|
||
**控制器类**: `com.ether.pms.ops.controller.MaintenanceTaskController`
|
||
|
||
#### 维保任务 CRUD
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| POST | `/` | 创建维保任务 | MaintenanceTask | ApiResponse\<MaintenanceTask\> | OPS-017 |
|
||
| GET | `/` | 查询维保任务列表 | QueryParams | ApiResponse\<List\<MaintenanceTask\>\> | OPS-018 |
|
||
| GET | `/{id}` | 获取任务详情 | - | ApiResponse\<MaintenanceTask\> | OPS-018 |
|
||
| PUT | `/{id}` | 更新任务 | MaintenanceTask | ApiResponse\<MaintenanceTask\> | OPS-018 |
|
||
| DELETE | `/{id}` | 删除任务（逻辑删除，设为CANCELLED） | - | ApiResponse\<Void\> | OPS-024 |
|
||
|
||
**查询参数**（GET /）:
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| equipmentId | UUID | 否 | 按设备筛选 |
|
||
| planId | UUID | 否 | 按计划筛选 |
|
||
| status | Status | 否 | 按状态筛选 |
|
||
| priority | Priority | 否 | 按优先级筛选 |
|
||
| assignedTo | String | 否 | 按负责人筛选 |
|
||
| overdueDate | LocalDate | 否 | 逾期截止日期 |
|
||
|
||
> 查询参数互斥优先级：equipmentId > planId > status > priority > assignedTo > overdueDate
|
||
|
||
#### 维保任务状态流转
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| POST | `/{id}/assign` | 分配任务 | AssignRequest | ApiResponse\<MaintenanceTask\> | OPS-019 |
|
||
| POST | `/{id}/start` | 开始执行 | - | ApiResponse\<MaintenanceTask\> | OPS-020 |
|
||
| POST | `/{id}/complete` | 完成任务（简版） | CompleteRequest | ApiResponse\<MaintenanceTask\> | OPS-021 |
|
||
| POST | `/{id}/complete-details` | 完成任务（详版） | MaintenanceTask | ApiResponse\<MaintenanceTask\> | OPS-022 |
|
||
| POST | `/{id}/verify` | 验收任务 | VerifyRequest | ApiResponse\<MaintenanceTask\> | OPS-023 |
|
||
| POST | `/{id}/cancel` | 取消任务 | - | ApiResponse\<MaintenanceTask\> | OPS-024 |
|
||
| POST | `/{id}/rate` | 评分 | rating (query param) | ApiResponse\<MaintenanceTask\> | OPS-025 |
|
||
|
||
**请求体定义**:
|
||
|
||
```java
|
||
// 分配请求
|
||
AssignRequest {
|
||
String assignedTo;
|
||
LocalDate assignedDate;
|
||
}
|
||
|
||
// 完成请求（简版）
|
||
CompleteRequest {
|
||
String result;
|
||
BigDecimal actualHours;
|
||
BigDecimal cost;
|
||
String completedBy;
|
||
}
|
||
|
||
// 验收请求
|
||
VerifyRequest {
|
||
String verifiedBy;
|
||
String remark;
|
||
Integer rating;
|
||
}
|
||
```
|
||
|
||
#### 维保任务统计
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| GET | `/stats` | 任务统计 | - | ApiResponse\<MaintenanceTaskStatsDTO\> | OPS-026 |
|
||
|
||
**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\> | 按触发类型分布 |
|
||
|
||
### 3.3 InspectionTemplateController
|
||
|
||
**基础路径**: `/api/ops/inspection-templates`
|
||
**控制器类**: `com.ether.pms.mdm.controller.InspectionTemplateController`（位于module-mdm）
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| GET | `/` | 按项目查询模板 | projectId | ApiResponse\<List\<InspectionTemplate\>\> | OPS-028 |
|
||
| POST | `/` | 创建模板 | InspectionTemplate | ApiResponse\<InspectionTemplate\> | OPS-028 |
|
||
| GET | `/{id}` | 获取模板详情 | - | ApiResponse\<InspectionTemplate\> | OPS-028 |
|
||
| PUT | `/{id}` | 更新模板 | InspectionTemplate | ApiResponse\<InspectionTemplate\> | OPS-028 |
|
||
| POST | `/{id}/copy` | 复制模板 | newName (query param) | ApiResponse\<InspectionTemplate\> | OPS-029 |
|
||
| GET | `/by-type/{equipmentType}` | 按设备类型查询 | - | ApiResponse\<List\<InspectionTemplate\>\> | OPS-028 |
|
||
|
||
### 3.4 SparePartController
|
||
|
||
**基础路径**: `/api/ops/spare-parts`
|
||
**控制器类**: `com.ether.pms.mdm.controller.SparePartController`（位于module-mdm）
|
||
|
||
#### 分类管理
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| GET | `/categories` | 获取所有分类 | - | ApiResponse\<List\<SparePartCategory\>\> | OPS-031 |
|
||
| POST | `/categories` | 创建分类 | SparePartCategory | ApiResponse\<SparePartCategory\> | OPS-031 |
|
||
|
||
#### 备件管理
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| GET | `/` | 查询备件列表 | projectId, categoryId(可选) | ApiResponse\<List\<SparePart\>\> | OPS-030 |
|
||
| GET | `/{id}` | 获取备件详情 | - | ApiResponse\<SparePart\> | OPS-030 |
|
||
| POST | `/` | 创建备件 | SparePart | ApiResponse\<SparePart\> | OPS-030 |
|
||
| PUT | `/{id}` | 更新备件 | SparePart | ApiResponse\<SparePart\> | OPS-030 |
|
||
| DELETE | `/{id}` | 删除备件（设为INACTIVE） | - | ApiResponse\<Void\> | OPS-030 |
|
||
| GET | `/low-stock` | 低库存预警 | projectId | ApiResponse\<List\<SparePart\>\> | OPS-034 |
|
||
|
||
#### 库存操作
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| POST | `/in-stock` | 入库 | StockRequest | ApiResponse\<SparePartRecord\> | OPS-032 |
|
||
| POST | `/out-stock` | 出库 | OutStockRequest | ApiResponse\<SparePartRecord\> | OPS-033 |
|
||
| GET | `/{id}/records` | 获取出入库记录 | - | ApiResponse\<List\<SparePartRecord\>\> | OPS-035 |
|
||
|
||
**请求体定义**:
|
||
|
||
```java
|
||
// 入库请求
|
||
StockRequest {
|
||
@NotNull UUID sparePartId;
|
||
@NotNull Integer quantity;
|
||
UUID recordedBy;
|
||
String remarks;
|
||
}
|
||
|
||
// 出库请求
|
||
OutStockRequest {
|
||
@NotNull UUID sparePartId;
|
||
@NotNull Integer quantity;
|
||
UUID relatedOrderId; // 关联工单ID
|
||
UUID recordedBy;
|
||
String remarks;
|
||
}
|
||
```
|
||
|
||
### 3.5 EnergyController
|
||
|
||
**基础路径**: `/api/ops/energy`
|
||
**控制器类**: `com.ether.pms.mdm.controller.EnergyController`（位于module-mdm）
|
||
|
||
#### 计量点管理
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| POST | `/meters` | 创建计量点 | EnergyMeter | ApiResponse\<EnergyMeter\> | OPS-036 |
|
||
| GET | `/meters` | 查询计量点 | projectId, energyType(可选) | ApiResponse\<List\<EnergyMeter\>\> | OPS-036 |
|
||
| GET | `/meters/{id}` | 获取计量点详情 | - | ApiResponse\<EnergyMeter\> | OPS-036 |
|
||
| PUT | `/meters/{id}` | 更新计量点 | EnergyMeter | ApiResponse\<EnergyMeter\> | OPS-036 |
|
||
| DELETE | `/meters/{id}` | 删除计量点 | - | ApiResponse\<Void\> | OPS-036 |
|
||
|
||
#### 能耗记录
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| POST | `/consumption` | 抄表记录 | RecordConsumptionRequest | ApiResponse\<EnergyConsumption\> | OPS-037 |
|
||
| GET | `/consumption/{meterId}` | 获取能耗记录 | startDate, endDate(可选) | ApiResponse\<List\<EnergyConsumption\>\> | OPS-037 |
|
||
|
||
#### 能耗统计
|
||
|
||
| 方法 | 路径 | 说明 | 参数 | 响应 | 功能ID |
|
||
|------|------|------|------|------|--------|
|
||
| GET | `/statistics/by-type` | 按类型统计 | projectId, month | ApiResponse\<Map\<EnergyType, BigDecimal\>\> | OPS-038 |
|
||
| GET | `/statistics/unit-consumption` | 单位面积能耗 | projectId, month | ApiResponse\<BigDecimal\> | OPS-039 |
|
||
|
||
**请求体定义**:
|
||
|
||
```java
|
||
// 抄表请求
|
||
RecordConsumptionRequest {
|
||
@NotNull UUID meterId;
|
||
@NotNull BigDecimal currentReading;
|
||
UUID recordedBy;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、业务规则
|
||
|
||
### 4.1 工单状态机
|
||
|
||
#### 完整状态流转图
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> PENDING : 创建工单
|
||
|
||
PENDING --> ASSIGNED : 派单(assign)
|
||
PENDING --> CANCELLED : 取消(cancel)
|
||
|
||
ASSIGNED --> IN_PROGRESS : 开始执行(start)
|
||
ASSIGNED --> SUSPENDED : 挂起(suspend)
|
||
ASSIGNED --> RETURNED : 退回(return)
|
||
ASSIGNED --> CANCELLED : 取消(cancel)
|
||
|
||
IN_PROGRESS --> COMPLETED : 完成(complete)
|
||
IN_PROGRESS --> SUSPENDED : 挂起(suspend)
|
||
IN_PROGRESS --> CANCELLED : 取消(cancel)
|
||
|
||
SUSPENDED --> IN_PROGRESS : 恢复(resume)\n[默认回到IN_PROGRESS]
|
||
SUSPENDED --> ASSIGNED : 恢复(resume)\n[previousStatus=ASSIGNED时]
|
||
|
||
RETURNED --> PENDING : 退回后重新变为待分配
|
||
|
||
COMPLETED --> VERIFIED : 验收(verify)
|
||
|
||
VERIFIED --> [*]
|
||
CANCELLED --> [*]
|
||
```
|
||
|
||
#### 8种状态说明
|
||
|
||
| 状态 | 中文 | 说明 | 可转入状态 |
|
||
|------|------|------|-----------|
|
||
| PENDING | 待分配 | 工单创建后的初始状态 | ASSIGNED, CANCELLED |
|
||
| ASSIGNED | 已派单 | 已分配负责人/服务商 | IN_PROGRESS, SUSPENDED, RETURNED, CANCELLED |
|
||
| IN_PROGRESS | 执行中 | 正在处理 | COMPLETED, SUSPENDED, CANCELLED |
|
||
| SUSPENDED | 已挂起 | 暂停处理，记录前一状态 | IN_PROGRESS, ASSIGNED（取决于previousStatus） |
|
||
| RETURNED | 已退回 | 被退回重新分配 | PENDING |
|
||
| COMPLETED | 已完成 | 处理完毕 | VERIFIED |
|
||
| VERIFIED | 已验收 | 验收通过 | 终态 |
|
||
| CANCELLED | 已取消 | 工单取消 | 终态 |
|
||
|
||
#### 每个流转的前置条件与自动处理
|
||
|
||
| 当前状态 | 操作 | 目标状态 | 前置条件 | 自动处理 |
|
||
|---------|------|---------|---------|---------|
|
||
| PENDING | assign | ASSIGNED | - | 设置 assignedTo/assignedVendor/assignedDate |
|
||
| ASSIGNED | start | IN_PROGRESS | - | 设置 actualStart = now() |
|
||
| IN_PROGRESS | complete | COMPLETED | - | 设置 actualEnd = now()，自动计算 actualHours |
|
||
| COMPLETED | verify | VERIFIED | - | 设置 verifiedBy/verifiedDate/rating |
|
||
| PENDING/ASSIGNED/IN_PROGRESS | cancel | CANCELLED | status 非 COMPLETED/VERIFIED | - |
|
||
| ASSIGNED/IN_PROGRESS | suspend | SUSPENDED | - | 保存 previousStatus = 当前状态 |
|
||
| SUSPENDED | resume | previousStatus | status == SUSPENDED | 恢复到 previousStatus，默认 IN_PROGRESS |
|
||
| ASSIGNED | return | PENDING | status == ASSIGNED | 清空 assignedTo/assignedVendor/assignedDate |
|
||
|
||
#### previousStatus回溯机制
|
||
|
||
```
|
||
挂起时:
|
||
workOrder.previousStatus = workOrder.status // 保存当前状态
|
||
workOrder.status = SUSPENDED
|
||
|
||
恢复时:
|
||
targetStatus = workOrder.previousStatus != null
|
||
? workOrder.previousStatus
|
||
: IN_PROGRESS // 默认恢复到IN_PROGRESS
|
||
workOrder.previousStatus = null // 清空
|
||
workOrder.status = targetStatus
|
||
```
|
||
|
||
#### 工单编号生成规则
|
||
|
||
```
|
||
格式: WO-YYYYMMDD-XXXX
|
||
示例: WO-20260518-0001
|
||
|
||
生成算法:
|
||
1. 日期前缀: "WO-" + LocalDate.now().format("yyyyMMdd") + "-"
|
||
2. 查询当天最大编号: findMaxWorkNoByPrefix(prefix + "%")
|
||
3. 序号递增: maxWorkNo存在时取后4位+1，否则从1开始
|
||
4. 格式化: String.format("%04d", sequence)
|
||
```
|
||
|
||
#### 完成工单自动计算工时
|
||
|
||
```java
|
||
actualHours = Duration.between(actualStart, actualEnd).toMinutes() / 60.0
|
||
// 精度：保留2位小数，四舍五入
|
||
```
|
||
|
||
### 4.2 维保任务触发机制
|
||
|
||
#### 4种触发类型
|
||
|
||
| 触发类型 | 枚举值 | 说明 | 优先级自动判定 |
|
||
|---------|--------|------|---------------|
|
||
| 计划触发 | PLAN | 由维保计划周期性触发 | MEDIUM |
|
||
| 巡检触发 | INSPECTION | 巡检发现异常时触发 | HIGH |
|
||
| 故障触发 | FAULT | 设备故障时触发 | HIGH（含紧急关键词时URGENT） |
|
||
| 手动创建 | MANUAL | 人工手动创建 | MEDIUM |
|
||
|
||
#### 自动优先级判定算法
|
||
|
||
```
|
||
输入: MaintenanceTask (taskType, triggerType, title, description)
|
||
|
||
1. IF taskType == EMERGENCY
|
||
→ return URGENT
|
||
|
||
2. IF triggerType == FAULT
|
||
→ 检查 title + description 是否包含紧急关键词
|
||
→ 紧急关键词: [困人, 漏水, 停电, 火灾, 爆炸, 漏电, 冒烟, 故障停机]
|
||
→ IF 包含任一关键词 → return URGENT
|
||
→ ELSE → return HIGH
|
||
|
||
3. IF triggerType == INSPECTION
|
||
→ return HIGH
|
||
|
||
4. IF triggerType == PLAN
|
||
→ return MEDIUM
|
||
|
||
5. 默认 → return MEDIUM
|
||
```
|
||
|
||
#### 维保任务状态机
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> PENDING : 创建任务
|
||
|
||
PENDING --> ASSIGNED : 分配(assign)
|
||
PENDING --> CANCELLED : 取消(cancel)
|
||
|
||
ASSIGNED --> IN_PROGRESS : 开始执行(start)
|
||
ASSIGNED --> CANCELLED : 取消(cancel)
|
||
|
||
IN_PROGRESS --> COMPLETED : 完成(complete/complete-details)
|
||
IN_PROGRESS --> CANCELLED : 取消(cancel)
|
||
|
||
COMPLETED --> VERIFIED : 验收(verify)
|
||
|
||
VERIFIED --> [*]
|
||
CANCELLED --> [*]
|
||
```
|
||
|
||
#### 维保任务与工单状态机差异
|
||
|
||
| 差异点 | WorkOrder | MaintenanceTask |
|
||
|--------|-----------|-----------------|
|
||
| 状态数量 | 8种（含SUSPENDED/RETURNED） | 6种（无SUSPENDED/RETURNED） |
|
||
| 完成方式 | 仅一种 complete | 两种：complete（简版）+ complete-details（详版） |
|
||
| 评分方式 | 验收时评分 | 验收时评分 + 独立 rate 接口 |
|
||
| 删除行为 | 逻辑删除（isDeleted=true） | 逻辑删除（设为CANCELLED） |
|
||
| 完成后联动 | 无 | 自动更新设备维保记录 |
|
||
| 挂起/恢复 | 支持 | 不支持 |
|
||
| 退回 | 支持（ASSIGNED→PENDING） | 不支持 |
|
||
|
||
#### 维保任务完成后联动
|
||
|
||
维保任务完成（completeTaskWithDetails）时自动更新设备信息：
|
||
|
||
```
|
||
1. 更新设备维保商:
|
||
equipment.maintenanceVendor = task.assignedVendor
|
||
|
||
2. 更新下次巡检日期（仅预防性维护）:
|
||
IF task.taskType == PREVENTIVE
|
||
THEN equipment.nextInspectionDate = now() + equipment.inspectionCycle
|
||
默认周期: 30天
|
||
|
||
3. 异常容错:
|
||
更新设备失败不影响工单完成（catch异常仅打印日志）
|
||
```
|
||
|
||
#### 任务编号生成规则
|
||
|
||
```
|
||
格式: EQ-YYYYMMDD-XXXX
|
||
示例: EQ-20260518-0001
|
||
|
||
生成算法: 与工单编号类似，前缀为 EQ-
|
||
```
|
||
|
||
### 4.3 巡检模板管理
|
||
|
||
**模板创建规则**:
|
||
- templateCode 自动生成（UNIQUE约束）
|
||
- 模板创建时可同时配置检查项列表（@Transient字段，需单独持久化）
|
||
- 模板状态默认为 ACTIVE
|
||
|
||
**模板复制规则**:
|
||
- 复制模板时创建新模板，名称使用传入的 newName
|
||
- 检查项同时复制到新模板
|
||
- 新模板的 templateCode 自动生成
|
||
|
||
**检查项配置**:
|
||
- InspectionItem 通过 templateId 关联模板
|
||
- isMandatory = true 的检查项为必检项，不可跳过
|
||
- isNormalRequired = true 的检查项需要判定正常/异常
|
||
- sortOrder 控制检查项的展示顺序
|
||
|
||
### 4.4 备件库存管理
|
||
|
||
#### 入库流程
|
||
|
||
```
|
||
1. 校验: quantity > 0
|
||
2. 查询备件: getSparePartById(sparePartId)
|
||
3. 更新库存: currentStock += quantity
|
||
4. 创建入库记录: RecordType=IN, balance=更新后库存
|
||
5. 生成记录编码: REC + IN + yyyyMMddHHmmss
|
||
```
|
||
|
||
#### 出库流程
|
||
|
||
```
|
||
1. 校验: quantity > 0
|
||
2. 查询备件: getSparePartById(sparePartId)
|
||
3. 校验库存: currentStock >= quantity
|
||
→ 不满足: 抛出 BusinessException("库存不足，当前库存：X，需要出库：Y")
|
||
4. 更新库存: currentStock -= quantity
|
||
5. 创建出库记录: RecordType=OUT, balance=更新后库存, relatedOrderId=关联工单
|
||
6. 生成记录编码: REC + OUT + yyyyMMddHHmmss
|
||
```
|
||
|
||
#### 低库存预警
|
||
|
||
```
|
||
预警条件: currentStock < safeStock
|
||
查询方式: sparePartRepository.findLowStockParts(projectId)
|
||
```
|
||
|
||
#### 库存余额计算
|
||
|
||
```
|
||
每次出入库操作后:
|
||
record.balance = sparePart.currentStock (操作后的库存余额)
|
||
```
|
||
|
||
#### 关联工单
|
||
|
||
- 出库时可指定 relatedOrderId 关联工单
|
||
- 用于追踪工单的备件消耗
|
||
|
||
#### 并发场景考虑
|
||
|
||
> 当前实现未使用乐观锁或悲观锁，存在并发安全问题：
|
||
|
||
| 并发场景 | 风险 | 当前处理 | 建议方案 |
|
||
|----------|------|----------|---------|
|
||
| 同时出库 | 库存超卖 | 无保护 | 添加 @Version 乐观锁或 SELECT FOR UPDATE 悲观锁 |
|
||
| 同时入库 | 库存计算错误 | 无保护 | 添加 @Version 乐观锁 |
|
||
| 并发读写 | 读到中间状态 | 无保护 | 使用数据库事务隔离级别 |
|
||
|
||
**建议并发控制方案**:
|
||
|
||
```java
|
||
// 方案1: 乐观锁（推荐）
|
||
@Version
|
||
private Long version;
|
||
|
||
// 出库时:
|
||
SparePart sp = repository.findById(id);
|
||
if (sp.getCurrentStock() < quantity) throw ...;
|
||
sp.setCurrentStock(sp.getCurrentStock() - quantity);
|
||
repository.save(sp); // version不匹配时抛出OptimisticLockException
|
||
|
||
// 方案2: 悲观锁
|
||
@Lock(LockModeType.PESSIMISTIC_WRITE)
|
||
@Query("SELECT sp FROM SparePart sp WHERE sp.id = :id")
|
||
SparePart findByIdForUpdate(@Param("id") UUID id);
|
||
```
|
||
|
||
### 4.5 能耗计量管理
|
||
|
||
#### 抄表流程
|
||
|
||
```
|
||
1. 校验计量点: meterId 存在且 status == ACTIVE
|
||
2. 获取上次抄表记录: findTopByMeterIdOrderByConsumptionDateDesc
|
||
3. 计算消耗量: consumption = currentReading - previousReading
|
||
4. 校验读数: consumption >= 0（当前读数不能小于上次读数）
|
||
5. 计算费用: amount = consumption x meter.unitPrice
|
||
6. 创建能耗记录: recordMethod=MANUAL
|
||
```
|
||
|
||
#### 消耗量计算
|
||
|
||
```
|
||
consumption = currentReading - previousReading
|
||
|
||
特殊情况:
|
||
- 首次抄表: previousReading = 0
|
||
- 读数倒退: 抛出 BusinessException("当前读数不能小于上次读数")
|
||
```
|
||
|
||
#### 费用计算
|
||
|
||
```
|
||
amount = consumption x meter.unitPrice
|
||
|
||
条件:
|
||
- meter.unitPrice 不为空
|
||
- consumption > 0
|
||
```
|
||
|
||
#### 按类型统计
|
||
|
||
```
|
||
输入: projectId, month (LocalDate)
|
||
1. 计算月份范围: startDate = month.withDayOfMonth(1), endDate = month.withDayOfMonth(length)
|
||
2. 初始化所有EnergyType为0
|
||
3. 查询项目总消耗: sumConsumptionByProjectAndDateRange
|
||
4. 当前实现: 将总消耗分配给LIGHTING类型（TODO: 应按meter.energyType汇总）
|
||
```
|
||
|
||
> 当前按类型统计实现不完整，所有消耗归入LIGHTING类型，需改为按meter.energyType分别汇总。
|
||
|
||
#### 单位面积能耗
|
||
|
||
```
|
||
输入: projectId, month
|
||
1. 获取项目所有ACTIVE状态的计量点
|
||
2. 遍历每个计量点，查询当月消耗量
|
||
3. 累加总消耗量
|
||
|
||
注意: 当前实现未除以建筑面积，仅返回总消耗量
|
||
TODO: 需要获取项目建筑面积，计算 单位面积能耗 = 总消耗量 / 建筑面积
|
||
```
|
||
|
||
### 4.6 工单明细管理
|
||
|
||
#### 3种明细类型
|
||
|
||
| 类型 | 枚举值 | 中文 | 用途 |
|
||
|------|--------|------|------|
|
||
| PART | 备件 | 记录工单使用的备件及费用 |
|
||
| INSPECTION_ITEM | 巡检项 | 记录工单的巡检检查项 |
|
||
| CHECKPOINT | 检查点 | 记录工单的关键检查点 |
|
||
|
||
#### 费用计算
|
||
|
||
```
|
||
前端计算:
|
||
item.totalPrice = item.quantity x item.unitPrice
|
||
partsCost = SUM(item.totalPrice) WHERE item.itemType == PART
|
||
totalCost = laborCost + partsCost
|
||
```
|
||
|
||
#### 批量添加
|
||
|
||
- 支持批量添加工单明细
|
||
- 受 BatchOperationValidator 限制（校验批量操作大小）
|
||
- 每条明细的 workOrderId 自动设置为当前工单ID
|
||
- sortOrder 控制明细展示顺序
|
||
|
||
---
|
||
|
||
## 五、执行约束
|
||
|
||
### 5.1 工单编号唯一性
|
||
|
||
- workNo 字段在数据库层设置 UNIQUE 约束
|
||
- 生成算法基于日期前缀+4位序号，按日期递增
|
||
- 编号格式: `WO-YYYYMMDD-XXXX`
|
||
- 同一天内序号从0001开始递增
|
||
|
||
### 5.2 任务编号唯一性
|
||
|
||
- taskNo 字段在数据库层设置 UNIQUE 约束
|
||
- 编号格式: `EQ-YYYYMMDD-XXXX`
|
||
- 生成算法与工单编号类似
|
||
|
||
### 5.3 备件库存非负约束
|
||
|
||
- 出库时校验: `currentStock >= quantity`
|
||
- 不满足时抛出 BusinessException(6104, "库存不足，当前库存：X，需要出库：Y")
|
||
- 入库数量必须 > 0，否则抛出 BusinessException(6102, "入库数量必须大于0")
|
||
- 出库数量必须 > 0，否则抛出 BusinessException(6103, "出库数量必须大于0")
|
||
|
||
### 5.4 能耗读数递增约束
|
||
|
||
- 抄表时校验: `currentReading >= previousReading`
|
||
- 不满足时抛出 BusinessException(6103, "当前读数不能小于上次读数")
|
||
- 首次抄表时 previousReading = 0
|
||
|
||
### 5.5 工单状态流转约束
|
||
|
||
- 只能按合法路径流转，非法流转抛出 RuntimeException
|
||
- COMPLETED/VERIFIED 状态不可取消
|
||
- SUSPENDED 状态只能恢复（resume），不能直接转为其他状态
|
||
- RETURNED 状态自动转为 PENDING
|
||
|
||
**合法流转矩阵**:
|
||
|
||
| 当前\目标 | PENDING | ASSIGNED | IN_PROGRESS | SUSPENDED | RETURNED | COMPLETED | VERIFIED | CANCELLED |
|
||
|----------|---------|----------|-------------|-----------|----------|-----------|----------|-----------|
|
||
| PENDING | - | V | - | - | - | - | - | V |
|
||
| ASSIGNED | - | - | V | V | V | - | - | V |
|
||
| IN_PROGRESS | - | - | - | V | - | V | - | V |
|
||
| SUSPENDED | - | V* | V* | - | - | - | - | - |
|
||
| RETURNED | V | - | - | - | - | - | - | - |
|
||
| COMPLETED | - | - | - | - | - | - | V | - |
|
||
| VERIFIED | - | - | - | - | - | - | - | - |
|
||
| CANCELLED | - | - | - | - | - | - | - | - |
|
||
|
||
> V* 表示 SUSPENDED 恢复时回到 previousStatus
|
||
|
||
### 5.6 维保计划周期约束
|
||
|
||
- cycleDays 必须 > 0（周期天数必须为正数）
|
||
- nextDate = lastDate + cycleDays（下次执行日期由周期推算）
|
||
- 计划状态变更：ACTIVE 可转为 INACTIVE 或 SUSPENDED
|
||
|
||
---
|
||
|
||
## 六、权限控制
|
||
|
||
| API路径 | 操作 | 所需权限 | 说明 |
|
||
|---------|------|----------|------|
|
||
| POST /api/wo/work-orders | 创建工单 | wo:work-order:create | 需项目级权限 |
|
||
| GET /api/wo/work-orders | 查询工单 | wo:work-order:read | 需项目级权限 |
|
||
| PUT /api/wo/work-orders/{id} | 更新工单 | wo:work-order:update | 需项目级权限 |
|
||
| DELETE /api/wo/work-orders/{id} | 删除工单 | wo:work-order:delete | 需项目级权限 |
|
||
| POST /api/wo/work-orders/{id}/assign | 派单 | wo:work-order:assign | 需项目级权限 |
|
||
| POST /api/wo/work-orders/{id}/start | 开始执行 | wo:work-order:execute | 需项目级权限 |
|
||
| POST /api/wo/work-orders/{id}/complete | 完成工单 | wo:work-order:execute | 需项目级权限 |
|
||
| POST /api/wo/work-orders/{id}/verify | 验收工单 | wo:work-order:verify | 需项目级权限 |
|
||
| POST /api/wo/work-orders/{id}/cancel | 取消工单 | wo:work-order:cancel | 需项目级权限 |
|
||
| POST /api/wo/work-orders/{id}/suspend | 挂起工单 | wo:work-order:suspend | 需项目级权限 |
|
||
| POST /api/wo/work-orders/{id}/resume | 恢复工单 | wo:work-order:resume | 需项目级权限 |
|
||
| POST /api/wo/work-orders/{id}/return | 退回工单 | wo:work-order:return | 需项目级权限 |
|
||
| POST /api/ops/maintenance-tasks | 创建维保任务 | ops:maintenance-task:create | 需项目级权限 |
|
||
| POST /api/ops/maintenance-tasks/{id}/assign | 分配任务 | ops:maintenance-task:assign | 需项目级权限 |
|
||
| POST /api/ops/maintenance-tasks/{id}/start | 开始执行 | ops:maintenance-task:execute | 需项目级权限 |
|
||
| POST /api/ops/maintenance-tasks/{id}/complete | 完成任务 | ops:maintenance-task:execute | 需项目级权限 |
|
||
| POST /api/ops/maintenance-tasks/{id}/verify | 验收任务 | ops:maintenance-task:verify | 需项目级权限 |
|
||
| POST /api/ops/spare-parts/in-stock | 入库 | ops:spare-part:stock-in | 需项目级权限 |
|
||
| POST /api/ops/spare-parts/out-stock | 出库 | ops:spare-part:stock-out | 需项目级权限 |
|
||
| POST /api/ops/energy/consumption | 抄表 | ops:energy:record | 需项目级权限 |
|
||
|
||
> 当前实现中权限控制尚未集成Spring Security，以上为设计预期权限矩阵。
|
||
|
||
---
|
||
|
||
## 七、例外情况处理
|
||
|
||
| 例外场景 | 触发条件 | 处理方式 | 错误码/信息 |
|
||
|----------|----------|----------|------------|
|
||
| 工单状态流转非法 | 从PENDING直接complete | 抛出RuntimeException | "只能完成进行中的工单" |
|
||
| 工单已完成后取消 | status=COMPLETED/VERIFIED时cancel | 抛出RuntimeException | "无法取消已完成的工单" |
|
||
| 挂起非ASSIGNED/IN_PROGRESS工单 | status不合法时suspend | 抛出RuntimeException | "只能挂起已派单或执行中的工单" |
|
||
| 恢复非SUSPENDED工单 | status!=SUSPENDED时resume | 抛出RuntimeException | "只能恢复已挂起的工单" |
|
||
| 退回非ASSIGNED工单 | status!=ASSIGNED时return | 抛出RuntimeException | "只能退回已派单的工单" |
|
||
| 备件库存不足 | 出库数量>当前库存 | 抛出BusinessException | 6104 "库存不足，当前库存：X，需要出库：Y" |
|
||
| 入库数量非法 | quantity <= 0 | 抛出BusinessException | 6102 "入库数量必须大于0" |
|
||
| 出库数量非法 | quantity <= 0 | 抛出BusinessException | 6103 "出库数量必须大于0" |
|
||
| 能耗读数倒退 | currentReading < previousReading | 抛出BusinessException | 6103 "当前读数不能小于上次读数" |
|
||
| 能源仪表不存在 | meterId无效 | 抛出BusinessException | 6101 "能源仪表不存在" |
|
||
| 仪表非ACTIVE状态 | 抄表时meter.status!=ACTIVE | 抛出BusinessException | 6102 "只能对ACTIVE状态的仪表进行抄表" |
|
||
| 维保计划关联设备不存在 | equipmentId无效 | 数据库外键约束 | 需添加业务校验 |
|
||
| 维保任务不存在 | taskId无效 | 抛出BusinessException | ErrorCode.NOT_FOUND "维保工单不存在" |
|
||
| 工单不存在 | workOrderId无效或已删除 | 抛出RuntimeException | "工单不存在: {id}" |
|
||
| 维保任务评分越界 | rating < 1 或 rating > 5 | 抛出BusinessException | 6006 "评分必须在1-5之间" |
|
||
| 维保任务评分状态非法 | 非COMPLETED/VERIFIED状态评分 | 抛出BusinessException | 6005 "只有已完成或已验收的工单才能评分" |
|
||
| 巡检模板被引用不能删除 | 模板被巡检记录引用 | - | 当前无校验，建议增加 |
|
||
| 备件不存在 | sparePartId无效 | 抛出BusinessException | 6101 "备件不存在" |
|
||
|
||
---
|
||
|
||
**附录：已知代码问题与改进建议**
|
||
|
||
| 问题 | 位置 | 影响 | 建议 |
|
||
|------|------|------|------|
|
||
| 备件出入库无并发控制 | SparePartServiceImpl | 高并发下可能库存超卖 | 添加 @Version 乐观锁或 SELECT FOR UPDATE |
|
||
| 能耗按类型统计实现不完整 | EnergyConsumptionServiceImpl | 所有消耗归入LIGHTING类型 | 按 meter.energyType 分别汇总 |
|
||
| 单位面积能耗未除以建筑面积 | EnergyConsumptionServiceImpl | 返回的是总消耗量而非单位面积能耗 | 获取项目建筑面积做除法 |
|
||
| 工单查询参数互斥 | WorkOrderController/MaintenanceTaskController | 多条件同时传入只生效一个 | 改为 Specification 动态查询 |
|
||
| 维保任务查询无分页 | MaintenanceTaskController | 数据量大时可能OOM | 改为分页查询 |
|
||
| 工单删除/退回使用RuntimeException | WorkOrderServiceImpl | 异常信息不够结构化 | 改为 BusinessException + ErrorCode |
|
||
| 维保任务删除实际是取消 | MaintenanceTaskServiceImpl | deleteTask 实际设置 status=CANCELLED | 命名与行为不一致，建议重命名 |
|
||
| 前后端状态枚举不一致 | maintenance.ts vs MaintenanceTask | 前端含ACCEPTED，后端含ASSIGNED/VERIFIED | 统一前后端状态定义 |
|
||
| 前端维保计划两套API | maintenance.ts + maintenance-plan.ts | 接口重复，维护困难 | 统一为一套API |
|
||
| 工单无流转记录 | WorkOrderServiceImpl | 无法追溯工单状态变更历史 | 新增 WorkOrderFlow 实体 |
|