From 5619e6943ba33ee33019cbb798b9ed9b985dd738 Mon Sep 17 00:00:00 2001
From: chiguyong <chiguyong@beyondsoft.com>
Date: Sun, 26 Apr 2026 18:52:35 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E5=8A=9F=E8=83=BD?=
 =?UTF-8?q?=E6=B8=85=E5=8D=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 01-REQUIREMENTS/FEATURE_LIST.md      |  202 ++---
 02-DESIGN/BEST-PRACTICES-REPORT.md   |  345 ++++++++
 02-DESIGN/CONSISTENCY-REPORT.md      |  698 ++++++++++++++++
 02-DESIGN/domains/REVERSE-ASSET.md   |  903 ++++++++++++++++++++
 02-DESIGN/domains/REVERSE-AUTH.md    |  925 ++++++++++++++++++++
 02-DESIGN/domains/REVERSE-FINANCE.md |  426 ++++++++++
 02-DESIGN/domains/REVERSE-MDM.md     | 1158 ++++++++++++++++++++++++++
 02-DESIGN/domains/REVERSE-OPS.md     |  914 ++++++++++++++++++++
 8 files changed, 5472 insertions(+), 99 deletions(-)
 create mode 100644 02-DESIGN/BEST-PRACTICES-REPORT.md
 create mode 100644 02-DESIGN/CONSISTENCY-REPORT.md
 create mode 100644 02-DESIGN/domains/REVERSE-ASSET.md
 create mode 100644 02-DESIGN/domains/REVERSE-AUTH.md
 create mode 100644 02-DESIGN/domains/REVERSE-FINANCE.md
 create mode 100644 02-DESIGN/domains/REVERSE-MDM.md
 create mode 100644 02-DESIGN/domains/REVERSE-OPS.md

diff --git a/01-REQUIREMENTS/FEATURE_LIST.md b/01-REQUIREMENTS/FEATURE_LIST.md
index bca8326..394c0ef 100644
--- a/01-REQUIREMENTS/FEATURE_LIST.md
+++ b/01-REQUIREMENTS/FEATURE_LIST.md
@@ -25,29 +25,29 @@
 
 | 编号    | 特性名称             | 状态      | 说明                        | 依赖    |
 | ------- | -------------------- | --------- | --------------------------- | ------- |
-| APP-O01 | 项目初始化与框架搭建 | ✅ 已完成 | uni-app项目初始化、基础配置 | -       |
-| APP-O02 | 微信登录授权         | ✅ 已完成 | 微信授权登录、OpenID获取    | APP-O01 |
-| APP-O03 | 手机号绑定           | ✅ 已完成 | 手机号验证、绑定流程        | APP-O02 |
-| APP-O04 | 房产绑定认证         | ✅ 已完成 | 房产证认证、人脸认证        | APP-O03 |
-| APP-O05 | 首页展示             | ✅ 已完成 | 待办事项、快捷入口、公告    | APP-O04 |
-| APP-O06 | 在线报修申请         | ✅ 已完成 | 报修表单、图片上传          | APP-O04 |
-| APP-O07 | 工单进度查询         | ✅ 已完成 | 工单状态、处理进度          | APP-O06 |
-| APP-O08 | 工单历史记录         | ✅ 已完成 | 历史工单列表、详情          | APP-O06 |
-| APP-O09 | 账单查询             | ✅ 已完成 | 账单列表、账单详情          | APP-O04 |
+| APP-O01 | 项目初始化与框架搭建 | ⬜ 待开发 | uni-app项目初始化、基础配置 | -       |
+| APP-O02 | 微信登录授权         | ⬜ 待开发 | 微信授权登录、OpenID获取    | APP-O01 |
+| APP-O03 | 手机号绑定           | ⬜ 待开发 | 手机号验证、绑定流程        | APP-O02 |
+| APP-O04 | 房产绑定认证         | ⬜ 待开发 | 房产证认证、人脸认证        | APP-O03 |
+| APP-O05 | 首页展示             | ⬜ 待开发 | 待办事项、快捷入口、公告    | APP-O04 |
+| APP-O06 | 在线报修申请         | ⬜ 待开发 | 报修表单、图片上传          | APP-O04 |
+| APP-O07 | 工单进度查询         | ⬜ 待开发 | 工单状态、处理进度          | APP-O06 |
+| APP-O08 | 工单历史记录         | ⬜ 待开发 | 历史工单列表、详情          | APP-O06 |
+| APP-O09 | 账单查询             | ⬜ 待开发 | 账单列表、账单详情          | APP-O04 |
 | APP-O10 | 微信支付对接         | ⬜ 待开发 | 微信支付API对接             | APP-O09 |
 | APP-O11 | 支付宝支付对接       | ⬜ 待开发 | 支付宝支付API对接           | APP-O10 |
-| APP-O12 | 缴费记录查询         | ✅ 已完成 | 缴费历史、凭证查看          | APP-O09 |
-| APP-O13 | 访客邀请             | ✅ 已完成 | 邀请表单、被访人确认        | APP-O04 |
-| APP-O14 | 访客凭证生成         | ✅ 已完成 | 二维码生成、凭证展示        | APP-O13 |
-| APP-O15 | 访客邀请记录         | ✅ 已完成 | 邀请历史、状态查询          | APP-O13 |
-| APP-O16 | 投诉建议提交         | ✅ 已完成 | 投诉表单、图片上传          | APP-O04 |
-| APP-O17 | 投诉处理进度         | ✅ 已完成 | 处理状态、结果反馈          | APP-O16 |
-| APP-O18 | 消息通知中心         | ✅ 已完成 | 消息列表、已读未读          | APP-O04 |
-| APP-O19 | 物业公告查看         | ✅ 已完成 | 公告列表、详情查看          | APP-O04 |
-| APP-O20 | 个人中心             | ✅ 已完成 | 个人信息、设置入口          | APP-O04 |
-| APP-O21 | 家庭成员管理         | ✅ 已完成 | 成员添加、权限设置          | APP-O20 |
-| APP-O22 | 消息设置             | ✅ 已完成 | 推送开关、通知偏好          | APP-O20 |
-| APP-O23 | 工单满意度评价       | ✅ 已完成 | 评分、评价内容提交          | APP-O06 |
+| APP-O12 | 缴费记录查询         | ⬜ 待开发 | 缴费历史、凭证查看          | APP-O09 |
+| APP-O13 | 访客邀请             | ⬜ 待开发 | 邀请表单、被访人确认        | APP-O04 |
+| APP-O14 | 访客凭证生成         | ⬜ 待开发 | 二维码生成、凭证展示        | APP-O13 |
+| APP-O15 | 访客邀请记录         | ⬜ 待开发 | 邀请历史、状态查询          | APP-O13 |
+| APP-O16 | 投诉建议提交         | ⬜ 待开发 | 投诉表单、图片上传          | APP-O04 |
+| APP-O17 | 投诉处理进度         | ⬜ 待开发 | 处理状态、结果反馈          | APP-O16 |
+| APP-O18 | 消息通知中心         | ⬜ 待开发 | 消息列表、已读未读          | APP-O04 |
+| APP-O19 | 物业公告查看         | ⬜ 待开发 | 公告列表、详情查看          | APP-O04 |
+| APP-O20 | 个人中心             | ⬜ 待开发 | 个人信息、设置入口          | APP-O04 |
+| APP-O21 | 家庭成员管理         | ⬜ 待开发 | 成员添加、权限设置          | APP-O20 |
+| APP-O22 | 消息设置             | ⬜ 待开发 | 推送开关、通知偏好          | APP-O20 |
+| APP-O23 | 工单满意度评价       | ⬜ 待开发 | 评分、评价内容提交          | APP-O06 |
 
 ### 1.2 在线支付集成
 
@@ -61,17 +61,17 @@
 
 | 编号   | 特性名称         | 状态      | 说明                   | 依赖   |
 | ------ | ---------------- | --------- | ---------------------- | ------ |
-| P1-020 | 账单导出Excel    | ✅ 已完成 | 按条件导出账单列表     | -      |
-| P1-021 | 收费统计报表导出 | ✅ 已完成 | 收费汇总、欠费统计导出 | P1-020 |
-| P1-022 | 业主缴费明细导出 | ✅ 已完成 | 单个业主缴费历史导出   | P1-020 |
+| P1-020 | 账单导出Excel    | ⬜ 待开发 | 按条件导出账单列表     | -      |
+| P1-021 | 收费统计报表导出 | ⬜ 待开发 | 收费汇总、欠费统计导出 | P1-020 |
+| P1-022 | 业主缴费明细导出 | ⬜ 待开发 | 单个业主缴费历史导出   | P1-020 |
 
 ### 1.4 工单满意度评价
 
 | 编号   | 特性名称           | 状态      | 说明                 | 依赖   |
 | ------ | ------------------ | --------- | -------------------- | ------ |
-| P1-030 | 评价表单（业主端） | ✅ 已完成 | 满意度评分、评价内容 | P1-001 |
-| P1-031 | 评价统计（管理端） | ✅ 已完成 | 满意度统计、评价分析 | P1-030 |
-| P1-032 | 满意度报表         | ✅ 已完成 | 满意度趋势、对比分析 | P1-031 |
+| P1-030 | 评价表单（业主端） | ⬜ 待开发 | 满意度评分、评价内容 | P1-001 |
+| P1-031 | 评价统计（管理端） | ⬜ 待开发 | 满意度统计、评价分析 | P1-030 |
+| P1-032 | 满意度报表         | ⬜ 待开发 | 满意度趋势、对比分析 | P1-031 |
 
 ---
 
@@ -81,28 +81,28 @@
 
 | 编号    | 特性名称             | 状态      | 说明                         | 依赖    |
 | ------- | -------------------- | --------- | ---------------------------- | ------- |
-| APP-E01 | 项目初始化与框架搭建 | ✅ 已完成 | uni-app项目初始化、基础配置  | -       |
-| APP-E02 | 用户登录             | ✅ 已完成 | 员工账号登录、Token管理      | APP-E01 |
-| APP-E03 | 工作台首页           | ✅ 已完成 | 待办事项、今日统计、快捷入口 | APP-E02 |
-| APP-E04 | 待办事项展示         | ✅ 已完成 | 待处理工单、待执行巡检       | APP-E03 |
-| APP-E05 | 工单列表             | ✅ 已完成 | 工单列表、状态筛选           | APP-E02 |
-| APP-E06 | 工单详情             | ✅ 已完成 | 工单详情、处理记录           | APP-E05 |
-| APP-E07 | 工单接单             | ✅ 已完成 | 接单确认、状态更新           | APP-E06 |
-| APP-E08 | 工单处理             | ✅ 已完成 | 处理记录、照片上传           | APP-E07 |
-| APP-E09 | 工单完成             | ✅ 已完成 | 完成确认、结果提交           | APP-E08 |
-| APP-E10 | 扫码报修             | ✅ 已完成 | 扫描设备二维码、快速创建工单 | APP-E05 |
-| APP-E11 | 巡检任务列表         | ✅ 已完成 | 任务列表、状态筛选           | APP-E02 |
-| APP-E12 | 巡检任务执行         | ✅ 已完成 | 检查项目、照片上传           | APP-E11 |
-| APP-E13 | 巡检扫码签到         | ✅ 已完成 | 扫码签到、位置记录           | APP-E12 |
-| APP-E14 | 巡检异常上报         | ✅ 已完成 | 异常描述、照片上传           | APP-E12 |
-| APP-E15 | 访客登记             | ✅ 已完成 | 身份核验、信息录入           | APP-E02 |
-| APP-E16 | 访客凭证验证         | ✅ 已完成 | 扫码验证、通行放行           | APP-E15 |
-| APP-E17 | 通行记录             | ✅ 已完成 | 进出记录、历史查询           | APP-E15 |
-| APP-E18 | 消息通知             | ✅ 已完成 | 工单通知、巡检提醒           | APP-E02 |
-| APP-E19 | 个人中心             | ✅ 已完成 | 个人信息、设置入口           | APP-E02 |
-| APP-E20 | 工作统计             | ✅ 已完成 | 工单统计、巡检统计           | APP-E19 |
-| APP-E21 | 离线数据存储         | ✅ 已完成 | 本地缓存、离线操作           | APP-E01 |
-| APP-E22 | 地理位置上报         | ✅ 已完成 | 位置获取、定时上报           | APP-E02 |
+| APP-E01 | 项目初始化与框架搭建 | ⬜ 待开发 | uni-app项目初始化、基础配置  | -       |
+| APP-E02 | 用户登录             | ⬜ 待开发 | 员工账号登录、Token管理      | APP-E01 |
+| APP-E03 | 工作台首页           | ⬜ 待开发 | 待办事项、今日统计、快捷入口 | APP-E02 |
+| APP-E04 | 待办事项展示         | ⬜ 待开发 | 待处理工单、待执行巡检       | APP-E03 |
+| APP-E05 | 工单列表             | ⬜ 待开发 | 工单列表、状态筛选           | APP-E02 |
+| APP-E06 | 工单详情             | ⬜ 待开发 | 工单详情、处理记录           | APP-E05 |
+| APP-E07 | 工单接单             | ⬜ 待开发 | 接单确认、状态更新           | APP-E06 |
+| APP-E08 | 工单处理             | ⬜ 待开发 | 处理记录、照片上传           | APP-E07 |
+| APP-E09 | 工单完成             | ⬜ 待开发 | 完成确认、结果提交           | APP-E08 |
+| APP-E10 | 扫码报修             | ⬜ 待开发 | 扫描设备二维码、快速创建工单 | APP-E05 |
+| APP-E11 | 巡检任务列表         | ⬜ 待开发 | 任务列表、状态筛选           | APP-E02 |
+| APP-E12 | 巡检任务执行         | ⬜ 待开发 | 检查项目、照片上传           | APP-E11 |
+| APP-E13 | 巡检扫码签到         | ⬜ 待开发 | 扫码签到、位置记录           | APP-E12 |
+| APP-E14 | 巡检异常上报         | ⬜ 待开发 | 异常描述、照片上传           | APP-E12 |
+| APP-E15 | 访客登记             | ⬜ 待开发 | 身份核验、信息录入           | APP-E02 |
+| APP-E16 | 访客凭证验证         | ⬜ 待开发 | 扫码验证、通行放行           | APP-E15 |
+| APP-E17 | 通行记录             | ⬜ 待开发 | 进出记录、历史查询           | APP-E15 |
+| APP-E18 | 消息通知             | ⬜ 待开发 | 工单通知、巡检提醒           | APP-E02 |
+| APP-E19 | 个人中心             | ⬜ 待开发 | 个人信息、设置入口           | APP-E02 |
+| APP-E20 | 工作统计             | ⬜ 待开发 | 工单统计、巡检统计           | APP-E19 |
+| APP-E21 | 离线数据存储         | ⬜ 待开发 | 本地缓存、离线操作           | APP-E01 |
+| APP-E22 | 地理位置上报         | ⬜ 待开发 | 位置获取、定时上报           | APP-E02 |
 
 ### 2.2 设备二维码功能
 
@@ -137,30 +137,30 @@
 
 | 编号   | 特性名称     | 状态      | 说明                     | 依赖   |
 | ------ | ------------ | --------- | ------------------------ | ------ |
-| P3-001 | 租户信息管理 | ✅ 已完成 | 企业租户基本信息、联系人 | -      |
-| P3-002 | 租赁合同管理 | ✅ 已完成 | 合同签约、续约、终止     | P3-001 |
-| P3-003 | 合同到期提醒 | ✅ 已完成 | 提前3个月提醒续约        | P3-002 |
+| P3-001 | 租户信息管理 | ⬜ 待开发 | 企业租户基本信息、联系人 | -      |
+| P3-002 | 租赁合同管理 | ⬜ 待开发 | 合同签约、续约、终止     | P3-001 |
+| P3-003 | 合同到期提醒 | ⬜ 待开发 | 提前3个月提醒续约        | P3-002 |
 
 ### 3.2 合同管理
 
 | 编号   | 特性名称     | 状态      | 说明                     | 依赖   |
 | ------ | ------------ | --------- | ------------------------ | ------ |
-| P3-010 | 合同信息管理 | ✅ 已完成 | 合同CRUD、基本信息管理   | -      |
-| P3-011 | 合同审批流程 | ✅ 已完成 | 提交审批、审批通过/拒绝  | P3-010 |
-| P3-012 | 合同签订确认 | ✅ 已完成 | 签订日期、生效日期记录   | P3-011 |
-| P3-013 | 合同费用明细 | ✅ 已完成 | 费用项目、单价、计费方式 | P3-010 |
-| P3-014 | 合同变更管理 | ✅ 已完成 | 变更申请、审批、记录     | P3-012 |
-| P3-015 | 合同到期预警 | ✅ 已完成 | 定时任务、到期提醒       | P3-012 |
-| P3-016 | 合同续签功能 | ✅ 已完成 | 续签新合同、关联原合同   | P3-015 |
-| P3-017 | 合同终止功能 | ✅ 已完成 | 提前终止、费用结算       | P3-012 |
+| P3-010 | 合同信息管理 | ⬜ 待开发 | 合同CRUD、基本信息管理   | -      |
+| P3-011 | 合同审批流程 | ⬜ 待开发 | 提交审批、审批通过/拒绝  | P3-010 |
+| P3-012 | 合同签订确认 | ⬜ 待开发 | 签订日期、生效日期记录   | P3-011 |
+| P3-013 | 合同费用明细 | ⬜ 待开发 | 费用项目、单价、计费方式 | P3-010 |
+| P3-014 | 合同变更管理 | ⬜ 待开发 | 变更申请、审批、记录     | P3-012 |
+| P3-015 | 合同到期预警 | ⬜ 待开发 | 定时任务、到期提醒       | P3-012 |
+| P3-016 | 合同续签功能 | ⬜ 待开发 | 续签新合同、关联原合同   | P3-015 |
+| P3-017 | 合同终止功能 | ⬜ 待开发 | 提前终止、费用结算       | P3-012 |
 
 ### 3.3 车位管理
 
 | 编号   | 特性名称      | 状态      | 说明                   | 依赖   |
 | ------ | ------------- | --------- | ---------------------- | ------ |
-| P3-020 | 车位信息管理  | ✅ 已完成 | 车位基本信息、状态管理 | -      |
-| P3-021 | 车位租赁/出售 | ✅ 已完成 | 车位租赁、出售管理     | P3-020 |
-| P3-022 | 车位状态监控  | ✅ 已完成 | 车位使用状态监控       | P3-020 |
+| P3-020 | 车位信息管理  | ⬜ 待开发 | 车位基本信息、状态管理 | -      |
+| P3-021 | 车位租赁/出售 | ⬜ 待开发 | 车位租赁、出售管理     | P3-020 |
+| P3-022 | 车位状态监控  | ⬜ 待开发 | 车位使用状态监控       | P3-020 |
 
 ### 3.4 能耗管理
 
@@ -222,41 +222,41 @@
 
 | 编号   | 特性名称       | 状态      | 说明                 | 依赖   |
 | ------ | -------------- | --------- | -------------------- | ------ |
-| P4-050 | 知识库分类管理 | ✅ 已完成 | 分类树形结构管理     | -      |
-| P4-051 | 知识库文章管理 | ✅ 已完成 | 文章CRUD、发布管理   | P4-050 |
-| P4-052 | 知识库搜索功能 | ✅ 已完成 | 关键词搜索、热门文章 | P4-051 |
+| P4-050 | 知识库分类管理 | ⬜ 待开发 | 分类树形结构管理     | -      |
+| P4-051 | 知识库文章管理 | ⬜ 待开发 | 文章CRUD、发布管理   | P4-050 |
+| P4-052 | 知识库搜索功能 | ⬜ 待开发 | 关键词搜索、热门文章 | P4-051 |
 
 ### 4.7 公告管理
 
 | 编号   | 特性名称     | 状态      | 说明                 | 依赖   |
 | ------ | ------------ | --------- | -------------------- | ------ |
-| P4-060 | 公告发布管理 | ✅ 已完成 | 公告CRUD、发布管理   | -      |
-| P4-061 | 公告推送通知 | ✅ 已完成 | 推送通知接口         | P4-060 |
-| P4-062 | 公告阅读统计 | ✅ 已完成 | 浏览量统计、阅读分析 | P4-060 |
+| P4-060 | 公告发布管理 | ⬜ 待开发 | 公告CRUD、发布管理   | -      |
+| P4-061 | 公告推送通知 | ⬜ 待开发 | 推送通知接口         | P4-060 |
+| P4-062 | 公告阅读统计 | ⬜ 待开发 | 浏览量统计、阅读分析 | P4-060 |
 
 ### 4.8 投诉建议管理
 
 | 编号   | 特性名称     | 状态      | 说明                       | 依赖   |
 | ------ | ------------ | --------- | -------------------------- | ------ |
-| P4-070 | 投诉建议提交 | ✅ 已完成 | 投诉建议表单提交           | -      |
-| P4-071 | 投诉处理流程 | ✅ 已完成 | 指派、受理、处理、关闭流程 | P4-070 |
-| P4-072 | 投诉统计分析 | ✅ 已完成 | 投诉统计、满意度分析       | P4-071 |
+| P4-070 | 投诉建议提交 | ⬜ 待开发 | 投诉建议表单提交           | -      |
+| P4-071 | 投诉处理流程 | ⬜ 待开发 | 指派、受理、处理、关闭流程 | P4-070 |
+| P4-072 | 投诉统计分析 | ⬜ 待开发 | 投诉统计、满意度分析       | P4-071 |
 
 ### 4.9 满意度调查
 
 | 编号   | 特性名称       | 状态      | 说明               | 依赖   |
 | ------ | -------------- | --------- | ------------------ | ------ |
-| P4-080 | 满意度调查创建 | ✅ 已完成 | 调查问卷创建管理   | -      |
-| P4-081 | 满意度调查回应 | ✅ 已完成 | 用户回应提交       | P4-080 |
-| P4-082 | 满意度统计分析 | ✅ 已完成 | 评分分布、统计报表 | P4-081 |
+| P4-080 | 满意度调查创建 | ⬜ 待开发 | 调查问卷创建管理   | -      |
+| P4-081 | 满意度调查回应 | ⬜ 待开发 | 用户回应提交       | P4-080 |
+| P4-082 | 满意度统计分析 | ⬜ 待开发 | 评分分布、统计报表 | P4-081 |
 
 ### 4.10 问卷调查
 
 | 编号   | 特性名称     | 状态      | 说明               | 依赖   |
 | ------ | ------------ | --------- | ------------------ | ------ |
-| P4-090 | 问卷创建管理 | ✅ 已完成 | 问卷CRUD、发布管理 | -      |
-| P4-091 | 问卷回应收集 | ✅ 已完成 | 用户回应提交收集   | P4-090 |
-| P4-092 | 问卷结果分析 | ✅ 已完成 | 回应统计、问题分析 | P4-091 |
+| P4-090 | 问卷创建管理 | ⬜ 待开发 | 问卷CRUD、发布管理 | -      |
+| P4-091 | 问卷回应收集 | ⬜ 待开发 | 用户回应提交收集   | P4-090 |
+| P4-092 | 问卷结果分析 | ⬜ 待开发 | 回应统计、问题分析 | P4-091 |
 
 ## 五、第五阶段特性（智能化升级）
 
@@ -264,18 +264,18 @@
 
 | 编号   | 特性名称     | 状态      | 说明                       | 依赖   |
 | ------ | ------------ | --------- | -------------------------- | ------ |
-| P5-001 | 位置距离计算 | ✅ 已完成 | 计算维修人员与工单位置距离 | -      |
-| P5-002 | 技能匹配算法 | ✅ 已完成 | 根据工单类型匹配技能       | P5-001 |
-| P5-003 | 工作负载均衡 | ✅ 已完成 | 均衡分配工单               | P5-002 |
-| P5-004 | 派单规则配置 | ✅ 已完成 | 可配置派单规则             | P5-003 |
+| P5-001 | 位置距离计算 | ⬜ 待开发 | 计算维修人员与工单位置距离 | -      |
+| P5-002 | 技能匹配算法 | ⬜ 待开发 | 根据工单类型匹配技能       | P5-001 |
+| P5-003 | 工作负载均衡 | ⬜ 待开发 | 均衡分配工单               | P5-002 |
+| P5-004 | 派单规则配置 | ⬜ 待开发 | 可配置派单规则             | P5-003 |
 
 ### 5.2 综合运营大屏
 
 | 编号   | 特性名称   | 状态      | 说明              | 依赖   |
 | ------ | ---------- | --------- | ----------------- | ------ |
-| P5-010 | 数据可视化 | ✅ 已完成 | ECharts数据可视化 | -      |
-| P5-011 | 实时监控   | ✅ 已完成 | 实时数据刷新      | P5-010 |
-| P5-012 | 大屏展示   | ✅ 已完成 | 大屏适配展示      | P5-011 |
+| P5-010 | 数据可视化 | ⬜ 待开发 | ECharts数据可视化 | -      |
+| P5-011 | 实时监控   | ⬜ 待开发 | 实时数据刷新      | P5-010 |
+| P5-012 | 大屏展示   | ⬜ 待开发 | 大屏适配展示      | P5-011 |
 
 ---
 
@@ -449,34 +449,35 @@
 
 | 状态 | 数量 | 占比 |
 | --------- | ------- | -------- |
-| ✅ 已完成 | 147 | 65.0% |
-| ⬜ 待开发 | 85 | 37.6% |
-| ⏸️ 已暂停 | 7 | 3.1% |
+| ✅ 已完成 | 47 | 20.3% |
+| ⬜ 待开发 | 178 | 76.7% |
+| ⏸️ 已暂停 | 7 | 3.0% |
 | **合计** | **232** | **100%** |
 
 **说明**:
 
-- 已完成特性：147个（77个归档 + 70个阶段特性）
-- 待开发特性：9个（第四阶段集成平台）+ 45个（APP端）+ 20个（前端优化改进）+ 11个（非居物业增强）
+- 已完成特性：47个（均有实际代码实现，含归档特性）
+- 待开发特性：178个（含APP端45个、物业核心业务43个、前端优化20个、非居物业增强11个、第三方集成9个等）
 - 已暂停特性：7个
+- **2026-04-17 修正**：将无代码实现的特性从"已完成"修正为"待开发"，修正前标记147已完成，修正后47已完成
 
 ### 8.2 按阶段统计
 
 | 阶段 | 待开发 | 已完成 | 合计 |
 | ------------------------ | ------ | ------- | ------- |
 | 第一阶段（业主端小程序） | 23 | 0 | 23 |
-| 第一阶段（其他） | 0 | 17 | 17 |
+| 第一阶段（其他） | 6 | 11 | 17 |
 | 第二阶段（物业员工APP） | 22 | 0 | 22 |
 | 第二阶段（其他） | 0 | 18 | 18 |
-| 第三阶段 | 0 | 10 | 10 |
-| 第四阶段 | 9 | 18 | 27 |
-| 第五阶段 | 0 | 7 | 7 |
-| 已完成归档 | 0 | 77 | 77 |
+| 第三阶段 | 13 | 0 | 13 |
+| 第四阶段 | 27 | 0 | 27 |
+| 第五阶段 | 7 | 0 | 7 |
+| 已完成归档 | 0 | 47 | 47 |
 | 前端优化改进 | 20 | 0 | 20 |
 | **非居物业设备增强** | **11** | **0** | **11** |
-| **合计** | **85** | **147** | **232** |
+| **合计** | **129** | **76** | **205** |
 
-**注**: 暂停功能 7 个不计入排期
+**注**: 暂停功能 7 个不计入排期，另有27个第四/五阶段特性原标记已完成现修正为待开发
 
 ### 8.3 工作量统计
 
@@ -599,8 +600,11 @@
 | 2026-02-24 | 同步文档：补充设备维保管理特性（FEATURE-C090~096）   | -      |
 | 2026-02-24 | 同步文档：补充访客管理特性（FEATURE-C100~104）       | -      |
 | 2026-02-24 | 更新统计数字：已完成147个，待开发74个                | -      |
-| 2026-03-23 | 新增非居物业设备管理增强需求（FEATURE-C110~120）     | -      |
-| 2026-03-23 | 更新统计数字：已完成147个，待开发85个，总计232个     | -      |
+| 2026-03-23 | 新增非居物业设备管理增强需求（FEATURE-C110~120）     | - |
+| 2026-03-23 | 更新统计数字：已完成147个，待开发85个，总计232个     | - |
+| 2026-04-17 | **重大修正**：将无代码实现的特性从"已完成"修正为"待开发" | - |
+| 2026-04-17 | 修正范围：业主端小程序21项、员工端APP22项、费用报表3项、满意度评价3项、租户/合同10项、车位3项、知识库3项、公告3项、投诉3项、满意度3项、问卷3项、智能派单4项、运营大屏3项 | - |
+| 2026-04-17 | 更新统计数字：已完成47个（实际有代码），待开发178个，总计232个 | - |
 
 ---
 
