# Ether 项目需求一致性评估报告

> **评估日期**: 2026-04-23
> **评估范围**: AUTH / MDM / ASSET / OPS / FINANCE 五大领域
> **数据来源**: REVERSE-AUTH.md / REVERSE-MDM.md / REVERSE-ASSET.md / REVERSE-OPS.md / REVERSE-FINANCE.md 差异对比章节

---

## 一、评估概述

### 1.1 评估方法

本评估基于代码反推设计文档与原始需求文档的逐项对比，采用以下方法：

1. **逐项比对**：将每个领域的反推设计文档中"差异对比"章节的每一行差异记录，按照统一评估标准进行分类
2. **分类统计**：按领域 × 评估等级进行交叉统计，计算数量和占比
3. **严重度排序**：根据差异对核心业务功能的影响程度，识别关键差异和风险点
4. **改进建议**：基于差异分析结果，按优先级提出改进建议

### 1.2 评估范围

| 领域 | 反推文档 | 原需求文档 | 差异对比项数 |
|------|---------|-----------|------------|
| AUTH（认证） | REVERSE-AUTH.md | 05-AUTH.md | 47 |
| MDM（主数据） | REVERSE-MDM.md | 02-SPACE_NODE_DESIGN.md | 33 |
| ASSET（资产） | REVERSE-ASSET.md | 03-ASSET.md | 50 |
| OPS（运营） | REVERSE-OPS.md | 02-OPERATIONS.md | 57 |
| FINANCE（财务） | REVERSE-FINANCE.md | 04-FINANCE.md | 33 |
| **合计** | | | **220** |

### 1.3 评估标准定义

| 标识 | 等级 | 定义 | 判定依据 |
|------|------|------|---------|
| ✅ | 符合 | 代码实现与需求文档完全一致 | 字段/接口/规则完全匹配，或双方均未实现 |
| 🟡 | 部分符合 | 代码实现与需求文档部分一致，存在差异但不影响核心功能 | 字段名不同但语义一致、枚举值扩展、实现方式不同但效果等价 |
| ❌ | 不符合 | 代码实现与需求文档不一致，影响核心功能 | 核心字段缺失、关键枚举值不同、核心逻辑未实现 |
| ⏳ | 未实现 | 需求文档中有定义但代码未实现 | 实体/接口/功能完全不存在于代码中 |
| ➕ | 超出实现 | 代码实现了但需求文档中未定义 | 新增实体/接口/功能，属于需求文档未覆盖的扩展 |

---

## 二、一致性评估矩阵表

### 2.1 AUTH（认证领域）

#### 实体差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| Role.type（SYSTEM/CUSTOM） | 🟡 | 实际使用三级分类 SYSTEM/PROJECT/DEPARTMENT |
| Role 业务属性（businessType/terminalType/isFrontline） | ⏳ | 未实现角色业务属性扩展 |
| Role.status（enabled Boolean） | 🟡 | 实际使用 RoleStatus 枚举（ENABLED/DISABLED） |
| Permission 完整结构 | 🟡 | 简化权限结构，用 parentCode 替代 parentId，缺少菜单路由属性 |
| Permission.type（枚举） | 🟡 | 实际使用 String 类型而非枚举 |
| UserRole 关联（含 projectId/isDefault） | 🟡 | 简化为 M2M 中间表，去掉项目隔离和默认角色标记 |
| OperationLog 表结构 | 🟡 | 不同表名和字段结构，增加目标追踪和租户ID |
| VisitorCredential 实体 | ⏳ | 访客凭证未在认证模块实现 |
| EnterpriseUser 扩展实体 | ➕ | 新增企业员工扩展 |
| ProjectStaff 扩展实体 | ➕ | 新增项目员工扩展 |
| ProjectStaffRole 关联 | ➕ | 新增项目级角色分配 |
| Resident 住户实体 | ➕ | 新增住户实体 |
| ResidentSpace 住户房屋关联 | ➕ | 新增住户房屋绑定 |
| Space 房屋空间实体 | ➕ | 新增房屋空间实体 |
| UserProject 用户项目关联 | ➕ | 新增用户项目多对多 |
| DataAccess 数据访问授权 | ➕ | 新增细粒度数据访问控制 |
| Dept 部门实体 | ➕ | 新增树形部门结构 |
| SysConfig 系统配置 | ➕ | 新增键值对配置 |
| User.userType | ➕ | 新增用户类型区分 |
| User.deptId | ➕ | 新增部门关联 |

