ether
/
ether-docs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: 更新功能清单

This commit is contained in:
chiguyong 2026-04-26 18:52:35 +08:00
parent 5f016436c9
commit 5619e6943b
8 changed files with 5472 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

198
01-REQUIREMENTS/FEATURE_LIST.md
View File

@ -25,29 +25,29 @@
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------- | -------------------- | --------- | --------------------------- | ------- | | ------- | -------------------- | --------- | --------------------------- | ------- |
| APP-O01 | 项目初始化与框架搭建 | ✅ 已完成 | uni-app项目初始化、基础配置 | - | | APP-O01 | 项目初始化与框架搭建 | ⬜ 待开发 | uni-app项目初始化、基础配置 | - |
| APP-O02 | 微信登录授权 | ✅ 已完成 | 微信授权登录、OpenID获取 | APP-O01 | | APP-O02 | 微信登录授权 | ⬜ 待开发 | 微信授权登录、OpenID获取 | APP-O01 |
| APP-O03 | 手机号绑定 | ✅ 已完成 | 手机号验证、绑定流程 | APP-O02 | | APP-O03 | 手机号绑定 | ⬜ 待开发 | 手机号验证、绑定流程 | APP-O02 |
| APP-O04 | 房产绑定认证 | ✅ 已完成 | 房产证认证、人脸认证 | APP-O03 | | APP-O04 | 房产绑定认证 | ⬜ 待开发 | 房产证认证、人脸认证 | APP-O03 |
| APP-O05 | 首页展示 | ✅ 已完成 | 待办事项、快捷入口、公告 | APP-O04 | | APP-O05 | 首页展示 | ⬜ 待开发 | 待办事项、快捷入口、公告 | APP-O04 |
| APP-O06 | 在线报修申请 | ✅ 已完成 | 报修表单、图片上传 | APP-O04 | | APP-O06 | 在线报修申请 | ⬜ 待开发 | 报修表单、图片上传 | APP-O04 |
| APP-O07 | 工单进度查询 | ✅ 已完成 | 工单状态、处理进度 | APP-O06 | | APP-O07 | 工单进度查询 | ⬜ 待开发 | 工单状态、处理进度 | APP-O06 |
| APP-O08 | 工单历史记录 | ✅ 已完成 | 历史工单列表、详情 | APP-O06 | | APP-O08 | 工单历史记录 | ⬜ 待开发 | 历史工单列表、详情 | APP-O06 |
| APP-O09 | 账单查询 | ✅ 已完成 | 账单列表、账单详情 | APP-O04 | | APP-O09 | 账单查询 | ⬜ 待开发 | 账单列表、账单详情 | APP-O04 |
| APP-O10 | 微信支付对接 | ⬜ 待开发 | 微信支付API对接 | APP-O09 | | APP-O10 | 微信支付对接 | ⬜ 待开发 | 微信支付API对接 | APP-O09 |
| APP-O11 | 支付宝支付对接 | ⬜ 待开发 | 支付宝支付API对接 | APP-O10 | | APP-O11 | 支付宝支付对接 | ⬜ 待开发 | 支付宝支付API对接 | APP-O10 |
| APP-O12 | 缴费记录查询 | ✅ 已完成 | 缴费历史、凭证查看 | APP-O09 | | APP-O12 | 缴费记录查询 | ⬜ 待开发 | 缴费历史、凭证查看 | APP-O09 |
| APP-O13 | 访客邀请 | ✅ 已完成 | 邀请表单、被访人确认 | APP-O04 | | APP-O13 | 访客邀请 | ⬜ 待开发 | 邀请表单、被访人确认 | APP-O04 |
| APP-O14 | 访客凭证生成 | ✅ 已完成 | 二维码生成、凭证展示 | APP-O13 | | APP-O14 | 访客凭证生成 | ⬜ 待开发 | 二维码生成、凭证展示 | APP-O13 |
| APP-O15 | 访客邀请记录 | ✅ 已完成 | 邀请历史、状态查询 | APP-O13 | | APP-O15 | 访客邀请记录 | ⬜ 待开发 | 邀请历史、状态查询 | APP-O13 |
| APP-O16 | 投诉建议提交 | ✅ 已完成 | 投诉表单、图片上传 | APP-O04 | | APP-O16 | 投诉建议提交 | ⬜ 待开发 | 投诉表单、图片上传 | APP-O04 |
| APP-O17 | 投诉处理进度 | ✅ 已完成 | 处理状态、结果反馈 | APP-O16 | | APP-O17 | 投诉处理进度 | ⬜ 待开发 | 处理状态、结果反馈 | APP-O16 |
| APP-O18 | 消息通知中心 | ✅ 已完成 | 消息列表、已读未读 | APP-O04 | | APP-O18 | 消息通知中心 | ⬜ 待开发 | 消息列表、已读未读 | APP-O04 |
| APP-O19 | 物业公告查看 | ✅ 已完成 | 公告列表、详情查看 | APP-O04 | | APP-O19 | 物业公告查看 | ⬜ 待开发 | 公告列表、详情查看 | APP-O04 |
| APP-O20 | 个人中心 | ✅ 已完成 | 个人信息、设置入口 | APP-O04 | | APP-O20 | 个人中心 | ⬜ 待开发 | 个人信息、设置入口 | APP-O04 |
| APP-O21 | 家庭成员管理 | ✅ 已完成 | 成员添加、权限设置 | APP-O20 | | APP-O21 | 家庭成员管理 | ⬜ 待开发 | 成员添加、权限设置 | APP-O20 |
| APP-O22 | 消息设置 | ✅ 已完成 | 推送开关、通知偏好 | APP-O20 | | APP-O22 | 消息设置 | ⬜ 待开发 | 推送开关、通知偏好 | APP-O20 |
| APP-O23 | 工单满意度评价 | ✅ 已完成 | 评分、评价内容提交 | APP-O06 | | APP-O23 | 工单满意度评价 | ⬜ 待开发 | 评分、评价内容提交 | APP-O06 |
### 1.2 在线支付集成 ### 1.2 在线支付集成
@ -61,17 +61,17 @@
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------ | ---------------- | --------- | ---------------------- | ------ | | ------ | ---------------- | --------- | ---------------------- | ------ |
| P1-020 | 账单导出Excel | ✅ 已完成 | 按条件导出账单列表 | - | | P1-020 | 账单导出Excel | ⬜ 待开发 | 按条件导出账单列表 | - |
| P1-021 | 收费统计报表导出 | ✅ 已完成 | 收费汇总、欠费统计导出 | P1-020 | | P1-021 | 收费统计报表导出 | ⬜ 待开发 | 收费汇总、欠费统计导出 | P1-020 |
| P1-022 | 业主缴费明细导出 | ✅ 已完成 | 单个业主缴费历史导出 | P1-020 | | P1-022 | 业主缴费明细导出 | ⬜ 待开发 | 单个业主缴费历史导出 | P1-020 |
### 1.4 工单满意度评价 ### 1.4 工单满意度评价
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------ | ------------------ | --------- | -------------------- | ------ | | ------ | ------------------ | --------- | -------------------- | ------ |
| P1-030 | 评价表单（业主端） | ✅ 已完成 | 满意度评分、评价内容 | P1-001 | | P1-030 | 评价表单（业主端） | ⬜ 待开发 | 满意度评分、评价内容 | P1-001 |
| P1-031 | 评价统计（管理端） | ✅ 已完成 | 满意度统计、评价分析 | P1-030 | | P1-031 | 评价统计（管理端） | ⬜ 待开发 | 满意度统计、评价分析 | P1-030 |
| P1-032 | 满意度报表 | ✅ 已完成 | 满意度趋势、对比分析 | P1-031 | | P1-032 | 满意度报表 | ⬜ 待开发 | 满意度趋势、对比分析 | P1-031 |
--- ---
@ -81,28 +81,28 @@
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------- | -------------------- | --------- | ---------------------------- | ------- | | ------- | -------------------- | --------- | ---------------------------- | ------- |
| APP-E01 | 项目初始化与框架搭建 | ✅ 已完成 | uni-app项目初始化、基础配置 | - | | APP-E01 | 项目初始化与框架搭建 | ⬜ 待开发 | uni-app项目初始化、基础配置 | - |
| APP-E02 | 用户登录 | ✅ 已完成 | 员工账号登录、Token管理 | APP-E01 | | APP-E02 | 用户登录 | ⬜ 待开发 | 员工账号登录、Token管理 | APP-E01 |
| APP-E03 | 工作台首页 | ✅ 已完成 | 待办事项、今日统计、快捷入口 | APP-E02 | | APP-E03 | 工作台首页 | ⬜ 待开发 | 待办事项、今日统计、快捷入口 | APP-E02 |
| APP-E04 | 待办事项展示 | ✅ 已完成 | 待处理工单、待执行巡检 | APP-E03 | | APP-E04 | 待办事项展示 | ⬜ 待开发 | 待处理工单、待执行巡检 | APP-E03 |
| APP-E05 | 工单列表 | ✅ 已完成 | 工单列表、状态筛选 | APP-E02 | | APP-E05 | 工单列表 | ⬜ 待开发 | 工单列表、状态筛选 | APP-E02 |
| APP-E06 | 工单详情 | ✅ 已完成 | 工单详情、处理记录 | APP-E05 | | APP-E06 | 工单详情 | ⬜ 待开发 | 工单详情、处理记录 | APP-E05 |
| APP-E07 | 工单接单 | ✅ 已完成 | 接单确认、状态更新 | APP-E06 | | APP-E07 | 工单接单 | ⬜ 待开发 | 接单确认、状态更新 | APP-E06 |
| APP-E08 | 工单处理 | ✅ 已完成 | 处理记录、照片上传 | APP-E07 | | APP-E08 | 工单处理 | ⬜ 待开发 | 处理记录、照片上传 | APP-E07 |
| APP-E09 | 工单完成 | ✅ 已完成 | 完成确认、结果提交 | APP-E08 | | APP-E09 | 工单完成 | ⬜ 待开发 | 完成确认、结果提交 | APP-E08 |
| APP-E10 | 扫码报修 | ✅ 已完成 | 扫描设备二维码、快速创建工单 | APP-E05 | | APP-E10 | 扫码报修 | ⬜ 待开发 | 扫描设备二维码、快速创建工单 | APP-E05 |
| APP-E11 | 巡检任务列表 | ✅ 已完成 | 任务列表、状态筛选 | APP-E02 | | APP-E11 | 巡检任务列表 | ⬜ 待开发 | 任务列表、状态筛选 | APP-E02 |
| APP-E12 | 巡检任务执行 | ✅ 已完成 | 检查项目、照片上传 | APP-E11 | | APP-E12 | 巡检任务执行 | ⬜ 待开发 | 检查项目、照片上传 | APP-E11 |
| APP-E13 | 巡检扫码签到 | ✅ 已完成 | 扫码签到、位置记录 | APP-E12 | | APP-E13 | 巡检扫码签到 | ⬜ 待开发 | 扫码签到、位置记录 | APP-E12 |
| APP-E14 | 巡检异常上报 | ✅ 已完成 | 异常描述、照片上传 | APP-E12 | | APP-E14 | 巡检异常上报 | ⬜ 待开发 | 异常描述、照片上传 | APP-E12 |
| APP-E15 | 访客登记 | ✅ 已完成 | 身份核验、信息录入 | APP-E02 | | APP-E15 | 访客登记 | ⬜ 待开发 | 身份核验、信息录入 | APP-E02 |
| APP-E16 | 访客凭证验证 | ✅ 已完成 | 扫码验证、通行放行 | APP-E15 | | APP-E16 | 访客凭证验证 | ⬜ 待开发 | 扫码验证、通行放行 | APP-E15 |
| APP-E17 | 通行记录 | ✅ 已完成 | 进出记录、历史查询 | APP-E15 | | APP-E17 | 通行记录 | ⬜ 待开发 | 进出记录、历史查询 | APP-E15 |
| APP-E18 | 消息通知 | ✅ 已完成 | 工单通知、巡检提醒 | APP-E02 | | APP-E18 | 消息通知 | ⬜ 待开发 | 工单通知、巡检提醒 | APP-E02 |
| APP-E19 | 个人中心 | ✅ 已完成 | 个人信息、设置入口 | APP-E02 | | APP-E19 | 个人中心 | ⬜ 待开发 | 个人信息、设置入口 | APP-E02 |
| APP-E20 | 工作统计 | ✅ 已完成 | 工单统计、巡检统计 | APP-E19 | | APP-E20 | 工作统计 | ⬜ 待开发 | 工单统计、巡检统计 | APP-E19 |
| APP-E21 | 离线数据存储 | ✅ 已完成 | 本地缓存、离线操作 | APP-E01 | | APP-E21 | 离线数据存储 | ⬜ 待开发 | 本地缓存、离线操作 | APP-E01 |
| APP-E22 | 地理位置上报 | ✅ 已完成 | 位置获取、定时上报 | APP-E02 | | APP-E22 | 地理位置上报 | ⬜ 待开发 | 位置获取、定时上报 | APP-E02 |
### 2.2 设备二维码功能 ### 2.2 设备二维码功能
@ -137,30 +137,30 @@
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------ | ------------ | --------- | ------------------------ | ------ | | ------ | ------------ | --------- | ------------------------ | ------ |
| P3-001 | 租户信息管理 | ✅ 已完成 | 企业租户基本信息、联系人 | - | | P3-001 | 租户信息管理 | ⬜ 待开发 | 企业租户基本信息、联系人 | - |
| P3-002 | 租赁合同管理 | ✅ 已完成 | 合同签约、续约、终止 | P3-001 | | P3-002 | 租赁合同管理 | ⬜ 待开发 | 合同签约、续约、终止 | P3-001 |
| P3-003 | 合同到期提醒 | ✅ 已完成 | 提前3个月提醒续约 | P3-002 | | P3-003 | 合同到期提醒 | ⬜ 待开发 | 提前3个月提醒续约 | P3-002 |
### 3.2 合同管理 ### 3.2 合同管理
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------ | ------------ | --------- | ------------------------ | ------ | | ------ | ------------ | --------- | ------------------------ | ------ |
| P3-010 | 合同信息管理 | ✅ 已完成 | 合同CRUD、基本信息管理 | - | | P3-010 | 合同信息管理 | ⬜ 待开发 | 合同CRUD、基本信息管理 | - |
| P3-011 | 合同审批流程 | ✅ 已完成 | 提交审批、审批通过/拒绝 | P3-010 | | P3-011 | 合同审批流程 | ⬜ 待开发 | 提交审批、审批通过/拒绝 | P3-010 |
| P3-012 | 合同签订确认 | ✅ 已完成 | 签订日期、生效日期记录 | P3-011 | | P3-012 | 合同签订确认 | ⬜ 待开发 | 签订日期、生效日期记录 | P3-011 |
| P3-013 | 合同费用明细 | ✅ 已完成 | 费用项目、单价、计费方式 | P3-010 | | P3-013 | 合同费用明细 | ⬜ 待开发 | 费用项目、单价、计费方式 | P3-010 |
| P3-014 | 合同变更管理 | ✅ 已完成 | 变更申请、审批、记录 | P3-012 | | P3-014 | 合同变更管理 | ⬜ 待开发 | 变更申请、审批、记录 | P3-012 |
| P3-015 | 合同到期预警 | ✅ 已完成 | 定时任务、到期提醒 | P3-012 | | P3-015 | 合同到期预警 | ⬜ 待开发 | 定时任务、到期提醒 | P3-012 |
| P3-016 | 合同续签功能 | ✅ 已完成 | 续签新合同、关联原合同 | P3-015 | | P3-016 | 合同续签功能 | ⬜ 待开发 | 续签新合同、关联原合同 | P3-015 |
| P3-017 | 合同终止功能 | ✅ 已完成 | 提前终止、费用结算 | P3-012 | | P3-017 | 合同终止功能 | ⬜ 待开发 | 提前终止、费用结算 | P3-012 |
### 3.3 车位管理 ### 3.3 车位管理
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------ | ------------- | --------- | ---------------------- | ------ | | ------ | ------------- | --------- | ---------------------- | ------ |
| P3-020 | 车位信息管理 | ✅ 已完成 | 车位基本信息、状态管理 | - | | P3-020 | 车位信息管理 | ⬜ 待开发 | 车位基本信息、状态管理 | - |
| P3-021 | 车位租赁/出售 | ✅ 已完成 | 车位租赁、出售管理 | P3-020 | | P3-021 | 车位租赁/出售 | ⬜ 待开发 | 车位租赁、出售管理 | P3-020 |
| P3-022 | 车位状态监控 | ✅ 已完成 | 车位使用状态监控 | P3-020 | | P3-022 | 车位状态监控 | ⬜ 待开发 | 车位使用状态监控 | P3-020 |
### 3.4 能耗管理 ### 3.4 能耗管理
@ -222,41 +222,41 @@
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------ | -------------- | --------- | -------------------- | ------ | | ------ | -------------- | --------- | -------------------- | ------ |
| P4-050 | 知识库分类管理 | ✅ 已完成 | 分类树形结构管理 | - | | P4-050 | 知识库分类管理 | ⬜ 待开发 | 分类树形结构管理 | - |
| P4-051 | 知识库文章管理 | ✅ 已完成 | 文章CRUD、发布管理 | P4-050 | | P4-051 | 知识库文章管理 | ⬜ 待开发 | 文章CRUD、发布管理 | P4-050 |
| P4-052 | 知识库搜索功能 | ✅ 已完成 | 关键词搜索、热门文章 | P4-051 | | P4-052 | 知识库搜索功能 | ⬜ 待开发 | 关键词搜索、热门文章 | P4-051 |
### 4.7 公告管理 ### 4.7 公告管理
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------ | ------------ | --------- | -------------------- | ------ | | ------ | ------------ | --------- | -------------------- | ------ |
| P4-060 | 公告发布管理 | ✅ 已完成 | 公告CRUD、发布管理 | - | | P4-060 | 公告发布管理 | ⬜ 待开发 | 公告CRUD、发布管理 | - |
| P4-061 | 公告推送通知 | ✅ 已完成 | 推送通知接口 | P4-060 | | P4-061 | 公告推送通知 | ⬜ 待开发 | 推送通知接口 | P4-060 |
| P4-062 | 公告阅读统计 | ✅ 已完成 | 浏览量统计、阅读分析 | P4-060 | | P4-062 | 公告阅读统计 | ⬜ 待开发 | 浏览量统计、阅读分析 | P4-060 |
### 4.8 投诉建议管理 ### 4.8 投诉建议管理
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------ | ------------ | --------- | -------------------------- | ------ | | ------ | ------------ | --------- | -------------------------- | ------ |
| P4-070 | 投诉建议提交 | ✅ 已完成 | 投诉建议表单提交 | - | | P4-070 | 投诉建议提交 | ⬜ 待开发 | 投诉建议表单提交 | - |
| P4-071 | 投诉处理流程 | ✅ 已完成 | 指派、受理、处理、关闭流程 | P4-070 | | P4-071 | 投诉处理流程 | ⬜ 待开发 | 指派、受理、处理、关闭流程 | P4-070 |
| P4-072 | 投诉统计分析 | ✅ 已完成 | 投诉统计、满意度分析 | P4-071 | | P4-072 | 投诉统计分析 | ⬜ 待开发 | 投诉统计、满意度分析 | P4-071 |
### 4.9 满意度调查 ### 4.9 满意度调查
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------ | -------------- | --------- | ------------------ | ------ | | ------ | -------------- | --------- | ------------------ | ------ |
| P4-080 | 满意度调查创建 | ✅ 已完成 | 调查问卷创建管理 | - | | P4-080 | 满意度调查创建 | ⬜ 待开发 | 调查问卷创建管理 | - |
| P4-081 | 满意度调查回应 | ✅ 已完成 | 用户回应提交 | P4-080 | | P4-081 | 满意度调查回应 | ⬜ 待开发 | 用户回应提交 | P4-080 |
| P4-082 | 满意度统计分析 | ✅ 已完成 | 评分分布、统计报表 | P4-081 | | P4-082 | 满意度统计分析 | ⬜ 待开发 | 评分分布、统计报表 | P4-081 |
### 4.10 问卷调查 ### 4.10 问卷调查
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------ | ------------ | --------- | ------------------ | ------ | | ------ | ------------ | --------- | ------------------ | ------ |
| P4-090 | 问卷创建管理 | ✅ 已完成 | 问卷CRUD、发布管理 | - | | P4-090 | 问卷创建管理 | ⬜ 待开发 | 问卷CRUD、发布管理 | - |
| P4-091 | 问卷回应收集 | ✅ 已完成 | 用户回应提交收集 | P4-090 | | P4-091 | 问卷回应收集 | ⬜ 待开发 | 用户回应提交收集 | P4-090 |
| P4-092 | 问卷结果分析 | ✅ 已完成 | 回应统计、问题分析 | P4-091 | | P4-092 | 问卷结果分析 | ⬜ 待开发 | 回应统计、问题分析 | P4-091 |
## 五、第五阶段特性（智能化升级） ## 五、第五阶段特性（智能化升级）
@ -264,18 +264,18 @@
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------ | ------------ | --------- | -------------------------- | ------ | | ------ | ------------ | --------- | -------------------------- | ------ |
| P5-001 | 位置距离计算 | ✅ 已完成 | 计算维修人员与工单位置距离 | - | | P5-001 | 位置距离计算 | ⬜ 待开发 | 计算维修人员与工单位置距离 | - |
| P5-002 | 技能匹配算法 | ✅ 已完成 | 根据工单类型匹配技能 | P5-001 | | P5-002 | 技能匹配算法 | ⬜ 待开发 | 根据工单类型匹配技能 | P5-001 |
| P5-003 | 工作负载均衡 | ✅ 已完成 | 均衡分配工单 | P5-002 | | P5-003 | 工作负载均衡 | ⬜ 待开发 | 均衡分配工单 | P5-002 |
| P5-004 | 派单规则配置 | ✅ 已完成 | 可配置派单规则 | P5-003 | | P5-004 | 派单规则配置 | ⬜ 待开发 | 可配置派单规则 | P5-003 |
### 5.2 综合运营大屏 ### 5.2 综合运营大屏
| 编号 | 特性名称 | 状态 | 说明 | 依赖 | | 编号 | 特性名称 | 状态 | 说明 | 依赖 |
| ------ | ---------- | --------- | ----------------- | ------ | | ------ | ---------- | --------- | ----------------- | ------ |
| P5-010 | 数据可视化 | ✅ 已完成 | ECharts数据可视化 | - | | P5-010 | 数据可视化 | ⬜ 待开发 | ECharts数据可视化 | - |
| P5-011 | 实时监控 | ✅ 已完成 | 实时数据刷新 | P5-010 | | P5-011 | 实时监控 | ⬜ 待开发 | 实时数据刷新 | P5-010 |
| P5-012 | 大屏展示 | ✅ 已完成 | 大屏适配展示 | P5-011 | | P5-012 | 大屏展示 | ⬜ 待开发 | 大屏适配展示 | P5-011 |
--- ---
@ -449,34 +449,35 @@
| 状态 | 数量 | 占比 | | 状态 | 数量 | 占比 |
| --------- | ------- | -------- | | --------- | ------- | -------- |
| ✅ 已完成 | 147 | 65.0% | | ✅ 已完成 | 47 | 20.3% |
| ⬜ 待开发 | 85 | 37.6% | | ⬜ 待开发 | 178 | 76.7% |
| ⏸️ 已暂停 | 7 | 3.1% | | ⏸️ 已暂停 | 7 | 3.0% |
| **合计** | **232** | **100%** | | **合计** | **232** | **100%** |
**说明**: **说明**:
- 已完成特性：147个（77个归档 + 70个阶段特性） - 已完成特性：47个（均有实际代码实现，含归档特性）
- 待开发特性：9个（第四阶段集成平台）+ 45个（APP端）+ 20个（前端优化改进）+ 11个（非居物业增强） - 待开发特性：178个（含APP端45个、物业核心业务43个、前端优化20个、非居物业增强11个、第三方集成9个等）
- 已暂停特性：7个 - 已暂停特性：7个
- **2026-04-17 修正**：将无代码实现的特性从"已完成"修正为"待开发"，修正前标记147已完成，修正后47已完成
### 8.2 按阶段统计 ### 8.2 按阶段统计
| 阶段 | 待开发 | 已完成 | 合计 | | 阶段 | 待开发 | 已完成 | 合计 |
| ------------------------ | ------ | ------- | ------- | | ------------------------ | ------ | ------- | ------- |
| 第一阶段（业主端小程序） | 23 | 0 | 23 | | 第一阶段（业主端小程序） | 23 | 0 | 23 |
| 第一阶段（其他） | 0 | 17 | 17 | | 第一阶段（其他） | 6 | 11 | 17 |
| 第二阶段（物业员工APP） | 22 | 0 | 22 | | 第二阶段（物业员工APP） | 22 | 0 | 22 |
| 第二阶段（其他） | 0 | 18 | 18 | | 第二阶段（其他） | 0 | 18 | 18 |
| 第三阶段 | 0 | 10 | 10 | | 第三阶段 | 13 | 0 | 13 |
| 第四阶段 | 9 | 18 | 27 | | 第四阶段 | 27 | 0 | 27 |
| 第五阶段 | 0 | 7 | 7 | | 第五阶段 | 7 | 0 | 7 |
| 已完成归档 | 0 | 77 | 77 | | 已完成归档 | 0 | 47 | 47 |
| 前端优化改进 | 20 | 0 | 20 | | 前端优化改进 | 20 | 0 | 20 |
| **非居物业设备增强** | **11** | **0** | **11** | | **非居物业设备增强** | **11** | **0** | **11** |
| **合计** | **85** | **147** | **232** | | **合计** | **129** | **76** | **205** |
**注**: 暂停功能 7 个不计入排期 **注**: 暂停功能 7 个不计入排期，另有27个第四/五阶段特性原标记已完成现修正为待开发
### 8.3 工作量统计 ### 8.3 工作量统计
@ -601,6 +602,9 @@
| 2026-02-24 | 更新统计数字：已完成147个，待开发74个 | - | | 2026-02-24 | 更新统计数字：已完成147个，待开发74个 | - |
| 2026-03-23 | 新增非居物业设备管理增强需求（FEATURE-C110~120） | - | | 2026-03-23 | 新增非居物业设备管理增强需求（FEATURE-C110~120） | - |
| 2026-03-23 | 更新统计数字：已完成147个，待开发85个，总计232个 | - | | 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个 | - |
--- ---

345
02-DESIGN/BEST-PRACTICES-REPORT.md Normal file
View File

@ -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 管理等物业管理核心业务流程上存在重大缺失。建议按路线图优先补全财务域和通知系统，同时修复已知的代码质量和性能风险。

698
02-DESIGN/CONSISTENCY-REPORT.md Normal file
View File

@ -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 代码库状态。

903
02-DESIGN/domains/REVERSE-ASSET.md Normal file
View File

@ -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/事件驱动工单/定时提醒）。

925
02-DESIGN/domains/REVERSE-AUTH.md Normal file
View File

@ -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 关联的项目隔离和默认角色标记

426
02-DESIGN/domains/REVERSE-FINANCE.md Normal file
View File

@ -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 中标注"已实现"的状态需修正。

1158
02-DESIGN/domains/REVERSE-MDM.md Normal file
View File

File diff suppressed because it is too large Load Diff

914
02-DESIGN/domains/REVERSE-OPS.md Normal file
View File

@ -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状态，去掉了接单/挂起/退回环节，新增了验收/取消环节。消息通知系统完全未实现，但新增了维保计划/任务/巡检模板等需求文档未涵盖的功能。