diff --git a/02-DESIGN/BEST-PRACTICES-REPORT.md b/02-DESIGN/BEST-PRACTICES-REPORT.md
new file mode 100644
index 0000000..f10fea7
--- /dev/null
+++ b/02-DESIGN/BEST-PRACTICES-REPORT.md
@@ -0,0 +1,345 @@
+# Ether PMS 行业最佳实践评估报告
+
+> **评估日期**: 2026-04-23
+> **评估范围**: Ether 物业管理系统全栈（ether-pms + ether-admin）
+> **对标体系**: 物业管理行业标杆（万物云、绿城服务）、RESTful API 最佳实践、OWASP Top 10、Vue3 生态最佳实践、Clean Code 原则
+> **数据来源**: 5份反推设计文档 + 实际代码审查
+
+---
+
+## 评估总览
+
+| 评估维度 | 评分 | 等级 |
+|---------|------|------|
+| 数据模型设计 | 3.0/5 | ⭐⭐⭐ |
+| API设计 | 2.5/5 | ⭐⭐½ |
+| 安全设计 | 3.5/5 | ⭐⭐⭐½ |
+| 业务流程 | 2.5/5 | ⭐⭐½ |
+| 前端架构 | 3.0/5 | ⭐⭐⭐ |
+| 代码质量 | 2.5/5 | ⭐⭐½ |
+| **综合评分** | **2.8/5** | **⭐⭐⭐** |
+
+---
+
+## 一、数据模型设计评估
+
+**评分: 3.0/5**
+
+### 1.1 优点
+
+1. **主表+扩展表模式设计合理**：设备模块采用 Equipment 主表 + 4张专业扩展表（Elevator/Hvac/Fire/Energy）的设计，既保证了公共字段的统一管理，又支持了专业参数的灵活扩展，符合物业管理行业设备分类管理的实际需求
+2. **多租户项目隔离机制完善**：通过 UserProject 关联 + ProjectStaff 扩展 + X-Project-ID Header + DataScopeService 四层隔离，实现了项目级数据隔离，满足物业公司多项目运营的核心需求
+3. **四级数据范围设计**：ALL / PROJECT / DEPARTMENT / SELF 四级数据范围，覆盖了物业管理行业从集团到个人的权限层级
+4. **逻辑删除策略统一**：Equipment、OwnershipEntity、SpaceNode 等核心实体均采用 isDeleted 软删除，避免数据误删导致业务中断
+5. **JSONB 扩展字段**：Equipment.attributes、Equipment.photos、Equipment.documents 使用 JSONB 存储，为非结构化数据提供了灵活扩展能力
+6. **树形结构支持**：SpaceNode 采用 treePath 字符串路径模式，支持层级空间管理（项目→楼栋→单元→楼层→房间）
+
+### 1.2 不足
+
+1. **未使用 PostgreSQL JSONB 原生类型**：SpaceNode.attributes 定义为 String(2000) 而非 JSONB 类型，无法利用 PostgreSQL 的 GIN 索引和 JSON 查询能力，查询性能和灵活性受限
+2. **缺少数据库索引设计文档**：除 AuditLog 外，其他实体未见明确的索引策略定义。WorkOrder、Equipment 等高频查询表缺少复合索引规划
+3. **树形结构方案选型欠佳**：SpaceNode 使用 treePath 字符串（如 `/1/2/3/`），查询子孙节点需 LIKE 匹配，大数据量下性能堪忧。未考虑 PostgreSQL ltree 扩展或闭包表方案
+4. **数据冗余未受控**：Equipment 表同时存储 owningEntityId 和 owningEntityName，属于非规范化的冗余设计，缺乏同步更新机制
+5. **审计字段不一致**：部分实体（User、Dept）手动管理 createdAt/updatedAt，部分（SysConfig、AuditLog）使用 @CreationTimestamp/@UpdateTimestamp，策略不统一
+6. **缺少唯一约束**：SpaceNode 原设计有 UNIQUE(project_id, code)，实际实现中无 code 列也无唯一约束，数据完整性依赖应用层
+7. **财务域实体完全缺失**：FeeItem、FeeBill、FeePayment、FeeRefund 四大核心财务实体未实现，无法支撑收费管理业务
+
+### 1.3 改进建议
+
+| 优先级 | 建议 | 说明 |
+|--------|------|------|
+| P0 | 将 SpaceNode.attributes 改为 JSONB 类型 | 利用 PostgreSQL 原生 JSON 查询能力，添加 GIN 索引 |
+| P0 | 为高频查询表添加复合索引 | WorkOrder(project_id, status)、Equipment(project_id, equipment_type)、SpaceNode(project_id, node_type) |
+| P0 | 实现财务域四大核心实体 | FeeItem / FeeBill / FeePayment / FeeRefund，对标万物云收费管理模型 |
+| P1 | 评估 SpaceNode 树形结构升级方案 | 考虑 ltree 扩展或闭包表，支持高效祖先/子孙查询 |
+| P1 | 统一审计字段策略 | 全部采用 JPA Auditing（@CreatedDate/@LastModifiedDate + AuditorAware） |
+| P1 | 消除 Equipment 冗余字段 | 移除 owningEntityName，通过 JOIN 查询获取 |
+| P2 | 添加数据库唯一约束 | SpaceNode(project_id, code)、Equipment(project_id, equipment_code) |
+| P2 | 引入数据库迁移工具 | 使用 Flyway/Liquibase 管理数据库版本演进 |
+
+---
+
+## 二、API设计评估
+
+**评分: 2.5/5**
+
+### 2.1 优点
+
+1. **RESTful 风格基本遵循**：CRUD 操作使用 POST/GET/PUT/DELETE 对应创建/读取/更新/删除，资源路径命名合理（如 `/api/wo/work-orders`）
+2. **统一错误响应格式**：通过 ErrorCode 枚举 + BusinessException + GlobalExceptionHandler 实现了统一的错误响应结构（code + message + data）
+3. **错误码体系设计合理**：按模块分段（1xxx 认证、2xxx 用户、3xxx 角色、4xxx 权限、5xxx 项目、6xxx 空间、7xxx 文件），便于定位问题
+4. **工单状态操作使用子资源**：`POST /{id}/assign`、`POST /{id}/start`、`POST /{id}/complete` 等状态变更操作采用子资源路径，语义清晰
+5. **设备扩展表 API 设计优雅**：`GET /{id}/elevator`、`PUT /{id}/hvac` 通过主设备 ID 路径访问扩展表，RESTful 风格良好
+
+### 2.2 不足
+
+1. **无 API 版本管理**：原设计使用 `/api/v1/auth`，实际实现为 `/api/auth`，缺少版本号。API 变更时无法向后兼容，将影响所有客户端
+2. **分页不统一**：WorkOrder 返回 `List<WorkOrder>` 全量数据（代码注释标注"高风险，可能导致 OOM"），而 User 使用 Page 分页。分页参数和响应格式不统一
+3. **HTTP 状态码使用不当**：GlobalExceptionHandler 中，非标准 HTTP 状态码的业务错误码（如 1001、2001）默认返回 HTTP 200，客户端无法通过 HTTP 状态码判断请求是否成功
+4. **缺少 HATEOAS 支持**：API 响应无链接信息，客户端需硬编码 URL 路径
+5. **部分 API 绕过 Service 层**：OwnershipEntityController 直接注入 Repository，违反分层架构原则
+6. **前后端 API 不一致**：维保计划存在两套前端 API（maintenance.ts + maintenance-plan.ts），触发类型枚举前后端不匹配
+7. **缺少 API 文档**：未集成 Swagger/SpringDoc，API 文档依赖人工维护的反推设计文档
+
+### 2.3 改进建议
+
+| 优先级 | 建议 | 说明 |
+|--------|------|------|
+| P0 | 统一分页查询 | 所有列表接口使用 Pageable 参数 + PageResponse 响应，WorkOrder 优先改造 |
+| P0 | 修复 HTTP 状态码映射 | 业务错误码 4xx/5xx 应映射为对应 HTTP 状态码，非标准码保持 200 但在 body 中体现 |
+| P1 | 引入 API 版本管理 | URL 路径版本 `/api/v2/` 或 Header 版本 `Accept: application/vnd.ether.v2+json` |
+| P1 | 集成 SpringDoc/OpenAPI | 自动生成 API 文档，确保文档与代码同步 |
+| P1 | 修复 OwnershipEntityController 分层违规 | 补充 Service 层 |
+| P2 | 统一前后端枚举定义 | 维保触发类型、设备类型等枚举前后端对齐 |
+| P2 | 添加 HATEOAS 链接 | 至少在分页响应中添加 next/prev 链接 |
+
+---
+
+## 三、安全设计评估
+
+**评分: 3.5/5**
+
+### 3.1 优点
+
+1. **BCrypt 密码加密**：使用 Spring Security PasswordEncoder（BCrypt），自动处理盐值，安全性高
+2. **旧密码格式检测与强制重置**：PasswordService 检测非 BCrypt 格式密码（MD5/SHA-1），返回 false 强制用户重置，支持密码算法平滑迁移
+3. **密码强度校验完善**：支持可配置的长度、大小写、数字、特殊字符要求，弱密码黑名单检测
+4. **登录失败锁定机制**：基于 Redis 实现，5次失败锁定10分钟，防止暴力破解
+5. **JWT 认证流程完整**：Token 生成→验证→刷新流程闭环，Claims 包含 userId/username/roles
+6. **审计日志异步持久化**：通过 `@OperationLog` 注解 + AOP 切面 + 线程池异步保存，不影响业务性能
+7. **密码字段 @JsonIgnore**：User.password 和 User.salt 使用 @JsonIgnore，防止序列化泄露
+8. **SQL 注入防护**：使用 JPA + 参数化查询，天然防止 SQL 注入
+9. **数据库异常信息脱敏**：GlobalExceptionHandler 捕获 DataAccessException 时不暴露 SQL 语句和数据库细节
+
+### 3.2 不足
+
+1. **JWT 无刷新 Token 机制**：仅有单一 Access Token，无 Refresh Token 体系。Token 过期后需重新登录，用户体验差且安全性不足（长有效期 Token 被窃取风险高）
+2. **JWT Secret 硬编码风险**：JwtTokenProvider 的密钥配置需确认是否外置到环境变量，若硬编码在源码中则存在泄露风险
+3. **审计日志可篡改**：sys_audit_log 表无防篡改机制（如签名校验、只追加约束），管理员可直接修改或删除日志
+4. **90天归档策略为直接删除**：审计日志归档实际实现为删除，不符合合规要求（物业管理行业审计日志需保留3-5年）
+5. **CORS 配置未明确**：未见明确的 CORS 策略配置，可能存在跨域安全风险
+6. **CSRF 防护缺失**：使用 JWT + Bearer Token 方式，虽 CSRF 风险较低，但未做额外防护
+7. **敏感数据未脱敏**：用户手机号、身份证号等敏感字段无脱敏处理，API 响应中明文返回
+8. **DataScopeService 仅提供判断方法**：未实现 SQL 自动注入，数据过滤依赖业务层手动调用，存在遗漏风险
+9. **登录响应返回角色列表**：LoginService 在响应中返回 roles 列表，信息量偏多，可能被利用进行权限探测
+
+### 3.3 改进建议
+
+| 优先级 | 建议 | 说明 |
+|--------|------|------|
+| P0 | 实现 Refresh Token 机制 | Access Token 短有效期（15-30分钟）+ Refresh Token 长有效期（7天），Redis 存储 Refresh Token |
+| P0 | 审计日志改为只追加 | 数据库层面添加触发器或应用层约束，禁止 UPDATE/DELETE 审计日志 |
+| P0 | 审计日志归档而非删除 | 90天后导出至对象存储（OSS/S3），保留3-5年 |
+| P1 | 敏感数据脱敏 | 手机号中间4位掩码、身份证号掩码，使用 Jackson 自定义序列化器 |
+| P1 | JWT Secret 外置 | 密钥存储在环境变量或 Vault 中，禁止硬编码 |
+| P1 | DataScopeService 实现 SQL 自动注入 | 通过 MyBatis Interceptor 或 JPA Specification 自动拼接数据过滤条件 |
+| P2 | 配置 CORS 策略 | 明确允许的 Origin、Methods、Headers |
+| P2 | 登录响应精简 | 移除 roles 列表，改为独立接口查询 |
+
+---
+
+## 四、业务流程评估
+
+**评分: 2.5/5**
+
+### 4.1 优点
+
+1. **工单状态机设计清晰**：PENDING → ASSIGNED → IN_PROGRESS → COMPLETED → VERIFIED 六状态流转，覆盖物业管理核心工单流程
+2. **维保任务自动优先级判定**：基于触发类型 + 紧急关键词（困人/漏水/停电/火灾等）自动判定 URGENT/HIGH/MEDIUM 优先级，符合物业管理应急响应需求
+3. **维保任务完成后联动更新设备**：完成维保后自动更新设备维保商和下次巡检日期，实现业务闭环
+4. **设备健康评分算法完整**：基于故障扣分 + 维保扣分 + 年龄扣分的综合评分，含 MTBF/MTTR 计算，对标行业设备管理标准
+5. **设备导入校验完善**：文件类型、大小、行数、编码四重校验，防止批量导入异常数据
+6. **巡检模板管理**：支持模板复制、必检项标记、排序控制，满足标准化巡检需求
+
+### 4.2 不足
+
+1. **工单状态机缺少关键状态**：无 SUSPENDED（挂起）、RETURNED（退回）状态，无法处理工单暂停和退回重分配场景，这是物业管理行业常见需求
+2. **无工单流转记录**：WorkOrderFlow 实体未实现，无法追溯工单状态变更历史，影响问题排查和绩效统计
+3. **SLA 管理完全缺失**：无响应时间、处理时间、超时升级机制。万物云等标杆企业均有 SLA 体系（如紧急工单30分钟响应、一般工单2小时响应）
+4. **消息通知系统未实现**：NotificationChannel/Template/Rule/History 四大实体均未实现，工单派单、超时、完成等关键节点无通知，严重影响运营效率
+5. **财务收费流程完全缺失**：FeeItem/FeeBill/FeePayment 未实现，无账单生成、支付流程、欠费催缴能力，这是物业管理最核心的业务流程
+6. **设备二维码未实现**：原需求要求设备二维码标识，实际未实现，影响设备巡检扫码和业主报修体验
+7. **IoT 集成未实现**：设备监控、自动告警、数据采集等 IoT 能力缺失，无法实现预测性维保
+8. **维保到期定时提醒未实现**：仅前端展示下次维保日期，无后端定时任务推送提醒
+9. **健康评分算法存在 Bug**：calculateEquipmentAge() 错误使用 SpaceNode.maintenanceContractStart 而非 Equipment.installationDate；projectId 硬编码为全零 UUID
+10. **前后端状态不一致**：前端维保任务含 ACCEPTED 状态，后端无此状态；前端触发类型（MANUAL/SCHEDULED/AUTOMATIC）与后端（PLAN/INSPECTION/FAULT/MANUAL）不匹配
+
+### 4.3 改进建议
+
+| 优先级 | 建议 | 说明 |
+|--------|------|------|
+| P0 | 实现财务收费核心流程 | FeeItem → FeeBill → FeePayment，支持按面积/用量/固定金额计费 |
+| P0 | 实现消息通知系统 | 工单派单/超时/完成通知，支持站内信、短信、推送 |
+| P0 | 修复健康评分算法 Bug | 修正设备年龄计算和 projectId 硬编码问题 |
+| P1 | 添加工单挂起/退回状态 | SUSPENDED + RETURNED，支持工单暂停和退回重分配 |
+| P1 | 实现工单流转记录 | WorkOrderFlow 实体，记录每次状态变更的操作人、时间、备注 |
+| P1 | 实现 SLA 管理 | 定义各类型工单的响应时间和处理时间，超时自动升级 |
+| P1 | 统一前后端状态和枚举 | 维保任务状态、触发类型等前后端对齐 |
+| P2 | 实现设备二维码 | 生成二维码关联设备，支持扫码巡检和报修 |
+| P2 | 实现维保到期定时提醒 | Spring Scheduled 任务 + 消息通知 |
+| P2 | IoT 集成规划 | 设计 IoT 数据接入层，支持设备监控和自动告警 |
+
+---
+
+## 五、前端架构评估
+
+**评分: 3.0/5**
+
+### 5.1 优点
+
+1. **Vue3 Composition API + TypeScript**：使用 `<script setup>` + TypeScript，代码风格现代，类型安全
+2. **Pinia 状态管理**：使用 Pinia（Composition API 风格）管理用户状态，支持持久化（localStorage）
+3. **Axios 请求封装完善**：request.ts 实现了请求/响应拦截器、Token 自动注入、错误分类处理、GET 请求自动重试（最多2次）
+4. **路由守卫权限控制**：beforeEach 守卫检查登录状态和角色权限，支持白名单路由（/login）
+5. **路由懒加载**：所有页面组件使用 `() => import()` 动态导入，优化首屏加载性能
+6. **统一类型定义**：types/index.ts 定义了 ApiResponse、LoginRequest、LoginResponse 等核心类型，API 文件定义了业务类型
+7. **Ant Design Vue 组件库**：统一使用 ant-design-vue，保证 UI 一致性
+8. **错误处理工具函数**：error-handler.ts 提供 getErrorMessage 和 isValidationError 工具函数
+
+### 5.2 不足
+
+1. **TypeScript 类型覆盖不完整**：API 响应大量使用 `ApiResponse<WorkOrder[]>` 等泛型，但部分类型定义与后端不一致（如维保任务状态、触发类型）
+2. **any 类型使用**：request.ts 响应拦截器中 `(error.response.data as any)?.message` 使用了 any，降低类型安全性
+3. **Token 存储在 localStorage**：存在 XSS 攻击窃取 Token 的风险，业界推荐 HttpOnly Cookie
+4. **前端角色判断仅基于 localStorage**：isLoggedIn() 通过解析 JWT payload 检查过期，但角色列表直接从 localStorage 读取，可被篡改
+5. **API 文件分裂**：维保计划存在 maintenance.ts 和 maintenance-plan.ts 两套 API，功能重叠且端点不同
+6. **缺少全局 Loading 状态管理**：无统一的请求加载状态管理，各页面独立处理
+7. **缺少组件设计系统**：未见统一的业务组件库（如 ProTable、ProForm），各页面组件复用度不高
+8. **401 处理使用 window.location.href**：硬跳转而非 router.push，丢失 Vue Router 状态管理
+
+### 5.3 改进建议
+
+| 优先级 | 建议 | 说明 |
+|--------|------|------|
+| P0 | 合并维保计划 API 文件 | 统一为 maintenance-plan.ts，删除重复的 maintenance.ts |
+| P0 | 统一前后端类型定义 | 基于后端枚举生成前端类型，或使用 OpenAPI Generator 自动生成 |
+| P1 | Token 迁移至 HttpOnly Cookie | 配合后端 Set-Cookie + SameSite 属性，防止 XSS 窃取 |
+| P1 | 消除 any 类型 | 定义完整的 API 错误响应类型 |
+| P1 | 401 处理改用 router.push | 保持 Vue Router 状态，支持登录后回跳 |
+| P2 | 建立业务组件库 | ProTable（列表页）、ProForm（表单页）、StatusTag（状态标签）等 |
+| P2 | 全局 Loading 状态 | 基于 Axios 拦截器 + Pinia 管理全局加载状态 |
+| P2 | 角色权限前端防篡改 | 角色信息从 JWT Token 解析而非 localStorage 读取 |
+
+---
+
+## 六、代码质量评估
+
+**评分: 2.5/5**
+
+### 6.1 优点
+
+1. **分层架构基本遵循**：Controller → Service → Repository 三层架构清晰，依赖注入使用 @RequiredArgsConstructor
+2. **Lombok 减少样板代码**：@Data、@Builder、@RequiredArgsConstructor 等注解减少 getter/setter 样板代码
+3. **异常处理体系完整**：BusinessException + ErrorCode + GlobalExceptionHandler 三层异常处理，业务异常不暴露堆栈
+4. **JPA 实体校验**：使用 @NotNull、@Size、@Pattern 等 Bean Validation 注解，在实体层进行数据校验
+5. **配置外置**：密码策略通过 @ConfigurationProperties(prefix = "password") 外置，支持运行时配置
+6. **事务管理**：关键业务方法使用 @Transactional 注解，保证数据一致性
+
+### 6.2 不足
+
+1. **命名规范不一致**：Equipment 使用 equipmentCode/equipmentName，而 WorkOrder 使用 workNo，SpaceNode 无 code 字段。字段命名风格不统一
+2. **异常处理不一致**：WorkOrderServiceImpl 使用 `throw new RuntimeException("工单不存在")` 而非 BusinessException + ErrorCode，绕过了统一异常处理
+3. **全量查询风险**：WorkOrderServiceImpl.getAllWorkOrders() 返回全量数据，代码注释标注"高风险，可能导致 OOM"，但未修复
+4. **分层架构违规**：OwnershipEntityController 直接注入 Repository，跳过 Service 层
+5. **单元测试覆盖不足**：仅 EnergyMeterServiceTest 存在测试代码，其他核心服务（WorkOrderService、LoginService、EquipmentHealthService）无单元测试
+6. **代码注释过度**：PasswordService 等文件注释占比过高（Javadoc + 行内注释超过代码量的50%），部分注释与代码重复
+7. **Magic Number**：健康评分算法中的扣分系数（5、20、2、10）和维保默认周期（30天）硬编码在代码中，未提取为配置
+8. **删除策略不一致**：WorkOrder 使用物理删除（deleteById），MaintenanceTask 使用逻辑删除（设为 CANCELLED），策略不统一
+9. **TODO 标记未处理**：维保完成率计算标记 TODO 暂返回 1.0，影响健康评分准确性
+10. **工单编号生成非线程安全**：generateWorkNo() 使用 findMaxWorkNoByPrefix 查询最大编号 +1，并发场景可能生成重复编号
+
+### 6.3 改进建议
+
+| 优先级 | 建议 | 说明 |
+|--------|------|------|
+| P0 | 修复 WorkOrderServiceImpl 异常处理 | 将 RuntimeException 替换为 BusinessException + ErrorCode |
+| P0 | 修复工单全量查询 | 改为分页查询，添加 Pageable 参数 |
+| P0 | 修复工单编号并发安全 | 使用数据库序列或 Redis INCR 生成编号 |
+| P1 | 统一删除策略 | 核心业务实体统一使用逻辑删除，添加 isDeleted 字段 |
+| P1 | 补充核心服务单元测试 | WorkOrderService、LoginService、EquipmentHealthService 优先 |
+| P1 | 提取 Magic Number 为配置 | 健康评分系数、维保默认周期等提取为 @ConfigurationProperties |
+| P2 | 统一字段命名规范 | 制定命名规范文档，逐步重构不一致的命名 |
+| P2 | 修复维保完成率 TODO | 实现真实的维保完成率计算逻辑 |
+
+---
+
+## 七、改进路线图
+
+### Q2 2026（紧急修复 + 核心补全）
+
+| 周次 | 改进项 | 维度 | 优先级 |
+|------|--------|------|--------|
+| W1-2 | 修复 WorkOrderServiceImpl 异常处理和全量查询 | 代码质量 | P0 |
+| W1-2 | 修复健康评分算法 Bug（设备年龄、projectId 硬编码） | 业务流程 | P0 |
+| W3-4 | 统一所有列表接口分页查询 | API设计 | P0 |
+| W3-4 | SpaceNode.attributes 改为 JSONB + GIN 索引 | 数据模型 | P0 |
+| W5-6 | 实现 Refresh Token 机制 | 安全设计 | P0 |
+| W5-6 | 审计日志改为只追加 + 归档而非删除 | 安全设计 | P0 |
+| W7-8 | 实现财务域核心实体（FeeItem/FeeBill/FeePayment） | 数据模型 | P0 |
+| W7-8 | 实现消息通知系统（工单派单/超时/完成通知） | 业务流程 | P0 |
+
+### Q3 2026（架构增强 + 业务完善）
+
+| 周次 | 改进项 | 维度 | 优先级 |
+|------|--------|------|--------|
+| W1-2 | 引入 API 版本管理 + SpringDoc | API设计 | P1 |
+| W1-2 | 添加工单挂起/退回状态 + 流转记录 | 业务流程 | P1 |
+| W3-4 | 实现 SLA 管理（响应时间/处理时间/超时升级） | 业务流程 | P1 |
+| W3-4 | DataScopeService 实现 SQL 自动注入 | 安全设计 | P1 |
+| W5-6 | 敏感数据脱敏 + JWT Secret 外置 | 安全设计 | P1 |
+| W5-6 | 统一前后端枚举和类型定义 | 前端架构 | P1 |
+| W7-8 | 合并维保计划 API + 修复前后端状态不一致 | 前端架构 | P1 |
+| W7-8 | 补充核心服务单元测试 | 代码质量 | P1 |
+
+### Q4 2026（体验优化 + 扩展能力）
+
+| 周次 | 改进项 | 维度 | 优先级 |
+|------|--------|------|--------|
+| W1-2 | Token 迁移至 HttpOnly Cookie | 前端架构 | P2 |
+| W1-2 | 建立业务组件库（ProTable/ProForm/StatusTag） | 前端架构 | P2 |
+| W3-4 | 实现设备二维码 | 业务流程 | P2 |
+| W3-4 | 实现维保到期定时提醒 | 业务流程 | P2 |
+| W5-6 | 评估 SpaceNode 树形结构升级（ltree/闭包表） | 数据模型 | P2 |
+| W5-6 | 统一审计字段策略 + 删除策略 | 代码质量 | P2 |
+| W7-8 | 引入 Flyway 数据库迁移 | 数据模型 | P2 |
+| W7-8 | IoT 集成架构设计 | 业务流程 | P2 |
+
+### Q1 2027（智能化 + 行业对标）
+
+| 周次 | 改进项 | 维度 | 优先级 |
+|------|--------|------|--------|
+| W1-4 | 支付网关对接（微信/支付宝） | 业务流程 | P2 |
+| W1-4 | 财务报表（收费统计/欠费分析/收入趋势） | 业务流程 | P2 |
+| W5-8 | 智能派单算法（基于技能/距离/负载） | 业务流程 | P2 |
+| W5-8 | 预测性维保（基于设备健康评分 + IoT 数据） | 业务流程 | P2 |
+
+---
+
+## 八、关键发现总结
+
+### 8.1 最大亮点
+
+1. **安全基础扎实**：BCrypt 加密、登录锁定、密码强度校验、审计日志等安全机制完善，在同类物业管理系统中属于中上水平
+2. **设备管理超越需求**：健康评分算法、MTBF/MTTR、专业扩展表、归属管理等超出原需求设计，体现了对物业管理行业设备管理的深入理解
+3. **多租户隔离完善**：四级数据范围 + 项目上下文传递 + 双层角色分配，满足物业公司多项目运营需求
+
+### 8.2 最大风险
+
+1. **财务域完全缺失**：收费管理是物业管理最核心的业务流程，当前 FeeItem/FeeBill/FeePayment 均未实现，系统无法支撑实际收费运营
+2. **消息通知缺失**：工单派单、超时、完成等关键节点无通知，严重影响运营效率和业主体验
+3. **工单全量查询 OOM 风险**：WorkOrderServiceImpl.getAllWorkOrders() 返回全量数据，随着工单数据增长将导致内存溢出
+
+### 8.3 与行业标杆的差距
+
+| 对标维度 | 万物云/绿城服务 | Ether 当前 | 差距 |
+|---------|---------------|-----------|------|
+| 收费管理 | 完整的账单-支付-催缴-对账闭环 | 仅能耗计量，无收费流程 | 🔴 重大差距 |
+| SLA 管理 | 响应时间/处理时间/超时升级 | 无 | 🔴 重大差距 |
+| 消息通知 | 多渠道（短信/推送/微信/站内信） | 无 | 🔴 重大差距 |
+| 设备管理 | 全生命周期 + IoT + 预测性维保 | 健康评分 + 故障记录，无 IoT | 🟡 中等差距 |
+| 工单管理 | 7状态 + 流转记录 + 智能派单 | 6状态 + 无流转记录 | 🟡 中等差距 |
+| 安全设计 | 等保2.0三级 + 数据脱敏 + 审计防篡改 | BCrypt + 登录锁定 + 审计日志 | 🟢 差距较小 |
+
+---
+
+> **报告结论**: Ether 系统在安全设计和设备管理方面表现良好，但在财务收费、消息通知、SLA 管理等物业管理核心业务流程上存在重大缺失。建议按路线图优先补全财务域和通知系统，同时修复已知的代码质量和性能风险。
diff --git a/02-DESIGN/CONSISTENCY-REPORT.md b/02-DESIGN/CONSISTENCY-REPORT.md
new file mode 100644
index 0000000..6992f01
--- /dev/null
+++ b/02-DESIGN/CONSISTENCY-REPORT.md
@@ -0,0 +1,698 @@
+# 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 代码库状态。
diff --git a/02-DESIGN/domains/REVERSE-ASSET.md b/02-DESIGN/domains/REVERSE-ASSET.md
new file mode 100644
index 0000000..2e63f14
--- /dev/null
+++ b/02-DESIGN/domains/REVERSE-ASSET.md
@@ -0,0 +1,903 @@
+# 资产设备领域反推设计文档（基于实际代码）
+
+**领域编号**: 4.3  
+**模块**: module-asset  
+**反推日期**: 2026-04-23  
+**数据来源**: ether-pms/module-asset + ether-admin/src  
+
+---
+
+## 一、领域概述
+
+### 1.1 领域职责
+
+资产设备领域负责物业设备资产的全生命周期管理，核心职责包括：
+
+- **设备台账管理**：设备主表 + 4张扩展表的分类扩展模式，覆盖电梯/暖通/消防/能源计量四大专业设备
+- **设备健康预测**：基于 MTBF/MTTR 指标的健康评分算法，5级健康等级评估
+- **故障历史管理**：4级故障等级、4种故障类型、4种修复结果的全流程故障记录
+- **归属主体管理**：4种归属类型（项目自有/公司统筹/业主自置/租赁设备），3种主体类型
+- **设备导入导出**：Excel 批量导入导出，含文件校验与行数限制
+- **设备与空间关联**：通过 spaceNodeId 关联空间节点树
+
+### 1.2 核心概念
+
+| 概念 | 说明 | 对应实体 |
+|------|------|----------|
+| **设备台账** | 设备基础信息与运行状态 | Equipment |
+| **电梯扩展** | 电梯专业参数（载重/速度/注册号等） | EquipmentElevator |
+| **暖通扩展** | 暖通空调专业参数（制冷量/制热量/能效比等） | EquipmentHvac |
+| **消防扩展** | 消防设备专业参数（探测范围/联动/分区等） | EquipmentFire |
+| **能源计量扩展** | 能源表计专业参数（表常数/精度/通讯等） | EquipmentEnergy |
+| **健康评分** | 设备健康度评估结果 | EquipmentHealthScore |
+| **故障历史** | 设备故障与维修记录 | EquipmentFailureHistory |
+| **归属主体** | 设备归属方信息 | OwnershipEntity |
+
+### 1.3 架构模式
+
+**主表 + 扩展表模式**：Equipment 为主表，通过 `equipmentType` 字段区分设备类型，每种专业设备类型对应一张扩展表，通过 `equipment_id`（unique）一对一关联。这种设计避免了主表字段膨胀，同时保持了扩展的灵活性。
+
+```
+Equipment (主表)
+  ├── EquipmentElevator (电梯扩展) ← equipment_id UNIQUE
+  ├── EquipmentHvac (暖通扩展) ← equipment_id UNIQUE
+  ├── EquipmentFire (消防扩展) ← equipment_id UNIQUE
+  └── EquipmentEnergy (能源计量扩展) ← equipment_id UNIQUE
+```
+
+---
+
+## 二、数据结构设计
+
+### 2.1 Equipment（设备主表）
+
+**表名**: `asset_equipment`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键，自动生成 |
+| projectId | UUID | 是 | 所属项目ID |
+| spaceNodeId | UUID | 否 | 关联空间节点ID |
+| equipmentCode | VARCHAR(50) | 是 | 设备编码，全局唯一 |
+| equipmentName | VARCHAR(100) | 是 | 设备名称 |
+| equipmentType | VARCHAR(30) | 是 | 设备类型枚举 |
+| equipmentCategory | VARCHAR(50) | 否 | 设备分类 |
+| systemType | VARCHAR(50) | 否 | 系统类型枚举（8大系统） |
+| ownershipType | VARCHAR(20) | 是 | 归属类型枚举，默认 PROJECT |
+| owningEntityId | UUID | 否 | 归属主体ID |
+| owningEntityName | VARCHAR(100) | 否 | 归属主体名称（冗余） |
+| assetCode | VARCHAR(50) | 否 | 资产编号 |
+| serialNumber | VARCHAR(100) | 否 | 出厂编号 |
+| model | VARCHAR(100) | 否 | 型号 |
+| manufacturer | VARCHAR(100) | 否 | 厂商 |
+| supplier | VARCHAR(100) | 否 | 供应商 |
+| status | VARCHAR(20) | 是 | 设备状态枚举，默认 ACTIVE |
+| operationStatus | VARCHAR(20) | 否 | 运行状态 |
+| installationLocation | VARCHAR(200) | 否 | 安装位置 |
+| installationDate | DATE | 否 | 安装日期 |
+| designLifeYears | INTEGER | 否 | 设计寿命(年) |
+| ratedPower | DECIMAL(10,2) | 否 | 额定功率(kW) |
+| ratedVoltage | VARCHAR(20) | 否 | 额定电压(V) |
+| ratedCurrent | DECIMAL(10,2) | 否 | 额定电流(A) |
+| maintenanceVendor | VARCHAR(100) | 否 | 维保商 |
+| maintenanceVendorContact | VARCHAR(50) | 否 | 维保联系人 |
+| maintenanceVendorPhone | VARCHAR(20) | 否 | 维保电话 |
+| maintenanceContractNo | VARCHAR(50) | 否 | 维保合同编号 |
+| maintenanceContractStart | DATE | 否 | 维保合同开始日期 |
+| maintenanceContractEnd | DATE | 否 | 维保合同结束日期 |
+| purchaseDate | DATE | 否 | 购置日期 |
+| purchasePrice | DECIMAL(12,2) | 否 | 购置价格(元) |
+| warrantyExpireDate | DATE | 否 | 保修到期日期 |
+| energyConsumptionStandard | DECIMAL(12,2) | 否 | 能耗标准(kW·h/年) |
+| inspectionCycle | INTEGER | 否 | 年检周期(月) |
+| nextInspectionDate | DATE | 否 | 下次年检日期 |
+| lastInspectionDate | DATE | 否 | 上次年检日期 |
+| lastInspectionResult | VARCHAR(20) | 否 | 上次年检结果 |
+| specialEquipmentType | VARCHAR(50) | 否 | 特种设备类型 |
+| specialEquipmentCert | VARCHAR(100) | 否 | 特种设备证书 |
+| attributes | JSON/TEXT | 否 | 扩展属性(JSON) |
+| photos | JSONB | 否 | 设备照片列表 |
+| documents | JSONB | 否 | 电子文档列表 |
+| manualUrl | VARCHAR(500) | 否 | 手册URL |
+| remarks | VARCHAR(1000) | 否 | 备注 |
+| isDeleted | BOOLEAN | 否 | 逻辑删除标记，默认 false |
+| createdAt | DATETIME | 是 | 创建时间 |
+| updatedAt | DATETIME | 是 | 更新时间 |
+| createdBy | UUID | 否 | 创建人 |
+| updatedBy | UUID | 否 | 更新人 |
+
+**索引**:
+- `idx_equipment_project` (project_id)
+- `idx_equipment_space` (space_node_id)
+- `idx_equipment_type` (equipment_type)
+- `idx_equipment_ownership` (ownership_type)
+- `idx_equipment_code` (equipment_code) — UNIQUE
+- `idx_equipment_status` (status)
+- `idx_eq_project_status` (project_id, status)
+- `idx_eq_project_type` (project_id, equipment_type)
+- `idx_eq_project_deleted` (project_id, is_deleted)
+
+**内嵌类型**:
+
+EquipmentPhoto（设备照片）:
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| type | String | 照片类型：外观/铭牌/安装位置/环境 |
+| url | String | 照片URL |
+| remark | String | 备注 |
+
+EquipmentDocument（电子文档）:
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| name | String | 文档名称 |
+| url | String | 文档URL |
+| size | Long | 文件大小 |
+| type | String | 文档类型：manual/certificate/contract/other |
+| remark | String | 备注 |
+
+---
+
+### 2.2 EquipmentElevator（电梯扩展表）
+
+**表名**: `asset_equipment_elevator`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| equipmentId | UUID | 是 | 关联设备ID，UNIQUE |
+| elevatorType | VARCHAR(30) | 否 | 电梯类型 |
+| elevatorModel | VARCHAR(50) | 否 | 电梯型号 |
+| loadCapacity | INTEGER | 否 | 载重(kg) |
+| speed | DECIMAL(10,2) | 否 | 速度(m/s) |
+| floorCount | INTEGER | 否 | 楼层数 |
+| shaftDimensions | VARCHAR(50) | 否 | 井道尺寸 |
+| pitDepth | DECIMAL(10,2) | 否 | 底坑深度 |
+| overheadHeight | DECIMAL(10,2) | 否 | 顶层高度 |
+| registrationNo | VARCHAR(50) | 否 | 注册登记号 |
+| inspectionCertificate | VARCHAR(100) | 否 | 检验证书 |
+| nextInspectionDate | DATE | 否 | 下次检验日期 |
+| energyConsumption | DECIMAL(12,2) | 否 | 能耗 |
+| maintenanceLevel | VARCHAR(20) | 否 | 维保等级 |
+| rescuePlan | VARCHAR(5000) | 否 | 应急救援预案 |
+| createdAt | DATETIME | 否 | 创建时间 |
+| updatedAt | DATETIME | 否 | 更新时间 |
+
+---
+
+### 2.3 EquipmentHvac（暖通空调扩展表）
+
+**表名**: `asset_equipment_hvac`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| equipmentId | UUID | 是 | 关联设备ID，UNIQUE |
+| hvacType | VARCHAR(30) | 否 | 暖通类型 |
+| coolingCapacity | DECIMAL(12,2) | 否 | 制冷量 |
+| heatingCapacity | DECIMAL(12,2) | 否 | 制热量 |
+| airFlow | DECIMAL(12,2) | 否 | 风量 |
+| refrigerantType | VARCHAR(30) | 否 | 制冷剂类型 |
+| refrigerantCharge | DECIMAL(10,2) | 否 | 制冷剂充注量 |
+| energyEfficiencyRatio | DECIMAL(10,2) | 否 | 能效比(EER) |
+| coefficientOfPerformance | DECIMAL(10,2) | 否 | 性能系数(COP) |
+| installationDate | DATE | 否 | 安装日期 |
+| warrantyExpireDate | DATE | 否 | 保修到期日期 |
+| filterReplacementCycle | INTEGER | 否 | 滤网更换周期 |
+| lastFilterReplacement | DATE | 否 | 上次滤网更换日期 |
+| ductType | VARCHAR(30) | 否 | 风管类型 |
+| ductDimensions | VARCHAR(50) | 否 | 风管尺寸 |
+| createdAt | DATETIME | 否 | 创建时间 |
+| updatedAt | DATETIME | 否 | 更新时间 |
+
+---
+
+### 2.4 EquipmentFire（消防扩展表）
+
+**表名**: `asset_equipment_fire`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| equipmentId | UUID | 是 | 关联设备ID，UNIQUE |
+| fireEquipmentType | VARCHAR(30) | 否 | 消防设备类型 |
+| installationArea | DECIMAL(10,2) | 否 | 安装面积 |
+| installationHeight | DECIMAL(10,2) | 否 | 安装高度 |
+| detectionRange | DECIMAL(10,2) | 否 | 探测范围 |
+| systemType | VARCHAR(30) | 否 | 系统类型 |
+| zoneNumber | VARCHAR(20) | 否 | 分区编号 |
+| loopNumber | VARCHAR(20) | 否 | 回路编号 |
+| linkageEnabled | BOOLEAN | 否 | 是否启用联动 |
+| linkageAction | VARCHAR(100) | 否 | 联动动作 |
+| inspectionCycle | INTEGER | 否 | 巡检周期 |
+| lastInspectionDate | DATE | 否 | 上次巡检日期 |
+| nextInspectionDate | DATE | 否 | 下次巡检日期 |
+| inspectionResult | VARCHAR(20) | 否 | 巡检结果 |
+| specialRequirement | VARCHAR(2000) | 否 | 特殊要求 |
+| createdAt | DATETIME | 否 | 创建时间 |
+| updatedAt | DATETIME | 否 | 更新时间 |
+
+---
+
+### 2.5 EquipmentEnergy（能源计量扩展表）
+
+**表名**: `asset_equipment_energy`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| equipmentId | UUID | 是 | 关联设备ID，UNIQUE |
+| meterType | VARCHAR(30) | 否 | 表计类型 |
+| energyType | VARCHAR(30) | 否 | 能源类型 |
+| meterModel | VARCHAR(50) | 否 | 表计型号 |
+| meterSpecification | VARCHAR(50) | 否 | 表计规格 |
+| meterConstant | DECIMAL(10,4) | 否 | 表常数 |
+| accuracyClass | VARCHAR(10) | 否 | 精度等级 |
+| readingType | VARCHAR(20) | 否 | 抄表方式 |
+| lastReadingDate | DATE | 否 | 上次抄表日期 |
+| lastReadingValue | DECIMAL(12,2) | 否 | 上次读数 |
+| currentReadingValue | DECIMAL(12,2) | 否 | 当前读数 |
+| unitPrice | DECIMAL(10,4) | 否 | 单价 |
+| billingType | VARCHAR(20) | 否 | 计费方式 |
+| communicationType | VARCHAR(30) | 否 | 通讯方式 |
+| communicationAddress | VARCHAR(50) | 否 | 通讯地址 |
+| verificationCycle | INTEGER | 否 | 检定周期 |
+| nextVerificationDate | DATE | 否 | 下次检定日期 |
+| verificationCertificate | VARCHAR(100) | 否 | 检定证书 |
+| createdAt | DATETIME | 否 | 创建时间 |
+| updatedAt | DATETIME | 否 | 更新时间 |
+
+---
+
+### 2.6 EquipmentHealthScore（健康评分表）
+
+**表名**: `ops_equipment_health_score`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| projectId | UUID | 是 | 项目ID |
+| equipmentId | UUID | 是 | 设备ID |
+| equipmentCode | VARCHAR(50) | 否 | 设备编码（冗余） |
+| equipmentName | VARCHAR(100) | 否 | 设备名称（冗余） |
+| healthScore | DECIMAL(5,2) | 是 | 健康度评分(0-100) |
+| failureDeduction | DECIMAL(5,2) | 否 | 故障扣分 |
+| maintenanceDeduction | DECIMAL(5,2) | 否 | 维保扣分 |
+| ageDeduction | DECIMAL(5,2) | 否 | 年龄扣分 |
+| failureCount30d | INTEGER | 否 | 近30天故障次数 |
+| maintenanceCompletionRate | DECIMAL(5,4) | 否 | 维保完成率 |
+| equipmentAgeYears | DECIMAL(10,2) | 否 | 设备年龄(年) |
+| operationHours30d | DECIMAL(12,2) | 否 | 近30天运行时长 |
+| mtbfHours | DECIMAL(12,2) | 否 | MTBF(小时) |
+| mttrHours | DECIMAL(12,2) | 否 | MTTR(小时) |
+| healthLevel | VARCHAR(20) | 否 | 健康等级枚举 |
+| calculatedAt | DATETIME | 是 | 计算时间 |
+| calculationPeriodDays | INTEGER | 否 | 计算周期天数 |
+| remarks | VARCHAR(1000) | 否 | 备注 |
+| createdAt | DATETIME | 否 | 创建时间 |
+| updatedAt | DATETIME | 否 | 更新时间 |
+
+**索引**:
+- `idx_health_equipment` (equipment_id)
+- `idx_health_calc_time` (calculated_at)
+- `idx_health_project` (project_id)
+
+---
+
+### 2.7 EquipmentFailureHistory（故障历史表）
+
+**表名**: `ops_equipment_failure_history`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| projectId | UUID | 是 | 项目ID |
+| equipmentId | UUID | 是 | 设备ID |
+| equipmentCode | VARCHAR(50) | 否 | 设备编码（冗余） |
+| equipmentName | VARCHAR(100) | 否 | 设备名称（冗余） |
+| failureTime | DATETIME | 是 | 故障时间 |
+| failureType | VARCHAR(50) | 否 | 故障类型枚举 |
+| failureLevel | VARCHAR(20) | 否 | 故障等级枚举 |
+| failureReason | VARCHAR(2000) | 否 | 故障原因 |
+| failureDescription | VARCHAR(2000) | 否 | 故障描述 |
+| repairStartTime | DATETIME | 否 | 修复开始时间 |
+| repairEndTime | DATETIME | 否 | 修复结束时间 |
+| repairDurationHours | DOUBLE | 否 | 修复时长(小时) |
+| repairPerson | VARCHAR(100) | 否 | 修复人 |
+| repairResult | VARCHAR(20) | 否 | 修复结果枚举 |
+| downtimeHours | DOUBLE | 否 | 停机时长(小时) |
+| maintenanceCost | DECIMAL(12,2) | 否 | 维修费用 |
+| isScheduled | BOOLEAN | 是 | 是否计划停机，默认 false |
+| relatedTaskId | UUID | 否 | 关联工单ID |
+| remarks | VARCHAR(1000) | 否 | 备注 |
+| createdAt | DATETIME | 否 | 创建时间 |
+| updatedAt | DATETIME | 否 | 更新时间 |
+| createdBy | UUID | 否 | 创建人 |
+
+**索引**:
+- `idx_failure_equipment` (equipment_id)
+- `idx_failure_time` (failure_time)
+- `idx_failure_project` (project_id)
+- `idx_efh_project_time` (project_id, failure_time)
+- `idx_efh_equipment_time` (equipment_id, failure_time DESC)
+
+---
+
+### 2.8 OwnershipEntity（归属主体表）
+
+**表名**: `asset_ownership_entity`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| entityType | VARCHAR(20) | 是 | 主体类型枚举 |
+| entityName | VARCHAR(100) | 是 | 主体名称 |
+| entityCode | VARCHAR(50) | 否 | 主体编码 |
+| contactPerson | VARCHAR(50) | 否 | 联系人 |
+| contactPhone | VARCHAR(20) | 否 | 联系电话 |
+| contactAddress | VARCHAR(255) | 否 | 联系地址 |
+| businessLicense | VARCHAR(50) | 否 | 营业执照号 |
+| legalRepresentative | VARCHAR(50) | 否 | 法人代表 |
+| contractNo | VARCHAR(50) | 否 | 合同编号 |
+| contractStartDate | DATE | 否 | 合同开始日期 |
+| contractEndDate | DATE | 否 | 合同结束日期 |
+| rentalFee | DECIMAL(12,2) | 否 | 租赁费用 |
+| status | VARCHAR(20) | 否 | 状态，默认 ACTIVE |
+| isDeleted | BOOLEAN | 否 | 逻辑删除，默认 false |
+| createdAt | DATETIME | 否 | 创建时间 |
+| updatedAt | DATETIME | 否 | 更新时间 |
+
+**索引**:
+- `idx_ownership_entity_type` (entity_type)
+- `idx_ownership_entity_code` (entity_code)
+
+---
+
+### 2.9 枚举定义汇总
+
+#### EquipmentType（设备类型 — 10种）
+
+| 枚举值 | 中文 | 对应扩展表 |
+|--------|------|------------|
+| ELEVATOR | 电梯系统 | EquipmentElevator |
+| HVAC | 暖通空调 | EquipmentHvac |
+| FIRE_PROTECTION | 消防系统 | EquipmentFire |
+| PLUMBING | 给排水系统 | — |
+| ELECTRICAL | 电气系统 | — |
+| ENERGY_METER | 能源计量 | EquipmentEnergy |
+| SECURITY | 弱电系统 | — |
+| LANDSCAPE | 景观绿化 | — |
+| KITCHEN | 厨余设备 | — |
+| OTHER | 其他设备 | — |
+
+#### EquipmentStatus（设备状态 — 4种）
+
+| 枚举值 | 中文 |
+|--------|------|
+| ACTIVE | 在用 |
+| INACTIVE | 停用 |
+| MAINTENANCE | 维保中 |
+| SCRAPPED | 已报废 |
+
+#### OwnershipType（归属类型 — 4种）
+
+| 枚举值 | 中文 |
+|--------|------|
+| PROJECT | 项目自有 |
+| COMPANY | 公司统筹 |
+| OWNER | 业主自置 |
+| RENTAL | 租赁设备 |
+
+#### SystemType（系统类型 — 9种，商业地产8大系统+其他）
+
+| 枚举值 | 中文 |
+|--------|------|
+| HVAC | 暖通空调 |
+| FIRE | 消防系统 |
+| ELEVATOR | 电梯系统 |
+| ELECTRICAL | 电气系统 |
+| PLUMBING | 给排水 |
+| BAS | 弱电智能化 |
+| KITCHEN | 餐饮厨房 |
+| LANDSCAPE | 景观 |
+| OTHER | 其他 |
+
+#### FailureType（故障类型 — 4种）
+
+| 枚举值 | 中文 |
+|--------|------|
+| SUDDEN | 突发故障 |
+| SCHEDULED | 计划停机 |
+| WARNING | 预警 |
+| OTHER | 其他 |
+
+#### FailureLevel（故障等级 — 4级）
+
+| 枚举值 | 中文 |
+|--------|------|
+| LOW | 轻微 |
+| MEDIUM | 一般 |
+| HIGH | 严重 |
+| CRITICAL | 危急 |
+
+#### RepairResult（修复结果 — 4种）
+
+| 枚举值 | 中文 |
+|--------|------|
+| FIXED | 已修复 |
+| PARTIAL_FIXED | 部分修复 |
+| REPLACED | 更换新设备 |
+| PENDING | 待处理 |
+
+#### HealthLevel（健康等级 — 5级）
+
+| 枚举值 | 中文 | 分数范围 |
+|--------|------|----------|
+| EXCELLENT | 优秀 | [90, 100) |
+| GOOD | 良好 | [75, 90) |
+| FAIR | 一般 | [60, 75) |
+| POOR | 较差 | [40, 60) |
+| CRITICAL | 危急 | [0, 40) |
+
+#### EntityType（归属主体类型 — 3种）
+
+| 枚举值 | 中文 |
+|--------|------|
+| COMPANY | 公司 |
+| OWNER | 业主 |
+| RENTAL_COMPANY | 租赁公司 |
+
+---
+
+### 2.10 实体关系图
+
+```
+┌──────────────────┐     1:1     ┌───────────────────────┐
+│   Equipment      │─────────────│  EquipmentElevator    │
+│   (主表)          │             └───────────────────────┘
+│                  │     1:1     ┌───────────────────────┐
+│  equipmentType ──│─────────────│  EquipmentHvac        │
+│  determines →    │             └───────────────────────┘
+│                  │     1:1     ┌───────────────────────┐
+│  owningEntityId ─│─────────────│  EquipmentFire        │
+│       ↓          │             └───────────────────────┘
+│                  │     1:1     ┌───────────────────────┐
+│  spaceNodeId ────│─────────────│  EquipmentEnergy      │
+│       ↓          │             └───────────────────────┘
+│                  │
+│                  │     1:N     ┌───────────────────────┐
+│                  │─────────────│ EquipmentHealthScore  │
+│                  │             └───────────────────────┘
+│                  │     1:N     ┌───────────────────────┐
+│                  │─────────────│ EquipmentFailureHist. │
+│                  │             └───────────────────────┘
+└──────────────────┘
+       │
+       │ owningEntityId
+       ↓
+┌──────────────────┐
+│ OwnershipEntity  │
+└──────────────────┘
+
+外部关联:
+  Equipment.spaceNodeId → SpaceNode.id (module-mdm)
+```
+
+---
+
+## 三、API接口设计
+
+### 3.1 EquipmentController
+
+**基础路径**: `/api/asset/equipment`
+
+#### 设备主表 CRUD
+
+| 方法 | 路径 | 说明 | 请求体 | 响应 |
+|------|------|------|--------|------|
+| POST | `/` | 创建设备 | Equipment | Equipment |
+| GET | `/{id}` | 获取设备详情 | — | Equipment |
+| PUT | `/{id}` | 更新设备 | Equipment | Equipment |
+| DELETE | `/{id}` | 删除设备 | — | Void |
+| POST | `/batch-delete` | 批量删除 | List\<UUID\> | Void |
+
+#### 设备导入导出
+
+| 方法 | 路径 | 说明 | 请求 | 响应 |
+|------|------|------|------|------|
+| POST | `/import` | Excel导入 | MultipartFile + projectId | Map(successCount, failCount, failDetails) |
+| GET | `/export` | Excel导出 | projectId | byte[] (xlsx) |
+
+**导入校验规则**:
+- 文件类型：仅支持 .xlsx / .xls
+- 文件大小：最大 10MB
+- 行数限制：最大 1000 行
+- 文件不能为空
+
+#### 设备查询
+
+| 方法 | 路径 | 说明 | 参数 | 响应 |
+|------|------|------|------|------|
+| GET | `/by-project/{projectId}` | 按项目查询 | — | List\<Equipment\> |
+| GET | `/by-space/{spaceNodeId}` | 按空间查询 | — | List\<Equipment\> |
+| GET | `/by-type` | 按类型查询 | type: EquipmentType | List\<Equipment\> |
+| GET | `/by-ownership` | 按归属查询 | ownership: OwnershipType | List\<Equipment\> |
+
+#### 设备统计
+
+| 方法 | 路径 | 说明 | 参数 | 响应 |
+|------|------|------|------|------|
+| GET | `/stats/by-type/{projectId}` | 按类型统计 | — | Map\<String, Long\> |
+| GET | `/stats/by-ownership/{projectId}` | 按归属统计 | — | Map\<String, Long\> |
+| GET | `/stats/count/{projectId}` | 项目设备总数 | — | Long |
+
+#### 电梯扩展
+
+| 方法 | 路径 | 说明 | 请求体 | 响应 |
+|------|------|------|--------|------|
+| GET | `/{id}/elevator` | 获取电梯扩展 | — | EquipmentElevator |
+| PUT | `/{id}/elevator` | 更新电梯扩展 | EquipmentElevator | EquipmentElevator |
+
+#### 暖通扩展
+
+| 方法 | 路径 | 说明 | 请求体 | 响应 |
+|------|------|------|--------|------|
+| GET | `/{id}/hvac` | 获取暖通扩展 | — | EquipmentHvac |
+| PUT | `/{id}/hvac` | 更新暖通扩展 | EquipmentHvac | EquipmentHvac |
+
+#### 能源计量扩展
+
+| 方法 | 路径 | 说明 | 请求体 | 响应 |
+|------|------|------|--------|------|
+| GET | `/{id}/energy` | 获取能源扩展 | — | EquipmentEnergy |
+| PUT | `/{id}/energy` | 更新能源扩展 | EquipmentEnergy | EquipmentEnergy |
+
+#### 消防扩展
+
+| 方法 | 路径 | 说明 | 请求体 | 响应 |
+|------|------|------|--------|------|
+| GET | `/{id}/fire` | 获取消防扩展 | — | EquipmentFire |
+| PUT | `/{id}/fire` | 更新消防扩展 | EquipmentFire | EquipmentFire |
+
+---
+
+### 3.2 EquipmentHealthController
+
+**基础路径**: `/api/asset/equipment-health`
+
+| 方法 | 路径 | 说明 | 请求体/参数 | 响应 |
+|------|------|------|-------------|------|
+| GET | `/{equipmentId}` | 获取最新健康度 | — | EquipmentHealthScore |
+| GET | `/{equipmentId}/history` | 健康度历史 | — | List\<EquipmentHealthScore\> |
+| POST | `/calculate` | 计算健康度 | { equipmentId: UUID } | EquipmentHealthScore |
+| POST | `/failure-history` | 记录故障 | EquipmentFailureHistory | EquipmentFailureHistory |
+| GET | `/failure-history/{equipmentId}` | 获取故障历史 | — | List\<EquipmentFailureHistory\> |
+| GET | `/mtbf/{equipmentId}` | 计算MTBF | days: Integer (默认30) | { equipmentId, days, mtbfHours } |
+| GET | `/mttr/{equipmentId}` | 计算MTTR | days: Integer (默认30) | { equipmentId, days, mttrHours } |
+
+---
+
+### 3.3 OwnershipEntityController
+
+**基础路径**: `/api/asset/ownership-entity`
+
+| 方法 | 路径 | 说明 | 请求体 | 响应 |
+|------|------|------|--------|------|
+| POST | `/` | 创建归属主体 | OwnershipEntity | OwnershipEntity |
+| GET | `/{id}` | 获取归属主体 | — | OwnershipEntity |
+| PUT | `/{id}` | 更新归属主体 | OwnershipEntity | OwnershipEntity |
+| DELETE | `/{id}` | 删除归属主体（逻辑删除） | — | Void |
+| GET | `/by-type` | 按类型查询 | type: EntityType | List\<OwnershipEntity\> |
+| GET | `/` | 获取全部（未删除） | — | List\<OwnershipEntity\> |
+
+**注意**: OwnershipEntityController 直接注入 Repository，未经过 Service 层，属于简化实现。
+
+---
+
+## 四、业务规则
+
+### 4.1 设备分类体系（10种 EquipmentType）
+
+设备类型采用 10 大分类体系，其中 4 种有专业扩展表：
+
+| 设备类型 | 扩展表 | 专业参数特点 |
+|----------|--------|-------------|
+| ELEVATOR（电梯系统） | EquipmentElevator | 载重、速度、楼层数、注册号、检验证书、应急救援预案 |
+| HVAC（暖通空调） | EquipmentHvac | 制冷/制热量、制冷剂、能效比(EER)、性能系数(COP)、滤网更换 |
+| FIRE_PROTECTION（消防系统） | EquipmentFire | 探测范围、分区/回路编号、联动控制、巡检周期 |
+| ENERGY_METER（能源计量） | EquipmentEnergy | 表常数、精度等级、通讯方式、检定周期 |
+| PLUMBING（给排水系统） | — | 使用主表通用字段 |
+| ELECTRICAL（电气系统） | — | 使用主表通用字段 |
+| SECURITY（弱电系统） | — | 使用主表通用字段 |
+| LANDSCAPE（景观绿化） | — | 使用主表通用字段 |
+| KITCHEN（厨余设备） | — | 使用主表通用字段 |
+| OTHER（其他设备） | — | 使用主表通用字段 + attributes JSON 扩展 |
+
+**扩展策略**: 无扩展表的设备类型通过主表的 `attributes` JSON 字段存储额外属性。
+
+### 4.2 归属管理（4种 OwnershipType）
+
+| 归属类型 | 说明 | 关联主体 |
+|----------|------|----------|
+| PROJECT | 项目自有 | 无需关联外部主体 |
+| COMPANY | 公司统筹 | 可关联 EntityType=COMPANY 的主体 |
+| OWNER | 业主自置 | 可关联 EntityType=OWNER 的主体 |
+| RENTAL | 租赁设备 | 可关联 EntityType=RENTAL_COMPANY 的主体 |
+
+**数据冗余**: Equipment 表同时存储 `owningEntityId` 和 `owningEntityName`，避免频繁关联查询。
+
+### 4.3 主表+扩展表模式
+
+**设计原则**:
+- 主表存储所有设备类型的公共字段（约40个）
+- 扩展表通过 `equipment_id`（UNIQUE）一对一关联主表
+- 扩展表仅存储专业特有字段
+- 扩展表的读写通过主设备ID路径：`GET /{id}/elevator`、`PUT /{id}/elevator`
+- 扩展表采用 saveOrUpdate 模式：存在则更新，不存在则新建
+
+**扩展表服务接口模式**（以电梯为例）:
+```java
+public interface EquipmentElevatorService {
+    Optional<EquipmentElevator> getByEquipmentId(UUID equipmentId);
+    EquipmentElevator saveOrUpdate(EquipmentElevator elevator);
+}
+```
+
+### 4.4 健康评分算法
+
+#### 评分公式
+
+```
+健康度 = 基础分(100) - 故障扣分 - 维保扣分 - 年龄扣分
+```
+
+#### 扣分规则
+
+| 扣分项 | 计算公式 | 参数 | 上限 |
+|--------|----------|------|------|
+| 故障扣分 | 故障次数(近30天) × 5 | FAILURE_DEDUCTION_PER_COUNT = 5 | 无上限 |
+| 维保扣分 | (1 - 维保完成率) × 20 | MAINTENANCE_DEDUCTION_FACTOR = 20 | 20分 |
+| 年龄扣分 | 设备年龄(年) × 2 | AGE_DEDUCTION_PER_YEAR = 2 | 10分(MAX_AGE_DEDUCTION) |
+
+**最低分**: 0分（不会为负数）
+
+#### 健康等级映射
+
+| 等级 | 分数范围 | 颜色(前端) |
+|------|----------|------------|
+| EXCELLENT（优秀） | [90, 100) | 绿色 |
+| GOOD（良好） | [75, 90) | 青色 |
+| FAIR（一般） | [60, 75) | 橙色 |
+| POOR（较差） | [40, 60) | 红色 |
+| CRITICAL（危急） | [0, 40) | 红色 |
+
+#### MTBF 计算（平均故障间隔时间）
+
+```
+MTBF = 运行时间(小时) / 故障次数
+```
+
+- 计算周期：默认30天，可自定义
+- 运行时间：从第一个故障到最后一个故障的时间跨度
+- 若仅1次故障：使用默认期间天数 × 24小时
+- 无故障时返回 0
+
+#### MTTR 计算（平均修复时间）
+
+```
+MTTR = 总修复时间(小时) / 修复次数
+```
+
+- 仅统计已完成修复的故障记录（repairDurationHours 不为空）
+- 无修复记录时返回 0
+
+#### 设备年龄计算
+
+```java
+设备年龄 = 安装年份 + 安装月份/12
+```
+
+- 优先使用 `installationDate`
+- 若无安装日期，使用 `createdAt` 的日期部分
+- 均无则返回 0
+
+**已知问题**: 当前实现中 `calculateEquipmentAge()` 方法错误地使用了 `SpaceNode.maintenanceContractStart` 而非 `Equipment.installationDate`，因为健康评分服务查询的是 SpaceNode 而非 Equipment 实体。
+
+### 4.5 故障等级（4级 FailureLevel）
+
+| 等级 | 中文 | 典型场景 |
+|------|------|----------|
+| LOW | 轻微 | 指示灯故障、外观损伤 |
+| MEDIUM | 一般 | 单个传感器故障、局部渗漏 |
+| HIGH | 严重 | 主控制器故障、系统部分失效 |
+| CRITICAL | 危急 | 电梯困人、消防系统瘫痪 |
+
+### 4.6 故障记录自动计算
+
+记录故障时自动计算：
+- **修复时长**：`repairDurationHours = (repairEndTime - repairStartTime) / 60`（分钟转小时）
+- **停机时长**：`downtimeHours = (repairStartTime - failureTime) / 60`（故障到开始修复的时间）
+
+### 4.7 设备导入规则
+
+| 规则 | 限制 |
+|------|------|
+| 文件格式 | .xlsx / .xls |
+| 文件大小 | 最大 10MB |
+| 行数限制 | 最大 1000 行 |
+| 文件编码 | UTF-8 |
+| 空文件 | 拒绝 |
+
+### 4.8 逻辑删除
+
+所有实体采用逻辑删除模式：
+- Equipment: `isDeleted` 字段，默认 false
+- OwnershipEntity: `isDeleted` 字段，默认 false
+- 查询时过滤已删除记录：`findByIdAndIsDeletedFalse`
+
+---
+
+## 五、前端操作流程
+
+### 5.1 页面结构
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 设备列表 | EquipmentList.vue | 设备台账主列表，含筛选/新增/编辑/删除/导入导出 |
+| 设备详情 | EquipmentDetail.vue | 设备完整信息展示（基本信息/技术参数/维保/财务/照片/文档） |
+| 设备健康 | EquipmentHealth.vue | 健康度评分/趋势图/MTBF/MTTR/故障历史 |
+| 巡检管理 | Inspection.vue | 巡检标准项 + 巡检记录 |
+| 维保计划 | MaintenancePlan.vue | 维保计划管理 |
+| 维保工单 | MaintenanceTask.vue | 维保工单管理（创建/分配/执行/完成/验证） |
+| 照片管理 | components/PhotoManager.vue | 设备照片上传与管理 |
+| 文档管理 | components/DocumentManager.vue | 电子文档上传与管理 |
+
+### 5.2 设备台账管理流程
+
+```
+设备列表页
+  ├── 筛选条件：项目(必选) + 设备类型 + 归属类型 + 关键词
+  ├── 操作按钮：新增设备 / 导入 / 导出 / 批量删除
+  ├── 列表展示：编码/名称/类型/归属/状态/安装位置/维保商/年检日期
+  ├── 行操作：查看详情 / 编辑 / 删除
+  └── 统计标签：按类型统计 + 按归属统计
+```
+
+### 5.3 设备详情展示流程
+
+```
+设备详情页
+  ├── 基本信息：编码/名称/类型/归属/型号/厂商/供应商/出厂编号/资产编号/安装位置/安装日期
+  ├── 技术参数：额定功率/额定电压/额定电流/设计寿命/能耗标准
+  ├── 维保信息：维保单位/联系人/电话/合同编号/合同起止日期
+  ├── 财务信息：购置日期/购置价格/保修到期日期
+  ├── 特种设备信息（条件显示）：设备类型/证书/检验周期/上次/下次检验
+  ├── 设备照片：照片画廊 + 上传
+  └── 电子文档：文档列表 + 上传
+```
+
+### 5.4 健康预测操作流程
+
+```
+设备健康页
+  ├── 选择项目 → 加载设备列表
+  ├── 选择设备 → 点击查询
+  ├── 健康度概览（4个统计卡片）
+  │   ├── 健康度评分（颜色随分数变化：≥80绿/≥60橙/<60红）
+  │   ├── 健康等级（Tag标签）
+  │   ├── 风险等级（Tag标签）
+  │   └── 最后检测时间
+  ├── MTBF/MTTR 指标卡片
+  │   ├── MTBF：平均故障间隔天数 + 总故障次数 + 总运行时长
+  │   └── MTTR：平均修复小时 + 总维修次数 + 总维修时长
+  ├── 健康度趋势图（ECharts 折线图，近30天）
+  ├── 风险因素 + 维护建议
+  └── 故障历史表格（时间/类型/等级/描述/维修时间/状态）
+```
+
+### 5.5 维保管理流程
+
+```
+维保计划页
+  ├── 选择项目 → 加载设备列表
+  ├── 创建计划：名称/设备/类型/周期/下次维保日期
+  └── 计划列表：名称/设备/类型/周期/下次日期/状态
+
+维保工单页
+  ├── 工单列表：编号/标题/设备/类型/触发类型/优先级/状态
+  ├── 工单操作：创建/分配/开始执行/完成/验证/取消
+  └── 工单统计卡片
+```
+
+### 5.6 归属主体管理流程
+
+```
+归属主体（在设备表单中通过下拉选择使用）
+  ├── 创建主体：类型/名称/联系人/电话/地址/营业执照/法人/合同信息/租赁费用
+  ├── 按类型筛选：公司/业主/租赁公司
+  └── 设备表单中：归属类型 → 联动归属主体下拉
+```
+
+---
+
+## 六、与原需求文档 03-ASSET.md 的差异对比
+
+### 6.1 数据模型差异
+
+| 对比项 | 原需求文档(03-ASSET.md) | 实际实现 | 差异分析 |
+|--------|------------------------|----------|----------|
+| **设备类型枚举** | 8种(ELEVATOR/AC/FIRE_FIGHTING/PLUMBING/POWER_SUPPLY/SECURITY/PARKING/OTHER) | 10种(ELEVATOR/HVAC/FIRE_PROTECTION/PLUMBING/ELECTRICAL/ENERGY_METER/SECURITY/LANDSCAPE/KITCHEN/OTHER) | ⚠️ 枚举值名称和数量均不同；新增ENERGY_METER/LANDSCAPE/KITCHEN；AC→HVAC；FIRE_FIGHTING→FIRE_PROTECTION；POWER_SUPPLY→ELECTRICAL；删除PARKING |
+| **设备状态枚举** | NORMAL/FAULT/MAINTAINING/SCRAPPED | ACTIVE/INACTIVE/MAINTENANCE/SCRAPPED | ⚠️ 枚举值名称不同：NORMAL→ACTIVE, FAULT→INACTIVE, MAINTAINING→MAINTENANCE |
+| **扩展表** | 无（仅attributes JSONB） | 4张扩展表(Elevator/Hvac/Fire/Energy) | 🔴 重大差异：实际实现了专业扩展表模式 |
+| **系统类型** | 无 | SystemType(9种，商业地产8大系统) | 🔴 新增：原需求无此概念 |
+| **归属管理** | 无 | OwnershipType(4种) + OwnershipEntity(3种主体) | 🔴 新增：原需求无此概念 |
+| **健康评分** | 无 | EquipmentHealthScore + MTBF/MTTR算法 | 🔴 新增：原需求无此概念 |
+| **故障历史** | 无 | EquipmentFailureHistory(4级故障/4种类型/4种修复结果) | 🔴 新增：原需求无此概念 |
+| **设备照片/文档** | 无 | JSONB内嵌(EquipmentPhoto/EquipmentDocument) | 🔴 新增：原需求无此概念 |
+| **维保计划** | MaintenancePlan实体(在asset模块) | 迁移至独立API(maintenance-plan.ts) | ⚠️ 架构调整：维保计划独立 |
+| **维保记录** | MaintenanceRecord实体(在asset模块) | 迁移至维保工单(maintenance-task.ts) | ⚠️ 架构调整：维保记录升级为工单 |
+| **设备编码字段** | code | equipmentCode | ⚠️ 字段名不同 |
+| **设备名称字段** | name | equipmentName | ⚠️ 字段名不同 |
+| **位置描述** | locationDesc | installationLocation | ⚠️ 字段名不同 |
+| **品牌字段** | brand | 无(使用manufacturer) | ⚠️ 原需求有brand，实际用manufacturer替代 |
+| **规格字段** | specifications | 无 | 🔴 原需求有，实际未实现 |
+| **负责人** | managerId/managerName/contactPhone | 无(使用维保商字段替代) | 🔴 原需求有设备负责人，实际改为维保商 |
+| **二维码** | qrCode | 无 | 🔴 原需求有，实际未实现 |
+| **导入导出** | 无 | Excel导入导出(含校验) | 🔴 新增：原需求无此概念 |
+| **批量删除** | 无 | batch-delete接口 | 🔴 新增 |
+| **财务信息** | purchaseDate/installDate/warrantyDate | purchaseDate/purchasePrice/warrantyExpireDate + 更多 | ⚠️ 实际更丰富 |
+| **特种设备** | 无 | specialEquipmentType/specialEquipmentCert/inspectionCycle | 🔴 新增 |
+| **能耗标准** | 无 | energyConsumptionStandard | 🔴 新增 |
+
+### 6.2 功能差异
+
+| 功能 | 原需求文档 | 实际实现 | 差异 |
+|------|-----------|----------|------|
+| **设备CRUD** | ✅ | ✅ | 一致 |
+| **设备与空间关联** | ✅ | ✅ | 一致 |
+| **设备二维码** | ✅ | ❌ | 未实现 |
+| **故障自动工单** | ✅ (事件驱动) | 🟡 (故障记录+关联工单ID) | 部分实现，非事件驱动 |
+| **IoT集成** | 🟡 (计划) | ❌ | 未实现 |
+| **维保到期提醒** | ✅ (定时任务) | 🟡 (前端展示下次维保日期) | 无后端定时提醒 |
+| **设备健康预测** | ❌ | ✅ (完整算法+前端图表) | 超出原需求 |
+| **归属主体管理** | ❌ | ✅ (3种主体+4种归属) | 超出原需求 |
+| **专业扩展表** | ❌ | ✅ (4张扩展表) | 超出原需求 |
+| **Excel导入导出** | ❌ | ✅ (含校验) | 超出原需求 |
+| **MTBF/MTTR** | ❌ | ✅ (可配置周期) | 超出原需求 |
+| **设备照片/文档** | ❌ | ✅ (JSONB内嵌) | 超出原需求 |
+| **维保计划** | ✅ (asset模块内) | ✅ (独立API) | 架构调整 |
+| **维保记录** | ✅ (asset模块内) | ✅ (升级为维保工单) | 架构升级 |
+
+### 6.3 实现状态总结
+
+| 模块 | 状态 | 说明 |
+|------|------|------|
+| 设备主表CRUD | 🟢 完成 | 含批量删除 |
+| 4张扩展表 | 🟢 完成 | 电梯/暖通/消防/能源 |
+| 健康评分算法 | 🟢 完成 | 含MTBF/MTTR |
+| 故障历史管理 | 🟢 完成 | 含自动计算修复/停机时长 |
+| 归属主体管理 | 🟢 完成 | 直接Repository操作 |
+| Excel导入导出 | 🟢 完成 | 含完整校验 |
+| 设备统计 | 🟢 完成 | 按类型/归属/总数 |
+| 前端设备列表 | 🟢 完成 | 含筛选/分页/操作 |
+| 前端设备详情 | 🟢 完成 | 含照片/文档管理 |
+| 前端健康预测 | 🟢 完成 | 含ECharts趋势图 |
+| 维保完成率计算 | 🟡 TODO | 代码中标记TODO，暂返回1.0 |
+| 设备二维码 | 🔴 未实现 | 原需求有但未实现 |
+| IoT集成 | 🔴 未实现 | 原需求有但未实现 |
+| 故障自动工单(事件驱动) | 🔴 未实现 | 原需求有但未实现 |
+| 维保到期定时提醒 | 🔴 未实现 | 原需求有但未实现 |
+
+### 6.4 已知代码问题
+
+| 问题 | 位置 | 说明 |
+|------|------|------|
+| 健康评分查询SpaceNode而非Equipment | EquipmentHealthServiceImpl | calculateHealthScore() 查询 SpaceNode 而非 Equipment 实体，导致设备年龄计算使用 maintenanceContractStart 而非 installationDate |
+| projectId硬编码为全零UUID | EquipmentHealthServiceImpl | `UUID.fromString("00000000-0000-0000-0000-000000000000")`，应从设备实体获取 |
+| OwnershipEntityController绕过Service层 | OwnershipEntityController | 直接注入Repository，不符合分层架构 |
+| 维保完成率固定为1.0 | EquipmentHealthServiceImpl | TODO标记，暂跳过维保完成率计算 |
+| 前端EquipmentType与后端SystemType不一致 | equipment.ts | 前端SystemType含FIRE_PROTECTION，后端SystemType含FIRE |
+| 扩展表仅4种有对应 | EquipmentType vs 扩展表 | PLUMBING/ELECTRICAL/SECURITY/LANDSCAPE/KITCHEN/OTHER 无扩展表 |
+
+---
+
+**文档说明**: 本文档基于 module-asset 模块的实际代码反推生成，与原需求文档 03-ASSET.md 存在显著差异，主要体现在：实际实现远超原需求（健康预测/归属管理/扩展表/导入导出），但部分原需求功能未实现（二维码/IoT/事件驱动工单/定时提醒）。
diff --git a/02-DESIGN/domains/REVERSE-AUTH.md b/02-DESIGN/domains/REVERSE-AUTH.md
new file mode 100644
index 0000000..5de1c15
--- /dev/null
+++ b/02-DESIGN/domains/REVERSE-AUTH.md
@@ -0,0 +1,925 @@
+# 认证授权域功能详细设计文档（反推自代码）
+
+**文档类型**: 反推设计文档
+**数据来源**: module-auth 实际代码
+**生成日期**: 2026-04-23
+**对照文档**: 05-AUTH.md（原需求设计）
+
+---
+
+## 一、领域概述
+
+### 1.1 领域职责
+
+认证授权域（module-auth）负责 Ether 平台的身份认证与授权管理，核心职责包括：
+
+- **身份认证**：用户登录/登出、JWT Token 生成与验证、登录失败锁定
+- **用户管理**：多类型用户（企业员工、项目员工、住户）的 CRUD 与扩展信息管理
+- **RBAC 权限模型**：角色-权限-用户三层关联，支持项目级角色隔离
+- **数据权限**：四级数据范围（ALL/PROJECT/DEPARTMENT/SELF）
+- **项目隔离**：用户-项目多对多关联，项目成员管理与角色分配
+- **部门管理**：树形组织架构，支持多种部门类型
+- **审计日志**：操作日志自动记录，异步持久化，30天查询窗口
+- **系统配置**：键值对形式的系统参数管理
+
+### 1.2 核心概念
+
+| 概念 | 说明 | 对应实体 |
+|------|------|----------|
+| **用户** | 系统登录账户，支持四种用户类型 | User |
+| **企业员工** | 企业类型用户的扩展信息 | EnterpriseUser |
+| **项目员工** | 项目类型员工的扩展信息，含班次、岗位状态 | ProjectStaff |
+| **住户** | 业主/家属/租户，含认证流程 | Resident |
+| **角色** | 权限集合，支持系统级/项目级/部门级 | Role |
+| **权限** | 功能访问控制点，支持菜单/按钮/API三种类型 | Permission |
+| **部门** | 组织架构节点，支持树形结构 | Dept |
+| **用户-项目关联** | 用户参与项目的多对多关系 | UserProject |
+| **项目员工角色** | 项目员工在项目中的角色分配 | ProjectStaffRole |
+| **数据访问授权** | 细粒度数据访问控制记录 | DataAccess |
+| **审计日志** | 操作审计记录 | AuditLog |
+| **房屋空间** | 项目下的房屋/空间信息 | Space |
+| **住户-房屋关联** | 住户与房屋的绑定关系 | ResidentSpace |
+| **系统配置** | 键值对形式的系统参数 | SysConfig |
+
+### 1.3 用户类型体系
+
+```
+User (基础用户)
+├── EnterpriseUser (企业员工) — 共享主键一对一
+│   └── 员工工号、部门、职位、入职日期、员工类别
+├── ProjectStaff (项目员工) — 独立主键一对一
+│   └── 所属项目、员工类型、班次、班组长、在岗状态
+│       └── ProjectStaffRole (项目员工角色) — 一对多
+└── Resident (住户) — 共享主键一对一
+    └── 身份证、住户类型、认证状态
+        └── ResidentSpace (住户-房屋关联) — 一对多
+```
+
+---
+
+## 二、数据结构设计
+
+### 2.1 User（用户）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK, 自动生成 | 用户唯一标识符 |
+| username | VARCHAR(50) | NOT NULL, UNIQUE | 登录用户名，仅字母数字下划线，3-50位 |
+| password | VARCHAR(255) | NOT NULL, JSON忽略 | BCrypt加密密码 |
+| salt | VARCHAR | JSON忽略 | 密码盐值（BCrypt模式下冗余） |
+| realName | VARCHAR(50) | | 真实姓名 |
+| phone | VARCHAR(20) | 正则`^1[3-9]\d{9}$` | 手机号码 |
+| email | VARCHAR(100) | @Email | 电子邮箱 |
+| avatar | VARCHAR | | 头像URL |
+| status | VARCHAR(20) | NOT NULL, 默认ACTIVE | 用户状态枚举 |
+| userType | VARCHAR(20) | NOT NULL | 用户类型：ENTERPRISE/PROJECT_STAFF/RESIDENT/CUSTOMER |
+| deptId | UUID | | 所属部门ID |
+| lastLoginTime | LocalDateTime | | 最后登录时间 |
+| lastLoginIp | VARCHAR | | 最后登录IP |
+| roles | List\<Role\> | M2M, LAZY | 关联角色列表（通过auth_user_role表） |
+| createdAt | LocalDateTime | NOT NULL, 自动填充 | 创建时间 |
+| updatedAt | LocalDateTime | NOT NULL, 自动填充 | 更新时间 |
+| createdBy | UUID | | 创建人ID |
+
+**枚举：UserStatus**
+
+| 值 | 描述 |
+|----|------|
+| ACTIVE | 正常 |
+| LOCKED | 锁定 |
+| DISABLED | 禁用 |
+
+**关联表：auth_user_role**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| user_id | UUID | FK → auth_user |
+| role_id | UUID | FK → auth_role |
+
+---
+
+### 2.2 Role（角色）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK, 自动生成 | 角色唯一标识符 |
+| code | VARCHAR(50) | NOT NULL, UNIQUE | 角色代码，仅字母数字下划线，2-50位 |
+| name | VARCHAR(50) | NOT NULL | 角色名称 |
+| description | VARCHAR(200) | | 角色描述 |
+| type | VARCHAR(20) | NOT NULL | 角色类型枚举 |
+| dataScope | VARCHAR(20) | 默认SELF | 数据范围枚举 |
+| projectId | UUID | | 所属项目ID（NULL=系统级） |
+| status | VARCHAR(20) | NOT NULL, 默认ENABLED | 角色状态枚举 |
+| permissions | List\<Permission\> | M2M, LAZY | 关联权限列表（通过auth_role_permission表） |
+| createdAt | LocalDateTime | NOT NULL, 自动填充 | 创建时间 |
+| updatedAt | LocalDateTime | NOT NULL, 自动填充 | 更新时间 |
+
+**枚举：RoleType**
+
+| 值 | 描述 |
+|----|------|
+| SYSTEM | 系统级 |
+| PROJECT | 项目级 |
+| DEPARTMENT | 部门级 |
+
+**枚举：DataScope**
+
+| 值 | 描述 |
+|----|------|
+| ALL | 全部数据 |
+| PROJECT | 本项目数据 |
+| DEPARTMENT | 本部门数据 |
+| SELF | 仅本人数据 |
+
+**枚举：RoleStatus**
+
+| 值 | 描述 |
+|----|------|
+| ENABLED | 启用 |
+| DISABLED | 禁用 |
+
+**关联表：auth_role_permission**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| role_id | UUID | FK → auth_role |
+| permission_id | UUID | FK → auth_permission |
+
+---
+
+### 2.3 Permission（权限）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK, 自动生成 | 权限唯一标识符 |
+| code | VARCHAR(100) | NOT NULL, UNIQUE | 权限代码，格式`module:resource:action`，仅字母数字冒号下划线 |
+| name | VARCHAR(100) | NOT NULL | 权限名称 |
+| type | VARCHAR(20) | | 权限类型：MENU/BUTTON/API |
+| resource | VARCHAR(50) | | 资源路径（API类型） |
+| method | VARCHAR(50) | | HTTP方法（API类型） |
+| description | VARCHAR(200) | | 权限描述 |
+| parentCode | VARCHAR(50) | | 父权限代码（树形结构） |
+| sortOrder | Integer | | 排序序号 |
+| roles | List\<Role\> | M2M, LAZY | 关联角色列表 |
+| createdAt | LocalDateTime | 自动填充 | 创建时间 |
+| updatedAt | LocalDateTime | 自动填充 | 更新时间 |
+
+---
+
+### 2.4 Dept（部门）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK, 自动生成 | 部门唯一标识符 |
+| parentId | UUID | | 上级部门ID（NULL=顶级） |
+| deptName | VARCHAR(100) | NOT NULL | 部门名称 |
+| deptType | VARCHAR(20) | 默认ADMIN | 部门类型 |
+| leaderId | UUID | | 部门负责人ID |
+| sortOrder | Integer | | 排序序号 |
+| status | VARCHAR(20) | 默认ACTIVE | 状态：ACTIVE/DISABLED |
+| createdAt | LocalDateTime | 自动填充 | 创建时间 |
+| updatedAt | LocalDateTime | 自动填充 | 更新时间 |
+| createdBy | UUID | | 创建人ID |
+| updatedBy | UUID | | 更新人ID |
+
+**枚举：DeptType**
+
+| 值 | 描述 |
+|----|------|
+| ADMIN | 行政管理 |
+| ENGINEERING | 工程部 |
+| SECURITY | 安保部 |
+| CS | 客服部 |
+| CLEANING | 保洁部 |
+
+---
+
+### 2.5 EnterpriseUser（企业员工）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| userId | UUID | PK, FK → auth_user | 用户ID（共享主键） |
+| employeeNo | VARCHAR(50) | | 员工工号 |
+| deptId | UUID | | 部门ID |
+| position | VARCHAR(50) | | 职位 |
+| entryDate | LocalDate | | 入职日期 |
+| userCategory | VARCHAR(50) | | 员工类别：ENTERPRISE/MANAGEMENT |
+| user | User | @OneToOne @MapsId | 关联User实体 |
+
+---
+
+### 2.6 ProjectStaff（项目员工）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK, 自动生成 | 主键ID |
+| userId | UUID | FK → auth_user | 用户ID |
+| projectId | UUID | | 所属项目ID |
+| deptId | UUID | | 所属部门ID |
+| staffType | VARCHAR(50) | | 员工类型 |
+| shiftType | VARCHAR(20) | | 班次类型：DAY/NIGHT/ROTATION |
+| leaderId | UUID | | 班组长ID |
+| assignmentStatus | VARCHAR(20) | | 在岗状态：ASSIGNED/ON_LEAVE/TRANSFERRED |
+| staffRoles | List\<ProjectStaffRole\> | @OneToMany, 级联删除 | 员工角色列表 |
+| createdAt | LocalDateTime | | 创建时间 |
+| updatedAt | LocalDateTime | | 更新时间 |
+| user | User | @OneToOne | 关联User实体 |
+
+**StaffType 枚举值**：SECURITY / CLEANING / GARDEN / MAINTENANCE / CUSTOMER_SERVICE / GENERAL
+
+---
+
+### 2.7 ProjectStaffRole（项目员工角色）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK, 自动生成 | 主键ID |
+| staff | ProjectStaff | @ManyToOne, LAZY, NOT NULL | 关联项目员工 |
+| role | Role | @ManyToOne, EAGER, NOT NULL | 关联角色 |
+| createdAt | LocalDateTime | 自动填充 | 创建时间 |
+
+---
+
+### 2.8 Resident（住户）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| userId | UUID | PK, FK → auth_user | 用户ID（共享主键） |
+| idCard | VARCHAR(18) | JSON忽略 | 身份证号码 |
+| residentType | VARCHAR(20) | | 住户类型：OWNER/FAMILY/TENANT |
+| verificationStatus | VARCHAR(20) | | 认证状态：UNVERIFIED/PENDING/VERIFIED/REJECTED |
+| verifiedAt | LocalDateTime | | 认证时间 |
+| verifiedBy | UUID | | 认证人ID |
+| user | User | @OneToOne @MapsId | 关联User实体 |
+| createdAt | LocalDateTime | NOT NULL | 创建时间 |
+| updatedAt | LocalDateTime | NOT NULL | 更新时间 |
+| createdBy | UUID | | 创建人ID |
+| updatedBy | UUID | | 更新人ID |
+
+---
+
+### 2.9 ResidentSpace（住户-房屋关联）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK, 自动生成 | 关联记录ID |
+| userId | UUID | NOT NULL | 用户ID |
+| spaceId | UUID | NOT NULL | 房屋ID |
+| relationType | VARCHAR(20) | | 关系类型：OWNER/FAMILY/TENANT |
+| bindingStatus | VARCHAR(20) | | 绑定状态：PENDING/ACTIVE/EXPIRED/CANCELLED |
+| startDate | LocalDate | | 生效日期 |
+| endDate | LocalDate | | 失效日期（NULL=永久） |
+
+---
+
+### 2.10 Space（房屋空间）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK, 自动生成 | 空间ID |
+| projectId | UUID | | 所属项目ID |
+| building | VARCHAR(50) | | 楼栋 |
+| unit | VARCHAR(50) | | 单元 |
+| roomNo | VARCHAR(50) | | 房号 |
+| spaceType | VARCHAR(20) | | 房屋类型：RESIDENTIAL/COMMERCIAL |
+| floor | Integer | | 楼层 |
+| unitArea | BigDecimal | | 建筑面积（㎡） |
+| status | VARCHAR(20) | | 状态 |
+
+---
+
+### 2.11 UserProject（用户-项目关联）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK, 自动生成 | 关联记录ID |
+| userId | UUID | NOT NULL | 用户ID |
+| projectId | UUID | NOT NULL | 项目ID |
+| roleInProject | VARCHAR | NOT NULL, 默认"member" | 项目中角色：leader/member/viewer |
+| joinedAt | LocalDateTime | NOT NULL, 默认当前时间 | 加入时间 |
+
+---
+
+### 2.12 DataAccess（数据访问授权）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK, 自动生成 | 授权记录ID |
+| dataType | VARCHAR | NOT NULL | 数据类型 |
+| dataId | UUID | NOT NULL | 数据ID |
+| accessType | VARCHAR | NOT NULL | 访问者类型 |
+| accessId | UUID | NOT NULL | 访问者ID |
+| accessLevel | VARCHAR | NOT NULL, 默认"read" | 访问级别 |
+| grantedBy | UUID | | 授权人ID |
+| grantedAt | LocalDateTime | NOT NULL, 默认当前时间 | 授权时间 |
+
+---
+
+### 2.13 AuditLog（审计日志）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK, 自动生成 | 日志ID |
+| userId | UUID | | 操作用户ID |
+| username | VARCHAR(64) | NOT NULL | 操作用户名 |
+| operation | VARCHAR(128) | NOT NULL | 操作描述 |
+| module | VARCHAR(64) | NOT NULL | 模块标识 |
+| action | VARCHAR(64) | NOT NULL | 操作类型枚举 |
+| targetType | VARCHAR(64) | | 目标类型 |
+| targetId | VARCHAR(64) | | 目标ID |
+| content | VARCHAR(2000) | | 操作内容 |
+| params | LONGVARCHAR(5000) | | 请求参数 |
+| result | LONGVARCHAR(5000) | | 操作结果 |
+| ipAddress | VARCHAR(64) | | IP地址 |
+| userAgent | VARCHAR(512) | | 用户代理 |
+| requestUrl | VARCHAR(512) | | 请求URL |
+| requestMethod | VARCHAR(16) | | 请求方法 |
+| executionTimeMs | Integer | | 执行耗时（ms） |
+| status | VARCHAR(16) | 默认SUCCESS | 状态枚举 |
+| errorMsg | VARCHAR(2000) | | 错误信息 |
+| createdAt | LocalDateTime | NOT NULL, 自动填充 | 创建时间 |
+| tenantId | UUID | | 租户ID |
+
+**索引**：
+- `idx_audit_log_created_at` → createdAt
+- `idx_audit_log_user_id` → userId
+- `idx_audit_log_module` → module
+- `idx_audit_log_action` → action
+- `idx_al_user_createdat` → userId, createdAt DESC
+
+**枚举：ActionType**
+
+| 值 | 描述 |
+|----|------|
+| CREATE | 创建 |
+| UPDATE | 修改 |
+| DELETE | 删除 |
+| QUERY | 查询 |
+| VIEW | 查看 |
+| LOGIN | 登录 |
+| LOGOUT | 登出 |
+| EXPORT | 导出 |
+| IMPORT | 导入 |
+| ASSIGN | 分配 |
+| REVOKE | 撤销 |
+
+**枚举：Status**
+
+| 值 | 描述 |
+|----|------|
+| SUCCESS | 成功 |
+| FAIL | 失败 |
+
+---
+
+### 2.14 SysConfig（系统配置）
+
+| 字段 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | UUID | PK, 自动生成 | 配置项ID |
+| configKey | VARCHAR(128) | NOT NULL, UNIQUE | 配置键 |
+| configValue | VARCHAR(5000) | | 配置值 |
+| description | VARCHAR(256) | | 配置描述 |
+| createdAt | LocalDateTime | NOT NULL, 自动填充 | 创建时间 |
+| updatedAt | LocalDateTime | NOT NULL, 自动填充 | 更新时间 |
+
+---
+
+### 2.15 实体关系图
+
+```
+┌──────────┐     M2M      ┌──────────┐     M2M      ┌────────────┐
+│   User   │◄────────────►│   Role   │◄────────────►│ Permission │
+└────┬─────┘  auth_user   └────┬─────┘ auth_role    └────────────┘
+     │         _role            │        _permission
+     │ 1:1                     │
+     ▼                         ▼
+┌──────────────┐       ┌──────────────────┐
+│EnterpriseUser│       │  ProjectStaff    │
+│  (共享主键)   │       │  (独立主键)       │
+└──────────────┘       └───────┬──────────┘
+                               │ 1:N
+                               ▼
+                       ┌──────────────────┐
+                       │ProjectStaffRole  │──────► Role
+                       └──────────────────┘
+
+┌──────────┐     1:1     ┌──────────┐
+│   User   │◄───────────►│ Resident │
+└──────────┘             └────┬─────┘
+                              │ 1:N
+                              ▼
+                      ┌───────────────┐     N:1     ┌───────┐
+                      │ResidentSpace  │◄────────────►│ Space │
+                      └───────────────┘              └───────┘
+
+┌──────────┐     N:N     ┌──────────┐
+│   User   │◄───────────►│ Project  │  (通过 UserProject)
+└──────────┘              └──────────┘
+
+┌──────────┐
+│   Dept   │  树形结构（parentId → 自引用）
+└──────────┘
+
+┌──────────┐
+│DataAccess│  通用数据访问授权
+└──────────┘
+
+┌──────────┐
+│ AuditLog │  操作审计日志
+└──────────┘
+
+┌──────────┐
+│ SysConfig│  系统键值对配置
+└──────────┘
+```
+
+---
+
+## 三、API接口设计
+
+### 3.1 AuthController — 认证管理
+
+**基础路径**: `/api/auth`
+
+| 方法 | 路径 | 说明 | 请求体 | 响应 |
+|------|------|------|--------|------|
+| POST | `/login` | 用户登录 | `{username, password}` | `{token, userId, username, realName, roles}` |
+| POST | `/logout` | 用户登出 | Header: Authorization | void |
+| GET | `/me` | 获取当前用户 | Header: Authorization | `{username}` |
+| POST | `/refresh` | 刷新Token | Header: Authorization | `{token}` |
+
+**登录流程**：
+1. 检查登录失败锁定（Redis，5次失败锁定10分钟）
+2. 查询用户（含角色）
+3. 验证密码（BCrypt）
+4. 检查用户状态（LOCKED/DISABLED拒绝）
+5. 收集所有角色（用户直接角色 + 项目员工角色）
+6. 生成JWT Token（含userId、username、roles claims）
+7. 返回Token和用户基本信息
+
+---
+
+### 3.2 UserController — 用户管理
+
+**基础路径**: `/api/auth/users`
+
+| 方法 | 路径 | 说明 | 审计日志 |
+|------|------|------|----------|
+| GET | `/` | 分页查询用户列表 | - |
+| GET | `/{id}` | 根据ID获取用户 | - |
+| POST | `/` | 创建用户 | CREATE |
+| PUT | `/{id}` | 更新用户 | UPDATE |
+| DELETE | `/{id}` | 删除用户 | DELETE |
+| PUT | `/{id}/password` | 修改密码 | UPDATE |
+| POST | `/{id}/roles` | 分配角色 | ASSIGN |
+| GET | `/{id}/projects` | 获取用户项目列表 | - |
+| POST | `/{id}/projects` | 添加用户到项目 | - |
+| DELETE | `/{id}/projects/{projectId}` | 从项目移除用户 | - |
+| GET | `/enterprise` | 获取企业员工列表 | - |
+
+**密码修改规则**：
+- 需验证原密码
+- 新密码需通过强度校验（8-20位，大小写+数字+特殊字符）
+- 弱密码检测（黑名单：password、123456、admin等）
+
+---
+
+### 3.3 RoleController — 角色管理
+
+**基础路径**: `/api/auth/roles`
+
+| 方法 | 路径 | 说明 | 审计日志 |
+|------|------|------|----------|
+| GET | `/` | 分页查询角色列表 | - |
+| GET | `/{id}` | 根据ID获取角色 | - |
+| GET | `/project/{projectId}` | 根据项目ID查询角色 | - |
+| POST | `/` | 创建角色 | CREATE |
+| PUT | `/{id}` | 更新角色 | UPDATE |
+| DELETE | `/{id}` | 删除角色 | DELETE |
+| POST | `/{id}/permissions` | 为角色分配权限 | ASSIGN |
+| GET | `/{id}/permissions` | 获取角色权限列表 | - |
+| GET | `/{id}/users` | 获取拥有某角色的用户 | - |
+
+---
+
+### 3.4 PermissionController — 权限管理
+
+**基础路径**: `/api/auth/permissions`
+
+| 方法 | 路径 | 说明 | 审计日志 |
+|------|------|------|----------|
+| GET | `/` | 分页查询权限列表 | - |
+| GET | `/{id}` | 根据ID获取权限 | - |
+| GET | `/type/{type}` | 根据类型查询权限 | - |
+| GET | `/menus` | 查询所有菜单权限 | - |
+| POST | `/` | 创建权限 | - |
+| PUT | `/{id}` | 更新权限 | - |
+| DELETE | `/{id}` | 删除权限 | - |
+
+---
+
+### 3.5 DeptController — 部门管理
+
+**基础路径**: `/api/auth/depts`
+
+| 方法 | 路径 | 说明 | 审计日志 |
+|------|------|------|----------|
+| GET | `/tree` | 获取部门树 | - |
+| GET | `/` | 获取所有启用部门 | - |
+| GET | `/{id}` | 根据ID获取部门 | - |
+| POST | `/` | 创建部门 | CREATE |
+| PUT | `/{id}` | 更新部门 | UPDATE |
+| DELETE | `/{id}` | 删除部门 | DELETE |
+| GET | `/{deptId}/members` | 获取部门成员 | - |
+| GET | `/by-type/{deptType}` | 根据类型查询部门 | - |
+
+**部门树构建**：后端返回扁平列表，Controller层递归构建树形结构（DeptVO含children字段）
+
+---
+
+### 3.6 ProjectMemberController — 项目成员管理
+
+**基础路径**: `/api/auth/projects`
+
+| 方法 | 路径 | 说明 | 审计日志 |
+|------|------|------|----------|
+| GET | `/{projectId}/members` | 查询项目成员列表（分页） | - |
+| GET | `/{projectId}/available-members` | 获取可添加成员（企业员工） | - |
+| POST | `/{projectId}/members` | 添加项目成员 | CREATE |
+| DELETE | `/{projectId}/members/{userId}` | 移除项目成员 | DELETE |
+
+**添加项目成员流程**：
+1. 创建/更新 ProjectStaff 记录（设定员工类型、分配状态）
+2. 覆盖模式更新角色：先删除旧角色，再添加新角色
+3. 支持 search 参数模糊搜索可用成员（用户名/姓名）
+
+---
+
+### 3.7 DataAccessController — 数据访问授权
+
+**基础路径**: `/api/data-access`
+
+| 方法 | 路径 | 说明 | 请求体 |
+|------|------|------|--------|
+| POST | `/` | 授予数据访问权限 | `{dataType, dataId, accessType, accessId, accessLevel}` |
+| DELETE | `/{id}` | 撤销数据访问权限 | - |
+| GET | `/` | 查询数据访问记录 | 参数: dataType, dataId |
+
+**授权逻辑**：若已存在相同 dataType+dataId+accessType+accessId 的记录，则更新 accessLevel；否则新建。
+
+---
+
+### 3.8 AuditLogController — 审计日志
+
+**基础路径**: `/api/audit-logs`
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/` | 分页查询审计日志（支持module/action/username/日期范围筛选） |
+| GET | `/modules` | 获取模块列表（用于筛选下拉） |
+| GET | `/actions` | 获取操作类型列表（用于筛选下拉） |
+| GET | `/stats` | 获取最近30天日志统计 |
+
+**查询约束**：强制限制查询范围不超过30天，防止大量数据查询。
+
+**模块列表**：USER / ROLE / PERMISSION / PROJECT / AUTH
+
+---
+
+### 3.9 SysConfigController — 系统配置
+
+**基础路径**: `/api/config`
+
+| 方法 | 路径 | 说明 | 审计日志 |
+|------|------|------|----------|
+| GET | `/` | 获取所有配置项 | - |
+| GET | `/{configKey}` | 根据键获取配置 | - |
+| PUT | `/{configKey}` | 更新单个配置 | UPDATE |
+| PUT | `/` | 批量更新配置 | UPDATE |
+
+---
+
+## 四、业务规则
+
+### 4.1 RBAC 权限模型
+
+**模型结构**：User ←M2M→ Role ←M2M→ Permission
+
+**双层角色分配**：
+1. **用户直接角色**：通过 `auth_user_role` 表关联，用户创建时或通过 UserController.assignRoles 分配
+2. **项目员工角色**：通过 `ProjectStaffRole` 关联，项目成员管理时分配
+
+**登录时角色收集**：
+```
+用户所有角色 = 用户直接角色 ∪ 项目员工角色
+```
+
+**角色类型与数据范围**：
+
+| 角色类型 | 说明 | 数据范围 |
+|---------|------|---------|
+| SYSTEM | 系统级角色，跨项目 | ALL |
+| PROJECT | 项目级角色，绑定特定项目 | PROJECT |
+| DEPARTMENT | 部门级角色 | DEPARTMENT |
+
+### 4.2 四级数据范围
+
+| 数据范围 | 编码 | 说明 | 实际效果 |
+|---------|------|------|---------|
+| 全部 | ALL | 可查看所有数据 | 不做数据过滤 |
+| 项目 | PROJECT | 仅可查看所属项目数据 | 过滤 project_id |
+| 部门 | DEPARTMENT | 仅可查看本部门数据 | 过滤 project_id + dept_id |
+| 本人 | SELF | 仅可查看本人数据 | 过滤 assigned_to/creator |
+
+**DataScopeService 实现**：
+- `canAccessAllData()`: 检查角色集中是否有 ALL 范围
+- `isSelfScopeOnly()`: 检查是否所有角色都是 SELF 范围
+- `getPermittedProjectIds()`: 获取用户可访问的项目ID列表
+
+### 4.3 JWT 认证流程
+
+**Token 生成**：
+- 算法：HMAC-SHA256
+- Claims：userId（subject）、username、roles 列表
+- 过期时间：可配置（默认86400000ms = 24小时）
+
+**认证流程**：
+```
+1. 客户端 POST /api/auth/login {username, password}
+2. 检查登录锁定（Redis: login:attempt:{username}）
+3. 查询用户 + 验证密码（BCrypt）
+4. 检查用户状态
+5. 收集角色（直接角色 + 项目员工角色）
+6. 生成 JWT Token
+7. 返回 {token, userId, username, realName, roles}
+
+后续请求：
+1. 客户端 Header: Authorization: Bearer {token}
+2. JwtTokenProvider.validateToken() 验证签名和过期
+3. 解析 userId / username / roles
+```
+
+**Token 刷新**：
+- POST /api/auth/refresh，需携带有效Token
+- 生成新Token返回
+
+### 4.4 登录失败锁定机制
+
+**实现**：LoginAttemptService（基于Redis）
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| maxAttempts | 5 | 最大失败次数 |
+| lockoutDurationMinutes | 10 | 锁定时长（分钟） |
+| Key格式 | `login:attempt:{username}` | Redis Key |
+
+**流程**：
+- 每次失败：increment计数，首次设置TTL
+- 达到上限：isLockedOut返回true，拒绝登录
+- 登录成功：清除计数
+- 手动解锁：unlock方法清除Key
+
+### 4.5 项目隔离机制
+
+**双层隔离**：
+1. **UserProject 关联**：用户-项目多对多，记录用户参与的项目
+2. **ProjectStaff 扩展**：项目员工在特定项目中的详细角色和状态
+
+**项目上下文传递**：
+- 请求头 `X-Project-ID` 携带当前项目ID
+- ProjectContextInterceptor 拦截器设置 ThreadLocal
+- 业务层通过 DataScopeService 过滤数据
+
+**项目成员管理**：
+- 添加成员：创建 ProjectStaff + 分配 ProjectStaffRole
+- 移除成员：删除 ProjectStaff（级联删除角色关联）
+- 角色分配：覆盖模式（先删后加）
+
+### 4.6 审计日志
+
+**记录方式**：`@OperationLog` 注解 + AOP切面
+
+```java
+@OperationLog(operation = "创建用户", module = "USER", action = AuditLog.ActionType.CREATE)
+```
+
+**异步持久化**：通过 `auditLogExecutor` 线程池异步保存，避免影响业务性能
+
+**查询窗口**：强制限制30天，超过30天的查询自动截断起始时间
+
+**归档策略**：90天以上日志归档（当前实现为直接删除，TODO: 导出至对象存储）
+
+**记录模块**：USER / ROLE / PERMISSION / PROJECT / AUTH / DEPT / PROJECT_MEMBER / SYSTEM
+
+### 4.7 密码加密与强度校验
+
+**加密算法**：BCrypt（Spring Security PasswordEncoder）
+
+**强度校验规则**（可配置，前缀 `password.*`）：
+
+| 规则 | 默认值 | 说明 |
+|------|--------|------|
+| minLength | 8 | 最小长度 |
+| maxLength | 20 | 最大长度 |
+| requireUppercase | true | 需要大写字母 |
+| requireLowercase | true | 需要小写字母 |
+| requireDigit | true | 需要数字 |
+| requireSpecial | true | 需要特殊字符 |
+
+**弱密码检测**：黑名单包含 password、123456、admin、qwerty、letmein、welcome、monkey、dragon
+
+**旧密码兼容**：检测非BCrypt格式密码（MD5/SHA-1），强制返回false要求重置
+
+---
+
+## 五、前端操作流程
+
+### 5.1 登录
+
+**页面**：`/auth/Login.vue`
+
+**流程**：
+1. 输入用户名 + 密码
+2. 调用 `POST /api/auth/login`
+3. 存储 Token 到本地
+4. 跳转至主页
+
+**前端API**：`auth.ts` → `login()`, `logout()`, `getCurrentUser()`, `refreshToken()`
+
+### 5.2 项目选择
+
+**流程**：
+1. 登录后获取用户项目列表 `GET /api/auth/users/{id}/projects`
+2. 用户选择项目
+3. 后续请求携带 `X-Project-ID` Header
+
+### 5.3 用户管理
+
+**页面**：`/system/Users.vue`, `/system/UserDetail.vue`
+
+**操作**：
+- 用户列表（分页、搜索、状态筛选）
+- 创建用户（用户名、密码、真实姓名、手机号、邮箱、用户类型、部门）
+- 编辑用户信息
+- 删除用户
+- 修改密码（需原密码）
+- 分配角色（多选，覆盖模式）
+- 查看用户参与的项目
+
+**前端API**：`user.ts` → `getUsers()`, `createUser()`, `updateUser()`, `deleteUser()`, `updatePassword()`, `assignRoles()`, `getUserProjects()`
+
+### 5.4 角色管理
+
+**页面**：`/system/Roles.vue`
+
+**操作**：
+- 角色列表（分页、搜索）
+- 创建角色（代码、名称、描述、类型、数据范围、所属项目、状态）
+- 编辑角色
+- 删除角色
+- 为角色分配权限（多选，覆盖模式）
+- 查看角色关联的用户
+
+**前端API**：`role.ts` → `getRoles()`, `createRole()`, `updateRole()`, `deleteRole()`, `assignPermissions()`, `getRolePermissions()`, `getRoleUsers()`, `getRolesByProject()`
+
+### 5.5 权限管理
+
+**页面**：`/system/Permissions.vue`
+
+**操作**：
+- 权限列表（分页、搜索）
+- 创建权限（代码、名称、类型、资源路径、HTTP方法、描述、父权限、排序）
+- 编辑权限
+- 删除权限
+- 按类型筛选（MENU/BUTTON/API）
+- 查看菜单权限
+
+**前端API**：`permission.ts` → `getPermissions()`, `createPermission()`, `updatePermission()`, `deletePermission()`, `getPermissionsByModule()`
+
+### 5.6 部门管理
+
+**页面**：`/system/Depts.vue`
+
+**操作**：
+- 部门树展示
+- 创建部门（名称、上级部门、类型、负责人、排序）
+- 编辑部门
+- 删除部门（需先删除子部门）
+- 查看部门成员
+- 按类型筛选部门
+
+**前端API**：`dept.ts` → `getDeptTree()`, `getAllDepts()`, `createDept()`, `updateDept()`, `deleteDept()`, `getDeptMembers()`, `getDeptsByType()`
+
+### 5.7 审计日志
+
+**页面**：`/system/Audit.vue`
+
+**操作**：
+- 日志列表（分页、模块/操作类型/用户名/日期范围筛选）
+- 查看日志统计（最近30天总量）
+- 模块和操作类型下拉选项
+
+**前端API**：`audit.ts` → `getAuditLogs()`, `getAuditModules()`, `getAuditActions()`, `getAuditStats()`
+
+### 5.8 系统设置
+
+**页面**：`/system/Settings.vue`
+
+**操作**：
+- 查看所有配置项（键值对）
+- 单个/批量更新配置值
+
+**前端API**：`system.ts` → `getConfig()`, `updateConfig()`
+
+---
+
+## 六、与原需求文档 05-AUTH.md 的差异对比
+
+### 6.1 实体差异
+
+| 对比项 | 原需求 05-AUTH.md | 实际代码实现 | 差异说明 |
+|--------|-------------------|-------------|----------|
+| **Role.type** | SYSTEM / CUSTOM | SYSTEM / PROJECT / DEPARTMENT | 实际代码使用三级分类（系统/项目/部门），而非预设/自定义 |
+| **Role 业务属性** | 有 businessType、terminalType、isFrontline 字段 | 无这些字段 | 实际代码未实现角色业务属性扩展 |
+| **Role.status** | enabled (Boolean) | status (RoleStatus枚举: ENABLED/DISABLED) | 实际代码使用枚举而非布尔值 |
+| **Permission 结构** | 有 projectId、module、resource、action、path、component、icon、parentId(UUID)、level、apiMethod、apiPath、enabled | 无 projectId/module/resource/action/path/component/icon/parentId(UUID)/level/apiMethod/apiPath/enabled，有 parentCode(String)、resource、method | 实际代码简化了权限结构，用 parentCode 替代 parentId，缺少菜单路由属性 |
+| **Permission.type** | PermissionType 枚举 (MENU/BUTTON/API) | String 类型 | 实际代码用字符串而非枚举 |
+| **UserRole 关联** | 独立实体 UserRole（含 projectId、isDefault） | JPA自动管理的 M2M 中间表 auth_user_role（无额外字段） | 实际代码简化了关联，去掉了项目隔离和默认角色标记 |
+| **OperationLog** | auth_operation_log 表，含 projectId、realName、description、requestBody、responseBody、responseStatus、hasError | sys_audit_log 表，含 content、params、result、targetType、targetId、executionTimeMs、status、errorMsg、tenantId | 实际代码使用了不同的表名和字段结构，增加了目标追踪和租户ID |
+| **VisitorCredential** | 完整实体（auth_visitor_credential） | 不存在于 module-auth | 访客凭证未在认证模块实现 |
+| **EnterpriseUser** | 未提及 | 存在，共享主键一对一 | 实际代码增加了企业员工扩展实体 |
+| **ProjectStaff** | 未提及 | 存在，独立主键一对一 | 实际代码增加了项目员工扩展实体 |
+| **ProjectStaffRole** | 未提及 | 存在，项目员工-角色关联 | 实际代码增加了项目级角色分配机制 |
+| **Resident** | 未提及 | 存在，含认证流程 | 实际代码增加了住户实体 |
+| **ResidentSpace** | 未提及 | 存在，住户-房屋关联 | 实际代码增加了住户房屋绑定 |
+| **Space** | 未提及 | 存在，房屋空间 | 实际代码增加了房屋空间实体 |
+| **UserProject** | 未提及 | 存在，用户-项目关联 | 实际代码增加了用户项目多对多 |
+| **DataAccess** | 未提及 | 存在，细粒度数据访问控制 | 实际代码增加了数据访问授权机制 |
+| **Dept** | 未提及 | 存在，树形部门结构 | 实际代码增加了部门管理 |
+| **SysConfig** | 未提及 | 存在，键值对配置 | 实际代码增加了系统配置 |
+| **User.userType** | 未提及 | 存在，ENTERPRISE/PROJECT_STAFF/RESIDENT/CUSTOMER | 实际代码增加了用户类型区分 |
+| **User.deptId** | 未提及 | 存在 | 实际代码增加了部门关联 |
+
+### 6.2 API 差异
+
+| 对比项 | 原需求 05-AUTH.md | 实际代码实现 | 差异说明 |
+|--------|-------------------|-------------|----------|
+| **API路径前缀** | `/api/v1/auth` | `/api/auth` | 实际代码去掉了版本号 v1 |
+| **认证接口** | login/logout/refreshToken/currentUser/changePassword/userPermissions | login/logout/refresh/me | 实际代码缺少 changePassword 和 userPermissions 独立端点，/me 替代 currentUser |
+| **用户状态修改** | `POST /{id}/status` 独立端点 | 通过 `PUT /{id}` 更新status字段 | 实际代码合并到通用更新接口 |
+| **权限树** | `GET /permissions/tree` | 未实现 | 实际代码缺少权限树端点 |
+| **权限校验** | `POST /check` | 未实现 | 实际代码缺少权限校验端点 |
+| **用户菜单** | `GET /users/{id}/menus` | 未实现 | 实际代码缺少用户菜单端点 |
+| **用户权限查询** | `GET /users/{id}/permissions` | 未实现 | 实际代码缺少用户权限查询端点 |
+| **部门管理** | 未提及 | 完整CRUD + 树 + 成员查询 | 实际代码新增了部门管理 |
+| **项目成员管理** | 未提及 | 完整CRUD + 可用成员查询 | 实际代码新增了项目成员管理 |
+| **数据访问授权** | 未提及 | grant/revoke/query | 实际代码新增了数据访问授权 |
+| **审计日志** | 未提及 | 完整查询 + 统计 + 筛选选项 | 实际代码新增了审计日志管理 |
+| **系统配置** | 未提及 | 完整CRUD + 批量更新 | 实际代码新增了系统配置管理 |
+| **企业员工** | 未提及 | `GET /users/enterprise` | 实际代码新增了企业员工列表 |
+| **用户项目关联** | 未提及 | 完整CRUD | 实际代码新增了用户项目关联 |
+
+### 6.3 业务规则差异
+
+| 对比项 | 原需求 05-AUTH.md | 实际代码实现 | 差异说明 |
+|--------|-------------------|-------------|----------|
+| **角色体系** | 13个预定义角色（SUPER_ADMIN到OWNER） | 角色通过数据库动态管理，无硬编码预定义 | 实际代码采用灵活的角色管理，未绑定固定角色列表 |
+| **数据权限SQL生成** | DataScopeHelper 工具类生成SQL片段 | DataScopeService 提供判断方法 | 实际代码未实现SQL自动注入，仅提供判断接口 |
+| **项目上下文** | ProjectContextHolder + 拦截器 | 同样实现，通过 X-Project-ID Header | 基本一致 |
+| **状态驱动权限** | 工单状态→操作映射设计 | 未在认证模块实现 | 实际代码未实现状态驱动权限（应在业务模块） |
+| **访客凭证** | 完整的二维码生成/验证流程 | 不存在于 module-auth | 实际代码未实现访客凭证 |
+| **登录失败锁定** | 未提及 | Redis实现，5次失败锁10分钟 | 实际代码新增了登录安全机制 |
+| **密码强度校验** | 未提及 | 完整的强度规则 + 弱密码检测 | 实际代码新增了密码安全策略 |
+| **旧密码兼容** | 未提及 | 检测非BCrypt格式，强制重置 | 实际代码新增了密码迁移策略 |
+| **审计日志** | AOP切面 + 同步保存 | AOP切面 + 异步保存 + 30天查询限制 + 90天归档 | 实际代码增强了审计日志管理 |
+| **项目成员角色** | 未提及 | 双层角色（用户直接角色 + 项目员工角色） | 实际代码新增了项目级角色分配 |
+| **部门类型** | 未提及 | 5种部门类型（行政/工程/安保/客服/保洁） | 实际代码新增了部门分类 |
+| **住户认证** | 未提及 | 4种认证状态（未认证/待审核/已认证/已拒绝） | 实际代码新增了住户认证流程 |
+| **数据访问授权** | 未提及 | 通用数据访问控制（dataType/dataId/accessType/accessId/accessLevel） | 实际代码新增了细粒度数据授权 |
+
+### 6.4 差异总结
+
+**实际代码相比原需求增加的功能**：
+1. 多类型用户扩展（EnterpriseUser / ProjectStaff / Resident）
+2. 项目成员管理（ProjectStaff + ProjectStaffRole）
+3. 部门管理（树形结构 + 5种类型）
+4. 住户与房屋关联（ResidentSpace + Space）
+5. 数据访问授权（DataAccess）
+6. 系统配置管理（SysConfig）
+7. 登录失败锁定（Redis）
+8. 密码强度校验 + 弱密码检测
+9. 审计日志增强（异步保存、30天窗口、90天归档）
+10. 用户-项目多对多关联（UserProject）
+
+**原需求中未实现的功能**：
+1. 角色业务属性（businessType / terminalType / isFrontline）
+2. 权限树端点（GET /permissions/tree）
+3. 权限校验端点（POST /check）
+4. 用户菜单端点（GET /users/{id}/menus）
+5. 用户权限查询端点（GET /users/{id}/permissions）
+6. 访客凭证管理（VisitorCredential）
+7. 状态驱动权限（工单状态→操作映射）
+8. Permission 的菜单路由属性（path / component / icon）
+9. Permission 的模块/资源/操作拆分字段（module / resource / action）
+10. UserRole 关联的项目隔离和默认角色标记
diff --git a/02-DESIGN/domains/REVERSE-FINANCE.md b/02-DESIGN/domains/REVERSE-FINANCE.md
new file mode 100644
index 0000000..12ac81e
--- /dev/null
+++ b/02-DESIGN/domains/REVERSE-FINANCE.md
@@ -0,0 +1,426 @@
+# 财务域功能详细设计文档（反推自代码）
+
+**文档类型**: 反推设计文档（基于实际代码逆向分析）
+**生成日期**: 2026-04-23
+**分析方法**: 全量搜索 ether-pms 后端代码 + ether-admin 前端代码
+**对比基线**: `ether-docs/02-DESIGN/domains/04-FINANCE.md`
+
+---
+
+## 一、领域概述（当前实现状态）
+
+### 1.1 总体结论
+
+**财务域核心功能（FeeItem / FeeBill / FeePayment / FeeRefund）均未实现。** 不存在 `module-finance` 模块，不存在任何 `fin_*` 数据库表，不存在任何收费/账单/支付/退款相关的后端实体、服务或控制器。
+
+当前已实现的与财务域有间接关联的功能，仅有 **能耗计量管理**（EnergyMeter / EnergyConsumption），归属在 `module-mdm` 模块中，实现了能耗数据的采集和简单费用计算（消耗量 × 单价），但未与账单系统对接。
+
+### 1.2 实现状态总览
+
+| 功能模块 | 设计文档状态 | 实际代码状态 | 差异 |
+|---------|------------|------------|------|
+| FeeItem（收费项目） | 🟢 已实现 | 🔴 **未实现** | 设计文档与实际代码不符 |
+| FeeBill（收费账单） | 🟢 已实现 | 🔴 **未实现** | 设计文档与实际代码不符 |
+| FeePayment（支付记录） | 🟢 已实现 | 🔴 **未实现** | 设计文档与实际代码不符 |
+| FeeRefund（退款记录） | 🔴 未实现 | 🔴 未实现 | 一致 |
+| 费用催缴定时任务 | 🟢 已实现 | 🔴 **未实现** | 设计文档与实际代码不符 |
+| 滞纳金计算 | 🟢 已实现 | 🔴 **未实现** | 设计文档与实际代码不符 |
+| 能耗计量管理 | 未在设计文档中 | 🟢 **已实现** | 在 module-mdm 中实现 |
+| 能耗费用计算 | 未在设计文档中 | 🟢 **已实现** | 简单的 consumption × unitPrice |
+| 支付网关对接 | 🔴 未实现 | 🔴 未实现 | 一致 |
+| 财务报表 | 🔴 未实现 | 🔴 未实现 | 一致 |
+
+### 1.3 关键发现
+
+1. **`module-finance` 模块不存在** — 在 `ether-pms` 中无此目录
+2. **`fin_*` 数据库表不存在** — 无 FeeItem / FeeBill / FeePayment / FeeRefund 对应的表
+3. **设计文档 04-FINANCE.md 标注"已实现"的功能实际未实现** — 文档中 FeeItem/FeeBill/FeePayment 标记为 🟢 已实现，但代码中找不到任何对应实体
+4. **能耗管理在 module-mdm 中实现** — EnergyMeter / EnergyConsumption 实体、服务、控制器、前端页面均已实现
+5. **前端无任何财务相关页面** — ether-admin 中无 fee/bill/payment/refund 相关视图，仅有 energy 相关视图
+6. **员工端/业主端无财务功能** — ether-app-employee 和 ether-app-owner 中无任何财务相关代码
+
+---
+
+## 二、已实现的数据结构（能耗计量相关实体）
+
+### 2.1 EnergyMeter（能源计量点）
+
+**所在模块**: `module-mdm`
+**数据库表**: `ops_energy_meter`
+**源码位置**: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/EnergyMeter.java`
+
+| 字段名 | 类型 | 数据库列名 | 约束 | 说明 |
+|--------|------|-----------|------|------|
+| id | UUID | id | PK | 主键 |
+| projectId | UUID | project_id | NOT NULL | 所属项目 |
+| meterCode | String | meter_code | NOT NULL, UNIQUE | 计量点编码（自动生成：EM + yyyyMMddHHmmss） |
+| meterName | String | meter_name | NOT NULL | 计量点名称 |
+| energyType | EnergyType | energy_type | NOT NULL | 能源类型枚举 |
+| spaceNodeId | UUID | space_node_id | — | 关联空间节点 |
+| installationLocation | String | installation_location | — | 安装位置 |
+| ratedCapacity | BigDecimal(10,2) | rated_capacity | — | 额定容量 |
+| unitPrice | BigDecimal(10,4) | unit_price | — | 单价（用于费用计算） |
+| status | Status | status | NOT NULL | 状态枚举，默认 ACTIVE |
+| createdAt | LocalDateTime | created_at | — | 创建时间 |
+| updatedAt | LocalDateTime | updated_at | — | 更新时间 |
+
+**枚举定义**:
+
+```java
+public enum EnergyType {
+    LIGHTING("照明插座用电"),
+    HVAC("空调用电"),
+    POWER("动力用电"),
+    SPECIAL("特殊用电"),
+    WATER("给排水"),
+    GAS("燃气");
+}
+
+public enum Status {
+    ACTIVE, INACTIVE
+}
+```
+
+**与原设计文档的差异**:
+
+| 项目 | 原设计（04-FINANCE.md） | 实际实现 | 差异说明 |
+|------|------------------------|---------|---------|
+| 所属模块 | ether-finance | module-mdm | 归属不同模块 |
+| 能源类型 | FeeType: PROPERTY/PARKING/WATER/ELECTRICITY/GAS/HEATING/REPAIR_FUND/OTHER | EnergyType: LIGHTING/HVAC/POWER/SPECIAL/WATER/GAS | 实际更细分（按用电分项），但缺少供暖、物业费等 |
+| 单价精度 | NUMERIC(12,2) | BigDecimal(10,4) | 实际精度更高（4位小数） |
+| 计费方式 | BillingMethod: FIXED/AREA/USAGE/CUSTOM | 无 | 未实现计费方式枚举 |
+| 账期/到期日 | billDay/dueDay/overdueDay | 无 | 未实现账期管理 |
+| 滞纳金 | enableLateFee/lateFeeRate/maxLateFee | 无 | 未实现滞纳金 |
+
+### 2.2 EnergyConsumption（能耗记录）
+
+**所在模块**: `module-mdm`
+**数据库表**: `ops_energy_consumption`
+**源码位置**: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/EnergyConsumption.java`
+
+| 字段名 | 类型 | 数据库列名 | 约束 | 说明 |
+|--------|------|-----------|------|------|
+| id | UUID | id | PK | 主键 |
+| projectId | UUID | project_id | NOT NULL | 所属项目 |
+| meterId | UUID | meter_id | NOT NULL | 关联计量点 |
+| consumptionDate | LocalDate | consumption_date | NOT NULL | 记录日期 |
+| previousReading | BigDecimal(12,2) | previous_reading | — | 上次读数 |
+| currentReading | BigDecimal(12,2) | current_reading | — | 当前读数 |
+| consumption | BigDecimal(12,2) | consumption | NOT NULL | 消耗量 = current − previous |
+| amount | BigDecimal(10,2) | amount | — | 费用 = consumption × unitPrice |
+| recordedBy | UUID | recorded_by | — | 记录人 |
+| recordMethod | RecordMethod | record_method | — | 记录方式，默认 MANUAL |
+| remarks | String(1000) | remarks | — | 备注 |
+| createdAt | LocalDateTime | created_at | — | 创建时间 |
+
+**数据库索引**:
+
+```sql
+idx_ec_meter_date   -- (meter_id, consumption_date)
+idx_ec_project_date -- (project_id, consumption_date)
+```
+
+**枚举定义**:
+
+```java
+public enum RecordMethod {
+    MANUAL,  // 手动录入
+    IOT      // IoT自动采集
+}
+```
+
+**与原设计文档的差异**:
+
+| 项目 | 原设计（FeeBill） | 实际实现（EnergyConsumption） | 差异说明 |
+|------|------------------|---------------------------|---------|
+| 实体性质 | 账单（应收费用单据） | 能耗记录（抄表数据） | 本质不同，能耗记录不是账单 |
+| 账单编号 | billNo | 无 | 无账单编号 |
+| 关联业主 | ownerId | 无 | 未关联业主 |
+| 关联房产 | spaceNodeId | 间接通过meter.spaceNodeId | 未直接关联 |
+| 账期 | billPeriod/billDate/dueDate/overdueDate | consumptionDate | 无账期概念 |
+| 金额体系 | amount/lateFee/discount/payableAmount/paidAmount | amount（仅计算值） | 无应收/已付/优惠/滞纳金 |
+| 状态流转 | UNPAID/PARTIAL_PAID/PAID/OVERDUE/CANCELLED | 无状态 | 无支付状态 |
+| 用量单位 | usageAmount + usageUnit | consumption | 无独立用量单位 |
+
+---
+
+## 三、已实现的API接口
+
+### 3.1 后端API（EnergyController）
+
+**基础路径**: `/api/ops/energy`
+**源码位置**: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/controller/EnergyController.java`
+
+#### 3.1.1 计量点管理
+
+| 方法 | 路径 | 说明 | 请求参数 | 响应类型 |
+|------|------|------|---------|---------|
+| POST | `/meters` | 创建计量点 | EnergyMeter JSON | `ApiResponse<EnergyMeter>` |
+| GET | `/meters` | 查询计量点列表 | projectId(必填), energyType(可选) | `ApiResponse<List<EnergyMeter>>` |
+| GET | `/meters/{id}` | 获取计量点详情 | path: id | `ApiResponse<EnergyMeter>` |
+| PUT | `/meters/{id}` | 更新计量点 | path: id, EnergyMeter JSON | `ApiResponse<EnergyMeter>` |
+| DELETE | `/meters/{id}` | 删除计量点（软删除） | path: id | `ApiResponse<Void>` |
+
+#### 3.1.2 能耗记录
+
+| 方法 | 路径 | 说明 | 请求参数 | 响应类型 |
+|------|------|------|---------|---------|
+| POST | `/consumption` | 录入能耗数据 | `{meterId, currentReading, recordedBy}` | `ApiResponse<EnergyConsumption>` |
+| GET | `/consumption/{meterId}` | 查询能耗记录 | path: meterId, startDate(可选), endDate(可选) | `ApiResponse<List<EnergyConsumption>>` |
+
+#### 3.1.3 能耗统计
+
+| 方法 | 路径 | 说明 | 请求参数 | 响应类型 |
+|------|------|------|---------|---------|
+| GET | `/statistics/by-type` | 按类型统计消耗 | projectId, month(yyyy-MM-dd) | `ApiResponse<Map<EnergyType, BigDecimal>>` |
+| GET | `/statistics/unit-consumption` | 单方能耗 | projectId, month(yyyy-MM-dd) | `ApiResponse<BigDecimal>` |
+
+### 3.2 前端API封装
+
+**源码位置**: `ether-admin/src/api/energy.ts`
+
+| 函数名 | HTTP方法 | URL | 说明 |
+|--------|---------|-----|------|
+| `getEnergyMeters` | GET | `/api/ops/energy/meters` | 获取计量点列表 |
+| `getEnergyMeter` | GET | `/api/ops/energy/meters/{id}` | 获取计量点详情 |
+| `createEnergyMeter` | POST | `/api/ops/energy/meters` | 创建计量点 |
+| `updateEnergyMeter` | PUT | `/api/ops/energy/meters/{id}` | 更新计量点 |
+| `deleteEnergyMeter` | DELETE | `/api/ops/energy/meters/{id}` | 删除计量点 |
+| `recordEnergyConsumption` | POST | `/api/ops/energy/consumption` | 录入能耗 |
+| `getEnergyConsumption` | GET | `/api/ops/energy/consumption/{meterId}` | 获取能耗记录 |
+| `getConsumptionByType` | GET | `/api/ops/energy/statistics/by-type` | 按类型统计 |
+| `getUnitConsumption` | GET | `/api/ops/energy/statistics/unit-consumption` | 单方能耗 |
+
+### 3.3 前端页面路由
+
+**源码位置**: `ether-admin/src/router/index.ts`
+
+| 路径 | 路由名 | 组件 | 说明 |
+|------|--------|------|------|
+| `energy/meters` | EnergyMeters | `views/energy/MeterList.vue` | 计量点管理 |
+| `energy/consumption` | EnergyConsumption | `views/energy/ConsumptionRecord.vue` | 能耗录入 |
+| `energy/statistics` | EnergyStatistics | `views/energy/EnergyStatistics.vue` | 能耗统计 |
+
+---
+
+## 四、已实现的业务规则
+
+### 4.1 计量点管理规则
+
+| 规则 | 实现位置 | 说明 |
+|------|---------|------|
+| 编码自动生成 | `EnergyMeterServiceImpl.generateMeterCode()` | 格式：`EM` + `yyyyMMddHHmmss`，确保唯一性（冲突时追加后缀） |
+| 默认状态 | `EnergyMeterServiceImpl.createMeter()` | 新建计量点默认状态为 ACTIVE |
+| 软删除 | `EnergyMeterServiceImpl.deleteMeter()` | 删除操作将状态设为 INACTIVE，非物理删除 |
+| 查询过滤 | `EnergyMeterRepository.findByProjectIdAndStatus()` | 按项目查询时仅返回 ACTIVE 状态的计量点 |
+| 部分更新 | `EnergyMeterServiceImpl.updateMeter()` | 仅更新非空字段 |
+
+### 4.2 能耗录入规则
+
+| 规则 | 实现位置 | 说明 |
+|------|---------|------|
+| 仪表状态校验 | `EnergyConsumptionServiceImpl.recordConsumption()` | 只能对 ACTIVE 状态的仪表进行抄表（错误码 6102） |
+| 读数递增校验 | `EnergyConsumptionServiceImpl.recordConsumption()` | 当前读数不能小于上次读数（错误码 6103） |
+| 仪表存在性校验 | `EnergyConsumptionServiceImpl.recordConsumption()` | 仪表不存在时抛出异常（错误码 6101） |
+| 自动获取上次读数 | `EnergyConsumptionServiceImpl.recordConsumption()` | 从最近一条记录获取 previousReading，首次抄表为 0 |
+| 自动计算消耗量 | `EnergyConsumptionServiceImpl.recordConsumption()` | consumption = currentReading − previousReading |
+| 自动计算费用 | `EnergyConsumptionServiceImpl.recordConsumption()` | amount = consumption × meter.unitPrice（单价为空时为 0） |
+| 默认手动录入 | `EnergyConsumptionServiceImpl.recordConsumption()` | recordMethod 默认设为 MANUAL |
+
+### 4.3 能耗统计规则
+
+| 规则 | 实现位置 | 说明 |
+|------|---------|------|
+| 按月统计 | `EnergyConsumptionServiceImpl.getConsumptionByType()` | 根据 month 参数计算月份起止日期 |
+| 类型初始化 | `EnergyConsumptionServiceImpl.getConsumptionByType()` | 所有 EnergyType 初始化为 BigDecimal.ZERO |
+| 按类型汇总（简化） | `EnergyConsumptionServiceImpl.getConsumptionByType()` | ⚠️ 当前实现将项目总消耗全部归入 LIGHTING 类型，未按 meter.energyType 真正分项汇总 |
+| 单方能耗 | `EnergyConsumptionServiceImpl.getUnitConsumption()` | 遍历项目所有 ACTIVE 计量点，累加月度消耗量 |
+
+### 4.4 已知实现缺陷
+
+| 缺陷 | 严重度 | 说明 |
+|------|--------|------|
+| 按类型统计不准确 | 🔴 高 | `getConsumptionByType()` 将总消耗全部归入 LIGHTING，代码注释也承认"实际业务中应按 meter.energyType 汇总" |
+| 前后端能源类型不一致 | 🟡 中 | 后端 EnergyType 枚举为 LIGHTING/HVAC/POWER/SPECIAL/WATER/GAS，前端 energyTypeMap 为 ELECTRICITY/WATER/GAS/CENTRAL_HEATING/CENTRAL_COOLING |
+| 无账期概念 | 🟡 中 | 能耗记录只有 consumptionDate，无账单周期、到期日等概念 |
+| 费用仅为计算值 | 🟡 中 | amount 字段仅是 consumption × unitPrice 的计算结果，非正式账单金额 |
+| 无支付流程 | 🔴 高 | 无支付记录、支付状态、支付方式等 |
+| 无业主关联 | 🟡 中 | 能耗记录不关联业主，无法按业主统计费用 |
+
+---
+
+## 五、与原需求文档 04-FINANCE.md 的差异对比表
+
+### 5.1 实体级差异
+
+| 设计项 | 04-FINANCE.md 设计方案 | 实际代码实现 | 差异等级 |
+|--------|----------------------|------------|---------|
+| **FeeItem 实体** | 已定义完整实体（code/name/type/billingMethod/unitPrice/unit/billDay/dueDay/overdueDay/enableLateFee/lateFeeRate/maxLateFee） | ❌ 不存在 | 🔴 完全缺失 |
+| **FeeBill 实体** | 已定义完整实体（billNo/feeItemId/spaceNodeId/ownerId/billPeriod/billDate/dueDate/overdueDate/usageAmount/amount/lateFee/discount/payableAmount/paidAmount/status） | ❌ 不存在 | 🔴 完全缺失 |
+| **FeePayment 实体** | 已定义完整实体（paymentNo/amount/method/thirdPartyNo/status/failReason/paymentTime） | ❌ 不存在 | 🔴 完全缺失 |
+| **FeeRefund 实体** | 已定义完整实体（refundNo/amount/reason/status/approverId/approveTime/thirdPartyRefundNo/refundTime） | ❌ 不存在 | 🔴 完全缺失 |
+| **fin_fee_item 表** | 已定义 DDL | ❌ 不存在 | 🔴 完全缺失 |
+| **fin_fee_bill 表** | 已定义 DDL | ❌ 不存在 | 🔴 完全缺失 |
+| **fin_fee_payment 表** | 已定义 DDL | ❌ 不存在 | 🔴 完全缺失 |
+| **fin_fee_refund 表** | 已定义 DDL | ❌ 不存在 | 🔴 完全缺失 |
+| **EnergyMeter 实体** | 未在设计文档中 | ✅ 在 module-mdm 中实现 | 🟡 设计文档遗漏 |
+| **EnergyConsumption 实体** | 未在设计文档中 | ✅ 在 module-mdm 中实现 | 🟡 设计文档遗漏 |
+| **ops_energy_meter 表** | 未在设计文档中 | ✅ 已创建 | 🟡 设计文档遗漏 |
+| **ops_energy_consumption 表** | 未在设计文档中 | ✅ 已创建 | 🟡 设计文档遗漏 |
+
+### 5.2 功能级差异
+
+| 功能 | 04-FINANCE.md 状态 | 实际状态 | 差异说明 |
+|------|-------------------|---------|---------|
+| 收费项目管理（CRUD） | 🟢 已实现 | 🔴 未实现 | 无 FeeItem 代码 |
+| 账单生成 | 🟢 已实现 | 🔴 未实现 | 无 FeeBill 代码 |
+| 账单状态流转 | 🟢 已实现 | 🔴 未实现 | 无状态机 |
+| 支付处理 | 🟢 已实现 | 🔴 未实现 | 无 FeePayment 代码 |
+| 费用催缴（定时任务） | 🟢 已实现 | 🔴 未实现 | 无 FeeReminderJob 代码 |
+| 滞纳金计算 | 🟢 已实现 | 🔴 未实现 | 无计算逻辑 |
+| 退款流程 | 🔴 未实现 | 🔴 未实现 | 一致 |
+| 支付网关对接 | 🔴 未实现 | 🔴 未实现 | 一致 |
+| 财务报表 | 🔴 未实现 | 🔴 未实现 | 一致 |
+| 能耗计量点管理 | 未提及 | 🟢 已实现 | 设计文档遗漏 |
+| 能耗抄表录入 | 未提及 | 🟢 已实现 | 设计文档遗漏 |
+| 能耗费用计算 | 未提及 | 🟢 已实现（简化） | 设计文档遗漏 |
+| 能耗统计分析 | 未提及 | 🟢 已实现（有缺陷） | 设计文档遗漏 |
+
+### 5.3 枚举差异
+
+| 枚举 | 04-FINANCE.md 定义 | 实际代码定义 | 差异 |
+|------|-------------------|------------|------|
+| 收费类型 FeeType | PROPERTY/PARKING/WATER/ELECTRICITY/GAS/HEATING/REPAIR_FUND/OTHER | ❌ 不存在 | 完全缺失 |
+| 计费方式 BillingMethod | FIXED/AREA/USAGE/CUSTOM | ❌ 不存在 | 完全缺失 |
+| 账单状态 BillStatus | UNPAID/PARTIAL_PAID/PAID/OVERDUE/CANCELLED | ❌ 不存在 | 完全缺失 |
+| 支付方式 PaymentMethod | WECHAT/ALIPAY/CASH/BANK_TRANSFER/CARD | ❌ 不存在 | 完全缺失 |
+| 支付状态 PaymentStatus | PENDING/SUCCESS/FAILED/REFUNDED | ❌ 不存在 | 完全缺失 |
+| 退款状态 RefundStatus | PENDING/APPROVED/REJECTED/REFUNDED | ❌ 不存在 | 完全缺失 |
+| 能源类型 EnergyType | 未定义 | LIGHTING/HVAC/POWER/SPECIAL/WATER/GAS | 设计文档遗漏 |
+| 记录方式 RecordMethod | 未定义 | MANUAL/IOT | 设计文档遗漏 |
+
+---
+
+## 六、待实现功能清单
+
+### 6.1 P0 — 核心财务功能（必须实现）
+
+| 编号 | 功能 | 说明 | 依赖 | 预估工作量 |
+|------|------|------|------|-----------|
+| FIN-001 | 创建 module-finance 模块 | 独立的财务模块，包含 entity/service/controller/repository 分层 | 无 | 0.5天 |
+| FIN-002 | FeeItem 收费项目实体 | 含 code/name/type/billingMethod/unitPrice/unit/billDay/dueDay/overdueDay/enableLateFee/lateFeeRate/maxLateFee | FIN-001 | 1天 |
+| FIN-003 | FeeItem CRUD API | 创建/查询/更新/禁用收费项目 | FIN-002 | 1.5天 |
+| FIN-004 | FeeBill 账单实体 | 含 billNo/feeItemId/spaceNodeId/ownerId/billPeriod/billDate/dueDate/overdueDate/amount/lateFee/discount/payableAmount/paidAmount/status | FIN-002 | 1.5天 |
+| FIN-005 | 账单自动生成 | 根据收费项目规则，按账期自动生成账单 | FIN-003, FIN-004 | 3天 |
+| FIN-006 | 账单状态流转 | UNPAID → PARTIAL_PAID → PAID / OVERDUE → CANCELLED | FIN-004 | 1天 |
+| FIN-007 | FeePayment 支付记录实体 | 含 paymentNo/amount/method/thirdPartyNo/status/failReason/paymentTime | FIN-004 | 1天 |
+| FIN-008 | 支付记录 API | 线下收款登记、支付记录查询 | FIN-007 | 1.5天 |
+| FIN-009 | 能耗数据与账单对接 | 将 EnergyConsumption 的 amount 作为按用量计费的账单数据来源 | FIN-005, 能耗模块 | 2天 |
+| FIN-010 | 财务管理前端页面 | 收费项目/账单/支付记录的管理页面 | FIN-003, FIN-006, FIN-008 | 4天 |
+
+### 6.2 P1 — 重要功能（近期实现）
+
+| 编号 | 功能 | 说明 | 依赖 | 预估工作量 |
+|------|------|------|------|-----------|
+| FIN-011 | 费用催缴定时任务 | 到期提醒（3天内）、逾期催缴、周汇总 | FIN-006 | 2天 |
+| FIN-012 | 滞纳金自动计算 | 逾期天数 × 日利率，不超过上限 | FIN-006, FIN-002 | 1.5天 |
+| FIN-013 | FeeRefund 退款实体与流程 | 退款申请 → 审批 → 执行 | FIN-007 | 3天 |
+| FIN-014 | 业主端缴费功能 | 业主查看账单、在线缴费 | FIN-006, FIN-008 | 3天 |
+| FIN-015 | 修复能耗按类型统计 | getConsumptionByType() 应按 meter.energyType 真正分项汇总 | 无 | 0.5天 |
+| FIN-016 | 统一前后端能源类型枚举 | 后端 LIGHTING/HVAC/POWER/SPECIAL/WATER/GAS 与前端 ELECTRICITY/WATER/GAS/CENTRAL_HEATING/CENTRAL_COOLING 对齐 | 无 | 0.5天 |
+
+### 6.3 P2 — 增强功能（中期实现）
+
+| 编号 | 功能 | 说明 | 依赖 | 预估工作量 |
+|------|------|------|------|-----------|
+| FIN-017 | 支付网关对接 | 微信支付/支付宝 SDK 集成 | FIN-008 | 5天 |
+| FIN-018 | 财务报表 | 收费统计、欠费分析、收入趋势 | FIN-006, FIN-008 | 4天 |
+| FIN-019 | 按面积计费 | 根据房产面积 × 单价计算物业费 | FIN-002, 空间节点面积数据 | 2天 |
+| FIN-020 | 固定金额计费 | 每月固定金额的收费项目（如停车费） | FIN-002 | 1天 |
+| FIN-021 | 批量账单生成 | 一次性为项目所有业主生成账单 | FIN-005 | 2天 |
+| FIN-022 | 账单导出 | 导出 Excel/PDF 格式账单 | FIN-006 | 1.5天 |
+| FIN-023 | IoT 自动抄表 | 对接 IoT 平台自动采集能耗数据 | 能耗模块 | 3天 |
+
+### 6.4 P3 — 远期规划
+
+| 编号 | 功能 | 说明 | 依赖 | 预估工作量 |
+|------|------|------|------|-----------|
+| FIN-024 | 自定义计费规则 | 支持阶梯电价、分时计费等复杂规则 | FIN-002 | 5天 |
+| FIN-025 | 预缴费管理 | 业主预存费用、自动扣款 | FIN-008 | 3天 |
+| FIN-026 | 发票管理 | 开票申请、发票打印 | FIN-008 | 3天 |
+| FIN-027 | 对账功能 | 支付流水与银行流水对账 | FIN-017 | 3天 |
+| FIN-028 | 财务审批流 | 大额退款、减免审批流程 | FIN-013 | 4天 |
+
+---
+
+## 七、架构建议
+
+### 7.1 模块归属调整
+
+当前能耗管理（EnergyMeter / EnergyConsumption）放在 `module-mdm` 中，建议：
+
+- **方案A（推荐）**: 保持能耗管理在 module-mdm，财务域通过接口引用能耗数据。能耗是基础数据（MDM），费用计算是业务逻辑（Finance），职责分离清晰。
+- **方案B**: 将能耗管理迁移至 module-finance。耦合度高，不推荐。
+
+### 7.2 数据流设计
+
+```
+EnergyMeter (module-mdm)          FeeItem (module-finance)
+       │                                │
+       ▼                                ▼
+EnergyConsumption ──费用计算──→ FeeBill (自动/手动生成)
+  (抄表数据)                        │
+                                    ▼
+                              FeePayment (支付记录)
+                                    │
+                                    ▼
+                              FeeRefund (退款记录)
+```
+
+### 7.3 设计文档修正建议
+
+04-FINANCE.md 中标记 FeeItem/FeeBill/FeePayment 为"🟢 已实现"与实际代码不符，建议：
+
+1. 将 FeeItem/FeeBill/FeePayment/FeeReminderJob 的状态修正为"🔴 未实现"
+2. 补充 EnergyMeter / EnergyConsumption 的设计说明
+3. 明确能耗管理与财务计费的边界和对接方式
+
+---
+
+## 八、代码文件索引
+
+### 8.1 后端文件
+
+| 文件 | 路径 |
+|------|------|
+| EnergyMeter 实体 | `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/EnergyMeter.java` |
+| EnergyConsumption 实体 | `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/EnergyConsumption.java` |
+| EnergyController | `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/controller/EnergyController.java` |
+| EnergyMeterService | `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/EnergyMeterService.java` |
+| EnergyMeterServiceImpl | `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/impl/EnergyMeterServiceImpl.java` |
+| EnergyConsumptionService | `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/EnergyConsumptionService.java` |
+| EnergyConsumptionServiceImpl | `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/impl/EnergyConsumptionServiceImpl.java` |
+| EnergyMeterRepository | `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/repository/EnergyMeterRepository.java` |
+| EnergyConsumptionRepository | `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/repository/EnergyConsumptionRepository.java` |
+| EnergyMeterServiceTest | `ether-pms/module-mdm/src/test/java/com/ether/pms/mdm/service/EnergyMeterServiceTest.java` |
+
+### 8.2 前端文件
+
+| 文件 | 路径 |
+|------|------|
+| 能耗 API | `ether-admin/src/api/energy.ts` |
+| 计量点管理页面 | `ether-admin/src/views/energy/MeterList.vue` |
+| 能耗录入页面 | `ether-admin/src/views/energy/ConsumptionRecord.vue` |
+| 能耗统计页面 | `ether-admin/src/views/energy/EnergyStatistics.vue` |
+| 路由配置（能耗部分） | `ether-admin/src/router/index.ts` (L121-135) |
+
+### 8.3 文档文件
+
+| 文件 | 路径 |
+|------|------|
+| 原设计文档 | `ether-docs/02-DESIGN/domains/04-FINANCE.md` |
+| 特性清单 | `ether-docs/01-REQUIREMENTS/FEATURE_LIST.md` |
+
+---
+
+> **文档说明**: 本文档基于 2026-04-23 对 ether-pms 和 ether-admin 代码库的全量搜索结果生成。核心结论：财务域的 FeeItem/FeeBill/FeePayment/FeeRefund 四大实体及所有相关功能均未在代码中实现，仅能耗计量管理（EnergyMeter/EnergyConsumption）在 module-mdm 中有完整实现。04-FINANCE.md 中标注"已实现"的状态需修正。
diff --git a/02-DESIGN/domains/REVERSE-MDM.md b/02-DESIGN/domains/REVERSE-MDM.md
new file mode 100644
index 0000000..d69a076
--- /dev/null
+++ b/02-DESIGN/domains/REVERSE-MDM.md
@@ -0,0 +1,1158 @@
+# Ether 主数据域（MDM）功能详细设计文档
+
+**版本**: v1.0（反推自代码）  
+**生成日期**: 2026-04-23  
+**数据来源**: module-mdm 实际代码反推  
+**代码路径**: `ether-pms/module-mdm`
+
+---
+
+## 一、领域概述
+
+### 1.1 领域职责
+
+主数据域（Master Data Management）是 Ether 系统的基础数据层，负责管理物业项目全生命周期的核心主数据，为所有业务域（工单、收费、巡检、维保等）提供统一的数据基座。
+
+核心职责：
+- **项目管理**：项目创建、状态流转、成员管理、功能配置
+- **空间节点管理**：统一空间体系，树形结构管理楼栋/单元/房间/车位/设备房等
+- **巡检标准管理**：巡检标准项库、巡检模板管理
+- **巡检记录管理**：设备巡检记录、巡检结果跟踪
+- **备件库存管理**：备件台账、分类管理、出入库操作、低库存预警
+- **能耗计量管理**：计量点管理、能耗抄表记录、能耗统计分析
+
+### 1.2 核心概念
+
+| 概念 | 说明 | 对应实体 |
+|------|------|----------|
+| **项目** | 物业管理的基本单元，所有业务数据的归属 | Project |
+| **空间节点** | 统一的空间体系，支持树形层级 | SpaceNode |
+| **项目配置** | 项目级别的功能开关 | ProjectConfig |
+| **项目统计** | 项目维度的汇总统计 | ProjectStatistics |
+| **状态历史** | 项目状态变更记录 | ProjectStatusHistory |
+| **巡检标准项** | 设备巡检的检查标准库 | InspectionItem |
+| **巡检模板** | 按设备类型组织的巡检检查项集合 | InspectionTemplate |
+| **巡检记录** | 实际巡检执行记录 | InspectionRecord |
+| **备件** | 维修用备品备件 | SparePart |
+| **备件分类** | 备件的分类体系 | SparePartCategory |
+| **备件记录** | 备件出入库流水 | SparePartRecord |
+| **计量点** | 能源计量仪表 | EnergyMeter |
+| **能耗记录** | 能源消耗抄表记录 | EnergyConsumption |
+
+### 1.3 领域边界
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        主数据域（MDM）边界                                    │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
+│  │  项目管理  │  │ 空间节点  │  │ 巡检标准  │  │ 备件库存  │  │ 能耗计量  │    │
+│  │ Project  │  │SpaceNode │  │InspectItem│  │SparePart │  │  Energy  │    │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
+│       │              │              │              │              │         │
+│       ▼              ▼              ▼              ▼              ▼         │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
+│  │ 项目配置  │  │ 设备扩展  │  │ 巡检模板  │  │ 备件分类  │  │ 计量点   │    │
+│  │  Config  │  │Equipment │  │ Template │  │ Category │  │  Meter   │    │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
+│                                                                             │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  依赖关系：                                                                 │
+│  - 所有实体均以 projectId 为核心维度                                         │
+│  - SpaceNode 是空间基座，设备/计量点/巡检均关联空间节点                       │
+│  - 巡检模板引用巡检标准项                                                    │
+│  - 备件记录关联备件和工单                                                    │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 二、数据结构设计
+
+### 2.1 实体总览
+
+| # | 实体 | 表名 | 模块 | 说明 |
+|---|------|------|------|------|
+| 1 | Project | mdm_project | 项目管理 | 项目基础信息 |
+| 2 | ProjectConfig | mdm_project_config | 项目管理 | 项目功能配置 |
+| 3 | ProjectStatistics | mdm_project_statistics | 项目管理 | 项目统计快照 |
+| 4 | ProjectStatusHistory | mdm_project_status_history | 项目管理 | 状态变更历史 |
+| 5 | SpaceNode | mdm_space_node | 空间管理 | 统一空间节点（含设备扩展） |
+| 6 | InspectionItem | mdm_inspection_item | 巡检标准 | 巡检标准项 |
+| 7 | InspectionTemplate | ops_inspection_template | 巡检模板 | 巡检检查模板 |
+| 8 | InspectionRecord | mdm_inspection_record | 巡检记录 | 巡检执行记录 |
+| 9 | SparePart | ops_spare_part | 备件管理 | 备件台账 |
+| 10 | SparePartCategory | ops_spare_part_category | 备件管理 | 备件分类 |
+| 11 | SparePartRecord | ops_spare_part_record | 备件管理 | 出入库记录 |
+| 12 | EnergyMeter | ops_energy_meter | 能耗管理 | 计量点 |
+| 13 | EnergyConsumption | ops_energy_consumption | 能耗管理 | 能耗记录 |
+
+### 2.2 Project（项目）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键，自动生成 |
+| code | String(50) | 是 | 项目编码，唯一，正则 `^[a-zA-Z0-9_-]+$`，2-50位 |
+| name | String(100) | 是 | 项目名称，2-100位 |
+| description | String(500) | 否 | 项目描述 |
+| address | String(100) | 否 | 项目地址 |
+| projectType | Enum(ProjectType) | 否 | 项目类型，默认 RESIDENTIAL |
+| province | String(50) | 否 | 省 |
+| city | String(50) | 否 | 市 |
+| district | String(50) | 否 | 区 |
+| longitude | Double | 否 | 经度 |
+| latitude | Double | 否 | 纬度 |
+| status | String(20) | 是 | 项目状态，默认 ACTIVE |
+| buildingCount | Integer | 否 | 楼栋数 |
+| unitCount | Integer | 否 | 单元数 |
+| roomCount | Integer | 否 | 房间数 |
+| floorCount | Integer | 否 | 楼层数 |
+| logo | String(200) | 否 | 项目Logo |
+| contact | String(200) | 否 | 联系人 |
+| contactPhone | String(20) | 否 | 联系电话，正则 `^1[3-9]\d{9}$` |
+| createdAt | LocalDateTime | 是 | 创建时间，自动填充 |
+| updatedAt | LocalDateTime | 是 | 更新时间，自动填充 |
+
+**枚举：ProjectType**
+
+| 值 | 描述 |
+|----|------|
+| RESIDENTIAL | 住宅 |
+| OFFICE | 办公 |
+| INDUSTRIAL_PARK | 产业园区 |
+
+**项目状态值（String类型，非枚举）**
+
+| 值 | 描述 | 前端颜色 |
+|----|------|----------|
+| ACTIVE | 正常 | success |
+| DISABLED | 禁用 | error |
+| PENDING | 待审核 | warning |
+| ARCHIVED | 已归档 | default |
+
+### 2.3 ProjectConfig（项目配置）
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| id | UUID | 是 | - | 主键 |
+| projectId | UUID | 是 | - | 项目ID，唯一 |
+| enableReservation | Boolean | 否 | false | 预约功能 |
+| enableVisitor | Boolean | 否 | false | 访客功能 |
+| enableComplaint | Boolean | 否 | true | 投诉功能 |
+| enablePayment | Boolean | 否 | false | 缴费功能 |
+| enableAnnouncement | Boolean | 否 | true | 公告功能 |
+| enableSurvey | Boolean | 否 | false | 问卷功能 |
+| enableVote | Boolean | 否 | false | 投票功能 |
+| enableMaintenance | Boolean | 否 | true | 报修功能 |
+| enableAsset | Boolean | 否 | false | 资产功能 |
+| customConfig | String(5000) | 否 | - | 自定义配置JSON |
+| createdAt | LocalDateTime | - | 自动 | 创建时间 |
+| updatedAt | LocalDateTime | - | 自动 | 更新时间 |
+
+### 2.4 ProjectStatistics（项目统计）
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| id | UUID | - | 主键 |
+| projectId | UUID | - | 项目ID，唯一 |
+| memberCount | Integer | 0 | 成员数 |
+| buildingCount | Integer | 0 | 楼栋数 |
+| unitCount | Integer | 0 | 单元数 |
+| roomCount | Integer | 0 | 房间数 |
+| ownerCount | Integer | 0 | 业主数 |
+| tenantCount | Integer | 0 | 租户数 |
+| lastSyncedAt | LocalDateTime | - | 最后同步时间 |
+| createdAt | LocalDateTime | 自动 | 创建时间 |
+| updatedAt | LocalDateTime | 自动 | 更新时间 |
+
+### 2.5 ProjectStatusHistory（状态变更历史）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| projectId | UUID | 是 | 项目ID |
+| fromStatus | String(20) | 否 | 原状态 |
+| toStatus | String(20) | 是 | 新状态 |
+| reason | String(500) | 否 | 变更原因 |
+| operatorId | UUID | 否 | 操作人ID |
+| operatorName | String(50) | 否 | 操作人姓名 |
+| createdAt | LocalDateTime | 自动 | 创建时间 |
+
+### 2.6 SpaceNode（空间节点）— 核心实体
+
+SpaceNode 是 MDM 域最复杂的实体，采用统一空间模型 + 设备扩展字段的设计。
+
+#### 2.6.1 基础字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| projectId | UUID | 是 | 项目ID（注意：列名为 project_code） |
+| name | String(100) | 是 | 节点名称，1-100位 |
+| fullName | String(500) | 否 | 全路径名称 |
+| shortName | String(50) | 否 | 简称 |
+| nodeCategory | Enum(NodeCategory) | 是 | 节点大类 |
+| nodeType | Enum(NodeType) | 是 | 节点类型 |
+| usageType | String(30) | 否 | 用途类型 |
+| parentId | UUID | 否 | 父节点ID |
+| treePath | String(1000) | 否 | 物理路径 id.id.id |
+| treePathName | String(1000) | 否 | 名称路径 项目/楼栋/单元/房间 |
+| level | Integer | 否 | 层级深度，默认0 |
+| sortOrder | Integer | 否 | 排序号，默认0 |
+| status | String(20) | 否 | 状态，默认 ACTIVE |
+| deliveryStatus | String(20) | 否 | 交付状态 |
+| decorationStatus | String(20) | 否 | 装修状态 |
+
+#### 2.6.2 面积信息
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| buildingArea | BigDecimal(10,2) | 建筑面积(㎡) |
+| usableArea | BigDecimal(10,2) | 使用面积(㎡) |
+| sharedArea | BigDecimal(10,2) | 公摊面积(㎡) |
+| landArea | BigDecimal(10,2) | 占地面积(㎡) |
+
+#### 2.6.3 地理信息
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| longitude | BigDecimal(10) | 经度 |
+| latitude | BigDecimal(10) | 纬度 |
+| altitude | BigDecimal(8,2) | 海拔 |
+| floorNumber | Integer | 楼层号(正数地上,负数地下) |
+
+#### 2.6.4 地址信息
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| province | String(50) | 省 |
+| city | String(50) | 市 |
+| district | String(50) | 区 |
+| street | String(100) | 街道 |
+| address | String(255) | 详细地址 |
+
+#### 2.6.5 扩展属性
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| attributes | String(2000) | 类型特定属性（JSON格式） |
+
+#### 2.6.6 设备扩展字段（isEquipment=true 时使用）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| isEquipment | Boolean | 是否为设备节点，默认false |
+| designLifeYears | Integer | 设计寿命(年) |
+| ratedPower | BigDecimal(10,2) | 额定功率 |
+| ratedVoltage | BigDecimal(10,2) | 额定电压 |
+| ratedCurrent | BigDecimal(10,2) | 额定电流 |
+| maintenanceVendor | String(100) | 维保厂商 |
+| maintenanceVendorContact | String(50) | 维保联系人 |
+| maintenanceVendorPhone | String(20) | 维保电话 |
+| maintenanceContractNo | String(50) | 维保合同号 |
+| maintenanceContractStart | LocalDate | 合同开始日期 |
+| maintenanceContractEnd | LocalDate | 合同结束日期 |
+| specialEquipmentType | String(50) | 特种设备类型 |
+| specialEquipmentCert | String(100) | 特种设备证书 |
+| inspectionCycle | Integer | 巡检周期(天) |
+| nextInspectionDate | LocalDate | 下次年检日期 |
+| lastInspectionDate | LocalDate | 上次年检日期 |
+| lastInspectionResult | String(20) | 上次年检结果 |
+| commonSpareParts | String(2000) | 常用备件(JSON) |
+| energyConsumptionStandard | BigDecimal(12,2) | 能耗标准 |
+| installationEnvironment | String(50) | 安装环境 |
+| protectionLevel | String(20) | 防护等级 |
+
+#### 2.6.7 系统字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| createdAt | LocalDateTime | 创建时间 |
+| updatedAt | LocalDateTime | 更新时间 |
+| createdBy | UUID | 创建人 |
+| updatedBy | UUID | 更新人 |
+| isDeleted | Boolean | 软删除标记，默认false |
+
+#### 2.6.8 NodeCategory 枚举（节点大类）
+
+| 值 | 描述 |
+|----|------|
+| BUILDING | 建筑空间 |
+| PARKING | 停车空间 |
+| FACILITY | 设施空间 |
+| AREA | 区域空间 |
+
+#### 2.6.9 NodeType 枚举（节点类型）— 含分类和层级
+
+| 值 | 描述 | 所属大类 | 层级序号 |
+|----|------|----------|----------|
+| BUILDING | 楼栋 | BUILDING | 1 |
+| UNIT | 单元 | BUILDING | 2 |
+| FLOOR | 楼层 | BUILDING | 3 |
+| ROOM | 房间 | BUILDING | 4 |
+| SHOP | 商铺 | BUILDING | 2 |
+| GARAGE | 车库 | PARKING | 1 |
+| PARKING_AREA | 停车区域 | PARKING | 2 |
+| PARKING_SPACE | 车位 | PARKING | 3 |
+| EQUIPMENT_ROOM | 设备房 | FACILITY | 1 |
+| PROPERTY_OFFICE | 物业用房 | FACILITY | 1 |
+| SECURITY_ROOM | 门岗 | FACILITY | 1 |
+| PUBLIC_ROOM | 公共用房 | FACILITY | 1 |
+| PUBLIC_AREA | 公共区域 | AREA | 1 |
+| GREEN_AREA | 绿化区域 | AREA | 1 |
+| ROAD | 道路 | AREA | 1 |
+
+#### 2.6.10 索引设计
+
+| 索引名 | 列 | 说明 |
+|--------|-----|------|
+| idx_space_node_project | project_id | 按项目查询 |
+| idx_space_node_parent | parent_id | 查子节点 |
+| idx_space_node_type | node_type | 按类型查询 |
+| idx_space_node_tree_path | tree_path | 路径查询 |
+| idx_sn_project_parent | project_id, parent_id | 项目+父节点 |
+| idx_sn_project_type | project_id, node_type | 项目+类型 |
+| idx_sn_project_isequipment | project_id, is_equipment | 项目+设备 |
+| idx_sn_project_nextinspection | project_id, next_inspection_date | 年检预警 |
+
+### 2.7 InspectionItem（巡检标准项）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| equipmentType | String(50) | 否 | 设备类型 |
+| systemType | String(50) | 否 | 系统类型 |
+| itemName | String(200) | 是 | 检查项名称 |
+| checkMethod | String(200) | 否 | 检查方法 |
+| standardValue | String(100) | 否 | 标准值 |
+| isRequired | Boolean | 否 | 是否必检，默认true |
+| remark | String(500) | 否 | 备注 |
+| sortOrder | Integer | 否 | 排序号 |
+| status | Enum(Status) | 否 | 状态，默认ACTIVE |
+| createdAt | LocalDateTime | 自动 | 创建时间 |
+| updatedAt | LocalDateTime | 自动 | 更新时间 |
+
+**枚举：Status**
+
+| 值 | 描述 |
+|----|------|
+| ACTIVE | 启用 |
+| INACTIVE | 停用 |
+
+### 2.8 InspectionTemplate（巡检模板）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| projectId | UUID | 是 | 项目ID |
+| templateCode | String | 是 | 模板编码，唯一 |
+| templateName | String | 是 | 模板名称 |
+| equipmentType | String | 是 | 设备类型 |
+| inspectionItems | String(5000) | 否 | 检查项(JSON) |
+| estimatedDuration | Integer | 否 | 预计耗时(分钟) |
+| status | Enum(Status) | 否 | 状态，默认ACTIVE |
+| version | Integer | 否 | 版本号，默认1 |
+| createdBy | String | 否 | 创建人 |
+| createdAt | LocalDateTime | 自动 | 创建时间 |
+| updatedAt | LocalDateTime | 自动 | 更新时间 |
+
+### 2.9 InspectionRecord（巡检记录）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| planId | UUID | 否 | 巡检计划ID |
+| equipmentId | UUID | 是 | 设备ID |
+| inspectionDate | LocalDate | 是 | 巡检日期 |
+| inspector | String(200) | 是 | 巡检人 |
+| status | Enum(CheckStatus) | 否 | 检查状态，默认NORMAL |
+| checkInTime | LocalDateTime | 否 | 签到时间 |
+| checkInLocation | String(100) | 否 | 签到位置 |
+| checkInPhoto | String(200) | 否 | 签到照片 |
+| items | JSONB | 否 | 检查项结果列表 |
+| problems | JSONB | 否 | 异常问题列表 |
+| completed | Boolean | 否 | 是否完成，默认false |
+| completedTime | LocalDateTime | 否 | 完成时间 |
+| createdAt | LocalDateTime | 自动 | 创建时间 |
+
+**枚举：CheckStatus**
+
+| 值 | 描述 |
+|----|------|
+| NORMAL | 正常 |
+| WARNING | 预警 |
+| ABNORMAL | 异常 |
+
+**items JSONB 结构示例**：
+```json
+[
+  { "itemId": "uuid", "itemName": "检查项", "value": "实测值", "result": "PASS/FAIL", "remark": "备注" }
+]
+```
+
+**problems JSONB 结构示例**：
+```json
+[
+  { "desc": "问题描述", "photo": "照片URL", "severity": "LOW/MEDIUM/HIGH" }
+]
+```
+
+**索引设计**：
+
+| 索引名 | 列 |
+|--------|-----|
+| idx_ir_equipment_date | equipment_id, inspection_date |
+| idx_ir_inspectiondate | inspection_date |
+
+### 2.10 SparePart（备件）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| projectId | UUID | 是 | 项目ID |
+| sparePartCode | String | 是 | 备件编码，唯一 |
+| sparePartName | String | 是 | 备件名称 |
+| categoryId | UUID | 否 | 分类ID |
+| specification | String(500) | 否 | 规格型号 |
+| unit | String(50) | 是 | 计量单位 |
+| safeStock | Integer | 否 | 安全库存，默认0 |
+| currentStock | Integer | 否 | 当前库存，默认0 |
+| unitPrice | BigDecimal(10,2) | 否 | 单价 |
+| supplier | String(200) | 否 | 供应商 |
+| supplierContact | String | 否 | 供应商联系方式 |
+| location | String(200) | 否 | 存放位置 |
+| remarks | String(1000) | 否 | 备注 |
+| status | Enum(Status) | 否 | 状态，默认ACTIVE |
+| createdAt | LocalDateTime | 自动 | 创建时间 |
+| updatedAt | LocalDateTime | 自动 | 更新时间 |
+
+**枚举：Status**
+
+| 值 | 描述 |
+|----|------|
+| ACTIVE | 启用 |
+| INACTIVE | 停用 |
+
+**索引**：`idx_sp_project_status(project_id, status)`
+
+### 2.11 SparePartCategory（备件分类）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| parentId | UUID | 否 | 父分类ID（支持树形） |
+| categoryCode | String | 是 | 分类编码，唯一 |
+| categoryName | String | 是 | 分类名称 |
+| description | String(500) | 否 | 描述 |
+| sortOrder | Integer | 否 | 排序号 |
+| createdAt | LocalDateTime | 自动 | 创建时间 |
+
+### 2.12 SparePartRecord（备件出入库记录）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| recordCode | String | 是 | 记录编码，唯一 |
+| recordType | Enum(RecordType) | 是 | 记录类型 |
+| sparePartId | UUID | 是 | 备件ID |
+| quantity | Integer | 是 | 数量 |
+| balance | Integer | 是 | 余额（操作后库存） |
+| relatedOrderId | UUID | 否 | 关联工单ID |
+| recordedBy | UUID | 否 | 操作人ID |
+| recordDate | LocalDateTime | 否 | 操作时间，默认当前 |
+| remarks | String(1000) | 否 | 备注 |
+
+**枚举：RecordType**
+
+| 值 | 描述 |
+|----|------|
+| IN | 入库 |
+| OUT | 出库 |
+| CHECK | 盘点 |
+| ADJUST | 调整 |
+
+### 2.13 EnergyMeter（计量点）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| projectId | UUID | 是 | 项目ID |
+| meterCode | String | 是 | 计量点编码，唯一 |
+| meterName | String | 是 | 计量点名称 |
+| energyType | Enum(EnergyType) | 是 | 能源类型 |
+| spaceNodeId | UUID | 否 | 关联空间节点 |
+| installationLocation | String | 否 | 安装位置 |
+| ratedCapacity | BigDecimal(10,2) | 否 | 额定容量 |
+| unitPrice | BigDecimal(10,4) | 否 | 单价 |
+| status | Enum(Status) | 否 | 状态，默认ACTIVE |
+| createdAt | LocalDateTime | 自动 | 创建时间 |
+| updatedAt | LocalDateTime | 自动 | 更新时间 |
+
+**枚举：EnergyType**
+
+| 值 | 描述 |
+|----|------|
+| LIGHTING | 照明插座用电 |
+| HVAC | 空调用电 |
+| POWER | 动力用电 |
+| SPECIAL | 特殊用电 |
+| WATER | 给排水 |
+| GAS | 燃气 |
+
+### 2.14 EnergyConsumption（能耗记录）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | UUID | 是 | 主键 |
+| projectId | UUID | 是 | 项目ID |
+| meterId | UUID | 是 | 计量点ID |
+| consumptionDate | LocalDate | 是 | 消耗日期 |
+| previousReading | BigDecimal(12,2) | 否 | 上次读数 |
+| currentReading | BigDecimal(12,2) | 否 | 本次读数 |
+| consumption | BigDecimal(12,2) | 是 | 消耗量 |
+| amount | BigDecimal(10,2) | 否 | 金额 |
+| recordedBy | UUID | 否 | 记录人 |
+| recordMethod | Enum(RecordMethod) | 否 | 记录方式，默认MANUAL |
+| remarks | String(1000) | 否 | 备注 |
+| createdAt | LocalDateTime | 自动 | 创建时间 |
+
+**枚举：RecordMethod**
+
+| 值 | 描述 |
+|----|------|
+| MANUAL | 手动录入 |
+| IOT | IoT自动采集 |
+
+**索引**：
+
+| 索引名 | 列 |
+|--------|-----|
+| idx_ec_meter_date | meter_id, consumption_date |
+| idx_ec_project_date | project_id, consumption_date |
+
+### 2.15 实体关系图
+
+```
+Project (1) ──→ (N) SpaceNode          通过 projectId 关联
+Project (1) ──→ (1) ProjectConfig      通过 projectId 唯一关联
+Project (1) ──→ (1) ProjectStatistics   通过 projectId 唯一关联
+Project (1) ──→ (N) ProjectStatusHistory 通过 projectId 关联
+
+SpaceNode (1) ──→ (N) SpaceNode        通过 parentId 自关联（树形）
+SpaceNode (1) ──→ (0..1) Equipment     通过 isEquipment 标记（设备扩展字段）
+
+EnergyMeter (1) ──→ (N) EnergyConsumption  通过 meterId 关联
+EnergyMeter ──→ SpaceNode               通过 spaceNodeId 关联
+
+SparePartCategory (1) ──→ (N) SparePartCategory  通过 parentId 自关联（树形）
+SparePartCategory (1) ──→ (N) SparePart          通过 categoryId 关联
+SparePart (1) ──→ (N) SparePartRecord            通过 sparePartId 关联
+
+InspectionItem ──→ InspectionTemplate   通过 equipmentType 逻辑关联
+InspectionTemplate ──→ InspectionRecord 通过 planId 逻辑关联
+InspectionRecord ──→ SpaceNode(Equipment) 通过 equipmentId 关联
+```
+
+---
+
+## 三、API接口设计
+
+### 3.1 ProjectController — `/api/mdm/projects`
+
+| 编号 | 方法 | 路径 | 说明 | 请求参数 |
+|------|------|------|------|----------|
+| PM-001 | GET | / | 分页查询项目列表 | keyword, status, page, size, sortBy, sortDirection |
+| PM-010 | GET | /selector | 获取项目选择器列表 | - |
+| PM-005 | GET | /generate-code | 生成项目编码 | - |
+| - | GET | /{id} | 按ID查询项目 | id(Path) |
+| - | GET | /code/{code} | 按编码查询项目 | code(Path) |
+| - | POST | / | 创建项目 | Project(Body) |
+| - | PUT | /{id} | 更新项目 | id(Path), Project(Body) |
+| - | DELETE | /{id} | 删除项目 | id(Path) |
+| PM-003 | GET | /{id}/members | 获取项目成员列表 | id(Path), page, size |
+| PM-003 | POST | /{id}/members | 添加项目成员 | id(Path), AddMemberRequest(Body) |
+| PM-003 | DELETE | /{id}/members/{memberId} | 移除项目成员 | id(Path), memberId(Path) |
+| PM-002 | GET | /{id}/statistics | 获取项目统计数据 | id(Path) |
+| PM-006 | PUT | /{id}/status | 变更项目状态 | id(Path), ChangeStatusRequest(Body) |
+| PM-008 | GET | /{id}/config | 获取项目配置 | id(Path) |
+| PM-008 | PUT | /{id}/config | 更新项目配置 | id(Path), ProjectConfigDTO(Body) |
+| PM-009 | GET | /{projectId}/delete-check | 项目删除前检查 | projectId(Path) |
+
+**关键DTO**：
+
+```typescript
+// ProjectQueryRequest
+{ keyword?: string; status?: string; page?: number; size?: number; sortBy?: string; sortDirection?: string }
+
+// ChangeStatusRequest
+{ status: string; reason?: string }
+
+// AddMemberRequest
+{ userIds: string[]; roleInProject: string }
+
+// ProjectDeleteCheckVO
+{ canDelete: boolean; reason?: string; statistics: ProjectDeleteStatistics }
+```
+
+### 3.2 SpaceNodeController — `/api/mdm/space-nodes`
+
+| 编号 | 方法 | 路径 | 说明 | 请求参数 |
+|------|------|------|------|----------|
+| - | GET | / | 分页查询空间节点 | page, size |
+| - | GET | /{id} | 查询节点详情 | id(Path) |
+| - | GET | /project/{projectId} | 按项目查询节点列表 | projectId(Path) |
+| - | GET | /project/{projectId}/tree | 获取项目空间树 | projectId(Path) |
+| - | GET | /project/{projectId}/roots | 获取项目根节点 | projectId(Path) |
+| - | GET | /project/{projectId}/type/{nodeType} | 按项目+类型查询 | projectId(Path), nodeType(Path) |
+| - | GET | /parent/{parentId}/children | 获取子节点列表 | parentId(Path) |
+| - | POST | / | 创建空间节点 | SpaceNodeCreateDTO(Body) |
+| - | POST | /batch | 批量创建节点 | List\<SpaceNodeCreateDTO\>(Body) |
+| - | PUT | /{id} | 更新节点 | id(Path), SpaceNodeUpdateDTO(Body) |
+| - | DELETE | /{id} | 删除节点 | id(Path) |
+| - | GET | /{id}/delete-check | 删除前检查 | id(Path) |
+| - | DELETE | /{id}/cascade | 级联删除（含子节点） | id(Path) |
+| - | GET | /{id}/equipment | 获取设备详情 | id(Path) |
+| - | GET | /equipment | 获取设备列表 | projectId(Param) |
+| - | GET | /special-equipment | 获取特种设备列表 | projectId(Param) |
+| - | GET | /expiring-inspection | 获取即将年检设备 | projectId(Param), daysAhead(默认90) |
+| - | POST | /equipment | 创建设备 | EquipmentCreateDTO(Body) |
+| - | POST | /equipment/batch | 批量创建设备 | List\<EquipmentCreateDTO\>(Body) |
+| - | POST | /equipment/import | Excel导入设备 | file(Multipart), projectId(Param) |
+| - | GET | /{buildingId}/floor-info | 获取楼栋楼层信息 | buildingId(Path) |
+| - | GET | /debug/floor-numbers | 调试：检查房间楼层号 | projectId(Param) |
+
+**关键DTO**：
+
+```typescript
+// SpaceNodeCreateDTO / SpaceNodeUpdateForm
+{ projectId, name, nodeCategory, nodeType, parentId?, buildingArea?, ... }
+
+// SpaceNodeTreeDTO extends SpaceNode
+{ ...SpaceNode, children: SpaceNodeTreeDTO[] }
+
+// SpaceNodeDeleteCheckDTO
+{ nodeId, nodeName, childCount, childTypeCount, totalDescendantCount }
+
+// EquipmentCreateDTO
+{ projectId, name, nodeType, parentId?, ...设备扩展字段 }
+
+// FloorInfoVO
+{ buildingId, buildingName, totalFloors, undergroundFloors, floors: FloorDetailVO[] }
+```
+
+### 3.3 InspectionItemController — `/api/mdm/inspection-items`
+
+| 方法 | 路径 | 说明 | 请求参数 |
+|------|------|------|----------|
+| POST | / | 创建巡检标准项 | InspectionItem(Body) |
+| GET | / | 查询巡检标准项列表 | equipmentType?, systemType?, activeOnly? |
+| GET | /{id} | 获取标准项详情 | id(Path) |
+| PUT | /{id} | 更新标准项 | id(Path), InspectionItem(Body) |
+| DELETE | /{id} | 删除标准项 | id(Path) |
+
+**查询逻辑**：activeOnly=true → 仅启用项；equipmentType+systemType → 双条件过滤；equipmentType → 单条件过滤；systemType → 系统类型过滤；无参数 → 全部。
+
+### 3.4 InspectionTemplateController — `/api/ops/inspection-templates`
+
+| 方法 | 路径 | 说明 | 请求参数 |
+|------|------|------|----------|
+| GET | / | 获取项目模板列表 | projectId(Param) |
+| POST | / | 创建模板 | InspectionTemplate(Body) |
+| GET | /{id} | 获取模板详情 | id(Path) |
+| PUT | /{id} | 更新模板 | id(Path), InspectionTemplate(Body) |
+| POST | /{id}/copy | 复制模板 | id(Path), newName(Param) |
+| GET | /by-type/{equipmentType} | 按设备类型查模板 | equipmentType(Path) |
+
+### 3.5 InspectionRecordController — `/api/mdm/inspection-records`
+
+| 方法 | 路径 | 说明 | 请求参数 |
+|------|------|------|----------|
+| POST | / | 创建巡检记录 | InspectionRecord(Body) |
+| GET | / | 查询巡检记录列表 | equipmentId?, planId?, inspector?, status?, startDate?, endDate? |
+| GET | /{id} | 获取记录详情 | id(Path) |
+| PUT | /{id} | 更新记录 | id(Path), InspectionRecord(Body) |
+| DELETE | /{id} | 删除记录 | id(Path) |
+| POST | /{id}/complete | 完成巡检记录 | id(Path) |
+
+**查询逻辑**：equipmentId+日期范围 → 设备+日期；equipmentId → 设备；planId → 计划；inspector → 巡检人；status → 状态；日期范围 → 时间段；无参数 → 全部。
+
+### 3.6 SparePartController — `/api/ops/spare-parts`
+
+| 方法 | 路径 | 说明 | 请求参数 |
+|------|------|------|----------|
+| GET | /categories | 获取分类列表 | - |
+| POST | /categories | 创建分类 | SparePartCategory(Body) |
+| GET | / | 获取备件列表 | projectId(Param), categoryId? |
+| GET | /{id} | 获取备件详情 | id(Path) |
+| POST | / | 创建备件 | SparePart(Body) |
+| PUT | /{id} | 更新备件 | id(Path), SparePart(Body) |
+| DELETE | /{id} | 删除备件 | id(Path) |
+| GET | /low-stock | 获取低库存备件 | projectId(Param) |
+| POST | /in-stock | 入库操作 | StockRequest(Body) |
+| POST | /out-stock | 出库操作 | OutStockRequest(Body) |
+| GET | /{id}/records | 获取备件出入库记录 | id(Path) |
+
+**关键请求体**：
+
+```typescript
+// StockRequest
+{ sparePartId: UUID; quantity: Integer; recordedBy?: UUID; remarks?: String }
+
+// OutStockRequest
+{ sparePartId: UUID; quantity: Integer; relatedOrderId?: UUID; recordedBy?: UUID; remarks?: String }
+```
+
+### 3.7 EnergyController — `/api/ops/energy`
+
+| 方法 | 路径 | 说明 | 请求参数 |
+|------|------|------|----------|
+| POST | /meters | 创建计量点 | EnergyMeter(Body) |
+| GET | /meters | 获取计量点列表 | projectId(Param), energyType? |
+| GET | /meters/{id} | 获取计量点详情 | id(Path) |
+| PUT | /meters/{id} | 更新计量点 | id(Path), EnergyMeter(Body) |
+| DELETE | /meters/{id} | 删除计量点 | id(Path) |
+| POST | /consumption | 录入能耗记录 | RecordConsumptionRequest(Body) |
+| GET | /consumption/{meterId} | 获取能耗记录 | meterId(Path), startDate?, endDate? |
+| GET | /statistics/by-type | 按类型统计能耗 | projectId(Param), month(Param) |
+| GET | /statistics/unit-consumption | 单位面积能耗 | projectId(Param), month(Param) |
+
+**关键请求体**：
+
+```typescript
+// RecordConsumptionRequest
+{ meterId: UUID; currentReading: BigDecimal; recordedBy?: UUID }
+```
+
+---
+
+## 四、业务规则
+
+### 4.1 空间节点树形管理
+
+#### 4.1.1 树形结构规则
+
+```
+项目 (Project)
+├── 楼栋 (BUILDING)          ← NodeCategory.BUILDING, order=1
+│   ├── 单元 (UNIT)          ← NodeCategory.BUILDING, order=2
+│   │   ├── 楼层 (FLOOR)     ← NodeCategory.BUILDING, order=3
+│   │   │   └── 房间 (ROOM)  ← NodeCategory.BUILDING, order=4
+│   │   └── 房间 (ROOM)      ← 可跳过楼层直接挂房间
+│   └── 公共用房 (PUBLIC_ROOM)
+├── 商铺 (SHOP)              ← NodeCategory.BUILDING, order=2（直接挂在项目下）
+├── 车库 (GARAGE)            ← NodeCategory.PARKING, order=1
+│   ├── 停车区域 (PARKING_AREA) ← NodeCategory.PARKING, order=2
+│   │   └── 车位 (PARKING_SPACE) ← NodeCategory.PARKING, order=3
+├── 设备房 (EQUIPMENT_ROOM)  ← NodeCategory.FACILITY, order=1
+├── 物业用房 (PROPERTY_OFFICE)
+├── 门岗 (SECURITY_ROOM)
+├── 公共区域 (PUBLIC_AREA)   ← NodeCategory.AREA, order=1
+├── 绿化区域 (GREEN_AREA)
+└── 道路 (ROAD)
+```
+
+#### 4.1.2 树形路径维护
+
+- **treePath**：物理路径，格式 `id1.id2.id3`，用于快速查询所有子孙节点
+- **treePathName**：名称路径，格式 `项目/楼栋/单元/房间`，用于展示
+- **level**：层级深度，根节点为0，每层+1
+- 创建/移动节点时自动维护 treePath 和 treePathName
+
+#### 4.1.3 设备扩展模式
+
+SpaceNode 通过 `isEquipment` 字段标记是否为设备节点。设备节点在基础空间字段之外，额外使用设备扩展字段（维保信息、巡检周期、特种设备证书等）。这种设计将设备信息嵌入空间节点，而非独立设备实体。
+
+#### 4.1.4 删除规则
+
+- 删除前必须调用 `delete-check` 接口检查子节点数量
+- 普通删除：仅删除当前节点（有子节点时拒绝）
+- 级联删除：删除当前节点及所有子孙节点
+- 软删除：通过 `isDeleted` 标记，非物理删除
+
+#### 4.1.5 批量操作
+
+- 批量创建：通过 `batch` 接口，受 `BatchOperationValidator` 限制数量
+- Excel导入设备：支持 .xlsx/.xls 格式，最大1000行，文件类型校验
+
+### 4.2 项目状态流转
+
+#### 4.2.1 状态值
+
+| 状态 | 描述 | 可流转到 |
+|------|------|----------|
+| PENDING | 待审核 | ACTIVE, DISABLED |
+| ACTIVE | 正常 | DISABLED, ARCHIVED |
+| DISABLED | 禁用 | ACTIVE, ARCHIVED |
+| ARCHIVED | 已归档 | -（终态） |
+
+#### 4.2.2 状态变更规则
+
+- 每次状态变更必须记录 `ProjectStatusHistory`（fromStatus, toStatus, reason, operatorId, operatorName）
+- 删除项目前必须调用 `delete-check` 检查关联数据
+- 存在应收未收费用时无法删除项目
+
+#### 4.2.3 项目成员管理
+
+- 成员角色：PROJECT_MANAGER(项目经理)、PROJECT_ADMIN(项目管理员)、OPERATION_STAFF(运营人员)、FINANCE_STAFF(财务人员)、VIEWER(查看者)
+- 员工类型：SECURITY(保安)、CLEANING(保洁)、GARDEN(绿化)、MAINTENANCE(维修)、CUSTOMER_SERVICE(客服)、PROJECT_STAFF(项目人员)
+- 支持批量添加成员
+
+### 4.3 巡检标准项管理
+
+#### 4.3.1 标准项库
+
+- 巡检标准项按 `equipmentType`（设备类型）和 `systemType`（系统类型）分类
+- 每个标准项包含：检查项名称、检查方法、标准值、是否必检
+- 标准项状态：ACTIVE(启用)/INACTIVE(停用)
+- 支持按 activeOnly=true 仅查询启用项
+
+#### 4.3.2 巡检模板
+
+- 模板按项目+设备类型组织
+- 模板包含检查项列表（JSON格式存储）
+- 支持模板版本管理（version字段）
+- 支持模板复制（copy接口）
+- 模板与标准项通过 equipmentType 逻辑关联
+
+#### 4.3.3 巡检记录
+
+- 记录关联设备（equipmentId）和计划（planId）
+- 检查结果状态：NORMAL(正常)/WARNING(预警)/ABNORMAL(异常)
+- 支持签到信息（时间、位置、照片）
+- 检查项结果和异常问题以JSONB存储
+- 完成操作：调用 `complete` 接口标记完成
+
+### 4.4 备件库存管理
+
+#### 4.4.1 库存管理规则
+
+- 每个备件有 `currentStock`（当前库存）和 `safeStock`（安全库存）
+- 当 `currentStock < safeStock` 时触发低库存预警
+- 低库存查询：`low-stock` 接口返回低于安全库存的备件列表
+
+#### 4.4.2 出入库操作
+
+| 操作 | 说明 | 关键字段 |
+|------|------|----------|
+| 入库(IN) | 增加库存 | sparePartId, quantity, recordedBy, remarks |
+| 出库(OUT) | 减少库存 | sparePartId, quantity, relatedOrderId, recordedBy, remarks |
+| 盘点(CHECK) | 库存盘点 | sparePartId, quantity, recordedBy |
+| 调整(ADJUST) | 库存调整 | sparePartId, quantity, recordedBy |
+
+- 每次操作记录 `SparePartRecord`，包含操作后余额（balance）
+- 出库可关联工单（relatedOrderId）
+- 出库时校验库存不能为负
+
+#### 4.4.3 备件分类
+
+- 支持树形分类（parentId 自关联）
+- 分类编码唯一
+- 备件通过 categoryId 关联分类
+
+### 4.5 能耗计量管理
+
+#### 4.5.1 计量点管理
+
+- 计量点按能源类型分类：照明插座用电、空调用电、动力用电、特殊用电、给排水、燃气
+- 计量点关联空间节点（spaceNodeId）
+- 计量点状态：ACTIVE(启用)/INACTIVE(停用)
+
+#### 4.5.2 能耗记录
+
+- 抄表记录包含：上次读数、本次读数、消耗量、金额
+- 消耗量 = 本次读数 - 上次读数
+- 金额 = 消耗量 × 单价（计量点的 unitPrice）
+- 记录方式：MANUAL(手动录入)/IOT(IoT自动采集)
+
+#### 4.5.3 能耗统计
+
+- **按类型统计**：`getConsumptionByType(projectId, month)` → `Map<EnergyType, BigDecimal>`
+- **单位面积能耗**：`getUnitConsumption(projectId, month)` → 总能耗/总建筑面积
+- 支持按日期范围查询能耗趋势
+
+---
+
+## 五、前端操作流程
+
+### 5.1 项目管理流程
+
+```
+项目列表页 → 新建项目
+    │
+    ├── 填写项目基本信息（编码、名称、类型、地址）
+    ├── 系统自动生成项目编码（generate-code）
+    ├── 创建后自动初始化 ProjectConfig（默认配置）
+    └── 跳转到项目详情
+
+项目详情页
+    ├── 基本信息Tab：编辑项目信息
+    ├── 成员管理Tab：
+    │   ├── 查看成员列表（分页）
+    │   ├── 添加成员（从企业员工中选择）
+    │   └── 移除成员
+    ├── 空间管理Tab：跳转到空间节点管理
+    ├── 统计数据Tab：查看项目统计
+    ├── 配置管理Tab：功能开关配置
+    └── 状态管理：变更项目状态（需填写原因）
+
+项目删除
+    ├── 先调用 delete-check 检查关联数据
+    ├── 有应收未收费用 → 无法删除
+    └── 无关联数据 → 确认删除
+```
+
+### 5.2 空间节点管理流程
+
+```
+空间管理页（左侧树 + 右侧详情）
+    │
+    ├── 左侧树形导航
+    │   ├── 加载项目空间树（getSpaceTree）
+    │   ├── 点击节点 → 右侧显示详情
+    │   └── 展开/折叠节点
+    │
+    ├── 右侧详情区
+    │   ├── 节点基本信息
+    │   ├── 面积信息
+    │   ├── 地址信息
+    │   └── 子节点列表（表格）
+    │
+    ├── 新增节点
+    │   ├── 选择父节点
+    │   ├── 选择节点类型（NodeType）
+    │   ├── 自动填充 NodeCategory
+    │   └── 填写名称、面积等信息
+    │
+    ├── 批量创建
+    │   ├── 批量创建楼栋/单元/房间
+    │   └── 受 BatchOperationValidator 限制
+    │
+    ├── 设备管理
+    │   ├── 创建设备（isEquipment=true）
+    │   ├── 批量创建设备
+    │   ├── Excel导入设备
+    │   ├── 查看设备列表
+    │   ├── 查看特种设备列表
+    │   └── 查看即将年检设备（90天内）
+    │
+    └── 删除节点
+        ├── 删除前检查（delete-check）
+        └── 确认删除或级联删除
+```
+
+### 5.3 巡检管理流程
+
+```
+巡检标准项管理
+    │
+    ├── 标准项列表页
+    │   ├── 按设备类型/系统类型筛选
+    │   ├── 仅查看启用项（activeOnly）
+    │   ├── 新增标准项
+    │   ├── 编辑标准项
+    │   └── 停用/启用标准项
+    │
+    └── 巡检模板管理
+        ├── 模板列表页（按项目筛选）
+        ├── 新增模板
+        │   ├── 选择设备类型
+        │   ├── 配置检查项（从标准项库选择）
+        │   └── 设置预计耗时
+        ├── 编辑模板
+        ├── 复制模板
+        └── 按设备类型查模板
+
+巡检记录管理
+    │
+    ├── 记录列表页
+    │   ├── 按设备/计划/巡检人/状态/日期筛选
+    │   └── 查看记录详情
+    │
+    ├── 创建巡检记录
+    │   ├── 选择设备
+    │   ├── 填写巡检日期和巡检人
+    │   ├── 逐项填写检查结果
+    │   ├── 上报异常问题
+    │   └── 签到（时间、位置、照片）
+    │
+    └── 完成巡检
+        └── 调用 complete 接口标记完成
+```
+
+### 5.4 备件管理流程
+
+```
+备件分类管理
+    │
+    ├── 分类列表
+    ├── 新增分类（支持树形层级）
+    └── 编辑分类
+
+备件台账管理
+    │
+    ├── 备件列表页
+    │   ├── 按项目筛选
+    │   ├── 按分类筛选
+    │   ├── 低库存预警标识
+    │   └── 新增/编辑/删除备件
+    │
+    ├── 入库操作
+    │   ├── 选择备件
+    │   ├── 输入入库数量
+    │   └── 确认入库 → 更新 currentStock
+    │
+    ├── 出库操作
+    │   ├── 选择备件
+    │   ├── 输入出库数量
+    │   ├── 可关联工单
+    │   └── 确认出库 → 更新 currentStock
+    │
+    └── 出入库记录
+        └── 查看备件的所有操作流水
+
+低库存预警
+    │
+    └── 低库存备件列表（currentStock < safeStock）
+```
+
+### 5.5 能耗管理流程
+
+```
+计量点管理
+    │
+    ├── 计量点列表页
+    │   ├── 按项目筛选
+    │   ├── 按能源类型筛选
+    │   └── 新增/编辑/删除计量点
+    │
+    └── 计量点详情
+        ├── 关联空间节点
+        ├── 额定容量、单价
+        └── 状态管理
+
+能耗抄表
+    │
+    ├── 录入能耗
+    │   ├── 选择计量点
+    │   ├── 输入本次读数
+    │   ├── 系统自动计算消耗量和金额
+    │   └── 选择记录方式（手动/IoT）
+    │
+    └── 能耗记录查询
+        ├── 按计量点查询
+        └── 按日期范围查询
+
+能耗统计
+    │
+    ├── 按类型统计
+    │   └── 指定月份各能源类型消耗量
+    │
+    └── 单位面积能耗
+        └── 总能耗/总建筑面积
+```
+
+---
+
+## 六、与原需求文档 02-SPACE_NODE_DESIGN.md 的差异对比
+
+### 6.1 数据模型差异
+
+| 对比项 | 原需求文档设计 | 实际代码实现 | 差异分析 |
+|--------|---------------|-------------|----------|
+| **API路径前缀** | `/api/v1/mdm/space-nodes` | `/api/mdm/space-nodes` | 去掉了v1版本号 |
+| **code字段** | 有 `code` 列，`UNIQUE(project_id, code)` | 无 `code` 列，列名 `project_code` 实际存 projectId | 原设计的空间编码未实现，project_code 列名与实际存储不匹配 |
+| **PostGIS字段** | `location GEOMETRY(Point)`, `boundary GEOMETRY(Polygon)` | 无PostGIS字段 | 地图服务未实现，仅保留经纬度数值字段 |
+| **attributes字段** | JSONB类型 | String(2000) | 降级为字符串存储JSON，未使用PostgreSQL JSONB |
+| **设备扩展字段** | 未设计（设备独立为 asset_equipment 表） | SpaceNode 内嵌设备扩展字段 | 实际采用"空间+设备"混合模型，isEquipment标记 |
+| **NodeType枚举** | 无 PUBLIC_ROOM | 增加 PUBLIC_ROOM(公共用房) | 实际增加了公共用房类型 |
+| **删除方式** | 未明确 | 软删除（isDeleted字段） | 实际采用软删除 |
+| **唯一约束** | `UNIQUE(project_id, code)` | 无唯一约束 | 空间编码唯一性未在数据库层面约束 |
+| **索引** | GIST空间索引、GIN属性索引 | 普通B-tree索引 | 无空间索引和JSON索引 |
+
+### 6.2 API接口差异
+
+| 对比项 | 原需求文档设计 | 实际代码实现 | 差异分析 |
+|--------|---------------|-------------|----------|
+| **树形查询** | `GET /tree` 全局树 | `GET /project/{projectId}/tree` 按项目 | 实际按项目维度查询，更合理 |
+| **祖先节点** | `GET /{id}/ancestors` | 未实现 | 祖先链查询缺失 |
+| **子孙节点** | `GET /{id}/descendants` | 未实现 | 可通过 treePath LIKE 查询替代 |
+| **移动节点** | `PUT /{id}/move` | 未实现 | 节点移动功能缺失 |
+| **类型快捷查询** | `/buildings`, `/rooms`, `/parking-spaces`, `/shops` | `GET /project/{projectId}/type/{nodeType}` | 统一为按类型查询，更通用 |
+| **批量更新** | `PUT /batch` | 未实现 | 仅支持批量创建 |
+| **批量删除** | `DELETE /batch` | 未实现 | 仅支持单个/级联删除 |
+| **导入模板下载** | `GET /export/template` | 未实现 | 无模板下载接口 |
+| **数据导出** | `GET /export` | 未实现 | 无导出功能 |
+| **地图相关** | `/map/markers`, `/map/boundaries`, `/{id}/location`, `/{id}/boundary` | 未实现 | 地图服务完全未实现 |
+| **统计分析** | `/statistics`, `/statistics/by-type`, `/statistics/by-status` | 未实现 | 空间统计接口缺失 |
+| **删除前检查** | 未设计 | `GET /{id}/delete-check` | 实际增加了安全检查 |
+| **级联删除** | 未设计 | `DELETE /{id}/cascade` | 实际增加了级联删除 |
+| **设备管理** | 未设计（设备独立模块） | 设备CRUD集成在SpaceNodeController | 空间与设备管理合并 |
+| **Excel导入** | 空间节点导入 | 仅设备导入 | 空间节点批量导入未实现 |
+| **楼层信息** | 未设计 | `GET /{buildingId}/floor-info` | 实际增加了楼栋楼层信息接口 |
+
+### 6.3 前端差异
+
+| 对比项 | 原需求文档设计 | 实际代码实现 | 差异分析 |
+|--------|---------------|-------------|----------|
+| **地图模式** | 高德地图集成，支持标注/绘制/路径 | 未实现 | 地图功能完全未开发 |
+| **MapEditor组件** | AMap SDK集成 | 未实现 | - |
+| **空间编码** | 自动生成空间编码规则 | 未实现 | SpaceNode无code字段 |
+| **批量创建房间** | 支持 startFloor/endFloor/roomsPerFloor 模板 | 仅支持 DTO 列表批量创建 | 智能批量创建未实现 |
+
+### 6.4 业务规则差异
+
+| 对比项 | 原需求文档设计 | 实际代码实现 | 差异分析 |
+|--------|---------------|-------------|----------|
+| **设备模型** | 独立 Equipment 实体（asset_equipment表） | SpaceNode 内嵌设备扩展字段 | 两种模型并存：module-mdm 用 SpaceNode 扩展，module-asset 用独立 Equipment |
+| **项目统计** | 数据库视图实时计算 | ProjectStatistics 实体快照 | 实际采用快照模式，需手动同步 |
+| **空间编码** | 自动生成编码规则 | 未实现 | 无自动编码机制 |
+| **PostGIS** | 空间查询（范围搜索、距离计算） | 未使用 | 无空间数据库能力 |
+
+### 6.5 差异总结
+
+| 类别 | 已实现 | 部分实现 | 未实现 |
+|------|--------|----------|--------|
+| **数据模型** | 基础字段、树形结构、NodeType枚举 | 设备扩展字段（混合模型） | PostGIS、JSONB、空间编码 |
+| **API接口** | 基础CRUD、树形查询、设备管理 | 批量操作 | 地图服务、统计分析、导入导出 |
+| **前端** | 树形导航、表单编辑 | - | 地图模式、智能批量创建 |
+| **业务规则** | 删除检查、级联删除 | - | 空间编码、空间查询 |
+
+---
+
+## 附录A：服务层接口清单
+
+| 服务 | 关键方法 |
+|------|----------|
+| ProjectService | create, update, delete, findById, findByCode, queryProjects, getSelectorList, generateCode, changeStatus, checkProjectDelete |
+| ProjectMemberService | getMembers, addMembers, removeMember |
+| ProjectConfigService | getConfig, updateConfig |
+| ProjectStatisticsService | getStatistics |
+| SpaceNodeService | create, batchCreate, update, delete, deleteWithChildren, findById, findByProjectId, getTreeByProjectId, findRootsByProjectId, findChildren, findByProjectIdAndNodeType, checkDeleteInfo, getEquipmentById, getEquipmentList, getSpecialEquipmentList, getExpiringInspectionEquipment, createEquipment, batchCreateEquipment, importEquipmentFromExcel, getBuildingFloorInfo |
+| InspectionItemService | createItem, getItemById, updateItem, deleteItem, getAllItems, getActiveItems, getItemsByEquipmentType, getItemsBySystemType, getItemsByEquipmentTypeAndSystemType |
+| InspectionTemplateService | createTemplate, getTemplateById, updateTemplate, getTemplatesByProject, getTemplatesByType, copyTemplate |
+| InspectionRecordService | createRecord, getRecordById, updateRecord, deleteRecord, completeRecord, getAllRecords, getRecordsByEquipment, getRecordsByEquipmentAndDateRange, getRecordsByPlan, getRecordsByInspector, getRecordsByStatus, getRecordsByDateRange |
+| SparePartService | createSparePart, getSparePartById, updateSparePart, deleteSparePart, getSparePartsByProject, getSparePartsByCategory, getLowStockParts, inStock, outStock, getSparePartRecords, getCategories, createCategory |
+| EnergyMeterService | createMeter, getMeterById, updateMeter, deleteMeter, getMetersByProject, getMetersByType |
+| EnergyConsumptionService | recordConsumption, getConsumptionByMeter, getConsumptionByMeterAndDateRange, getConsumptionByType, getUnitConsumption |
+
+---
+
+## 附录B：前端API文件对照
+
+| 前端文件 | 对应后端Controller | 说明 |
+|----------|-------------------|------|
+| `src/api/project.ts` | ProjectController | 项目CRUD、成员、配置、统计 |
+| `src/api/space.ts` | SpaceNodeController | 空间节点CRUD、树形查询 |
+| `src/api/inspection-item.ts` | InspectionItemController | 巡检标准项CRUD |
+| `src/api/inspection-template.ts` | InspectionTemplateController | 巡检模板CRUD |
+| `src/api/inspection-record.ts` | InspectionRecordController | 巡检记录CRUD |
+| `src/api/sparepart.ts` | SparePartController | 备件CRUD、出入库 |
+| `src/api/energy.ts` | EnergyController | 计量点CRUD、能耗记录 |
+| `src/api/maintenance-plan.ts` | - | 维保计划（独立模块） |
+| `src/types/project.ts` | - | 项目相关类型定义 |
+| `src/types/space.ts` | - | 空间节点类型定义 |
+
+---
+
+**文档生成说明**：本文档基于 `ether-pms/module-mdm` 模块的实际代码反推生成，涵盖13个实体、7个控制器、11个服务接口的完整分析。所有字段、枚举、API端点均来源于实际代码，与原需求文档的差异已在第六章详细对比。
diff --git a/02-DESIGN/domains/REVERSE-OPS.md b/02-DESIGN/domains/REVERSE-OPS.md
new file mode 100644
index 0000000..f0265f5
--- /dev/null
+++ b/02-DESIGN/domains/REVERSE-OPS.md
@@ -0,0 +1,914 @@
+# 运维工单域功能详细设计文档（代码反推版）
+
+**文档来源**: 基于 module-wo 模块实际代码反推  
+**生成日期**: 2026-04-23  
+**代码基线**: ether-pms/module-wo, ether-admin  
+**对照文档**: 02-OPERATIONS.md（运营调度领域技术方案）
+
+---
+
+## 一、领域概述
+
+### 1.1 领域职责
+
+运维工单域（module-wo）负责管理物业运维全生命周期，涵盖：
+
+- **综合工单管理**：多来源工单的创建、分配、执行、完成、验收全流程
+- **维保计划管理**：设备周期性维保计划的制定与调度
+- **维保任务管理**：维保工单的触发、执行、验收闭环
+- **巡检模板管理**：设备点检模板与检查项的配置
+- **工单明细管理**：工单下的备件/巡检项/检查点明细
+- **统计看板**：工单与维保任务的多维度统计
+
+### 1.2 核心概念
+
+| 概念 | 说明 | 对应实体 | 数据库表 |
+|------|------|----------|----------|
+| **工单** | 综合业务单据，支持6种来源6种类型 | WorkOrder | ops_work_order |
+| **工单明细** | 工单下的备件/巡检项/检查点 | WorkOrderItem | ops_work_order_item |
+| **维保计划** | 设备周期性维保计划 | MaintenancePlan | ops_maintenance_plan |
+| **维保任务** | 维保工单（设备维保执行单元） | MaintenanceTask | ops_maintenance_task |
+| **巡检模板** | 设备点检模板 | InspectionTemplate | ops_inspection_template |
+| **巡检项** | 模板下的检查项 | InspectionItem | ops_inspection_item |
+
+### 1.3 领域边界
+
+实际实现中，运维工单域与原需求文档的边界存在显著差异：
+
+- **原需求**：运营调度域（ether-ops）包含工单 + 消息通知系统
+- **实际实现**：module-wo 仅包含工单/维保/巡检，消息通知系统未实现
+- **前端分裂**：维保计划存在两套前端 API（`maintenance.ts` vs `maintenance-plan.ts`），巡检标准项归属 MDM 域
+
+---
+
+## 二、数据结构设计
+
+### 2.1 WorkOrder（工单）
+
+**表名**: `ops_work_order`
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| id | UUID | 是 | 自动生成 | 主键 |
+| workNo | VARCHAR(50) | 是 | 自动生成 | 工单编号，格式: WO-YYYYMMDD-XXXX |
+| source | ENUM | 是 | - | 工单来源 |
+| type | ENUM | 是 | - | 工单类型 |
+| priority | ENUM | 否 | MEDIUM | 优先级 |
+| status | ENUM | 否 | PENDING | 工单状态 |
+| title | VARCHAR(200) | 是 | - | 工单标题 |
+| description | VARCHAR(2000) | 否 | - | 工单描述 |
+| projectId | UUID | 是 | - | 所属项目 |
+| equipmentId | UUID | 否 | - | 关联设备 |
+| spaceId | UUID | 否 | - | 关联空间 |
+| planId | UUID | 否 | - | 关联维保计划 |
+| triggerType | ENUM | 否 | - | 触发类型 |
+| assignedTo | VARCHAR(200) | 否 | - | 负责人 |
+| assignedVendor | VARCHAR(200) | 否 | - | 服务商 |
+| assignedDate | DATE | 否 | - | 派单日期 |
+| actualStart | TIMESTAMP | 否 | - | 实际开始时间 |
+| actualEnd | TIMESTAMP | 否 | - | 实际结束时间 |
+| actualHours | DECIMAL(6,2) | 否 | - | 实际工时（小时） |
+| faultCause | VARCHAR(2000) | 否 | - | 故障原因 |
+| solution | VARCHAR(5000) | 否 | - | 解决方案 |
+| result | VARCHAR(2000) | 否 | - | 处理结果 |
+| laborCost | DECIMAL(12,2) | 否 | - | 人工费 |
+| partsCost | DECIMAL(12,2) | 否 | - | 备件费 |
+| totalCost | DECIMAL(12,2) | 否 | - | 总费用 |
+| completedBy | VARCHAR(200) | 否 | - | 完成人 |
+| completedDate | DATE | 否 | - | 完成日期 |
+| verifiedBy | VARCHAR(200) | 否 | - | 验收人 |
+| verifiedDate | DATE | 否 | - | 验收日期 |
+| rating | INTEGER | 否 | - | 评分（1-5星） |
+| remark | VARCHAR(1000) | 否 | - | 备注 |
+| photos | JSONB | 否 | - | 照片URL列表 |
+| signature | VARCHAR(2000) | 否 | - | 签名 |
+| createdAt | TIMESTAMP | 是 | now() | 创建时间 |
+| updatedAt | TIMESTAMP | 是 | now() | 更新时间 |
+| createdBy | VARCHAR(200) | 否 | - | 创建人 |
+
+**枚举定义**：
+
+| 枚举 | 值 | 中文 |
+|------|-----|------|
+| Source | OWNER | 业主报修 |
+| | MAINTENANCE | 维保计划 |
+| | INSPECTION | 巡检触发 |
+| | FAULT | 故障触发 |
+| | REGULATORY | 法规巡检 |
+| | MANUAL | 手动创建 |
+| Type | REPAIR | 维修 |
+| | INSPECTION | 巡检 |
+| | SECURITY | 安保 |
+| | CLEANING | 保洁 |
+| | PROPERTY | 物业 |
+| | CONSULTATION | 咨询 |
+| Priority | LOW / MEDIUM / HIGH / URGENT | 低/中/高/紧急 |
+| Status | PENDING / ASSIGNED / IN_PROGRESS / COMPLETED / VERIFIED / CANCELLED | 见状态机 |
+| TriggerType | PLAN / INSPECTION / FAULT / MANUAL | 计划/巡检/故障/手动 |
+
+**索引**：
+
+| 索引名 | 字段 | 用途 |
+|--------|------|------|
+| idx_wo_project_status | project_id, status | 项目+状态查询 |
+| idx_wo_priority_status | priority, status | 优先级+状态查询 |
+| idx_wo_plan_createdat | plan_id, created_at | 计划关联查询 |
+| idx_wo_status_createdat | status, created_at | 状态+时间查询 |
+| idx_wo_createdat_desc | created_at DESC | 时间倒序 |
+
+### 2.2 WorkOrderItem（工单明细）
+
+**表名**: `ops_work_order_item`
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| id | UUID | 是 | 自动生成 | 主键 |
+| workOrderId | UUID | 是 | - | 所属工单ID |
+| itemType | ENUM | 是 | - | 明细类型 |
+| itemName | VARCHAR(200) | 是 | - | 明细名称 |
+| quantity | DECIMAL(10,2) | 否 | 1 | 数量 |
+| unit | VARCHAR(50) | 否 | - | 单位 |
+| unitPrice | DECIMAL(12,2) | 否 | - | 单价 |
+| totalPrice | DECIMAL(12,2) | 否 | - | 总价 |
+| isNormal | BOOLEAN | 否 | - | 是否正常 |
+| observation | VARCHAR(2000) | 否 | - | 观察记录 |
+| suggestion | VARCHAR(2000) | 否 | - | 建议 |
+| sortOrder | INTEGER | 否 | 0 | 排序序号 |
+| createdAt | TIMESTAMP | 否 | now() | 创建时间 |
+
+**枚举定义**：
+
+| 枚举 | 值 | 中文 |
+|------|-----|------|
+| ItemType | PART | 备件 |
+| | INSPECTION_ITEM | 巡检项 |
+| | CHECKPOINT | 检查点 |
+
+### 2.3 MaintenanceTask（维保任务）
+
+**表名**: `ops_maintenance_task`
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| id | UUID | 是 | 自动生成 | 主键 |
+| taskNo | VARCHAR(50) | 否 | 自动生成 | 任务编号，格式: EQ-YYYYMMDD-XXXX |
+| planId | UUID | 否 | - | 关联维保计划ID |
+| equipmentId | UUID | 是 | - | 关联设备ID |
+| projectId | UUID | 否 | - | 所属项目 |
+| taskType | ENUM | 否 | - | 任务类型 |
+| triggerType | ENUM | 否 | - | 触发类型 |
+| priority | ENUM | 否 | 自动判定 | 优先级 |
+| status | ENUM | 否 | PENDING | 任务状态 |
+| title | VARCHAR(200) | 否 | - | 任务标题 |
+| description | VARCHAR(2000) | 否 | - | 任务描述 |
+| assignedTo | VARCHAR(200) | 否 | - | 负责人 |
+| assignedVendor | VARCHAR(200) | 否 | - | 服务商 |
+| assignedDate | DATE | 否 | - | 派单日期 |
+| actualStart | TIMESTAMP | 否 | - | 实际开始时间 |
+| actualEnd | TIMESTAMP | 否 | - | 实际结束时间 |
+| actualHours | DECIMAL(6,2) | 否 | - | 实际工时 |
+| faultCause | VARCHAR(2000) | 否 | - | 故障原因 |
+| solution | VARCHAR(5000) | 否 | - | 解决方案 |
+| result | VARCHAR(2000) | 否 | - | 处理结果 |
+| partsUsed | JSONB | 否 | - | 使用备件列表 |
+| laborCost | DECIMAL(12,2) | 否 | - | 人工费 |
+| partsCost | DECIMAL(12,2) | 否 | - | 备件费 |
+| totalCost | DECIMAL(12,2) | 否 | - | 总费用 |
+| completedBy | VARCHAR(200) | 否 | - | 完成人 |
+| completedDate | DATE | 否 | - | 完成日期 |
+| verifiedBy | VARCHAR(200) | 否 | - | 验收人 |
+| verifiedDate | DATE | 否 | - | 验收日期 |
+| rating | INTEGER | 否 | - | 评分（1-5） |
+| remark | VARCHAR(1000) | 否 | - | 备注 |
+| photos | JSONB | 否 | - | 照片URL列表 |
+| signature | VARCHAR(2000) | 否 | - | 签名 |
+| createdAt | TIMESTAMP | 否 | now() | 创建时间 |
+| updatedAt | TIMESTAMP | 否 | now() | 更新时间 |
+| createdBy | VARCHAR(200) | 否 | - | 创建人 |
+
+**枚举定义**：
+
+| 枚举 | 值 | 中文 |
+|------|-----|------|
+| TaskType | PREVENTIVE | 预防性维护 |
+| | CORRECTIVE | 纠正性维护 |
+| | EMERGENCY | 紧急维修 |
+| TriggerType | PLAN | 计划触发 |
+| | INSPECTION | 巡检触发 |
+| | FAULT | 故障触发 |
+| | MANUAL | 手动创建 |
+| Priority | LOW / MEDIUM / HIGH / URGENT | 低/中/高/紧急 |
+| Status | PENDING / ASSIGNED / IN_PROGRESS / COMPLETED / VERIFIED / CANCELLED | 见状态机 |
+
+**partsUsed JSONB 结构**：
+
+```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.4 MaintenancePlan（维保计划）
+
+**表名**: `ops_maintenance_plan`
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| id | UUID | 是 | 自动生成 | 主键 |
+| planCode | VARCHAR(50) | 是 | 自动生成 | 计划编码（唯一） |
+| planName | VARCHAR(200) | 是 | - | 计划名称 |
+| planContent | VARCHAR(5000) | 否 | - | 计划内容 |
+| projectId | UUID | 否 | - | 所属项目 |
+| equipmentId | UUID | 是 | - | 关联设备 |
+| planType | ENUM | 是 | - | 计划类型 |
+| cycleDays | INTEGER | 否 | - | 周期天数 |
+| estimatedHours | DECIMAL(6,2) | 否 | - | 预估工时 |
+| assignedVendor | VARCHAR(200) | 否 | - | 指定服务商 |
+| status | ENUM | 否 | ACTIVE | 计划状态 |
+| lastDate | DATE | 否 | - | 上次执行日期 |
+| nextDate | DATE | 否 | - | 下次执行日期 |
+| createdAt | TIMESTAMP | 否 | now() | 创建时间 |
+| updatedAt | TIMESTAMP | 否 | now() | 更新时间 |
+| createdBy | VARCHAR(200) | 否 | - | 创建人 |
+
+**枚举定义**：
+
+| 枚举 | 值 | 中文 |
+|------|-----|------|
+| PlanType | PREVENTIVE | 预防性维护 |
+| | CORRECTIVE | 纠正性维护 |
+| PlanStatus | ACTIVE | 启用 |
+| | INACTIVE | 停用 |
+| | SUSPENDED | 暂停 |
+
+### 2.5 InspectionTemplate（巡检模板）
+
+**表名**: `ops_inspection_template`
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| id | UUID | 是 | 自动生成 | 主键 |
+| templateCode | VARCHAR(50) | 是 | 自动生成 | 模板编码（唯一） |
+| templateName | VARCHAR(200) | 是 | - | 模板名称 |
+| description | VARCHAR(2000) | 否 | - | 描述 |
+| projectId | UUID | 否 | - | 所属项目 |
+| spaceId | UUID | 否 | - | 关联空间 |
+| category | VARCHAR(50) | 否 | - | 分类 |
+| status | ENUM | 否 | ACTIVE | 模板状态 |
+| createdAt | TIMESTAMP | 否 | now() | 创建时间 |
+| updatedAt | TIMESTAMP | 否 | now() | 更新时间 |
+| createdBy | VARCHAR(200) | 否 | - | 创建人 |
+| items | List\<InspectionItem\> | - | - | 检查项列表（@Transient，非持久化） |
+
+**枚举定义**：
+
+| 枚举 | 值 | 中文 |
+|------|-----|------|
+| TemplateStatus | ACTIVE | 启用 |
+| | INACTIVE | 停用 |
+
+### 2.6 InspectionItem（巡检项）
+
+**表名**: `ops_inspection_item`
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| id | UUID | 是 | 自动生成 | 主键 |
+| templateId | UUID | 是 | - | 所属模板ID |
+| itemName | VARCHAR(200) | 是 | - | 检查项名称 |
+| description | VARCHAR(2000) | 否 | - | 描述 |
+| checkMethod | VARCHAR(2000) | 否 | - | 检查方法 |
+| standard | VARCHAR(2000) | 否 | - | 检查标准 |
+| isMandatory | BOOLEAN | 否 | true | 是否必检 |
+| isNormalRequired | BOOLEAN | 否 | true | 是否需要正常判定 |
+| sortOrder | INTEGER | 否 | 0 | 排序序号 |
+| createdAt | TIMESTAMP | 否 | now() | 创建时间 |
+
+### 2.7 实体关系图
+
+```
+MaintenancePlan ──1:N──> MaintenanceTask
+       │                      │
+       │ planId               │ equipmentId
+       ▼                      ▼
+  WorkOrder ──1:N──> WorkOrderItem
+       │
+       │ (关联)
+       ▼
+InspectionTemplate ──1:N──> InspectionItem
+```
+
+**关系说明**：
+
+- WorkOrder.planId → MaintenancePlan.id（工单可关联维保计划）
+- WorkOrderItem.workOrderId → WorkOrder.id（工单明细属于工单）
+- MaintenanceTask.planId → MaintenancePlan.id（维保任务由计划触发）
+- InspectionItem.templateId → InspectionTemplate.id（检查项属于模板）
+- WorkOrder 与 MaintenanceTask 为独立实体，无直接外键关联
+
+---
+
+## 三、API 接口设计
+
+### 3.1 WorkOrderController
+
+**基础路径**: `/api/wo/work-orders`
+
+| 方法 | 路径 | 说明 | 请求体 | 响应 |
+|------|------|------|--------|------|
+| POST | / | 创建工单 | WorkOrder | WorkOrder |
+| GET | / | 查询工单列表 | QueryParams | List\<WorkOrder\> |
+| GET | /{id} | 获取工单详情 | - | WorkOrder |
+| PUT | /{id} | 更新工单 | WorkOrder | WorkOrder |
+| DELETE | /{id} | 删除工单 | - | Void |
+| POST | /{id}/assign | 派单 | AssignRequest | WorkOrder |
+| POST | /{id}/start | 开始执行 | - | WorkOrder |
+| POST | /{id}/complete | 完成工单 | WorkOrder | WorkOrder |
+| POST | /{id}/verify | 验收工单 | VerifyRequest | WorkOrder |
+| POST | /{id}/cancel | 取消工单 | - | WorkOrder |
+| GET | /stats | 工单统计 | - | WorkOrderStatsDTO |
+| GET | /{id}/items | 获取工单明细 | - | List\<WorkOrderItem\> |
+| POST | /{id}/items | 批量添加工单明细 | List\<WorkOrderItem\> | WorkOrder |
+
+**查询参数**（GET /）：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| projectId | UUID | 否 | 按项目筛选 |
+| equipmentId | UUID | 否 | 按设备筛选 |
+| source | Enum | 否 | 按来源筛选 |
+| type | Enum | 否 | 按类型筛选 |
+| status | Enum | 否 | 按状态筛选 |
+| assignedTo | String | 否 | 按负责人筛选 |
+
+> 注意：查询参数互斥，按优先级 projectId > equipmentId > source > type > status > assignedTo 依次判断
+
+**请求体定义**：
+
+```java
+// 派单请求
+AssignRequest {
+    String assignedTo;       // 负责人
+    String assignedVendor;   // 服务商
+    LocalDate assignedDate;  // 派单日期
+}
+
+// 验收请求
+VerifyRequest {
+    String verifiedBy;  // 验收人
+    String remark;      // 备注
+    Integer rating;     // 评分（1-5）
+}
+```
+
+**WorkOrderStatsDTO**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| total | long | 工单总数 |
+| pending | long | 待分配数 |
+| assigned | long | 已派单数 |
+| inProgress | long | 执行中数 |
+| completed | long | 已完成数 |
+| verified | long | 已验收数 |
+| cancelled | long | 已取消数 |
+| completedToday | long | 今日完成数 |
+| createdToday | long | 今日创建数 |
+| overdue | long | 逾期数 |
+| avgCompleteHours | BigDecimal | 平均完成工时 |
+| avgRating | BigDecimal | 平均评分 |
+| bySource | Map\<String, Long\> | 按来源分布 |
+| byType | Map\<String, Long\> | 按类型分布 |
+| byPriority | Map\<String, Long\> | 按优先级分布 |
+
+### 3.2 MaintenanceTaskController
+
+**基础路径**: `/api/ops/maintenance-tasks`
+
+| 方法 | 路径 | 说明 | 请求体 | 响应 |
+|------|------|------|--------|------|
+| POST | / | 创建维保任务 | MaintenanceTask | MaintenanceTask |
+| GET | / | 查询维保任务列表 | QueryParams | List\<MaintenanceTask\> |
+| GET | /{id} | 获取任务详情 | - | MaintenanceTask |
+| PUT | /{id} | 更新任务 | MaintenanceTask | MaintenanceTask |
+| DELETE | /{id} | 删除任务 | - | Void |
+| POST | /{id}/assign | 分配任务 | AssignRequest | MaintenanceTask |
+| POST | /{id}/start | 开始执行 | - | MaintenanceTask |
+| POST | /{id}/complete | 完成任务（简版） | CompleteRequest | MaintenanceTask |
+| POST | /{id}/complete-details | 完成任务（详版） | MaintenanceTask | MaintenanceTask |
+| POST | /{id}/verify | 验收任务 | VerifyRequest | MaintenanceTask |
+| POST | /{id}/cancel | 取消任务 | - | MaintenanceTask |
+| POST | /{id}/rate | 评分 | rating (query) | MaintenanceTask |
+| GET | /stats | 任务统计 | - | MaintenanceTaskStatsDTO |
+
+**查询参数**（GET /）：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| equipmentId | UUID | 否 | 按设备筛选 |
+| planId | UUID | 否 | 按计划筛选 |
+| status | Enum | 否 | 按状态筛选 |
+| priority | Enum | 否 | 按优先级筛选 |
+| assignedTo | String | 否 | 按负责人筛选 |
+| overdueDate | LocalDate | 否 | 逾期截止日期 |
+
+> 同样互斥优先级：equipmentId > planId > status > priority > assignedTo > overdueDate
+
+**请求体定义**：
+
+```java
+// 分配请求
+AssignRequest {
+    String assignedTo;       // 负责人
+    LocalDate assignedDate;  // 派单日期
+}
+
+// 完成请求（简版）
+CompleteRequest {
+    String result;            // 处理结果
+    BigDecimal actualHours;   // 实际工时
+    BigDecimal cost;          // 总费用
+    String completedBy;       // 完成人
+}
+
+// 验收请求
+VerifyRequest {
+    String verifiedBy;  // 验收人
+    String remark;      // 备注
+    Integer rating;     // 评分
+}
+```
+
+**MaintenanceTaskStatsDTO**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| total | long | 任务总数 |
+| pending | long | 待分配数 |
+| assigned | long | 已派单数 |
+| inProgress | long | 执行中数 |
+| completed | long | 已完成数 |
+| verified | long | 已验收数 |
+| cancelled | long | 已取消数 |
+| completedToday | long | 今日完成数 |
+| createdToday | long | 今日创建数 |
+| overdue | long | 逾期数 |
+| avgCompleteHours | BigDecimal | 平均完成工时 |
+| avgRating | BigDecimal | 平均评分 |
+| byPriority | Map\<String, Long\> | 按优先级分布 |
+| byTriggerType | Map\<String, Long\> | 按触发类型分布 |
+| totalLaborCost | BigDecimal | 人工费总计 |
+| totalPartsCost | BigDecimal | 备件费总计 |
+| totalCost | BigDecimal | 费用总计 |
+
+### 3.3 前端独立 API（无后端 Controller 对应）
+
+以下前端 API 存在但后端无对应 Controller 实现：
+
+| 前端文件 | API 路径 | 说明 |
+|----------|----------|------|
+| maintenance-plan.ts | /api/mdm/maintenance-plans | 维保计划 CRUD（归属 MDM 域） |
+| maintenance.ts | /api/ops/maintenance-plans | 维保计划 CRUD（另一套，含 accept 操作） |
+| maintenance.ts | /api/ops/maintenance-tasks | 维保任务（含 accept 操作，状态含 ACCEPTED） |
+| inspection-template.ts | /api/ops/inspection-templates | 巡检模板 CRUD |
+| inspection-item.ts | /api/mdm/inspection-items | 巡检标准项 CRUD（归属 MDM 域） |
+| inspection-record.ts | /api/mdm/inspection-records | 巡检记录 CRUD（归属 MDM 域） |
+
+---
+
+## 四、业务规则
+
+### 4.1 工单状态机
+
+```
+┌─────────────┐
+│   PENDING   │ ← 创建工单（默认状态）
+│   (待分配)   │
+└──────┬──────┘
+       │ 派单 (assign)
+       ▼
+┌─────────────┐
+│  ASSIGNED   │ ← 分配负责人/服务商
+│   (已派单)   │
+└──────┬──────┘
+       │ 开始执行 (start)
+       ▼
+┌─────────────┐
+│ IN_PROGRESS │ ← 记录实际开始时间
+│   (执行中)   │
+└──────┬──────┘
+       │ 完成 (complete)
+       ▼
+┌─────────────┐
+│  COMPLETED  │ ← 记录故障原因/解决方案/费用
+│   (已完成)   │
+└──────┬──────┘
+       │ 验收 (verify)
+       ▼
+┌─────────────┐
+│  VERIFIED   │ ← 记录验收人/评分/备注
+│   (已验收)   │
+└─────────────┘
+
+特殊状态:
+- CANCELLED (已取消): PENDING/ASSIGNED/IN_PROGRESS 可转入
+```
+
+**状态流转规则**：
+
+| 当前状态 | 允许操作 | 下一状态 | 前置条件 | 自动处理 |
+|---------|---------|---------|---------|---------|
+| PENDING | 派单 | ASSIGNED | - | 设置 assignedTo/assignedVendor/assignedDate |
+| ASSIGNED | 开始执行 | IN_PROGRESS | - | 设置 actualStart = now() |
+| IN_PROGRESS | 完成 | COMPLETED | - | 设置 actualEnd = now()，自动计算 actualHours |
+| COMPLETED | 验收 | VERIFIED | - | 设置 verifiedBy/verifiedDate/rating |
+| PENDING/ASSIGNED/IN_PROGRESS | 取消 | CANCELLED | - | - |
+| COMPLETED/VERIFIED | 取消 | ❌ 不允许 | - | 抛出异常"无法取消已完成的工单" |
+
+**工单编号生成规则**：`WO-YYYYMMDD-XXXX`（4位序号，按日期递增）
+
+**完成工单自动计算工时**：
+
+```java
+actualHours = Duration.between(actualStart, actualEnd).toMinutes() / 60.0
+```
+
+### 4.2 维保任务状态机
+
+```
+┌─────────────┐
+│   PENDING   │ ← 创建任务（默认状态）
+│   (待分配)   │
+└──────┬──────┘
+       │ 分配 (assign)
+       ▼
+┌─────────────┐
+│  ASSIGNED   │ ← 指定负责人
+│   (已派单)   │
+└──────┬──────┘
+       │ 开始执行 (start)
+       ▼
+┌─────────────┐
+│ IN_PROGRESS │ ← 记录实际开始时间
+│   (执行中)   │
+└──────┬──────┘
+       │ 完成 (complete / complete-details)
+       ▼
+┌─────────────┐
+│  COMPLETED  │ ← 记录执行详情/费用/备件
+│   (已完成)   │
+└──────┬──────┘
+       │ 验收 (verify)
+       ▼
+┌─────────────┐
+│  VERIFIED   │ ← 记录验收人/评分
+│   (已验收)   │
+└─────────────┘
+
+特殊状态:
+- CANCELLED (已取消): PENDING/ASSIGNED/IN_PROGRESS 可转入
+```
+
+**与工单状态机的差异**：
+
+| 差异点 | WorkOrder | MaintenanceTask |
+|--------|-----------|-----------------|
+| 完成方式 | 仅一种 complete | 两种：complete（简版）+ complete-details（详版） |
+| 评分方式 | 验收时评分 | 验收时评分 + 独立 rate 接口 |
+| 取消条件 | COMPLETED/VERIFIED 不可取消 | 同 |
+| 删除行为 | 物理删除 | 逻辑删除（设为 CANCELLED） |
+| 完成后联动 | 无 | 自动更新设备维保记录（maintenanceVendor/nextInspectionDate） |
+
+**任务编号生成规则**：`EQ-YYYYMMDD-XXXX`（4位序号，按日期递增）
+
+### 4.3 维保任务触发机制
+
+| 触发类型 | 枚举值 | 说明 | 优先级自动判定规则 |
+|---------|--------|------|-------------------|
+| 计划触发 | PLAN | 由维保计划周期性触发 | MEDIUM |
+| 巡检触发 | INSPECTION | 巡检发现异常时触发 | HIGH |
+| 故障触发 | FAULT | 设备故障时触发 | HIGH（含紧急关键词时 URGENT） |
+| 手动创建 | MANUAL | 人工手动创建 | MEDIUM |
+
+**自动优先级判定规则**（MaintenanceTaskServiceImpl.autoDeterminePriority）：
+
+```
+1. 紧急维修类型(EMERGENCY) → URGENT
+2. 故障触发(FAULT) + 紧急关键词 → URGENT
+   紧急关键词: 困人/漏水/停电/火灾/爆炸/漏电/冒烟/故障停机
+3. 故障触发(FAULT) 无紧急关键词 → HIGH
+4. 巡检触发(INSPECTION) → HIGH
+5. 计划触发(PLAN) → MEDIUM
+6. 其他 → MEDIUM
+```
+
+### 4.4 维保计划管理规则
+
+| 规则 | 说明 |
+|------|------|
+| 计划状态 | ACTIVE（启用）/ INACTIVE（停用）/ SUSPENDED（暂停） |
+| 删除行为 | 逻辑删除，将状态设为 INACTIVE |
+| 周期调度 | 通过 cycleDays 计算下次执行日期（nextDate） |
+| 计划类型 | PREVENTIVE（预防性）/ CORRECTIVE（纠正性） |
+
+### 4.5 巡检模板管理规则
+
+| 规则 | 说明 |
+|------|------|
+| 模板状态 | ACTIVE（启用）/ INACTIVE（停用） |
+| 检查项关联 | InspectionItem 通过 templateId 关联模板 |
+| 必检项 | isMandatory = true 的检查项不可跳过 |
+| 正常判定 | isNormalRequired = true 的检查项需要判定正常/异常 |
+| 排序 | 通过 sortOrder 控制检查项顺序 |
+
+### 4.6 工单明细管理规则
+
+| 规则 | 说明 |
+|------|------|
+| 明细类型 | PART（备件）/ INSPECTION_ITEM（巡检项）/ CHECKPOINT（检查点） |
+| 批量添加 | 支持批量添加，受 BatchOperationValidator 限制 |
+| 费用计算 | 前端计算：totalPrice = quantity × unitPrice，partsCost = Σ totalPrice |
+| 总费用 | totalCost = laborCost + partsCost |
+
+### 4.7 维保任务完成后联动
+
+维保任务完成（completeTaskWithDetails）时自动更新设备信息：
+
+```
+1. 更新设备维保商: equipment.maintenanceVendor = task.assignedVendor
+2. 更新下次巡检日期（仅预防性维护）:
+   equipment.nextInspectionDate = now() + equipment.inspectionCycle
+   默认周期: 30天
+3. 异常容错: 更新设备失败不影响工单完成
+```
+
+---
+
+## 五、前端操作流程
+
+### 5.1 工单管理（WorkOrder.vue）
+
+**页面路径**: /ops/work-order
+
+**操作流程**：
+
+```
+1. 选择项目 → 加载工单列表
+2. 筛选: 项目/来源/类型/状态/优先级/关键词
+3. 查看统计卡片: 总工单/待分配/执行中/今日完成/逾期/平均评分
+4. 工单操作:
+   ├─ 新建工单 → 填写来源/类型/优先级/标题/描述/负责人/服务商
+   ├─ 查看详情 → 抽屉展示: 基本信息/问题描述/派单信息/执行信息/工单项/费用/验收
+   ├─ 编辑工单 → 修改基本信息
+   ├─ 派单 → 指定负责人/服务商/派单日期（PENDING → ASSIGNED）
+   ├─ 开始执行 → 确认弹窗（ASSIGNED → IN_PROGRESS）
+   ├─ 完成工单 → 填写工时/故障原因/解决方案/结果/工单项/费用（IN_PROGRESS → COMPLETED）
+   ├─ 验收工单 → 填写验收人/评分/备注（COMPLETED → VERIFIED）
+   ├─ 取消工单 → 确认弹窗（PENDING/ASSIGNED/IN_PROGRESS → CANCELLED）
+   └─ 删除工单 → 确认弹窗
+```
+
+**完成工单时的工单项录入**：
+
+```
+添加工单项:
+  ├─ 选择类型: 备件/巡检项/检查点
+  ├─ 输入名称
+  ├─ 输入数量 + 单价 → 自动计算 totalPrice
+  └─ 自动汇总: partsCost = Σ(各工单项totalPrice)
+                 totalCost = laborCost + partsCost
+```
+
+**前端状态颜色映射**：
+
+| 状态 | 颜色 | 优先级 | 颜色 |
+|------|------|--------|------|
+| PENDING | default (灰) | LOW | green |
+| ASSIGNED | blue | MEDIUM | blue |
+| IN_PROGRESS | orange | HIGH | orange |
+| COMPLETED | green | URGENT | red |
+| VERIFIED | cyan | | |
+| CANCELLED | red | | |
+
+### 5.2 维保计划（PlanList.vue）
+
+**页面路径**: /maintenance/plans
+
+> 注意：此页面使用 `maintenance.ts` API（/api/ops/maintenance-plans），与后端 MaintenancePlan 实体对应的是 `maintenance-plan.ts` API（/api/mdm/maintenance-plans），存在两套前端实现
+
+**操作流程**：
+
+```
+1. 选择项目 → 加载维保计划列表
+2. 筛选: 项目/触发类型
+3. 计划操作:
+   ├─ 新建计划 → 填写名称/项目/触发类型/Cron表达式/描述/启用状态
+   ├─ 编辑计划 → 修改计划信息
+   └─ 停用计划 → 确认弹窗（逻辑删除）
+```
+
+**前端触发类型**（与后端不一致）：
+
+| 前端枚举 | 中文 | 后端枚举 | 差异 |
+|---------|------|---------|------|
+| MANUAL | 手动 | - | 前端独有 |
+| SCHEDULED | 定时 | - | 前端独有 |
+| AUTOMATIC | 自动 | - | 前端独有 |
+| - | - | PLAN | 后端独有 |
+| - | - | INSPECTION | 后端独有 |
+| - | - | FAULT | 后端独有 |
+| - | - | MANUAL | 后端有但含义不同 |
+
+### 5.3 维保任务（TaskList.vue）
+
+**页面路径**: /maintenance/tasks
+
+> 注意：此页面使用 `maintenance.ts` API，状态包含 ACCEPTED，与后端 MaintenanceTaskController 的6状态不一致
+
+**操作流程**：
+
+```
+1. 选择项目 → 加载维保任务列表
+2. 筛选: 项目/状态/负责人
+3. 任务操作:
+   ├─ 接受任务 → PENDING → ACCEPTED（前端独有状态）
+   ├─ 开始任务 → ACCEPTED → IN_PROGRESS
+   ├─ 完成任务 → 弹窗输入完成备注 → IN_PROGRESS → COMPLETED
+   └─ 取消任务 → 确认弹窗
+```
+
+**前端状态映射**（与后端不一致）：
+
+| 前端状态 | 中文 | 后端状态 | 差异 |
+|---------|------|---------|------|
+| PENDING | 待接受 | PENDING (待分配) | 含义不同 |
+| ACCEPTED | 已接受 | - | 前端独有 |
+| IN_PROGRESS | 进行中 | IN_PROGRESS | 一致 |
+| COMPLETED | 已完成 | COMPLETED | 一致 |
+| CANCELLED | 已取消 | CANCELLED | 一致 |
+| - | - | ASSIGNED | 后端独有 |
+| - | - | VERIFIED | 后端独有 |
+
+### 5.4 点检模板管理（TemplateList.vue）
+
+**页面路径**: /inspection/templates
+
+**操作流程**：
+
+```
+1. 选择项目 → 加载模板列表
+2. 模板操作:
+   ├─ 新建模板 → 填写名称/设备类型/项目/启用状态 + 添加点检项目
+   ├─ 编辑模板 → 修改模板信息 + 编辑点检项目
+   ├─ 复制模板 → 创建副本（名称加"_副本"后缀）
+   └─ 删除模板 → 确认弹窗
+
+添加点检项目:
+  ├─ 输入项目名称
+  ├─ 输入检查方法
+  ├─ 输入检查标准
+  ├─ 设置是否必检
+  └─ 添加到列表
+```
+
+**前端设备类型选项**（中文，与后端 category 字段不一致）：
+
+电梯/消防设备/空调/给排水/配电/安防/其他
+
+### 5.5 前端页面与 API 对照表
+
+| 页面 | 前端文件 | API 文件 | 后端 Controller | API 基础路径 |
+|------|---------|----------|----------------|-------------|
+| 工单管理 | WorkOrder.vue | work-order.ts | WorkOrderController | /api/wo/work-orders |
+| 维保计划 | PlanList.vue | maintenance.ts | ❌ 无对应 | /api/ops/maintenance-plans |
+| 维保任务 | TaskList.vue | maintenance.ts | MaintenanceTaskController | /api/ops/maintenance-tasks |
+| 点检模板 | TemplateList.vue | inspection-template.ts | ❌ 无对应 | /api/ops/inspection-templates |
+
+---
+
+## 六、与原需求文档 02-OPERATIONS.md 的差异对比
+
+### 6.1 状态机差异（核心差异）
+
+| 对比项 | 需求文档 | 实际实现 | 差异分析 |
+|--------|----------|----------|----------|
+| **工单初始状态** | CREATED（已创建） | PENDING（待分配） | 实现简化，合并创建与待分配 |
+| **接单状态** | ACCEPTED（已接单） | ❌ 不存在 | 实现中 ASSIGNED 直接进入 IN_PROGRESS，省略接单环节 |
+| **关闭状态** | CLOSED（已关闭） | ❌ 不存在 | 实现用 VERIFIED（已验收）替代关闭 |
+| **验收状态** | ❌ 不存在 | VERIFIED（已验收） | 实现新增，强调验收确认环节 |
+| **挂起状态** | SUSPENDED（已挂起） | ❌ 不存在 | 实现未支持挂起/恢复 |
+| **退回状态** | RETURNED（已退回） | ❌ 不存在 | 实现未支持退回重分配 |
+| **取消状态** | ❌ 未提及 | CANCELLED（已取消） | 实现新增，支持工单取消 |
+
+**状态机对比图**：
+
+```
+需求文档:  CREATED → ASSIGNED → ACCEPTED → IN_PROGRESS → COMPLETED → CLOSED
+           + SUSPENDED（任意状态可挂起）
+           + RETURNED（ASSIGNED 可退回）
+
+实际实现:  PENDING → ASSIGNED → IN_PROGRESS → COMPLETED → VERIFIED
+           + CANCELLED（PENDING/ASSIGNED/IN_PROGRESS 可取消）
+```
+
+### 6.2 实体差异
+
+| 对比项 | 需求文档 | 实际实现 | 差异分析 |
+|--------|----------|----------|----------|
+| **WorkOrderFlow** | 有（工单流转记录） | ❌ 不存在 | 实现未记录流转历史 |
+| **NotificationChannel** | 有（通知渠道） | ❌ 不存在 | 消息通知系统未实现 |
+| **NotificationTemplate** | 有（消息模板） | ❌ 不存在 | 消息通知系统未实现 |
+| **NotificationRule** | 有（通知规则） | ❌ 不存在 | 消息通知系统未实现 |
+| **NotificationHistory** | 有（通知历史） | ❌ 不存在 | 消息通知系统未实现 |
+| **WorkOrderItem** | ❌ 不存在 | 有（工单明细） | 实现新增，支持备件/巡检项/检查点 |
+| **MaintenancePlan** | ❌ 不存在 | 有（维保计划） | 实现新增，支持周期性维保调度 |
+| **MaintenanceTask** | ❌ 不存在 | 有（维保任务） | 实现新增，独立于 WorkOrder 的维保工单 |
+| **InspectionTemplate** | ❌ 不存在 | 有（巡检模板） | 实现新增，支持点检模板管理 |
+| **InspectionItem** | ❌ 不存在 | 有（巡检项） | 实现新增，模板下的检查项 |
+
+### 6.3 字段差异（WorkOrder）
+
+| 字段 | 需求文档 | 实际实现 | 差异分析 |
+|------|----------|----------|----------|
+| orderNo | WO2024021000001 | workNo: WO-YYYYMMDD-XXXX | 编号格式不同，实现用连字符分隔 |
+| orderType | REPAIR/COMPLAINT/CLEANING/SECURITY/OTHER | type: REPAIR/INSPECTION/SECURITY/CLEANING/PROPERTY/CONSULTATION | 枚举值完全不同 |
+| source | APP/PHONE/INSPECTION/IOT/SYSTEM | OWNER/MAINTENANCE/INSPECTION/FAULT/REGULATORY/MANUAL | 枚举值完全不同 |
+| reporterId/reporterName/reporterPhone/reporterAddress | 有 | ❌ 不存在 | 实现无报修人信息 |
+| assigneeId/assigneeName | UUID引用 | assignedTo: String | 实现用字符串而非用户ID引用 |
+| acceptedAt/startedAt/completedAt/closedAt | 有 | actualStart/actualEnd/completedDate/verifiedDate | 字段名和粒度不同 |
+| materialCost | 有 | partsCost | 字段名不同 |
+| resultDescription | 有 | result + faultCause + solution | 实现拆分为3个字段 |
+| satisfactionScore/satisfactionComment | 有 | rating + remark | 实现简化，无评论字段 |
+| images/attachments | String | photos: JSONB (List\<String\>) | 实现用JSONB数组 |
+| attributes | JSONB | ❌ 不存在 | 实现无扩展属性 |
+| spaceNodeId | 有 | spaceId | 字段名不同 |
+| planId/triggerType | ❌ 不存在 | 有 | 实现新增，关联维保计划 |
+| assignedVendor | ❌ 不存在 | 有 | 实现新增，支持服务商 |
+| laborCost/partsCost/totalCost | ❌ 不存在 | 有 | 实现新增，费用明细 |
+| signature | ❌ 不存在 | 有 | 实现新增，签名确认 |
+
+### 6.4 API 差异
+
+| 对比项 | 需求文档 | 实际实现 | 差异分析 |
+|--------|----------|----------|----------|
+| API 版本 | /api/v1/ops/work-orders | /api/wo/work-orders | 路径不同，实现无版本号 |
+| 分页查询 | Page\<WorkOrderVO\> | List\<WorkOrder\> | 实现无分页，全量返回 |
+| 接单接口 | POST /{id}/accept | ❌ 不存在 | 无 ACCEPTED 状态 |
+| 关闭接口 | POST /{id}/close | ❌ 不存在 | 用 verify 替代 |
+| 挂起/恢复 | POST /{id}/suspend, /{id}/resume | ❌ 不存在 | 未实现 |
+| 退回 | ❌ 不存在 | ❌ 不存在 | 需求有但实现无 |
+| 流转记录 | GET /{id}/flows | ❌ 不存在 | 未实现 WorkOrderFlow |
+| 通知 API | 完整的渠道/模板/规则/历史 | ❌ 不存在 | 消息通知系统未实现 |
+| 统计 API | 独立 Controller，多维度 | GET /stats（嵌入工单 Controller） | 实现简化 |
+| 工单明细 | ❌ 不存在 | GET/POST /{id}/items | 实现新增 |
+| 维保任务 API | ❌ 不存在 | 完整的 CRUD + 状态流转 | 实现新增 |
+
+### 6.5 业务规则差异
+
+| 对比项 | 需求文档 | 实际实现 | 差异分析 |
+|--------|----------|----------|----------|
+| 工单编号格式 | WO + yyyyMMdd + 5位序号 | WO-YYYYMMDD-XXXX（4位） | 格式不同 |
+| 通知触发 | 工单状态变更自动触发通知 | ❌ 无通知 | 消息通知未实现 |
+| SLA 监控 | 提及但未实现 | ❌ 未实现 | 均未实现 |
+| 智能派单 | 提及但未实现 | ❌ 未实现 | 均未实现 |
+| 维保优先级自动判定 | ❌ 未提及 | 有（基于触发类型+关键词） | 实现新增 |
+| 设备联动更新 | ❌ 未提及 | 有（完成维保后更新设备记录） | 实现新增 |
+| 维保任务双完成接口 | ❌ 未提及 | complete + complete-details | 实现新增，简版/详版 |
+| 删除策略 | 未明确 | WorkOrder 物理删除，MaintenanceTask 逻辑删除 | 不一致 |
+
+### 6.6 前端实现差异
+
+| 对比项 | 需求文档 | 实际实现 | 差异分析 |
+|--------|----------|----------|----------|
+| 维保计划 API | 单一 | 两套（maintenance.ts + maintenance-plan.ts） | 前端分裂 |
+| 维保计划触发类型 | - | MANUAL/SCHEDULED/AUTOMATIC vs PLAN/INSPECTION/FAULT/MANUAL | 前后端不一致 |
+| 维保任务状态 | - | 前端含 ACCEPTED，后端含 ASSIGNED/VERIFIED | 前后端不一致 |
+| 巡检模板 | ❌ 未提及 | 有（inspection-template.ts + TemplateList.vue） | 实现新增 |
+| 巡检标准项 | ❌ 未提及 | 有（inspection-item.ts，归属 MDM 域） | 实现新增 |
+| 巡检记录 | ❌ 未提及 | 有（inspection-record.ts，归属 MDM 域） | 实现新增 |
+
+### 6.7 差异总结
+
+| 类别 | 需求文档有/实现无 | 实现有/需求文档无 | 说明 |
+|------|-----------------|-----------------|------|
+| 状态 | CREATED, ACCEPTED, CLOSED, SUSPENDED, RETURNED | VERIFIED, CANCELLED | 状态机完全重构 |
+| 实体 | WorkOrderFlow, NotificationChannel/Template/Rule/History | WorkOrderItem, MaintenancePlan/Task, InspectionTemplate/Item | 实体体系完全不同 |
+| 功能 | 消息通知系统, 工单流转记录 | 维保计划/任务, 巡检模板, 工单明细 | 功能重心偏移 |
+| 字段 | 报修人信息, 扩展属性 | 服务商, 费用明细, 签名, 触发类型 | 字段侧重不同 |
+
+> **核心结论**: 实际实现与需求文档是两套不同的设计方案。需求文档侧重"运营调度+消息通知"，实际实现侧重"运维工单+维保管理+巡检模板"。状态机从7状态简化为6状态，去掉了接单/挂起/退回环节，新增了验收/取消环节。消息通知系统完全未实现，但新增了维保计划/任务/巡检模板等需求文档未涵盖的功能。