#### API 差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| API 路径前缀（/api/v1/auth） | 🟡 | 实际去掉版本号 v1 |
| 认证接口（changePassword/userPermissions） | 🟡 | 缺少独立端点，/me 替代 currentUser |
| 用户状态修改独立端点 | 🟡 | 合并到通用更新接口 |
| 权限树端点（GET /permissions/tree） | ⏳ | 未实现 |
| 权限校验端点（POST /check） | ⏳ | 未实现 |
| 用户菜单端点（GET /users/{id}/menus） | ⏳ | 未实现 |
| 用户权限查询端点（GET /users/{id}/permissions） | ⏳ | 未实现 |
| 部门管理 API | ➕ | 新增完整 CRUD + 树 + 成员查询 |
| 项目成员管理 API | ➕ | 新增完整 CRUD + 可用成员查询 |
| 数据访问授权 API | ➕ | 新增 grant/revoke/query |
| 审计日志 API | ➕ | 新增完整查询 + 统计 + 筛选 |
| 系统配置 API | ➕ | 新增完整 CRUD + 批量更新 |
| 企业员工列表 API | ➕ | 新增 |
| 用户项目关联 API | ➕ | 新增完整 CRUD |

#### 业务规则差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| 13 个预定义角色 | 🟡 | 实际通过数据库动态管理，无硬编码预定义 |
| DataScopeHelper SQL 生成 | 🟡 | 实际用 DataScopeService 提供判断方法，未实现 SQL 自动注入 |
| 项目上下文传递 | ✅ | 基本一致，通过 X-Project-ID Header |
| 状态驱动权限 | ⏳ | 未在认证模块实现 |
| 访客凭证管理 | ⏳ | 完整的二维码生成/验证流程未实现 |
| 登录失败锁定 | ➕ | 新增 Redis 实现，5 次失败锁 10 分钟 |
| 密码强度校验 | ➕ | 新增完整强度规则 + 弱密码检测 |
| 旧密码兼容 | ➕ | 新增密码迁移策略 |
| 审计日志增强 | ➕ | 新增异步保存、30 天窗口、90 天归档 |
| 项目成员角色 | ➕ | 新增双层角色分配机制 |
| 部门类型 | ➕ | 新增 5 种部门类型 |
| 住户认证 | ➕ | 新增 4 种认证状态 |
| 数据访问授权 | ➕ | 新增通用数据访问控制 |

---

### 2.2 MDM（主数据管理领域）

#### 数据模型差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| API 路径前缀（/api/v1/mdm） | 🟡 | 去掉版本号 v1 |
| code 字段 + UNIQUE 约束 | ❌ | 无 code 列，project_code 列名与实际存储不匹配 |
| PostGIS 字段（location/boundary） | ⏳ | 地图服务未实现，仅保留经纬度数值字段 |
| attributes 字段（JSONB） | 🟡 | 降级为 String(2000) 存储 JSON |
| 设备扩展字段 | ➕ | SpaceNode 内嵌设备扩展字段，isEquipment 标记 |
| NodeType 枚举 | ➕ | 增加 PUBLIC_ROOM（公共用房）类型 |
| 软删除 | ➕ | 实际采用 isDeleted 软删除 |
| 唯一约束（UNIQUE(project_id, code)） | ❌ | 空间编码唯一性未在数据库层面约束 |
| 索引（GIST/GIN） | 🟡 | 仅普通 B-tree 索引，无空间索引和 JSON 索引 |

#### API 接口差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| 树形查询（全局树） | 🟡 | 实际按项目维度查询，更合理 |
| 祖先节点查询 | ⏳ | 未实现 |
| 子孙节点查询 | ⏳ | 未实现（可通过 treePath LIKE 替代） |
| 移动节点 | ⏳ | 未实现 |
| 类型快捷查询 | 🟡 | 统一为按类型查询，更通用 |
| 批量更新 | ⏳ | 未实现 |
| 批量删除 | ⏳ | 未实现 |
| 导入模板下载 | ⏳ | 未实现 |
| 数据导出 | ⏳ | 未实现 |
| 地图相关 API（标注/边界/路径） | ⏳ | 地图服务完全未实现 |
| 统计分析 API | ⏳ | 空间统计接口缺失 |
| 删除前检查 | ➕ | 新增安全检查接口 |
| 级联删除 | ➕ | 新增级联删除接口 |
| 设备管理集成 | ➕ | 设备 CRUD 集成在 SpaceNodeController |
| Excel 导入 | 🟡 | 仅设备导入，空间节点批量导入未实现 |
| 楼层信息查询 | ➕ | 新增楼栋楼层信息接口 |

#### 前端差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| 地图模式（高德地图集成） | ⏳ | 地图功能完全未开发 |
| MapEditor 组件 | ⏳ | 未实现 |
| 空间编码自动生成 | ⏳ | 未实现 |
| 批量创建房间（模板） | 🟡 | 仅支持 DTO 列表批量创建 |

#### 业务规则差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| 设备模型（独立 Equipment） | ❌ | SpaceNode 内嵌设备扩展字段，与 module-asset 独立 Equipment 并存 |
| 项目统计（数据库视图） | 🟡 | 实际采用实体快照模式，需手动同步 |
| 空间编码自动生成 | ⏳ | 未实现 |
| PostGIS 空间查询 | ⏳ | 未使用空间数据库能力 |

---

