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 评估范围
| 领域 |
反推文档 |
原需求文档 |
差异对比项数 |
| 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%），但需要区分两种不同性质的偏差：
-
正向偏差（超出实现 38.6%）：代码在 AUTH、ASSET 领域远超原需求定义，体现了开发过程中的需求演化和功能增强。这类偏差通常是积极的，但也需要同步更新需求文档。
-
负向偏差（不符合 8.2% + 未实现 27.3%）：代码在 FINANCE、OPS、MDM 领域存在显著的功能缺失和逻辑偏差，特别是财务域核心功能完全缺失和运营域消息通知系统未实现，属于严重问题。
8.2 优先行动项
- 立即修正 04-FINANCE.md 的实现状态标注，消除文档失真
- 紧急启动 module-finance 模块开发，补齐财务域核心功能
- 尽快实现 消息通知系统和工单状态机补全
- 统一修复 前后端枚举不一致问题
- 逐步补齐 MDM 域地图服务和空间编码功能
8.3 文档治理建议
- 建立需求文档与代码实现的定期同步机制
- 需求文档中的实现状态标注必须经过代码验证
- 超出需求文档的代码实现应反向补充到需求文档
- 建议在每次迭代结束时进行一致性检查
报告生成说明: 本报告基于 REVERSE-AUTH.md / REVERSE-MDM.md / REVERSE-ASSET.md / REVERSE-OPS.md / REVERSE-FINANCE.md 五份反推设计文档的差异对比章节生成，共分析 220 项差异对比数据。评估结果反映 2026-04-23 代码库状态。