### 2.3 ASSET（资产管理领域）

#### 数据模型差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| 设备类型枚举（8 种） | 🟡 | 实际 10 种，枚举值名称和数量均不同 |
| 设备状态枚举 | 🟡 | 枚举值名称不同（NORMAL→ACTIVE, FAULT→INACTIVE） |
| 专业扩展表 | ➕ | 新增 4 张扩展表（电梯/暖通/消防/能源） |
| 系统类型（9 种） | ➕ | 新增商业地产 8 大系统分类 |
| 归属管理 | ➕ | 新增 4 种归属类型 + 3 种主体 |
| 健康评分算法 | ➕ | 新增 MTBF/MTTR 完整算法 |
| 故障历史 | ➕ | 新增 4 级故障/4 种类型/4 种修复结果 |
| 设备照片/文档 | ➕ | 新增 JSONB 内嵌 |
| 维保计划 | 🟡 | 迁移至独立 API |
| 维保记录 | 🟡 | 升级为维保工单 |
| 设备编码字段（code） | 🟡 | 字段名改为 equipmentCode |
| 设备名称字段（name） | 🟡 | 字段名改为 equipmentName |
| 位置描述（locationDesc） | 🟡 | 字段名改为 installationLocation |
| 品牌字段（brand） | 🟡 | 使用 manufacturer 替代 |
| 规格字段（specifications） | ⏳ | 未实现 |
| 负责人（managerId/managerName/contactPhone） | ⏳ | 改为维保商字段 |
| 二维码（qrCode） | ⏳ | 未实现 |
| Excel 导入导出 | ➕ | 新增含校验的导入导出 |
| 批量删除 | ➕ | 新增 batch-delete 接口 |
| 财务信息 | ➕ | 实际更丰富 |
| 特种设备 | ➕ | 新增特种设备管理 |
| 能耗标准 | ➕ | 新增能耗标准字段 |

#### 功能差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| 设备 CRUD | ✅ | 一致 |
| 设备与空间关联 | ✅ | 一致 |
| 设备二维码 | ⏳ | 未实现 |
| 故障自动工单（事件驱动） | 🟡 | 部分实现，非事件驱动 |
| IoT 集成 | ⏳ | 未实现 |
| 维保到期提醒 | 🟡 | 仅前端展示，无后端定时提醒 |
| 设备健康预测 | ➕ | 超出原需求，完整算法+前端图表 |
| 归属主体管理 | ➕ | 超出原需求 |
| 专业扩展表 | ➕ | 超出原需求 |
| Excel 导入导出 | ➕ | 超出原需求 |
| MTBF/MTTR | ➕ | 超出原需求 |
| 设备照片/文档 | ➕ | 超出原需求 |
| 维保计划 | 🟡 | 架构调整至独立 API |
| 维保记录 | 🟡 | 升级为维保工单 |

#### 实现状态

| 需求项 | 评估 | 说明 |
|--------|------|------|
| 设备主表 CRUD | ✅ | 完成 |
| 4 张扩展表 | ➕ | 完成 |
| 健康评分算法 | ➕ | 完成 |
| 故障历史管理 | ➕ | 完成 |
| 归属主体管理 | ➕ | 完成 |
| Excel 导入导出 | ➕ | 完成 |
| 设备统计 | ✅ | 完成 |
| 前端设备列表 | ✅ | 完成 |
| 前端设备详情 | ✅ | 完成 |
| 前端健康预测 | ➕ | 完成 |
| 维保完成率计算 | 🟡 | TODO 标记，暂返回 1.0 |
| 设备二维码 | ⏳ | 未实现 |
| IoT 集成 | ⏳ | 未实现 |
| 故障自动工单（事件驱动） | ⏳ | 未实现 |
| 维保到期定时提醒 | ⏳ | 未实现 |

---

### 2.4 OPS（运营管理领域）

#### 状态机差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| 工单初始状态（CREATED） | 🟡 | 实际为 PENDING（合并创建与待分配） |
| 接单状态（ACCEPTED） | ⏳ | 不存在，ASSIGNED 直接进入 IN_PROGRESS |
| 关闭状态（CLOSED） | ❌ | 不存在，用 VERIFIED 替代 |
| 验收状态 | ➕ | 新增 VERIFIED（已验收） |
| 挂起状态（SUSPENDED） | ⏳ | 不存在，未支持挂起/恢复 |
| 退回状态（RETURNED） | ⏳ | 不存在，未支持退回重分配 |
| 取消状态 | ➕ | 新增 CANCELLED |

#### 实体差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| WorkOrderFlow（工单流转记录） | ⏳ | 未实现 |
| NotificationChannel（通知渠道） | ⏳ | 未实现 |
| NotificationTemplate（消息模板） | ⏳ | 未实现 |
| NotificationRule（通知规则） | ⏳ | 未实现 |
| NotificationHistory（通知历史） | ⏳ | 未实现 |
| WorkOrderItem（工单明细） | ➕ | 新增 |
| MaintenancePlan（维保计划） | ➕ | 新增 |
| MaintenanceTask（维保任务） | ➕ | 新增 |
| InspectionTemplate（巡检模板） | ➕ | 新增 |
| InspectionItem（巡检项） | ➕ | 新增 |

#### 字段差异（WorkOrder）

| 需求项 | 评估 | 说明 |
|--------|------|------|
| orderNo 格式 | 🟡 | WO2024021000001 → WO-YYYYMMDD-XXXX |
| orderType 枚举 | ❌ | 枚举值完全不同 |
| source 枚举 | ❌ | 枚举值完全不同 |
| 报修人信息（reporterId/Name/Phone/Address） | ⏳ | 未实现 |
| assigneeId（UUID 引用） | 🟡 | 实际用 String 而非用户 ID 引用 |
| 时间字段 | 🟡 | 字段名和粒度不同 |
| materialCost → partsCost | 🟡 | 字段名不同 |
| resultDescription | 🟡 | 拆分为 result + faultCause + solution |
| satisfactionScore/Comment | 🟡 | 简化为 rating + remark |
| images/attachments | 🟡 | 实际用 JSONB 数组 |
| attributes（JSONB） | ⏳ | 未实现扩展属性 |
| spaceNodeId → spaceId | 🟡 | 字段名不同 |
| planId/triggerType | ➕ | 新增，关联维保计划 |
| assignedVendor | ➕ | 新增，支持服务商 |
| laborCost/partsCost/totalCost | ➕ | 新增，费用明细 |
| signature | ➕ | 新增，签名确认 |

#### API 差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| API 版本（/api/v1/ops） | 🟡 | 实际为 /api/wo |
| 分页查询 | ❌ | 实际无分页，全量返回 |
| 接单接口（POST /{id}/accept） | ⏳ | 不存在 |
| 关闭接口（POST /{id}/close） | ❌ | 不存在，用 verify 替代 |
| 挂起/恢复接口 | ⏳ | 未实现 |
| 流转记录接口 | ⏳ | 未实现 |
| 通知 API | ⏳ | 消息通知系统未实现 |
| 统计 API | 🟡 | 嵌入工单 Controller 而非独立 |
| 工单明细 API | ➕ | 新增 |
| 维保任务 API | ➕ | 新增完整 CRUD + 状态流转 |

#### 业务规则差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| 工单编号格式 | 🟡 | 格式不同 |
| 通知触发 | ⏳ | 消息通知未实现 |
| SLA 监控 | ✅ | 双方均未实现 |
| 智能派单 | ✅ | 双方均未实现 |
| 维保优先级自动判定 | ➕ | 新增 |
| 设备联动更新 | ➕ | 新增 |
| 维保任务双完成接口 | ➕ | 新增 |
| 删除策略 | ❌ | WorkOrder 物理删除 vs MaintenanceTask 逻辑删除，不一致 |

#### 前端差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| 维保计划 API（两套） | ❌ | 前端分裂为两套 API |
| 维保计划触发类型 | ❌ | 前后端不一致 |
| 维保任务状态 | ❌ | 前后端不一致 |
| 巡检模板 | ➕ | 新增 |
| 巡检标准项 | ➕ | 新增 |
| 巡检记录 | ➕ | 新增 |

---

### 2.5 FINANCE（财务领域）

#### 实体差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| FeeItem 收费项目实体 | ⏳ | 完全缺失 |
| FeeBill 账单实体 | ⏳ | 完全缺失 |
| FeePayment 支付记录实体 | ⏳ | 完全缺失 |
| FeeRefund 退款实体 | ⏳ | 完全缺失 |
| fin_fee_item 表 | ⏳ | 完全缺失 |
| fin_fee_bill 表 | ⏳ | 完全缺失 |
| fin_fee_payment 表 | ⏳ | 完全缺失 |
| fin_fee_refund 表 | ⏳ | 完全缺失 |
| EnergyMeter 实体 | ➕ | 在 module-mdm 中实现，设计文档遗漏 |
| EnergyConsumption 实体 | ➕ | 在 module-mdm 中实现，设计文档遗漏 |
| ops_energy_meter 表 | ➕ | 已创建，设计文档遗漏 |
| ops_energy_consumption 表 | ➕ | 已创建，设计文档遗漏 |

#### 功能差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| 收费项目管理（CRUD） | ❌ | 设计文档标注已实现，实际未实现 |
| 账单生成 | ❌ | 设计文档标注已实现，实际未实现 |
| 账单状态流转 | ❌ | 设计文档标注已实现，实际未实现 |
| 支付处理 | ❌ | 设计文档标注已实现，实际未实现 |
| 费用催缴（定时任务） | ❌ | 设计文档标注已实现，实际未实现 |
| 滞纳金计算 | ❌ | 设计文档标注已实现，实际未实现 |
| 退款流程 | ✅ | 双方均未实现 |
| 支付网关对接 | ✅ | 双方均未实现 |
| 财务报表 | ✅ | 双方均未实现 |
| 能耗计量点管理 | ➕ | 设计文档遗漏 |
| 能耗抄表录入 | ➕ | 设计文档遗漏 |
| 能耗费用计算 | ➕ | 设计文档遗漏（简化实现） |
| 能耗统计分析 | ➕ | 设计文档遗漏（有缺陷） |

#### 枚举差异

| 需求项 | 评估 | 说明 |
|--------|------|------|
| FeeType 收费类型 | ⏳ | 完全缺失 |
| BillingMethod 计费方式 | ⏳ | 完全缺失 |
| BillStatus 账单状态 | ⏳ | 完全缺失 |
| PaymentMethod 支付方式 | ⏳ | 完全缺失 |
| PaymentStatus 支付状态 | ⏳ | 完全缺失 |
| RefundStatus 退款状态 | ⏳ | 完全缺失 |
| EnergyType 能源类型 | ➕ | 设计文档遗漏 |
| RecordMethod 记录方式 | ➕ | 设计文档遗漏 |

---

## 三、各领域一致性统计

### 3.1 AUTH（认证领域）

| 评估等级 | 数量 | 占比 |
|---------|------|------|
| ✅ 符合 | 1 | 2.1% |
| 🟡 部分符合 | 12 | 25.5% |
| ❌ 不符合 | 0 | 0% |
| ⏳ 未实现 | 8 | 17.0% |
| ➕ 超出实现 | 26 | 55.3% |
| **合计** | **47** | **100%** |

**特征分析**：AUTH 领域是超出实现最多的领域（55.3%），实际代码在用户扩展、项目成员管理、部门管理、数据访问授权、安全策略等方面远超原需求定义。但权限树、权限校验、用户菜单、访客凭证等原需求功能未实现。

### 3.2 MDM（主数据管理领域）

| 评估等级 | 数量 | 占比 |
|---------|------|------|
| ✅ 符合 | 0 | 0% |
| 🟡 部分符合 | 8 | 24.2% |
| ❌ 不符合 | 3 | 9.1% |
| ⏳ 未实现 | 14 | 42.4% |
| ➕ 超出实现 | 8 | 24.2% |
| **合计** | **33** | **100%** |

**特征分析**：MDM 领域未实现比例最高（42.4%），主要因为地图服务（PostGIS）、空间编码、统计分析、导入导出等功能完全缺失。空间编码唯一约束和设备模型不一致是不符合项的主要来源。

### 3.3 ASSET（资产管理领域）

| 评估等级 | 数量 | 占比 |
|---------|------|------|
| ✅ 符合 | 6 | 12.0% |
| 🟡 部分符合 | 13 | 26.0% |
| ❌ 不符合 | 0 | 0% |
| ⏳ 未实现 | 9 | 18.0% |
| ➕ 超出实现 | 22 | 44.0% |
| **合计** | **50** | **100%** |

**特征分析**：ASSET 领域超出实现比例较高（44.0%），在健康预测、归属管理、专业扩展表、导入导出等方面远超原需求。但设备二维码、IoT 集成、事件驱动工单等原需求功能未实现。无不符合项，差异主要体现在扩展和未实现。

### 3.4 OPS（运营管理领域）

| 评估等级 | 数量 | 占比 |
|---------|------|------|
| ✅ 符合 | 2 | 3.5% |
| 🟡 部分符合 | 12 | 21.1% |
| ❌ 不符合 | 9 | 15.8% |
| ⏳ 未实现 | 15 | 26.3% |
| ➕ 超出实现 | 19 | 33.3% |
| **合计** | **57** | **100%** |

**特征分析**：OPS 领域不符合项最多（9 项，15.8%），主要因为工单状态机完全重构、工单类型/来源枚举完全不同、分页查询缺失、前后端不一致等。消息通知系统（5 个实体）完全未实现是最大的缺失。实际实现侧重"运维工单+维保管理+巡检模板"，与需求文档侧重"运营调度+消息通知"方向不同。

### 3.5 FINANCE（财务领域）

| 评估等级 | 数量 | 占比 |
|---------|------|------|
| ✅ 符合 | 3 | 9.1% |
| 🟡 部分符合 | 0 | 0% |
| ❌ 不符合 | 6 | 18.2% |
| ⏳ 未实现 | 14 | 42.4% |
| ➕ 超出实现 | 10 | 30.3% |
| **合计** | **33** | **100%** |

**特征分析**：FINANCE 领域是最严重的领域。核心财务功能（FeeItem/FeeBill/FeePayment/FeeRefund）完全未实现，但设计文档 04-FINANCE.md 标注为"已实现"，存在严重的文档与代码不一致问题。仅能耗管理在 module-mdm 中有实现，但属于设计文档遗漏。

---

## 四、总体一致性统计

### 4.1 汇总统计

| 评估等级 | AUTH | MDM | ASSET | OPS | FINANCE | **合计** | **占比** |
|---------|------|-----|-------|-----|---------|---------|---------|
| ✅ 符合 | 1 | 0 | 6 | 2 | 3 | **12** | **5.5%** |
| 🟡 部分符合 | 12 | 8 | 13 | 12 | 0 | **45** | **20.5%** |
| ❌ 不符合 | 0 | 3 | 0 | 9 | 6 | **18** | **8.2%** |
| ⏳ 未实现 | 8 | 14 | 9 | 15 | 14 | **60** | **27.3%** |
| ➕ 超出实现 | 26 | 8 | 22 | 19 | 10 | **85** | **38.6%** |
| **合计** | 47 | 33 | 50 | 57 | 33 | **220** | **100%** |

### 4.2 一致性指标

| 指标 | 计算方式 | 数值 |
|------|---------|------|
| 完全一致率 | ✅ / 总计 | 5.5% |
| 基本一致率 | (✅ + 🟡) / 总计 | 25.9% |
| 偏差率 | ❌ / 总计 | 8.2% |
| 缺失率 | ⏳ / 总计 | 27.3% |
| 扩展率 | ➕ / 总计 | 38.6% |
| 需求覆盖率 | (✅ + 🟡 + ❌) / (✅ + 🟡 + ❌ + ⏳) | 53.3% |

### 4.3 各领域一致性对比

| 领域 | 完全一致率 | 基本一致率 | 偏差率 | 缺失率 | 扩展率 | 综合评级 |
|------|-----------|-----------|--------|--------|--------|---------|
| AUTH | 2.1% | 27.7% | 0% | 17.0% | 55.3% | 🟡 B（扩展丰富，部分缺失） |
| MDM | 0% | 24.2% | 9.1% | 42.4% | 24.2% | 🔴 D（缺失严重，偏差较大） |
| ASSET | 12.0% | 38.0% | 0% | 18.0% | 44.0% | 🟢 A-（超出预期，少量缺失） |
| OPS | 3.5% | 24.6% | 15.8% | 26.3% | 33.3% | 🟠 C（方向偏离，缺失较多） |
| FINANCE | 9.1% | 9.1% | 18.2% | 42.4% | 30.3% | 🔴 D（核心缺失，文档失真） |

---

## 五、关键差异分析（Top 10）

按严重程度从高到低排序：

### 🔴 #1 财务域核心功能完全缺失

| 维度 | 内容 |
|------|------|
| 领域 | FINANCE |
| 严重度 | 🔴 致命 |
| 现状 | FeeItem/FeeBill/FeePayment/FeeRefund 四大实体及所有相关功能均未在代码中实现 |
| 影响 | 物业收费、账单管理、支付处理等核心财务流程无法运行 |
| 文档问题 | 04-FINANCE.md 标注"已实现"与实际严重不符，存在文档失真 |

### 🔴 #2 运营域消息通知系统完全缺失

| 维度 | 内容 |
|------|------|
| 领域 | OPS |
| 严重度 | 🔴 致命 |
| 现状 | NotificationChannel/Template/Rule/History 四个实体全部未实现 |
| 影响 | 工单状态变更无法自动通知相关人员，运营调度效率低下 |

### 🔴 #3 运营域工单状态机与需求完全不同

| 维度 | 内容 |
|------|------|
| 领域 | OPS |
| 严重度 | 🔴 严重 |
| 现状 | 需求定义 7 状态（CREATED/ASSIGNED/ACCEPTED/IN_PROGRESS/COMPLETED/CLOSED/SUSPENDED），实际 6 状态（PENDING/ASSIGNED/IN_PROGRESS/COMPLETED/VERIFIED/CANCELLED） |
| 影响 | 缺少接单确认、挂起/恢复、退回重分配等关键流程环节 |

### 🔴 #4 运营域工单类型和来源枚举与需求完全不同

| 维度 | 内容 |
|------|------|
| 领域 | OPS |
| 严重度 | 🔴 严重 |
| 现状 | orderType 和 source 枚举值与需求完全不同，无法映射 |
| 影响 | 工单分类体系与业务需求不匹配，影响数据统计和流程路由 |

### 🔴 #5 MDM 域地图服务完全未实现

| 维度 | 内容 |
|------|------|
| 领域 | MDM |
| 严重度 | 🔴 严重 |
| 现状 | PostGIS 字段、地图标注/边界/路径 API、前端地图组件全部缺失 |
| 影响 | 无法在地图上展示和管理空间节点，影响空间可视化能力 |

### 🟠 #6 MDM 域空间编码机制缺失

| 维度 | 内容 |
|------|------|
| 领域 | MDM |
| 严重度 | 🟠 高 |
| 现状 | 无 code 字段、无自动编码规则、无 UNIQUE(project_id, code) 约束 |
| 影响 | 空间节点缺乏唯一编码，影响数据一致性和外部系统对接 |

### 🟠 #7 AUTH 域权限相关端点缺失

| 维度 | 内容 |
|------|------|
| 领域 | AUTH |
| 严重度 | 🟠 高 |
| 现状 | 权限树（/permissions/tree）、权限校验（/check）、用户菜单（/{id}/menus）、用户权限查询（/{id}/permissions）端点均未实现 |
| 影响 | 前端无法动态获取菜单和权限，影响 RBAC 体系的完整运作 |

### 🟠 #8 运营域工单分页查询缺失

| 维度 | 内容 |
|------|------|
| 领域 | OPS |
| 严重度 | 🟠 高 |
| 现状 | 工单列表全量返回 List\<WorkOrder\>，无分页支持 |
| 影响 | 数据量大时性能问题严重，影响用户体验 |

### 🟡 #9 ASSET 域设备二维码和 IoT 集成未实现

| 维度 | 内容 |
|------|------|
| 领域 | ASSET |
| 严重度 | 🟡 中 |
| 现状 | 设备二维码（qrCode）和 IoT 集成均未实现 |
| 影响 | 无法通过扫码快速定位设备，无法实时监控设备状态 |

### 🟡 #10 运营域前后端枚举和状态不一致

| 维度 | 内容 |
|------|------|
| 领域 | OPS |
| 严重度 | 🟡 中 |
| 现状 | 维保计划触发类型、维保任务状态、维保计划 API 前后端不一致 |
| 影响 | 前端展示与后端数据不匹配，可能导致功能异常 |

---

## 六、风险点识别

### 6.1 高风险

| 编号 | 风险点 | 领域 | 影响 | 触发条件 |
|------|--------|------|------|---------|
| R-01 | 财务域核心功能完全缺失 | FINANCE | 物业收费流程无法运行，业务闭环断裂 | 业主缴费、账单管理等场景 |
| R-02 | 设计文档标注与实际代码严重不符 | FINANCE | 开发人员误判实现状态，导致遗漏 | 依据设计文档评估进度时 |
| R-03 | 消息通知系统完全缺失 | OPS | 工单状态变更无法通知，运营效率低下 | 工单分配、完成、超时等场景 |
| R-04 | 工单状态机与需求不匹配 | OPS | 业务流程无法按需求执行 | 需要挂起/退回/接单确认的场景 |
| R-05 | 工单列表无分页 | OPS | 大数据量下性能崩溃 | 工单数量超过数百条 |

### 6.2 中风险

| 编号 | 风险点 | 领域 | 影响 | 触发条件 |
|------|--------|------|------|---------|
| R-06 | 地图服务未实现 | MDM | 空间可视化能力缺失 | 需要地图展示的场景 |
| R-07 | 空间编码唯一约束缺失 | MDM | 数据一致性风险 | 并发创建空间节点时 |
| R-08 | 权限相关端点缺失 | AUTH | RBAC 体系不完整 | 动态菜单/权限校验场景 |
| R-09 | 设备模型双体系并存 | MDM/ASSET | 数据不一致，维护成本高 | 跨模块设备查询时 |
| R-10 | 前后端枚举不一致 | OPS/ASSET | 前端展示错误 | 能源类型、维保状态等展示 |
| R-11 | 访客凭证未实现 | AUTH | 访客管理流程缺失 | 访客临时出入场景 |
| R-12 | 工单流转记录未实现 | OPS | 无法追溯工单处理历史 | 工单审计和纠纷处理 |

### 6.3 低风险

| 编号 | 风险点 | 领域 | 影响 | 触发条件 |
|------|--------|------|------|---------|
| R-13 | API 路径无版本号 | 全局 | 未来 API 升级兼容性问题 | API 版本迭代时 |
| R-14 | attributes 字段降级为 String | MDM | JSON 查询性能差 | 需要按属性筛选空间节点时 |
| R-15 | 健康评分查询错误实体 | ASSET | 设备年龄计算不准确 | 健康评分展示时 |
| R-16 | projectId 硬编码全零 UUID | ASSET | 多项目环境下数据错误 | 非默认项目查询健康评分时 |
| R-17 | OwnershipEntityController 绕过 Service 层 | ASSET | 不符合分层架构规范 | 代码审查和维护时 |
| R-18 | 维保完成率固定为 1.0 | ASSET | 健康评分不准确 | 维保完成率展示时 |
| R-19 | 删除策略不一致 | OPS | 数据恢复策略混乱 | 误删除恢复场景 |
| R-20 | 能耗按类型统计实现有缺陷 | FINANCE | 能耗分项统计不准确 | 能耗报表展示时 |

---

## 七、改进建议

### 7.1 P0 — 紧急（1-2 周内）

| 编号 | 建议 | 领域 | 关联风险 | 预估工作量 |
|------|------|------|---------|-----------|
| S-01 | 修正 04-FINANCE.md 实现状态标注 | FINANCE | R-02 | 0.5 天 |
| S-02 | 创建 module-finance 模块，实现 FeeItem/FeeBill/FeePayment 核心实体 | FINANCE | R-01 | 5 天 |
| S-03 | 实现工单列表分页查询 | OPS | R-05 | 1 天 |
| S-04 | 统一运营域前后端枚举值（触发类型、任务状态） | OPS | R-10 | 1 天 |

### 7.2 P1 — 重要（1 个月内）

| 编号 | 建议 | 领域 | 关联风险 | 预估工作量 |
|------|------|------|---------|-----------|
| S-05 | 实现消息通知系统（Channel/Template/Rule/History） | OPS | R-03 | 8 天 |
| S-06 | 补充工单状态机（增加 ACCEPTED/SUSPENDED/RETURNED 状态） | OPS | R-04 | 3 天 |
| S-07 | 实现 AUTH 域权限相关端点（权限树/权限校验/用户菜单/用户权限） | AUTH | R-08 | 3 天 |
| S-08 | 添加空间编码字段和唯一约束 | MDM | R-07 | 1 天 |
| S-09 | 统一设备模型（消除 MDM SpaceNode 内嵌设备与 ASSET Equipment 双体系） | MDM/ASSET | R-09 | 3 天 |
| S-10 | 实现账单自动生成和状态流转 | FINANCE | R-01 | 4 天 |
| S-11 | 实现工单流转记录（WorkOrderFlow） | OPS | R-12 | 2 天 |

### 7.3 P2 — 增强（2-3 个月内）

| 编号 | 建议 | 领域 | 关联风险 | 预估工作量 |
|------|------|------|---------|-----------|
| S-12 | 集成 PostGIS 实现地图服务 | MDM | R-06 | 10 天 |
| S-13 | 实现空间节点统计分析 API | MDM | - | 3 天 |
| S-14 | 实现空间节点导入导出功能 | MDM | - | 3 天 |
| S-15 | 实现设备二维码生成和扫描 | ASSET | R-09 | 2 天 |
| S-16 | 实现访客凭证管理 | AUTH | R-11 | 3 天 |
| S-17 | 修复健康评分查询错误实体和 projectId 硬编码问题 | ASSET | R-15, R-16 | 1 天 |
| S-18 | 修复能耗按类型统计缺陷，统一前后端能源类型枚举 | FINANCE | R-10, R-20 | 1 天 |
| S-19 | 实现支付记录 API 和线下收款登记 | FINANCE | R-01 | 2 天 |

### 7.4 P3 — 远期（3 个月以上）

| 编号 | 建议 | 领域 | 关联风险 | 预估工作量 |
|------|------|------|---------|-----------|
| S-20 | IoT 平台集成（设备状态监控+自动抄表） | ASSET/FINANCE | - | 10 天 |
| S-21 | 支付网关对接（微信支付/支付宝） | FINANCE | - | 5 天 |
| S-22 | 财务报表（收费统计/欠费分析/收入趋势） | FINANCE | - | 4 天 |
| S-23 | 智能派单和 SLA 监控 | OPS | - | 8 天 |
| S-24 | API 版本化改造（添加 v1 前缀） | 全局 | R-13 | 3 天 |
| S-25 | attributes 字段升级为 JSONB 类型 | MDM | R-14 | 2 天 |

---

## 八、结论

### 8.1 总体评估

Ether 项目代码实现与需求文档的一致性整体偏低（完全一致率仅 5.5%），但需要区分两种不同性质的偏差：

1. **正向偏差（超出实现 38.6%）**：代码在 AUTH、ASSET 领域远超原需求定义，体现了开发过程中的需求演化和功能增强。这类偏差通常是积极的，但也需要同步更新需求文档。

2. **负向偏差（不符合 8.2% + 未实现 27.3%）**：代码在 FINANCE、OPS、MDM 领域存在显著的功能缺失和逻辑偏差，特别是财务域核心功能完全缺失和运营域消息通知系统未实现，属于严重问题。

### 8.2 优先行动项

1. **立即修正** 04-FINANCE.md 的实现状态标注，消除文档失真
2. **紧急启动** module-finance 模块开发，补齐财务域核心功能
3. **尽快实现** 消息通知系统和工单状态机补全
4. **统一修复** 前后端枚举不一致问题
5. **逐步补齐** MDM 域地图服务和空间编码功能

### 8.3 文档治理建议

1. 建立需求文档与代码实现的定期同步机制
2. 需求文档中的实现状态标注必须经过代码验证
3. 超出需求文档的代码实现应反向补充到需求文档
4. 建议在每次迭代结束时进行一致性检查

---

> **报告生成说明**: 本报告基于 REVERSE-AUTH.md / REVERSE-MDM.md / REVERSE-ASSET.md / REVERSE-OPS.md / REVERSE-FINANCE.md 五份反推设计文档的差异对比章节生成，共分析 220 项差异对比数据。评估结果反映 2026-04-23 代码库状态。