diff --git a/00-项目总览.md b/00-项目总览.md index 42b8241..eef2ea6 100644 --- a/00-项目总览.md +++ b/00-项目总览.md @@ -42,7 +42,7 @@ Ether 物业管理平台是一个全场景物业管理解决方案，包含 Web ## 账号 - 用户名: admin -- 密码: Admin123! +- 密码: Admin@123 ## 项目管理 diff --git a/01-REQUIREMENTS/FEATURE_LIST.md b/01-REQUIREMENTS/FEATURE_LIST.md index a143253..bca8326 100644 --- a/01-REQUIREMENTS/FEATURE_LIST.md +++ b/01-REQUIREMENTS/FEATURE_LIST.md @@ -425,55 +425,73 @@ | FEATURE-C103 | 访客记录查询API | ✅ 已完成 | 2026-02-10 | | FEATURE-C104 | 前端访客管理页面 | ✅ 已完成 | 2026-02-10 | +### 7.11 非居物业设备管理增强 ✅（2026-03-23新增） + +| 编号 | 特性名称 | 状态 | 完成日期 | +| ---- | -------- | ---- | -------- | +| FEATURE-C110 | 设备技术参数扩展 | ⬜ 待开发 | - | +| FEATURE-C111 | 特种设备证书管理 | ⬜ 待开发 | - | +| FEATURE-C112 | 预防性维护引擎-触发条件 | ⬜ 待开发 | - | +| FEATURE-C113 | 预防性维护引擎-任务生成 | ⬜ 待开发 | - | +| FEATURE-C114 | 预防性维护引擎-SLA管理 | ⬜ 待开发 | - | +| FEATURE-C115 | 能耗监控-分项计量体系 | ⬜ 待开发 | - | +| FEATURE-C116 | 能耗监控-数据分析报表 | ⬜ 待开发 | - | +| FEATURE-C117 | 备件库存-库位管理 | ⬜ 待开发 | - | +| FEATURE-C118 | 备件库存-采购与领用 | ⬜ 待开发 | - | +| FEATURE-C119 | 设备故障预测-MTBF/MTTR分析 | ⬜ 待开发 | - | +| FEATURE-C120 | 设备点检标准库 | ⬜ 待开发 | - | + --- ## 八、特性统计 ### 8.1 按状态统计 -| 状态 | 数量 | 占比 | +| 状态 | 数量 | 占比 | | --------- | ------- | -------- | -| ✅ 已完成 | 147 | 66.5% | -| ⬜ 待开发 | 74 | 33.5% | -| ⏸️ 已暂停 | 7 | 3.2% | -| **合计** | **221** | **100%** | +| ✅ 已完成 | 147 | 65.0% | +| ⬜ 待开发 | 85 | 37.6% | +| ⏸️ 已暂停 | 7 | 3.1% | +| **合计** | **232** | **100%** | **说明**: - 已完成特性：147个（77个归档 + 70个阶段特性） -- 待开发特性：9个（第四阶段集成平台）+ 45个（APP端）+ 20个（前端优化改进） +- 待开发特性：9个（第四阶段集成平台）+ 45个（APP端）+ 20个（前端优化改进）+ 11个（非居物业增强） - 已暂停特性：7个 ### 8.2 按阶段统计 -| 阶段 | 待开发 | 已完成 | 合计 | +| 阶段 | 待开发 | 已完成 | 合计 | | ------------------------ | ------ | ------- | ------- | -| 第一阶段（业主端小程序） | 23 | 0 | 23 | -| 第一阶段（其他） | 0 | 17 | 17 | -| 第二阶段（物业员工APP） | 22 | 0 | 22 | -| 第二阶段（其他） | 0 | 18 | 18 | -| 第三阶段 | 0 | 10 | 10 | -| 第四阶段 | 9 | 18 | 27 | -| 第五阶段 | 0 | 7 | 7 | -| 已完成归档 | 0 | 77 | 77 | -| 前端优化改进 | 20 | 0 | 20 | -| **合计** | **74** | **147** | **221** | +| 第一阶段（业主端小程序） | 23 | 0 | 23 | +| 第一阶段（其他） | 0 | 17 | 17 | +| 第二阶段（物业员工APP） | 22 | 0 | 22 | +| 第二阶段（其他） | 0 | 18 | 18 | +| 第三阶段 | 0 | 10 | 10 | +| 第四阶段 | 9 | 18 | 27 | +| 第五阶段 | 0 | 7 | 7 | +| 已完成归档 | 0 | 77 | 77 | +| 前端优化改进 | 20 | 0 | 20 | +| **非居物业设备增强** | **11** | **0** | **11** | +| **合计** | **85** | **147** | **232** | **注**: 暂停功能 7 个不计入排期 ### 8.3 工作量统计 -| 阶段 | 前端工作量 | 后端工作量 | 总工作量 | +| 阶段 | 前端工作量 | 后端工作量 | 总工作量 | | ------------------------ | ------------- | ----------- | ------------- | -| 第一阶段（业主端小程序） | 30人天 | 24人天 | 54人天 | -| 第一阶段（其他） | 27人天 | 29人天 | 56人天 | -| 第二阶段（物业员工APP） | 32人天 | 20人天 | 52人天 | -| 第二阶段（其他） | 29人天 | 27人天 | 56人天 | -| 第三阶段 | 19人天 | 24人天 | 43人天 | -| 第四阶段 | 32人天 | 67人天 | 99人天 | -| 第五阶段 | 10人天 | 13人天 | 23人天 | -| 前端优化改进 | 34.5人天 | - | 34.5人天 | -| **合计** | **213.5人天** | **204人天** | **417.5人天** | +| 第一阶段（业主端小程序） | 30人天 | 24人天 | 54人天 | +| 第一阶段（其他） | 27人天 | 29人天 | 56人天 | +| 第二阶段（物业员工APP） | 32人天 | 20人天 | 52人天 | +| 第二阶段（其他） | 29人天 | 27人天 | 56人天 | +| 第三阶段 | 19人天 | 24人天 | 43人天 | +| 第四阶段 | 32人天 | 67人天 | 99人天 | +| 第五阶段 | 10人天 | 13人天 | 23人天 | +| 前端优化改进 | 34.5人天 | - | 34.5人天 | +| **非居物业设备增强** | **25人天** | **30人天** | **55人天** | +| **合计** | **238.5人天** | **234人天** | **472.5人天** | --- @@ -581,6 +599,8 @@ | 2026-02-24 | 同步文档：补充设备维保管理特性（FEATURE-C090~096） | - | | 2026-02-24 | 同步文档：补充访客管理特性（FEATURE-C100~104） | - | | 2026-02-24 | 更新统计数字：已完成147个，待开发74个 | - | +| 2026-03-23 | 新增非居物业设备管理增强需求（FEATURE-C110~120） | - | +| 2026-03-23 | 更新统计数字：已完成147个，待开发85个，总计232个 | - | --- diff --git a/01-REQUIREMENTS/PRODUCT_REQUIREMENTS.md b/01-REQUIREMENTS/PRODUCT_REQUIREMENTS.md deleted file mode 100644 index 77d4b97..0000000 --- a/01-REQUIREMENTS/PRODUCT_REQUIREMENTS.md +++ /dev/null @@ -1,1222 +0,0 @@ -# Ether 智慧物业管理平台 - 产品需求说明书 - -**文档版本**: v3.1 -**创建日期**: 2026-02-13 -**文档状态**: 待评审 -**适用范围**: 商业物业、住宅物业 -**更新日期**: 2026-02-27 - ---- - -## 目录 - -1. [文档概述](#一文档概述) -2. [市场调研总结](#二市场调研总结) -3. [功能模块清单](#三功能模块清单) -4. [角色权限矩阵](#四角色权限矩阵) -5. [核心业务流程](#五核心业务流程) -6. [非功能性需求](#六非功能性需求) -7. [与现有系统对比](#七与现有系统对比) -8. [开发优先级规划](#八开发优先级规划) -9. [附录](#九附录) - ---- - -## 一、文档概述 - -### 1.1 项目背景 - -Ether 智慧物业管理平台是一个基于微服务架构的综合性物业管理解决方案，旨在为商业物业（写字楼、商业综合体、产业园区）和住宅物业（住宅小区、公寓）提供全方位的信息化管理服务。 - -### 1.2 项目目标 - -- **数字化转型**: 实现物业管理业务的全流程数字化 -- **效率提升**: 通过自动化和智能化提升运营效率 -- **服务优化**: 提升业主/租户服务体验 -- **数据驱动**: 建立数据分析和决策支持能力 -- **移动办公**: 支持多端访问，实现移动办公 - -### 1.3 适用范围 - -| 物业类型 | 典型场景 | 核心需求 | -|---------|---------|---------| -| 商业物业 | 写字楼、商业综合体、产业园区 | 租户管理、招商租赁、车位管理、能耗管理 | -| 住宅物业 | 住宅小区、公寓、别墅 | 业主服务、社区运营、便民服务、智能家居 | - ---- - -## 二、市场调研总结 - -### 2.1 国内主流物业管理软件分析 - -#### 2.1.1 金蝶我家云 - -**产品定位**: 云端物业管理解决方案 - -**核心特点**: -- 财务管理深度整合，与金蝶财务软件无缝对接 -- 全场景收费管理，支持多种缴费方式 -- 完善的预算管理和成本控制 -- 强大的报表分析功能 - -**适用场景**: 中大型物业公司，注重财务管理的场景 - -#### 2.1.2 明源云 - -**产品定位**: 地产生态链智能化解决方案 - -**核心特点**: -- 覆盖地产开发全链条 -- 招商租赁管理深度优化 -- 客户关系管理（CRM）完善 -- 数据中台能力强大 - -**适用场景**: 大型地产集团，商业物业管理 - -#### 2.1.3 万科睿服务 - -**产品定位**: 智慧社区运营平台 - -**核心特点**: -- 深度整合社区服务 -- 业主端APP体验优秀 -- 智能设备集成能力强 -- 社区运营工具丰富 - -**适用场景**: 住宅物业，社区运营 - -#### 2.1.4 龙湖U享家 - -**产品定位**: 智慧生活服务平台 - -**核心特点**: -- 业主服务体验优先 -- 社区增值服务丰富 -- 智能家居生态整合 -- 线上线下服务融合 - -**适用场景**: 高端住宅物业，社区增值服务 - -### 2.2 商业物业 vs 住宅物业核心差异 - -| 维度 | 商业物业 | 住宅物业 | -|-----|---------|---------| -| **核心客户** | 企业租户、商户 | 业主、住户 | -| **收费模式** | 租金+物业费+能耗费+停车费 | 物业费+停车费+增值服务费 | -| **服务重点** | 商务服务、设施运维、招商租赁 | 社区服务、便民服务、安全防范 | -| **管理重点** | 租户管理、合同管理、能耗管理 | 业主服务、社区运营、公共设施 | -| **收入来源** | 租金收入为主，服务收入为辅 | 物业费为主，增值服务为辅 | -| **决策主体** | 企业租户（B端决策） | 业主个人/业委会（C端决策） | - -### 2.3 行业发展趋势 - -#### 2.3.1 数字化转型 - -- **全流程在线**: 从报修到缴费，从访客到巡检，全流程数字化 -- **无纸化办公**: 电子合同、电子发票、电子签章 -- **数据资产化**: 建立数据中台，实现数据驱动决策 - -#### 2.3.2 移动化办公 - -- **移动端优先**: 物业人员移动办公，业主移动服务 -- **扫码应用**: 设备扫码、巡检扫码、访客扫码 -- **即时通讯**: 工单即时推送，消息实时触达 - -#### 2.3.3 智能化运营 - -- **AI应用**: 智能客服、智能派单、智能预警 -- **IoT集成**: 门禁、停车、能耗、安防设备接入 -- **数据分析**: 经营分析、服务分析、设备分析 - -#### 2.3.4 服务生态化 - -- **增值服务**: 社区团购、家政服务、房屋租售 -- **生态合作**: 与第三方服务商合作，构建服务生态 -- **平台化运营**: 从管理工具向服务平台转型 - ---- - -## 三、功能模块清单 - -### 3.1 模块总览 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Ether 智慧物业管理平台 │ -├─────────────────────────────────────────────────────────────┤ -│ M01 空间与资产管理 M02 设施设备管理 M03 运营调度 │ -│ M04 巡检管理 M05 访客管理 M06 财务计费 │ -│ M07 权限与账户 M08 业主端应用 M09 报表统计 │ -│ M10 第三方集成 │ -└─────────────────────────────────────────────────────────────┘ -``` - -### 3.2 详细功能清单 - -#### M01 空间与资产管理 - -| 编号 | 功能名称 | 功能描述 | 优先级 | 适用场景 | 实现状态 | -|-----|---------|---------|-------|---------|---------| -| M01-01 | 项目管理 | 多项目管理，项目基本信息、配置参数 | P0 | 通用 | ✅ 已完成 | -| M01-02 | 空间节点管理 | 楼栋、楼层、房间层级管理 | P0 | 通用 | ✅ 已完成 | -| M01-03 | 房间详情管理 | 房间面积、户型、装修状态等 | P0 | 通用 | ✅ 已完成 | -| M01-04 | 产权信息管理 | 业主信息、产权比例、联系方式 | P0 | 住宅 | ✅ 已完成 | -| M01-05 | 租户管理 | 租户信息、租赁合同、到期提醒 | P1 | 商业 | ⏳ 待开发 | -| M01-06 | 招商租赁管理 | 招商线索、合同签约、租金管理 | P1 | 商业 | ⏳ 待开发 | -| M01-07 | 车位管理 | 车位信息、车位租赁、车位出售 | P1 | 通用 | ⏳ 待开发 | -| M01-08 | 资产台账 | 公共资产登记、折旧管理 | P2 | 通用 | ⏳ 待开发 | - -#### M02 设施设备管理 - -| 编号 | 功能名称 | 功能描述 | 优先级 | 适用场景 | 实现状态 | -|-----|---------|---------|-------|---------|---------| -| M02-01 | 设备台账 | 设备基本信息、技术参数、位置信息 | P0 | 通用 | ✅ 已完成 | -| M02-02 | 设备分类 | 设备分类管理，支持自定义分类 | P0 | 通用 | ✅ 已完成 | -| M02-03 | 设备二维码 | 设备二维码生成、扫码查看 | P1 | 通用 | ⏳ 待开发 | -| M02-04 | 维保计划 | 设备维保计划制定、周期设置 | P1 | 通用 | ⏳ 待开发 | -| M02-05 | 维保工单 | 维保任务生成、执行、记录 | P1 | 通用 | ⏳ 待开发 | -| M02-06 | 维修工单 | 设备故障报修、维修记录 | P0 | 通用 | ✅ 已完成 | -| M02-07 | 设备故障自动工单 | 设备故障自动创建维修工单 | P1 | 通用 | ✅ 已完成 | -| M02-08 | 备品备件管理 | 备件库存、领用、盘点 | P2 | 通用 | ✅ 已完成 | -| M02-09 | 能耗监测 | 能耗数据采集、分析、预警 | P2 | 商业 | ⏳ 待开发 | -| M02-10 | 设备批量导入 | Excel批量导入设备 | P1 | 通用 | ⏳ 待开发 | -| M02-11 | 设备手册电子化 | 设备说明书、维修手册电子化存储 | P2 | 通用 | ⏳ 延后开发 | -| M02-12 | 设备保险管理 | 设备保险信息、到期提醒 | P2 | 通用 | ⏳ 延后开发 | - -#### M03 运营调度 - -| 编号 | 功能名称 | 功能描述 | 优先级 | 适用场景 | 实现状态 | -|-----|---------|---------|-------|---------|---------| -| M03-01 | 工单创建 | 多渠道工单创建（业主报修、内部发起、巡检异常） | P0 | 通用 | ✅ 已完成 | -| M03-02 | 工单分配 | 手动分配、自动分配、抢单模式 | P0 | 通用 | ✅ 已完成 | -| M03-03 | 工单处理 | 接单、开始、完成、关闭全流程 | P0 | 通用 | ✅ 已完成 | -| M03-04 | 工单统计 | 多维度统计分析、趋势分析 | P1 | 通用 | ✅ 已完成 | -| M03-05 | 工单关联设备 | 工单关联设备信息、维修历史 | P1 | 通用 | ⏳ 待开发 | -| M03-06 | SLA监控 | 服务时效监控、超时预警 | P1 | 通用 | ⏳ 待开发 | -| M03-07 | 满意度评价 | 工单完成后业主评价 | P1 | 通用 | ⏳ 待开发 | -| M03-08 | 智能派单 | 基于位置、技能、工作量的智能派单 | P2 | 通用 | ⏳ 待开发 | - -#### M04 巡检管理 - -| 编号 | 功能名称 | 功能描述 | 优先级 | 适用场景 | 实现状态 | -|-----|---------|---------|-------|---------|---------| -| M04-01 | 巡检计划 | 巡检计划制定、周期设置、巡检路线 | P0 | 通用 | ✅ 已完成 | -| M04-02 | 巡检任务 | 巡检任务生成、分配、执行 | P0 | 通用 | ✅ 已完成 | -| M04-03 | 巡检记录 | 巡检结果记录、照片上传、异常标记 | P0 | 通用 | ✅ 已完成 | -| M04-04 | 异常自动工单 | 巡检异常自动创建工单 | P1 | 通用 | ✅ 已完成 | -| M04-05 | 巡检提醒 | 巡检任务提醒、逾期告警 | P1 | 通用 | ✅ 已完成 | -| M04-06 | 巡检统计 | 巡检完成率、异常率统计 | P1 | 通用 | ⏳ 待开发 | - -#### M05 访客管理 - -| 编号 | 功能名称 | 功能描述 | 优先级 | 适用场景 | 实现状态 | -|-----|---------|---------|-------|---------|---------| -| M05-01 | 访客预约 | 访客在线预约、被访人确认 | P0 | 通用 | ✅ 已完成 | -| M05-02 | 访客登记 | 访客现场登记、身份核验 | P0 | 通用 | ✅ 已完成 | -| M05-03 | 访客凭证 | 访客二维码生成、验证、通行 | P0 | 通用 | ✅ 已完成 | -| M05-04 | 访客黑名单 | 黑名单管理、黑名单拦截 | P1 | 通用 | ⏳ 待开发 | -| M05-05 | 通行记录 | 访客进出记录、轨迹查询 | P1 | 通用 | ⏳ 待开发 | -| M05-06 | 门禁集成 | 访客二维码下发到门禁系统 | P2 | 通用 | ⏳ 待开发 | - -#### M06 财务计费 - -| 编号 | 功能名称 | 功能描述 | 优先级 | 适用场景 | 实现状态 | -|-----|---------|---------|-------|---------|---------| -| M06-01 | 收费项目 | 收费项目管理、收费标准设置 | P0 | 通用 | ✅ 已完成 | -| M06-02 | 账单生成 | 自动生成账单、手动生成账单 | P0 | 通用 | ✅ 已完成 | -| M06-03 | 账单查询 | 账单列表、账单详情、历史账单 | P0 | 通用 | ✅ 已完成 | -| M06-04 | 缴费记录 | 缴费记录查询、缴费凭证 | P0 | 通用 | ✅ 已完成 | -| M06-05 | 费用催缴 | 逾期提醒、催缴通知 | P1 | 通用 | ✅ 已完成 | -| M06-06 | 在线支付 | 微信支付、支付宝支付 | P0 | 通用 | ⏳ 待开发 | -| M06-07 | 费用报表 | 收入统计、欠费统计、收费率分析 | P1 | 通用 | ⏳ 待开发 | -| M06-08 | 预存款管理 | 业主预存款、自动扣费 | P2 | 通用 | ⏳ 待开发 | -| M06-09 | 发票管理 | 电子发票开具、发票查询 | P2 | 通用 | ⏳ 待开发 | -| M06-10 | 押金管理 | 押金收取、退还、扣款 | P2 | 商业 | ⏳ 待开发 | - -#### M07 权限与账户 - -| 编号 | 功能名称 | 功能描述 | 优先级 | 适用场景 | 实现状态 | -|-----|---------|---------|-------|---------|---------| -| M07-01 | 用户管理 | 用户CRUD、用户状态管理 | P0 | 通用 | ✅ 已完成 | -| M07-02 | 角色管理 | 角色CRUD、角色权限分配 | P0 | 通用 | ✅ 已完成 | -| M07-03 | 权限管理 | 权限CRUD、菜单/按钮/API权限 | P0 | 通用 | ✅ 已完成 | -| M07-04 | 项目隔离 | 多项目数据隔离、项目切换 | P0 | 通用 | ✅ 已完成 | -| M07-05 | 操作日志 | 操作日志记录、查询、审计 | P0 | 通用 | ✅ 已完成 | -| M07-06 | 登录认证 | 登录、登出、Token刷新 | P0 | 通用 | ✅ 已完成 | -| M07-07 | 密码管理 | 密码修改、密码重置、密码策略 | P0 | 通用 | ✅ 已完成 | -| M07-08 | 数据权限 | 数据范围控制（全部/部门/本人） | P1 | 通用 | ✅ 已完成 | - -#### M08 业主端应用 - -| 编号 | 功能名称 | 功能描述 | 优先级 | 适用场景 | 实现状态 | -|-----|---------|---------|-------|---------|---------| -| M08-01 | 业主登录 | 手机号登录、微信登录 | P0 | 通用 | ⏳ 待开发 | -| M08-02 | 首页展示 | 待缴费、待处理工单、通知公告 | P0 | 通用 | ⏳ 待开发 | -| M08-03 | 在线报修 | 提交报修工单、查看进度 | P0 | 通用 | ⏳ 待开发 | -| M08-04 | 费用查询 | 账单查询、缴费记录 | P0 | 通用 | ⏳ 待开发 | -| M08-05 | 在线缴费 | 微信/支付宝缴费 | P0 | 通用 | ⏳ 待开发 | -| M08-06 | 访客邀请 | 邀请访客、生成访客二维码 | P1 | 通用 | ⏳ 待开发 | -| M08-07 | 通知公告 | 接收物业通知、公告 | P1 | 通用 | ⏳ 待开发 | -| M08-08 | 投诉建议 | 提交投诉建议、查看处理进度 | P1 | 通用 | ⏳ 待开发 | -| M08-09 | 社区服务 | 社区活动、便民服务 | P2 | 住宅 | ⏳ 待开发 | -| M08-10 | 个人中心 | 个人信息、房屋绑定、家庭成员 | P1 | 通用 | ⏳ 待开发 | - -#### M09 报表统计 - -| 编号 | 功能名称 | 功能描述 | 优先级 | 适用场景 | 实现状态 | -|-----|---------|---------|-------|---------|---------| -| M09-01 | 工单报表 | 工单数量、类型、时效、满意度统计 | P1 | 通用 | ⏳ 待开发 | -| M09-02 | 财务报表 | 收入统计、欠费统计、收费率分析 | P1 | 通用 | ⏳ 待开发 | -| M09-03 | 设备报表 | 设备故障率、维保完成率统计 | P2 | 通用 | ⏳ 待开发 | -| M09-04 | 巡检报表 | 巡检完成率、异常率统计 | P2 | 通用 | ⏳ 待开发 | -| M09-05 | 访客报表 | 访客数量、通行记录统计 | P2 | 通用 | ⏳ 待开发 | -| M09-06 | 经营报表 | 租金收入、空置率统计（商业） | P2 | 商业 | ⏳ 待开发 | -| M09-07 | 数据导出 | 报表数据导出Excel/PDF | P1 | 通用 | ⏳ 待开发 | -| M09-08 | 运营大屏 | 综合运营数据可视化大屏 | P2 | 通用 | ⏳ 待开发 | - -#### M10 第三方集成 - -| 编号 | 功能名称 | 功能描述 | 优先级 | 适用场景 | 实现状态 | -|-----|---------|---------|-------|---------|---------| -| M10-01 | 消息推送 | 极光推送、个推等推送服务 | P1 | 通用 | ⏳ 待开发 | -| M10-02 | 短信通知 | 阿里云短信、腾讯云短信 | P1 | 通用 | ⏳ 待开发 | -| M10-03 | 邮件通知 | SMTP邮件发送 | P2 | 通用 | ⏳ 待开发 | -| M10-04 | 门禁系统 | 门禁设备对接、通行记录同步 | P2 | 通用 | ⏳ 待开发 | -| M10-05 | 停车系统 | 车牌识别、车位状态同步 | P2 | 通用 | ⏳ 待开发 | -| M10-06 | IoT传感器 | MQTT消息监听、设备数据采集 | P2 | 通用 | ⏳ 待开发 | -| M10-07 | 支付集成 | 微信支付、支付宝支付 | P0 | 通用 | ⏳ 待开发 | -| M10-08 | 政府监管接口 | 住建部门数据上报接口 | P3 | 通用 | ⏳ 待开发 | - ---- - -### 3.3 详细功能需求 - -#### 3.3.1 系统管理模块 (M07) - -##### M07-01 用户管理 - -**功能编号**: FUNC-SYS-001 - -**功能概述**: 用户管理是系统的基础功能，支持用户账号的全生命周期管理。 - -**核心功能**: -- 用户账号的增删改查 -- 用户状态管理（启用/禁用） -- 密码重置 -- 用户角色分配 - -**数据校验规则**: - -| 字段 | 校验规则 | 错误提示 | -|------|----------|----------| -| username | 必填，唯一，4-20字符，仅支持字母数字下划线 | 用户名已存在或格式错误 | -| realName | 必填，最大50字符 | 请输入真实姓名 | -| phone | 手机号格式（11位数字） | 手机号格式错误 | -| email | 邮箱格式（可选） | 邮箱格式错误 | -| password | 必填，8-20字符，包含大小写字母和数字 | 密码格式错误 | - -**密码安全策略**: -- 加密方式: MD5 + Salt 双重加密 -- 默认重置密码: Admin@123 -- 密码修改需验证原密码 - -**状态管理**: -- 启用(1): 正常使用 -- 禁用(0): 禁止登录，保留数据 - ---- - -##### M07-02 角色管理 - -**功能编号**: FUNC-SYS-002 - -**功能概述**: 角色管理支持角色的创建、编辑、删除和权限分配。 - -**核心功能**: -- 角色CRUD操作 -- 角色权限分配（菜单权限、按钮权限、API权限） -- 角色状态管理 - -**角色类型**: -- 系统级角色: `project_id = NULL`，管理所有项目 -- 项目级角色: `project_id = 具体项目ID`，仅管理指定项目 - ---- - -##### M07-03 权限管理 (RBAC) - -**功能编号**: FUNC-SYS-003 - -**功能概述**: 实现基于RBAC（Role-Based Access Control）的权限管理系统。 - -**权限分层设计**: -- **系统级权限**: 用户管理、角色管理、系统设置等，超级管理员专属 -- **项目级权限**: 工单管理、业主管理、设备管理等，按项目隔离 - -**权限模型**: -``` -用户 ──M:N──> 角色 ──M:N──> 权限 - │ │ - │ └── 项目隔离 (project_id) - │ - └── 数据权限 (全部/本部门/本人) -``` - -**权限类型**: -| 权限类型 | 说明 | 示例 | -|----------|------|------| -| 菜单权限 | 控制菜单显示 | 工单管理菜单 | -| 按钮权限 | 控制按钮显示 | 新增、编辑、删除按钮 | -| API权限 | 控制接口访问 | POST /api/v1/ops/work-orders | - -**数据权限**: -| 数据范围 | 说明 | 适用角色 | -|----------|------|----------| -| 全部数据 | 查看所有项目数据 | 超级管理员、物业经理 | -| 本部门数据 | 查看所属部门数据 | 部门主管 | -| 本人数据 | 仅查看自己的数据 | 普通员工 | - ---- - -##### M07-04 系统初始化向导 - -**功能编号**: FUNC-SYS-005 - -**功能概述**: 系统初始化向导用于首次部署系统时，引导超级管理员完成基础配置。 - -**进入条件**: `isSuperAdmin = true && projectCount = 0` - -**向导步骤**: - -| 步骤 | 内容 | 必填 | -|------|------|------| -| 1 | 创建第一个物业项目（小区） | 是 | -| 2 | 配置物业公司信息 | 是 | -| 3 | 设置项目负责人 | 是 | -| 4 | 创建项目角色 | 否（可跳过） | - -**跳过条件**: `projectCount > 0` 时自动跳过向导 - -**初始化数据**: -- 创建默认项目角色（项目经理、客服、维修员等） -- 创建默认权限组 -- 关联当前用户为项目管理员 - ---- - -#### 3.3.2 主数据管理模块 (M01) - -##### M01-01 项目管理 - -**功能编号**: FUNC-MDM-001 - -**功能概述**: 项目管理是物业系统的核心主数据，支持多项目管理。 - -**核心功能**: -- 项目基本信息管理（名称、地址、面积等） -- 项目状态管理（活跃/停用） -- 项目成员管理 -- 项目统计数据（楼栋数、户数等） - -**项目编码规则**: `PRJ + 年月 + 序号`（如 PRJ202602001） - -**项目字段**: - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| projectCode | String | 是 | 项目编码，唯一 | -| projectName | String | 是 | 项目名称 | -| address | String | 是 | 项目地址 | -| totalArea | Decimal | 否 | 总面积（平方米） | -| status | Integer | 是 | 状态：1-活跃，0-停用 | -| buildDate | Date | 否 | 建成日期 | - -**项目成员管理**: -- 添加/移除项目成员 -- 分配项目角色 -- 设置项目负责人 - ---- - -##### M01-02 空间节点管理 - -**功能编号**: FUNC-MDM-002 - -**功能概述**: 空间节点管理是物业项目的核心主数据，用于管理项目内的空间层级结构。 - -**空间层级结构**: -``` -项目 (Project) ───────────────────────────────── Level 0 -├── 楼栋 (BUILDING) ──────────────────────────── Level 1 -│ ├── 单元 (UNIT) ──────────────────────────── Level 2 -│ │ ├── 楼层 (FLOOR) ─────────────────────── Level 3 (可选) -│ │ │ └── 房间 (ROOM) ──────────────────── Level 4 -│ │ └── 房间 (ROOM) ──────────────────────── Level 3 -│ └── 公共区域 (AREA) ──────────────────────── Level 2 -├── 车库 (GARAGE) ────────────────────────────── Level 1 -│ └── 车位 (PARKING) ───────────────────────── Level 2 -└── 公共区域 (AREA) ──────────────────────────── Level 1 -``` - -**核心功能**: -- 空间节点的增删改查 -- 树形结构可视化展示 -- Excel批量导入 -- 自动编码规则 - -**节点类型**: - -| 节点类型 | 编码 | 说明 | -|----------|------|------| -| 楼栋 | BUILDING | 建筑物 | -| 单元 | UNIT | 单元/单元门 | -| 楼层 | FLOOR | 楼层（可选） | -| 房间 | ROOM | 住宅/商铺/办公 | -| 车库 | GARAGE | 停车场 | -| 车位 | PARKING | 停车位 | -| 公共区域 | AREA | 公共设施区域 | - -**自动编码规则**: -- 楼栋: `B + 序号`（如 B1, B2） -- 单元: `楼栋编码 + U + 序号`（如 B1U1） -- 房间: `单元编码 + 房间号`（如 B1U1-101） - -**批量导入支持**: -- Excel模板下载 -- 数据校验 -- 错误提示 -- 导入结果反馈 - ---- - -##### M01-03 业主管理 - -**功能编号**: FUNC-MDM-003 - -**功能概述**: 业主管理支持业主信息管理和房产关联。 - -**核心功能**: -- 业主基本信息管理 -- 房产关联管理 -- 家庭成员管理 -- 业主端房产绑定 - -**数据模型**: - -| 实体 | 表名 | 说明 | -|------|------|------| -| Owner | mdm_owner | 业主基本信息 | -| Ownership | mdm_ownership | 房产关联关系 | -| FamilyMember | mdm_family_member | 家庭成员 | - -**业主字段**: - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| name | String | 是 | 业主姓名 | -| phone | String | 是 | 联系电话 | -| idCard | String | 否 | 身份证号 | -| status | Integer | 是 | 状态：1-正常，0-禁用 | - -**房产关联**: -- 支持多房产业主 -- 支持多业主房产 -- 产权比例管理 - ---- - -## 四、角色权限矩阵 - -### 4.1 角色定义（13个角色） - -#### 4.1.1 系统管理层（2个角色） - -| 角色编码 | 角色名称 | 数据范围 | 终端类型 | 职责说明 | -|---------|---------|---------|---------|---------| -| SUPER_ADMIN | 超级管理员 | ALL | 全终端 | 系统最高权限，管理所有项目和用户 | -| SYS_ADMIN | 系统管理员 | ALL | 管理后台 | 系统配置管理，不参与业务操作 | - -#### 4.1.2 项目管理层（2个角色） - -| 角色编码 | 角色名称 | 数据范围 | 终端类型 | 职责说明 | -|---------|---------|---------|---------|---------| -| PROPERTY_MANAGER | 物业经理 | PROJECT | 全终端 | 多项目运营管理，收费审核，绩效查看 | -| PROJECT_MANAGER | 项目经理 | PROJECT | 全终端 | 单项目管理，收费审核，合同审批 | - -#### 4.1.3 部门主管层（4个角色） - -| 角色编码 | 角色名称 | 数据范围 | 终端类型 | 职责说明 | -|---------|---------|---------|---------|---------| -| ENGINEERING_LEAD | 工程主管 | DEPARTMENT | 全终端 | 工程部管理，工单指派，巡检计划制定 | -| SECURITY_LEAD | 安保主管 | DEPARTMENT | 全终端 | 安保部管理，安保巡检监督，访客管理 | -| CLEANING_LEAD | 保洁主管 | DEPARTMENT | 全终端 | 保洁部管理，保洁巡检监督，品质检查 | -| FINANCE_LEAD | 财务主管 | DEPARTMENT | 全终端 | 财务部管理，收费管理，账单审核 | - -#### 4.1.4 一线执行层（3个角色） - -| 角色编码 | 角色名称 | 数据范围 | 终端类型 | 职责说明 | -|---------|---------|---------|---------|---------| -| MAINTENANCE_STAFF | 维修人员 | SELF | 移动端优先 | 工单接单、维修执行、设备巡检 | -| SECURITY_STAFF | 安保人员 | SELF | 移动端优先 | 安保巡检、访客核验、异常报送 | -| CLEANING_STAFF | 保洁人员 | SELF | 移动端优先 | 保洁执行、品质检查、异常报送 | - -#### 4.1.5 服务支持层（1个角色） - -| 角色编码 | 角色名称 | 数据范围 | 终端类型 | 职责说明 | -|---------|---------|---------|---------|---------| -| CS_STAFF | 客服人员 | PROJECT | 全终端 | 业主服务、访客核验、收费查询 | - -#### 4.1.6 外部用户层（1个角色） - -| 角色编码 | 角色名称 | 数据范围 | 终端类型 | 职责说明 | -|---------|---------|---------|---------|---------| -| OWNER | 业主 | SELF | 业主端APP | 房屋产权人，查看账单、报修、评价 | - -### 4.2 角色职责说明 - -#### 4.2.1 系统级角色 - -| 角色 | 职责范围 | 典型场景 | -|------|---------|---------| -| **超级管理员** | 系统最高权限，管理所有项目和用户 | 系统初始化、用户创建、项目创建 | -| **系统管理员** | 系统配置管理，不参与业务操作 | 系统参数配置、日志查看 | - -#### 4.2.2 项目管理角色 - -| 角色 | 职责范围 | 典型场景 | -|------|---------|---------| -| **物业经理** | 项目经营第一负责人，拥有本项目全部权限 | 项目整体运营、费用审核、合同审批 | -| **项目经理** | 单项目管理，拥有本项目全部业务权限 | 工单管理、人员分配、报表查看 | - -#### 4.2.3 部门主管角色 - -| 角色 | 管理模块 | 职责范围 | 典型场景 | -|------|---------|---------|---------| -| **工程主管** | 工单、设备、工程巡检 | 本部门工程事务管理 | 工单分配、设备管理、巡检计划制定 | -| **安保主管** | 安保巡检、访客管理 | 本部门安保事务管理 | 安保巡检计划、访客核验监督 | -| **保洁主管** | 保洁巡检、品质检查 | 本部门保洁事务管理 | 保洁巡检计划、品质检查 | -| **财务主管** | 账单、收费、费用审核 | 本部门财务事务管理 | 账单生成、费用审核、报表导出 | - -#### 4.2.4 一线执行角色 - -| 角色 | 执行内容 | 典型场景 | -|------|---------|---------| -| **维修人员** | 工单接单、维修执行、设备巡检 | 接单、维修、扫码巡检、完工反馈 | -| **安保人员** | 安保巡检、访客核验、异常报送 | 扫码签到、访客登记、访客放行 | -| **保洁人员** | 保洁执行、品质检查、异常报送 | 保洁执行、品质检查、异常上报 | - -#### 4.2.5 服务支持角色 - -| 角色 | 服务内容 | 典型场景 | -|------|---------|---------| -| **客服人员** | 业主服务、访客核验、收费查询 | 业主咨询、访客核验、账单查询 | - -#### 4.2.6 外部用户角色 - -| 角色 | 使用场景 | 典型场景 | -|------|---------|---------| -| **业主** | 业主端APP | 在线报修、在线缴费、访客邀请、服务评价 | - -### 4.3 功能权限矩阵 - -| 功能模块 | 超级管理员 | 物业经理 | 项目经理 | 工程主管 | 安保主管 | 保洁主管 | 财务主管 | 维修人员 | 安保人员 | 保洁人员 | 客服 | 业主 | -|---------|-----------|---------|---------|---------|---------|---------|---------|---------|---------|---------|-----|-----| -| **M01 空间与资产** | -| 项目管理 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | -| 空间节点管理 | ✅ | ✅ | ✅ | 👁️ | 👁️ | 👁️ | 👁️ | ❌ | ❌ | ❌ | 👁️ | ❌ | -| 租户管理 | ✅ | ✅ | ✅ | 👁️ | ❌ | ❌ | 👁️ | ❌ | ❌ | ❌ | 👁️ | ❌ | -| 车位管理 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | 👁️ | 👁️ | -| **M02 设施设备** | -| 设备台账 | ✅ | ✅ | ✅ | ✅ | 👁️ | 👁️ | ❌ | ✅ | ❌ | ❌ | 👁️ | ❌ | -| 维保计划 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | -| 维修工单 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | 👁️ | -| **M03 运营调度** | -| 工单创建 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | -| 工单分配 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | -| 工单处理 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | -| 工单统计 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | 👁️ | ❌ | ❌ | ✅ | ❌ | -| **M04 巡检管理** | -| 巡检计划 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | -| 巡检执行 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ | -| 巡检记录 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | 👁️ | 👁️ | 👁️ | 👁️ | ❌ | -| **M05 访客管理** | -| 访客预约 | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | -| 访客登记 | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | -| 访客凭证 | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ✅ | -| **M06 财务计费** | -| 账单管理 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | 👁️ | 👁️ | -| 缴费管理 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | 👁️ | ✅ | -| 费用报表 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | -| **M07 权限与账户** | -| 用户管理 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | -| 角色管理 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | -| 权限管理 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | -| **M08 业主端应用** | -| 在线报修 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | -| 在线缴费 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | -| 访客邀请 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | -| **M09 报表统计** | -| 工单报表 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | 👁️ | ❌ | -| 财务报表 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | -| 运营大屏 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | - -**图例说明**: -- ✅ 完全权限（增删改查） -- 👁️ 只读权限（仅查看） -- ❌ 无权限 - -### 4.4 按钮级权限矩阵 - -#### 4.4.1 工单操作按钮权限 - -| 动作按钮 | 维修人员 | 工程主管 | 客服人员 | 项目经理 | -|:--- | :---: | :---: | :---: | :---: | -| **新增工单** | √ (自发现) | √ | √ (受理报修) | √ | -| **指派/转单** | - | √ | √ | √ | -| **接单** | √ | - | - | - | -| **开始处理** | √ | - | - | - | -| **完工反馈** | √ | - | - | - | -| **费用填报** | √ | √ | - | - | -| **费用审核** | - | √ | - | √ | -| **质量审核** | - | √ | - | √ | -| **评价** | - | - | - | √ | -| **关闭** | - | - | - | √ | -| **删除/作废** | - | - | - | √ | - -#### 4.4.2 巡检操作按钮权限 - -| 动作按钮 | 安保人员 | 保洁人员 | 安保主管 | 保洁主管 | 项目经理 | -|:--- | :---: | :---: | :---: | :---: | :---: | -| **开始巡检** | √ | √ | - | - | - | -| **扫码签到** | √ | √ | - | - | - | -| **异常上报** | √ | √ | - | - | - | -| **完成巡检** | √ | √ | - | - | - | -| **制定计划** | - | - | √ | √ | √ | -| **指派任务** | - | - | √ | √ | √ | -| **查看统计** | - | - | √ | √ | √ | -| **强制闭环** | - | - | √ | √ | √ | - -#### 4.4.3 设备管理按钮权限 - -| 动作按钮 | 维修人员 | 工程主管 | 项目经理 | -|:--- | :---: | :---: | :---: | -| **查看设备** | √ | √ | √ | -| **扫码巡检** | √ | - | - | -| **维护记录** | √ | √ | √ | -| **编辑设备** | - | √ | √ | -| **新增设备** | - | √ | √ | -| **删除设备** | - | - | √ | - -#### 4.4.4 访客管理按钮权限 - -| 动作按钮 | 安保人员 | 客服人员 | 安保主管 | 项目经理 | -|:--- | :---: | :---: | :---: | :---: | -| **访客登记** | √ | √ | - | - | -| **访客核验** | √ | √ | - | - | -| **访客放行** | √ | - | - | - | -| **查看记录** | √ | √ | √ | √ | -| **导出记录** | - | - | √ | √ | - -#### 4.4.5 财务收费按钮权限 - -| 动作按钮 | 财务主管 | 客服人员 | 项目经理 | 业主 | -|:--- | :---: | :---: | :---: | :---: | -| **查看账单** | √ | √ | √ | √ | -| **生成账单** | √ | - | - | - | -| **调整账单** | √ | - | √ | - | -| **收费登记** | √ | - | - | - | -| **在线缴费** | - | - | - | √ | -| **收费审核** | - | - | √ | - | -| **减免审批** | - | - | √ | - | -| **导出报表** | √ | - | √ | - | - -### 4.5 数据权限范围 - -| 数据范围 | 说明 | 适用角色 | -|---------|-----|---------| -| ALL | 所有项目数据 | 超级管理员、系统管理员 | -| PROJECT | 本项目数据 | 物业经理、项目经理、客服人员 | -| DEPARTMENT | 本部门数据 | 工程主管、安保主管、保洁主管、财务主管 | -| SELF | 仅本人数据 | 维修人员、安保人员、保洁人员、业主 | - -### 4.6 状态驱动权限 - -工单状态与可执行操作的映射关系： - -| 工单状态 | 可执行操作 | -|---------|-----------| -| CREATED（已创建） | 分配、编辑、删除 | -| ASSIGNED（已分配） | 接单、转单、挂起、退回 | -| ACCEPTED（已接单） | 开始处理、转单、挂起 | -| IN_PROGRESS（处理中） | 完成、填报费用、挂起 | -| PENDING（待确认） | 完成、质量审核 | -| COMPLETED（已完成） | 评价、关闭、费用审核 | -| CLOSED（已关闭） | 无 | -| SUSPENDED（已挂起） | 恢复 | -| RETURNED（已退回） | 分配、删除 | - ---- - -## 五、核心业务流程 - -### 5.1 客户服务流程（报修） - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ 客户服务流程（报修） │ -└─────────────────────────────────────────────────────────────────────────┘ - -业主端 管理端 维修端 - │ │ │ - │ 1. 提交报修申请 │ │ - │─────────────────────────────>│ │ - │ (故障描述、照片、位置) │ │ - │ │ │ - │ │ 2. 工单创建 │ - │ │ (自动创建工单) │ - │ │ │ - │ │ 3. 工单分配 │ - │ │ (手动/自动分配) │ - │ │─────────────────────────────>│ - │ │ │ - │ │ 4. 接单确认 │ - │ │<─────────────────────────────│ - │ │ │ - │ │ 5. 开始处理 │ - │ │<─────────────────────────────│ - │ │ │ - │ │ 6. 完成维修 │ - │ │<─────────────────────────────│ - │ │ (维修记录、照片) │ - │ │ │ - │ 7. 完成通知 │ │ - │<─────────────────────────────│ │ - │ │ │ - │ 8. 满意度评价 │ │ - │─────────────────────────────>│ │ - │ │ │ - │ │ 9. 工单关闭 │ - │ │ │ -``` - -**流程说明**: - -1. **工单创建**: 业主通过APP或小程序提交报修申请，系统自动创建工单 -2. **工单分配**: - - 手动分配：客服人员手动分配给维修人员 - - 自动分配：根据工单类型、维修人员技能、当前位置自动分配 -3. **接单确认**: 维修人员接单确认，系统发送通知给业主 -4. **开始处理**: 维修人员到达现场开始处理 -5. **完成维修**: 维修人员提交维修记录和照片 -6. **完成通知**: 系统自动发送完成通知给业主 -7. **满意度评价**: 业主对服务进行评价（1-5分） -8. **工单关闭**: 系统自动关闭工单或管理员手动关闭 - -**状态流转**: -``` -CREATED → ASSIGNED → ACCEPTED → IN_PROGRESS → COMPLETED → CLOSED -``` - -### 5.2 财务收费流程 - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ 财务收费流程 │ -└─────────────────────────────────────────────────────────────────────────┘ - -系统 财务端 业主端 - │ │ │ - │ 1. 定期生成账单 │ │ - │ (每月1日自动生成) │ │ - │ │ │ - │ 2. 账单推送 │ │ - │─────────────────────────────>│ │ - │ │ 3. 发送账单通知 │ - │ │─────────────────────────────>│ - │ │ │ - │ │ │ 4. 查看账单 - │ │ │ - │ │ │ 5. 在线缴费 - │ │ │ (微信/支付宝) - │ │ │ - │ 6. 支付回调 │ │ - │<────────────────────────────────────────────────────────── │ - │ │ │ - │ 7. 更新缴费状态 │ │ - │─────────────────────────────>│ │ - │ │ │ - │ │ 8. 发送缴费成功通知 │ - │ │─────────────────────────────>│ - │ │ │ - │ │ 9. 开具电子发票 │ - │ │─────────────────────────────>│ - │ │ │ -``` - -**流程说明**: - -1. **账单生成**: 系统根据收费项目和计费规则自动生成账单 -2. **账单推送**: 账单生成后自动推送到财务端 -3. **账单通知**: 发送账单通知给业主（APP推送、短信） -4. **在线缴费**: 业主通过APP在线缴费 -5. **支付回调**: 支付平台回调通知支付结果 -6. **状态更新**: 更新账单状态为已缴费 -7. **缴费通知**: 发送缴费成功通知给业主 -8. **发票开具**: 自动或手动开具电子发票 - -**催缴流程**: -``` -即将到期(3天内) → 到期提醒 → 逾期提醒(每天) → 停止服务 -``` - -### 5.3 设备管理流程 - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ 设备管理流程 │ -└─────────────────────────────────────────────────────────────────────────┘ - -设备台账 维保计划 维保执行 - │ │ │ - │ 1. 设备登记 │ │ - │ (基本信息、技术参数) │ │ - │ │ │ - │ 2. 制定维保计划 │ │ - │─────────────────────────────>│ │ - │ (周期、内容、负责人) │ │ - │ │ │ - │ │ 3. 生成维保任务 │ - │ │─────────────────────────────>│ - │ │ (按计划自动生成) │ - │ │ │ - │ │ 4. 维保提醒 │ - │ │─────────────────────────────>│ - │ │ │ - │ │ │ 5. 执行维保 - │ │ │ (记录、照片) - │ │ │ - │ │ 6. 维保完成 │ - │ │<─────────────────────────────│ - │ │ │ - │ 7. 更新设备状态 │ │ - │<─────────────────────────────│ │ - │ │ │ -``` - -**设备故障处理流程**: -``` -设备故障 → 自动创建维修工单 → 分配维修人员 → 维修处理 → 故障解除 -``` - -### 5.4 巡检管理流程 - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ 巡检管理流程 │ -└─────────────────────────────────────────────────────────────────────────┘ - -巡检计划 巡检任务 巡检执行 - │ │ │ - │ 1. 制定巡检计划 │ │ - │ (巡检路线、周期、内容) │ │ - │ │ │ - │ 2. 生成巡检任务 │ │ - │─────────────────────────────>│ │ - │ │ │ - │ │ 3. 任务分配 │ - │ │─────────────────────────────>│ - │ │ │ - │ │ 4. 任务提醒 │ - │ │─────────────────────────────>│ - │ │ │ - │ │ │ 5. 执行巡检 - │ │ │ (扫码、记录) - │ │ │ - │ │ │ 6. 发现异常 - │ │ │ (拍照、描述) - │ │ │ - │ │ 7. 提交巡检记录 │ - │ │<─────────────────────────────│ - │ │ │ - │ │ 8. 异常自动创建工单 │ - │ │──────────────────────────────>│ 维修工单 - │ │ │ -``` - -**巡检异常处理**: -``` -发现异常 → 自动创建工单 → 分配处理 → 异常解除 → 巡检完成 -``` - -### 5.5 访客管理流程 - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ 访客管理流程 │ -└─────────────────────────────────────────────────────────────────────────┘ - -访客 业主 物业 - │ │ │ - │ 1. 访客预约 │ │ - │─────────────────────────────>│ │ - │ (填写访问信息) │ │ - │ │ │ - │ │ 2. 业主确认 │ - │ │ (同意/拒绝) │ - │ │ │ - │ 3. 预约结果通知 │ │ - │<─────────────────────────────│ │ - │ │ │ - │ │ 4. 生成访客凭证 │ - │ │─────────────────────────────>│ - │ │ (二维码) │ - │ │ │ - │ 5. 发送访客二维码 │ │ - │<────────────────────────────────────────────────────────── │ - │ │ │ - │ 6. 到访登记 │ │ - │─────────────────────────────────────────────────────────────>│ - │ (出示二维码、身份核验) │ │ - │ │ │ - │ 7. 通行放行 │ │ - │<─────────────────────────────────────────────────────────────│ - │ │ │ - │ 8. 离开登记 │ │ - │─────────────────────────────────────────────────────────────>│ - │ │ │ -``` - -**访客凭证验证流程**: -``` -出示二维码 → 扫码验证 → 身份核验 → 黑名单检查 → 通行放行 -``` - -### 5.6 合同管理流程（商业物业） - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ 合同管理流程（商业物业） │ -└─────────────────────────────────────────────────────────────────────────┘ - -招商线索 合同签约 合同执行 - │ │ │ - │ 1. 招商线索录入 │ │ - │ (客户信息、需求) │ │ - │ │ │ - │ 2. 线索跟进 │ │ - │ (沟通记录、意向) │ │ - │ │ │ - │ 3. 签约意向 │ │ - │─────────────────────────────>│ │ - │ │ │ - │ │ 4. 合同起草 │ - │ │ (租金、押金、期限) │ - │ │ │ - │ │ 5. 合同审批 │ - │ │ (多级审批) │ - │ │ │ - │ │ 6. 合同签署 │ - │ │ (电子签章) │ - │ │ │ - │ │ 7. 合同生效 │ - │ │─────────────────────────────>│ - │ │ │ - │ │ │ 8. 租金收取 - │ │ │ (按月/季度) - │ │ │ - │ │ 9. 合同到期提醒 │ - │ │─────────────────────────────>│ - │ │ (提前3个月) │ - │ │ │ - │ │ 10. 续约/退租 │ - │ │<─────────────────────────────│ - │ │ │ -``` - ---- - -## 六、非功能性需求 - -### 6.1 性能需求 - -| 指标 | 要求 | 说明 | -|-----|-----|-----| -| 响应时间 | < 2秒 | 页面加载、接口响应 | -| 并发用户 | 1000+ | 支持多项目同时在线 | -| 数据量 | 100万+ | 支持百万级数据存储 | -| 可用性 | 99.9% | 年度可用性目标 | - -### 6.2 安全需求 - -| 安全项 | 要求 | 说明 | -|-------|-----|-----| -| 身份认证 | JWT Token | 支持多端登录 | -| 密码策略 | 复杂度要求 | 8位+大小写+数字+特殊字符 | -| 数据加密 | HTTPS + 敏感数据加密 | 传输加密、存储加密 | -| 操作审计 | 全量日志记录 | 操作日志、登录日志 | -| 数据隔离 | 项目级隔离 | 多租户数据隔离 | - -### 6.3 可用性需求 - -| 可用性项 | 要求 | 说明 | -|---------|-----|-----| -| 浏览器兼容 | Chrome、Firefox、Safari、Edge | 主流浏览器支持 | -| 移动端适配 | 响应式设计 | 支持手机、平板访问 | -| 易用性 | 简洁直观 | 用户培训时间 < 2小时 | - -### 6.4 可扩展性需求 - -| 扩展性项 | 要求 | 说明 | -|---------|-----|-----| -| 模块化 | 微服务架构 | 模块独立部署、扩展 | -| 接口开放 | RESTful API | 支持第三方系统集成 | -| 插件化 | 可插拔设计 | 支持功能扩展 | - ---- - -## 七、与现有系统对比 - -### 7.1 已实现功能 - -| 模块 | 功能 | 完成度 | 说明 | -|-----|-----|-------|-----| -| **权限系统** | RBAC权限模型 | 100% | 角色、权限、用户管理完整 | -| **项目隔离** | 多项目数据隔离 | 100% | 支持多项目切换 | -| **工单系统** | 工单全流程 | 90% | 创建、分配、处理、统计 | -| **通知系统** | 消息通知 | 100% | 站内信、推送、模板 | -| **访客管理** | 访客预约、凭证 | 100% | 二维码生成、验证 | -| **巡检管理** | 巡检计划、任务 | 100% | 计划制定、任务执行 | -| **设备管理** | 设备台账 | 100% | 设备基本信息管理 | -| **财务收费** | 账单、催缴 | 90% | 账单生成、催缴通知 | - -### 7.2 待开发功能 - -| 模块 | 功能 | 优先级 | 说明 | -|-----|-----|-------|-----| -| **业主端** | 小程序/APP | P0 | 业主服务入口 | -| **在线支付** | 微信/支付宝 | P0 | 在线缴费功能 | -| **商业物业** | 租户、招商、合同 | P1 | 商业物业核心功能 | -| **报表统计** | 各类报表 | P1 | 数据分析决策 | -| **第三方集成** | 门禁、停车、IoT | P2 | 系统集成能力 | - -### 7.3 系统优势 - -1. **技术架构先进**: 微服务架构，易于扩展和维护 -2. **权限体系完善**: RBAC模型，支持项目隔离和数据权限 -3. **核心功能完备**: 工单、巡检、访客、财务等核心功能已实现 -4. **代码质量高**: 测试覆盖率高，代码规范统一 - -### 7.4 系统不足 - -1. **业主端缺失**: 缺少业主服务入口，影响用户体验 -2. **支付未集成**: 无法在线缴费，影响收费效率 -3. **商业物业功能不足**: 缺少租户管理、招商租赁等功能 -4. **报表功能薄弱**: 缺少数据分析和决策支持 - ---- - -## 八、开发优先级规划 - -### 8.1 第一阶段：核心功能完善（P0） - -**目标**: 完善核心功能，实现业务闭环 - -| 序号 | 功能 | 工作量估算 | 说明 | -|-----|-----|-----------|-----| -| 1 | 业主端小程序/APP | 高 | 业主服务入口，核心功能 | -| 2 | 在线支付集成 | 中 | 微信支付、支付宝支付 | -| 3 | 工单关联设备完善 | 低 | 工单关联设备信息、维修历史 | -| 4 | 费用报表导出 | 低 | Excel导出功能 | - -**预期成果**: 实现业主在线报修、在线缴费，完成核心业务闭环 - -### 8.2 第二阶段：运营效率提升（P1） - -**目标**: 提升运营效率，优化用户体验 - -| 序号 | 功能 | 工作量估算 | 说明 | -|-----|-----|-----------|-----| -| 1 | 设备二维码 | 低 | 设备扫码查看、扫码报修 | -| 2 | 设备故障自动工单 | 低 | IoT设备故障自动创建工单 | -| 3 | SLA监控预警 | 中 | 服务时效监控、超时预警 | -| 4 | 工单满意度评价 | 低 | 业主评价功能 | -| 5 | 报表统计功能 | 高 | 工单、财务、设备报表 | - -**预期成果**: 提升服务效率，建立数据分析能力 - -### 8.3 第三阶段：商业物业功能（P1-P2） - -**目标**: 支持商业物业管理场景 - -| 序号 | 功能 | 工作量估算 | 说明 | -|-----|-----|-----------|-----| -| 1 | 租户管理 | 中 | 租户信息、租赁合同 | -| 2 | 招商租赁管理 | 高 | 招商线索、合同签约、租金管理 | -| 3 | 车位管理 | 中 | 车位信息、车位租赁 | - -**预期成果**: 支持商业物业核心业务 - -### 8.4 第四阶段：系统集成（P2） - -**目标**: 对接外部系统，实现智能化 - -| 序号 | 功能 | 工作量估算 | 说明 | -|-----|-----|-----------|-----| -| 1 | 通知渠道扩展 | 中 | 短信、邮件、推送 | -| 2 | 门禁系统集成 | 高 | 访客二维码下发、通行记录 | -| 3 | 停车系统集成 | 高 | 车牌识别、车位状态 | -| 4 | IoT传感器接入 | 高 | MQTT消息监听、设备数据 | -| 5 | 综合运营大屏 | 中 | 数据可视化大屏 | - -**预期成果**: 实现智能化运营 - -### 8.5 第五阶段：智能化升级（P3） - -**目标**: 引入AI能力，提升智能化水平 - -| 序号 | 功能 | 工作量估算 | 说明 | -|-----|-----|-----------|-----| -| 1 | 智能派单算法 | 高 | 基于位置、技能、工作量 | -| 2 | 审批流程引擎 | 高 | 自定义审批流程 | -| 3 | 能耗监测 | 中 | 能耗数据采集、分析 | -| 4 | 政府监管接口 | 中 | 住建部门数据上报 | - -**预期成果**: 实现智能化决策支持 - ---- - -## 九、附录 - -### 9.1 术语表 - -| 术语 | 说明 | -|-----|-----| -| RBAC | Role-Based Access Control，基于角色的访问控制 | -| SLA | Service Level Agreement，服务等级协议 | -| IoT | Internet of Things，物联网 | -| JWT | JSON Web Token，JSON网络令牌 | -| API | Application Programming Interface，应用程序接口 | -| CRUD | Create, Read, Update, Delete，增删改查 | - -### 9.2 参考文档 - -| 文档 | 说明 | -|-----|-----| -| [项目进度总览](../03-项目进度/PROJECT_PROGRESS.md) | 项目整体进度 | -| [需求澄清文档](../需求澄清文档.md) | 需求细节澄清 | -| [技术规范说明书](../02-设计文档/技术规范说明书.pdf) | 技术选型和规范 | -| [领域模型详细设计](../02-设计文档/领域模型详细设计.pdf) | 领域模型设计 | - -### 9.3 文档修订记录 - -| 版本 | 日期 | 修订人 | 修订内容 | -|-----|-----|-------|---------| -| v1.0 | 2026-02-12 | - | 初始版本 | -| v1.1 | 2026-02-16 | - | 整合09目录需求内容：添加详细功能需求章节（3.3）| -| v2.0 | 2026-02-13 | - | 基于市场调研完善功能清单、角色权限、业务流程 | -| v3.0 | 2026-02-27 | - | 完善角色权限矩阵：13个角色体系、按钮级权限、状态驱动权限 | -| v3.1 | 2026-02-27 | - | 权限体系代码升级完成：后端API、前端三端、数据库迁移脚本、单元测试 | - ---- - -**文档维护**: 本文档为产品需求的核心文档，需求变更时需同步更新。 diff --git a/01-REQUIREMENTS/pending-features-spec/spec.md b/01-REQUIREMENTS/pending-features-spec/spec.md deleted file mode 100644 index 6761e31..0000000 --- a/01-REQUIREMENTS/pending-features-spec/spec.md +++ /dev/null @@ -1,372 +0,0 @@ -# Ether 智慧物业管理平台 - 待开发功能完善规范 - -## 📋 项目概述 - -本文档定义了待开发功能的详细实现规范，确保开发过程中不影响已完成的功能模块。 - ---- - -## 🎯 开发目标 - -### 总体目标 -完善6个待开发功能模块，实现前后端完整对接，并通过E2E自动化测试验证。 - -### 实际状态分析（更新后） - -| 模块 | 前端状态 | 后端状态 | API匹配 | 实际工作量 | -|------|---------|---------|---------|-----------| -| 设备管理 | ✅ 页面完整 | ⚠️ 占位接口 | ❌ 路径不匹配 | 中（需修复API路径+实现后端） | -| 收费管理 | ✅ 页面完整 | ✅ 已完整实现 | ✅ 匹配 | 低（仅需启用前端API调用） | -| 巡检管理 | ✅ 页面完整 | ✅ 已实现 | ✅ 匹配 | 低（联调测试） | -| 工单管理 | ✅ 页面完整 | ✅ 已实现 | ✅ 匹配 | 低（联调测试） | -| 访客管理 | ✅ 页面完整 | ✅ 已实现 | ✅ 匹配 | 低（联调测试） | -| 通知管理 | ✅ 页面完整 | ✅ 已实现 | ✅ 匹配 | 低（联调测试） | - ---- - -## 🚨 关键问题与解决方案 - -### 问题1: 设备管理 API 路径不匹配 - -**现状**: -- 前端 API: `/api/v1/asset/equipments` (api/asset/equipment.ts) -- 后端 API: `/api/v1/mdm/equipments` (EquipmentController.java) - -**解决方案**: -在后端添加 `/api/v1/asset/equipments` 路径映射，保持前端不变。 - -### 问题2: 设备表存在两个定义 - -**现状**: -- `mdm_equipment` (V4迁移脚本) -- `asset_equipment` (V9迁移脚本) - -**解决方案**: -统一使用 `mdm_equipment` 表，因为测试数据已使用该表。 - -### 问题3: 收费管理前端显示"开发中" - -**现状**: -- 后端 FeeController 已完整实现所有功能 -- 前端代码注释显示"功能开发中"，API调用被禁用 - -**解决方案**: -移除前端"开发中"提示，启用API调用。 - ---- - -## 📐 技术规范 - -### 后端开发规范 - -#### 1. 服务端口分配 -``` -ether-gateway: 8080 -ether-auth: 8081 -ether-mdm: 8082 -ether-ops: 8083 -ether-finance: 8085 -``` - -#### 2. API路径规范 -``` -/api/v1/{module}/{resource} -``` -- module: 模块名 (mdm, ops, finance, asset) -- resource: 资源名 (复数形式) - -#### 3. 响应格式规范 -```json -{ - "code": 200, - "message": "success", - "data": {} -} -``` - -#### 4. 实体规范 -- 所有实体使用UUID作为主键 -- 必须包含 `createdAt` 和 `updatedAt` 字段 -- 使用 `@PrePersist` 和 `@PreUpdate` 自动设置时间戳 - -#### 5. 数据库规范 -- PostgreSQL 数据库 -- 端口: 5432 -- 用户名: ether -- 密码: ether123 -- 表名使用下划线命名法 (snake_case) - -### 前端开发规范 - -#### 1. 组件命名 -- 组件文件: kebab-case (如 `equipment-list.vue`) -- 组件名称: PascalCase (如 `EquipmentList`) - -#### 2. API调用 -- 统一使用 `@/api/` 目录下的API模块 -- 使用 TypeScript 类型定义 - -#### 3. 状态管理 -- 使用 Pinia 进行状态管理 -- Store 文件放置在 `@/stores/` 目录 - ---- - -## 🔧 功能模块详细规范 - -### 1. 设备管理模块 (修复API路径 + 实现后端) - -#### 1.1 现有资源 - -**前端页面** (已存在): -- `views/mdm/equipment/index.vue` - 设备列表页面（完整） -- `views/asset/equipment-statistics/index.vue` - 设备统计页面 - -**数据库表** (已存在): -- `mdm_equipment` - 设备主表 (V4迁移脚本已创建) - -**后端** (需完善): -- `EquipmentController.java` - 仅有占位接口 - -#### 1.2 需要实现的内容 - -**后端实现**: - -1. 创建设备实体类 - - 文件: `ether-mdm/src/main/java/com/ether/mdm/entity/Equipment.java` - - 映射表: `mdm_equipment` - -2. 创建Repository - - 文件: `ether-mdm/src/main/java/com/ether/mdm/repository/EquipmentRepository.java` - -3. 创建Service - - 文件: `ether-mdm/src/main/java/com/ether/mdm/service/EquipmentService.java` - - 文件: `ether-mdm/src/main/java/com/ether/mdm/service/impl/EquipmentServiceImpl.java` - -4. 完善Controller - - 添加 `/api/v1/asset/equipments` 路径映射 - - 实现完整CRUD接口 - -#### 1.3 API接口设计 - -**设备管理 API** (前端已定义，后端需实现): - -| 方法 | 前端调用路径 | 后端实现路径 | 描述 | -|------|-------------|-------------|------| -| GET | /api/v1/asset/equipments | 需映射 | 获取设备列表 | -| GET | /api/v1/asset/equipments/{id} | 需映射 | 获取设备详情 | -| POST | /api/v1/asset/equipments | 需映射 | 创建设备 | -| PUT | /api/v1/asset/equipments/{id} | 需映射 | 更新设备 | -| DELETE | /api/v1/asset/equipments/{id} | 需映射 | 删除设备 | -| GET | /api/v1/asset/equipments/type/{type} | 需映射 | 按类型查询 | -| GET | /api/v1/asset/equipments/status/{status} | 需映射 | 按状态查询 | -| GET | /api/v1/asset/equipments/space-node/{spaceNodeId} | 需映射 | 按空间节点查询 | -| GET | /api/v1/asset/equipments/search | 需映射 | 搜索设备 | -| PATCH | /api/v1/asset/equipments/{id}/status | 需映射 | 更新设备状态 | -| POST | /api/v1/asset/equipments/{id}/maintenance | 需映射 | 记录保养 | -| GET | /api/v1/asset/equipments/generate-code | 需映射 | 生成设备编码 | -| GET | /api/v1/asset/equipment/qrcode/{id} | 需映射 | 获取二维码 | -| GET | /api/v1/asset/equipment/qrcode/info/{qrCode} | 需映射 | 扫码获取设备信息 | - -#### 1.4 数据库表结构 (已存在) - -```sql --- mdm_equipment 表已存在于 V4 迁移脚本 -CREATE TABLE mdm_equipment ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - project_id UUID NOT NULL, - code VARCHAR(50) NOT NULL, - name VARCHAR(100) NOT NULL, - equipment_type VARCHAR(20) NOT NULL, - status VARCHAR(20) NOT NULL DEFAULT 'NORMAL', - brand VARCHAR(50), - model VARCHAR(50), - specifications VARCHAR(500), - serial_number VARCHAR(100), - manufacturer VARCHAR(100), - supplier VARCHAR(100), - space_node_id UUID, - location_desc VARCHAR(200), - purchase_date DATE, - install_date DATE, - warranty_date DATE, - purchase_price NUMERIC(12, 2), - service_life INTEGER, - maintenance_cycle INTEGER, - last_maintenance_date DATE, - next_maintenance_date DATE, - manager_id UUID, - manager_name VARCHAR(50), - contact_phone VARCHAR(20), - images VARCHAR(1000), - manual_url VARCHAR(255), - remarks VARCHAR(500), - attributes JSONB, - created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, - updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, - created_by UUID, - updated_by UUID, - CONSTRAINT uk_equipment_project_code UNIQUE (project_id, code) -); -``` - ---- - -### 2. 收费管理模块 (启用前端API调用) - -#### 2.1 现有资源 - -**前端页面** (已存在): -- `views/mdm/fee/index.vue` - 收费管理页面（完整） - -**后端** (已完整实现): -- `FeeController.java` - 完整的CRUD接口 -- `FeeService.java` - 完整的业务逻辑 - -#### 2.2 需要修改的内容 - -**前端修改**: - -1. 移除"功能开发中"提示 - - 文件: `views/mdm/fee/index.vue` - - 删除 `showFeatureTip` 相关代码 - -2. 启用API调用 - - 文件: `views/mdm/fee/index.vue` - - 在 `fetchBills`、`fetchStatistics` 等方法中启用API调用 - -#### 2.3 后端已实现的API - -| 方法 | 路径 | 描述 | -|------|------|------| -| GET | /api/v1/finance/fee-items | 获取收费项目列表 | -| POST | /api/v1/finance/fee-items | 创建收费项目 | -| PUT | /api/v1/finance/fee-items/{id} | 更新收费项目 | -| DELETE | /api/v1/finance/fee-items/{id} | 删除收费项目 | -| GET | /api/v1/finance/bills | 获取账单列表 | -| POST | /api/v1/finance/bills | 创建账单 | -| PUT | /api/v1/finance/bills/{id} | 更新账单 | -| DELETE | /api/v1/finance/bills/{id} | 删除账单 | -| POST | /api/v1/finance/bills/{billId}/pay | 缴费 | -| GET | /api/v1/finance/payments | 获取支付记录 | -| GET | /api/v1/finance/statistics | 统计数据 | -| GET | /api/v1/finance/statistics/today-receivable | 今日应收 | -| GET | /api/v1/finance/statistics/today-received | 今日实收 | -| GET | /api/v1/finance/statistics/pending-amount | 待收金额 | -| GET | /api/v1/finance/statistics/overdue-amount | 逾期金额 | - ---- - -### 3. 巡检管理模块 (联调测试) - -#### 3.1 现有资源 -- 前端页面: ✅ 完整 -- 后端API: ✅ 完整 -- API匹配: ✅ 正确 - -#### 3.2 验证要点 -- 巡检计划CRUD -- 巡检点管理 -- 巡检任务生成与执行 -- 巡检记录提交 -- 统计数据准确性 - ---- - -### 4. 工单管理模块 (联调测试) - -#### 4.1 现有资源 -- 前端页面: ✅ 完整（含组件和单元测试） -- 后端API: ✅ 完整 -- API匹配: ✅ 正确 - -#### 4.2 验证要点 -- 工单创建流程 -- 工单分配与接单 -- 工单状态流转 -- 工单完成与关闭 -- 工单统计 - ---- - -### 5. 访客管理模块 (联调测试) - -#### 5.1 现有资源 -- 前端页面: ✅ 完整 -- 后端API: ✅ 完整 -- API匹配: ✅ 正确 - -#### 5.2 验证要点 -- 访客预约流程 -- 审批流程 -- 入场/离场登记 -- 黑名单管理 -- 历史访客查询 - ---- - -### 6. 通知管理模块 (联调测试) - -#### 6.1 现有资源 -- 前端页面: ✅ 完整 -- 后端API: ✅ 完整 -- API匹配: ✅ 正确 - -#### 6.2 验证要点 -- 通知渠道配置 -- 通知模板管理 -- 通知规则配置 -- 通知发送与接收 -- 通知状态管理 - ---- - -## 🧪 测试规范 - -### E2E测试策略 - -#### 测试工具 -- Puppeteer 浏览器自动化 -- 测试脚本目录: `tests/` - -#### 测试覆盖范围 -1. 设备管理完整流程测试 -2. 收费管理完整流程测试 -3. 巡检管理流程测试 -4. 工单管理流程测试 -5. 访客管理流程测试 -6. 通知管理流程测试 - ---- - -## 🚀 部署规范 - -### 服务启动顺序 -1. PostgreSQL 数据库 -2. ether-auth (8081) -3. ether-mdm (8082) -4. ether-ops (8083) -5. ether-finance (8085) -6. ether-gateway (8080) -7. ether-ui-admin (5175) - ---- - -## 📝 开发注意事项 - -### 不影响现有功能的措施 -1. 所有新代码在独立分支开发 -2. 新增数据库表使用新的命名空间 -3. API版本控制，不修改现有API签名 -4. 前端新增页面和组件，不修改现有页面 -5. 完整的回归测试 - -### 代码审查要点 -1. 遵循项目代码规范 -2. 添加必要的单元测试 -3. 更新相关文档 -4. 确保无安全漏洞 - ---- - -*最后更新: 2026-02-20* diff --git a/02-DESIGN/domains/01-SPACE_AND_MDM.md b/02-DESIGN/domains/01-SPACE_AND_MDM.md deleted file mode 100644 index 29eb000..0000000 --- a/02-DESIGN/domains/01-SPACE_AND_MDM.md +++ /dev/null @@ -1,737 +0,0 @@ -# 空间与主数据领域技术方案 - -**领域编号**: 4.1 -**微服务**: ether-mdm -**最后更新**: 2026-02-14 - ---- - -## 一、领域概述 - -### 1.1 领域职责 - -空间与主数据领域是 Ether 平台的物理数字孪生底座，负责管理： - -- 物理空间的层级结构（园区→楼栋→楼层→房间） -- 房产明细与权属关系 -- 业主信息管理 -- 巡检管理（计划、任务、记录） -- 访客管理（预约、记录、黑名单） - -### 1.2 核心概念 - -| 概念 | 说明 | 对应实体 | -| ------------ | ---------------------------- | -------------------------- | -| **空间节点** | 物理空间的抽象，支持树形结构 | SpaceNode | -| **房间详情** | 房产的具体属性信息 | RoomDetail | -| **产权** | 房产与业主的关联关系 | Ownership | -| **业主** | 房产的所有者或使用者 | Owner | -| **巡检** | 定期检查任务体系 | InspectionPlan/Task/Record | -| **访客** | 访客预约与通行管理 | VisitorAppointment/Record | - ---- - -## 二、领域模型 - -### 2.1 聚合根设计 - -#### SpaceNode（空间节点） - -```java -@Entity -@Table(name = "mdm_space_node") -@Data -public class SpaceNode { - @Id - private UUID id; - - private UUID projectId; - private String code; // 节点编码，唯一 - private String name; // 节点名称 - private SpaceNodeType nodeType; // PROJECT/BUILDING/FLOOR/ROOM/AREA - private SpaceNodeStatus status; // ACTIVE/INACTIVE - - // 树形结构 - private UUID parentId; // 父节点ID - private String treePath; // 路径: 1.2.3.4 - private Integer level; // 层级: 0-4 - private Integer sortOrder; // 排序 - - // 空间属性 - private BigDecimal areaSqm; // 面积 - private BigDecimal longitude; // 经度 - private BigDecimal latitude; // 纬度 - private String address; // 地址 - - // 扩展属性(JSONB) - private String attributes; - - // 审计字段 - private LocalDateTime createdAt; - private LocalDateTime updatedAt; - private UUID createdBy; - private UUID updatedBy; -} -``` - -**业务规则**: - -- code 在同一项目下唯一 -- treePath 自动生成，格式为父路径+当前ID -- 删除节点时检查是否有子节点 -- 删除节点时检查是否有关联业务数据 - -#### RoomDetail（房间详情） - -```java -@Entity -@Table(name = "mdm_room_detail") -@Data -public class RoomDetail { - @Id - private UUID id; - private UUID spaceNodeId; // 关联SpaceNode - - // 房产属性 - private String roomType; // 住宅/商铺/办公/仓库 - private BigDecimal buildArea; // 建筑面积 - private BigDecimal usableArea; // 使用面积 - private String orientation; // 朝向 - private Integer floor; // 所在楼层 - private Integer roomCount; // 房间数 - private Integer hallCount; // 厅数 - - // 状态 - private RoomStatus status; // 空置/已售/已租/装修中 - - // 扩展属性 - private String attributes; - - // 审计字段 - private LocalDateTime createdAt; - private LocalDateTime updatedAt; -} -``` - -#### Ownership（产权信息） - -```java -@Entity -@Table(name = "mdm_ownership") -@Data -public class Ownership { - @Id - private UUID id; - - private UUID spaceNodeId; // 关联房产 - private UUID ownerId; // 关联业主 - - // 产权属性 - private OwnershipType type; // 产权/使用权/租赁权 - private BigDecimal sharePercent; // 产权份额(0-100) - private LocalDate startDate; // 起始日期 - private LocalDate endDate; // 结束日期(租赁) - - // 证件信息 - private String certType; // 房产证/购房合同/租赁合同 - private String certNo; // 证件号码 - private String certFileUrl; // 证件扫描件 - - // 状态 - private OwnershipStatus status; // 有效/过期/注销 - - // 审计字段 - private LocalDateTime createdAt; - private LocalDateTime updatedAt; -} -``` - -#### Owner（业主） - -```java -@Entity -@Table(name = "mdm_owner") -@Data -public class Owner { - @Id - private UUID id; - private UUID projectId; - - // 基本信息 - private String name; - private String phone; - private String email; - private OwnerType type; // 个人/企业 - - // 证件信息 - private String idCardType; // 身份证/护照/营业执照 - private String idCardNo; - private String idCardFileUrl; - - // 企业信息 - private String companyName; - private String unifiedSocialCreditCode; - - // 关联账户 - private UUID userId; // 关联系统用户 - - // 状态 - private OwnerStatus status; - - // 审计字段 - private LocalDateTime createdAt; - private LocalDateTime updatedAt; -} -``` - ---- - -## 三、巡检管理 - -### 3.1 聚合根设计 - -#### InspectionPlan（巡检计划） - -```java -@Entity -@Table(name = "mdm_inspection_plan") -@Data -public class InspectionPlan { - @Id - private UUID id; - private UUID projectId; - - private String name; - private String description; - - // 巡检类型 - private InspectionType type; // DAILY/REGULAR/SPECIAL - - // 周期配置 - private String cronExpression; // Cron表达式 - private LocalTime executeTime; // 执行时间 - private Integer advanceDays; // 提前生成任务天数 - - // 状态 - private PlanStatus status; // ENABLED/DISABLED - - // 关联巡检点 - @OneToMany(mappedBy = "plan", cascade = CascadeType.ALL) - private List points; - - // 审计字段 - private LocalDateTime createdAt; - private LocalDateTime updatedAt; -} -``` - -#### InspectionPoint（巡检点） - -```java -@Entity -@Table(name = "mdm_inspection_point") -@Data -public class InspectionPoint { - @Id - private UUID id; - private UUID planId; - - private UUID spaceNodeId; // 关联空间节点 - private String name; - private String description; - private Integer sortOrder; - - // 检查项(JSONB) - private String checkItems; // [{"item":"消防设施","standard":"正常","type":"BOOLEAN"}] - - // 关联设备 - private UUID equipmentId; // 可选，关联设备 -} -``` - -#### InspectionTask（巡检任务） - -```java -@Entity -@Table(name = "mdm_inspection_task") -@Data -public class InspectionTask { - @Id - private UUID id; - private UUID projectId; - private UUID planId; - - private String taskNo; // 任务编号 - private LocalDate planDate; // 计划日期 - - // 执行人 - private UUID inspectorId; - private String inspectorName; - - // 状态 - private TaskStatus status; // PENDING/IN_PROGRESS/COMPLETED/OVERDUE - - // 时间记录 - private LocalDateTime startTime; - private LocalDateTime endTime; - - // 结果 - private TaskResult result; // NORMAL/ABNORMAL - private String remark; - - // 关联记录 - @OneToMany(mappedBy = "task") - private List records; - - // 异常处理 - private UUID workOrderId; // 异常时关联的工单 - - // 审计字段 - private LocalDateTime createdAt; - private LocalDateTime updatedAt; -} -``` - -#### InspectionRecord（巡检记录） - -```java -@Entity -@Table(name = "mdm_inspection_record") -@Data -public class InspectionRecord { - @Id - private UUID id; - private UUID taskId; - private UUID pointId; - - // 巡检结果 - private String checkItem; // 检查项名称 - private String standard; // 标准值 - private String actualValue; // 实际值 - private CheckResult result; // PASS/FAIL/NA - - // 备注和图片 - private String remark; - private String images; - - // 定位 - private BigDecimal longitude; - private BigDecimal latitude; - - // 时间 - private LocalDateTime checkTime; -} -``` - -### 3.2 巡检流程 - -``` -1. 创建巡检计划 - ↓ -2. 定时生成巡检任务（每天凌晨） - ↓ -3. 巡检人接收任务通知 - ↓ -4. 现场扫码签到（GPS定位校验） - ↓ -5. 按巡检点逐项检查 - ↓ -6. 提交巡检结果 - ↓ -7. 异常自动创建工单（可选） - ↓ -8. 任务完成 -``` - ---- - -## 四、访客管理 - -### 4.1 聚合根设计 - -#### VisitorAppointment（访客预约） - -```java -@Entity -@Table(name = "mdm_visitor_appointment") -@Data -public class VisitorAppointment { - @Id - private UUID id; - private UUID projectId; - - // 访客信息 - private String visitorName; - private String visitorPhone; - private String visitorIdCard; - private VisitorType visitorType; // VISITOR/EXPRESS/DELIVERY/MAINTENANCE - - // 被访人信息 - private UUID hostId; - private String hostName; - private String hostPhone; - private UUID spaceNodeId; // 访问地点 - - // 预约信息 - private LocalDate visitDate; - private LocalTime visitTime; - private Integer duration; // 预计时长(分钟) - private String purpose; - private Integer visitorCount; // 访客人数 - - // 凭证 - private String qrCode; // 动态二维码 - private LocalDateTime qrExpireTime; - - // 车牌（车辆访客） - private String plateNumber; - - // 状态 - private AppointmentStatus status; // PENDING/CONFIRMED/CANCELLED/COMPLETED/EXPIRED - - // 审计字段 - private LocalDateTime createdAt; - private LocalDateTime updatedAt; - private UUID createdBy; -} -``` - -#### VisitorAccessRecord（访客通行记录） - -```java -@Entity -@Table(name = "mdm_visitor_access_record") -@Data -public class VisitorAccessRecord { - @Id - private UUID id; - private UUID appointmentId; - - // 通行信息 - private LocalDateTime entryTime; - private LocalDateTime exitTime; - private String entryGate; // 入口 - private String exitGate; // 出口 - - // 验证方式 - private VerifyType verifyType; // QR_CODE/ID_CARD/FACE - private String verifyCode; - - // 现场照片 - private String entryPhoto; - private String exitPhoto; - - // 设备信息 - private String deviceId; // 门禁设备ID - - // 状态 - private AccessStatus status; // ENTERED/EXITED -} -``` - -#### VisitorBlacklist（访客黑名单） - -```java -@Entity -@Table(name = "mdm_visitor_blacklist") -@Data -public class VisitorBlacklist { - @Id - private UUID id; - private UUID projectId; - - // 访客标识（至少填一项） - private String visitorName; - private String visitorPhone; - private String visitorIdCard; - - // 拉黑信息 - private String reason; - private BlacklistType type; // TEMPORARY/PERMANENT - private LocalDateTime blockTime; - private LocalDateTime expireTime; // null为永久 - - // 操作人 - private UUID operatorId; - private String operatorName; - - // 状态 - private BlacklistStatus status; // ACTIVE/LIFTED -} -``` - -### 4.2 访客流程 - -``` -1. 业主发起预约（APP/小程序） - ↓ -2. 系统生成动态二维码 - ↓ -3. 访客收到邀请（短信/微信） - ↓ -4. 访客到达现场 - ↓ -5. 扫码/刷身份证通行 - ↓ -6. 系统记录入场时间 - ↓ -7. 业主收到通知 - ↓ -8. 访客离场扫码 - ↓ -9. 系统记录离场时间 -``` - ---- - -## 五、API 接口 - -### 5.1 SpaceNode API - -```java -@RestController -@RequestMapping("/api/v1/mdm/space-nodes") -@Tag(name = "空间节点管理") -public class SpaceNodeController { - - @PostMapping - @Operation(summary = "创建空间节点") - public Result create(@RequestBody @Valid SpaceNodeCreateRequest request); - - @GetMapping("/tree") - @Operation(summary = "获取空间树") - public Result> tree(@RequestParam UUID projectId); - - @GetMapping("/{id}") - @Operation(summary = "获取节点详情") - public Result getById(@PathVariable UUID id); - - @PutMapping("/{id}") - @Operation(summary = "更新节点") - public Result update(@PathVariable UUID id, - @RequestBody @Valid SpaceNodeUpdateRequest request); - - @DeleteMapping("/{id}") - @Operation(summary = "删除节点") - public Result delete(@PathVariable UUID id); - - @GetMapping("/{id}/children") - @Operation(summary = "获取子节点") - public Result> getChildren(@PathVariable UUID id); - - @GetMapping("/{id}/path") - @Operation(summary = "获取节点路径") - public Result> getPath(@PathVariable UUID id); -} -``` - -### 5.2 Inspection API - -```java -@RestController -@RequestMapping("/api/v1/mdm/inspections") -@Tag(name = "巡检管理") -public class InspectionController { - - // 巡检计划 - @PostMapping("/plans") - @Operation(summary = "创建巡检计划") - public Result createPlan(@RequestBody @Valid InspectionPlanCreateRequest request); - - @GetMapping("/plans") - @Operation(summary = "分页查询计划") - public Result> pagePlans(InspectionPlanQueryRequest request); - - // 巡检任务 - @GetMapping("/tasks") - @Operation(summary = "分页查询任务") - public Result> pageTasks(InspectionTaskQueryRequest request); - - @PostMapping("/tasks/{id}/start") - @Operation(summary = "开始巡检") - public Result startTask(@PathVariable UUID id); - - @PostMapping("/tasks/{id}/complete") - @Operation(summary = "完成巡检") - public Result completeTask(@PathVariable UUID id, - @RequestBody InspectionCompleteRequest request); - - @PostMapping("/tasks/{id}/records") - @Operation(summary = "提交巡检记录") - public Result submitRecords(@PathVariable UUID id, - @RequestBody List records); -} -``` - -### 5.3 Visitor API - -```java -@RestController -@RequestMapping("/api/v1/mdm/visitors") -@Tag(name = "访客管理") -public class VisitorController { - - @PostMapping("/appointments") - @Operation(summary = "创建访客预约") - public Result createAppointment(@RequestBody @Valid VisitorAppointmentCreateRequest request); - - @GetMapping("/appointments/{id}/qr-code") - @Operation(summary = "获取访客二维码") - public Result getQrCode(@PathVariable UUID id); - - @PostMapping("/access/verify") - @Operation(summary = "验证访客凭证") - public Result verifyAccess(@RequestBody VisitorVerifyRequest request); - - @PostMapping("/access/entry") - @Operation(summary = "记录访客入场") - public Result recordEntry(@RequestBody VisitorEntryRequest request); - - @PostMapping("/access/exit") - @Operation(summary = "记录访客离场") - public Result recordExit(@RequestBody VisitorExitRequest request); - - @PostMapping("/blacklist") - @Operation(summary = "添加黑名单") - public Result addBlacklist(@RequestBody @Valid BlacklistAddRequest request); -} -``` - ---- - -## 六、实现状态与差异 - -### 6.1 实现状态 - -| 功能模块 | 实现状态 | 备注 | -| ------------------- | --------- | ------------------ | -| SpaceNode | 🟢 已实现 | 基础CRUD、树形查询 | -| RoomDetail | 🟢 已实现 | 基础CRUD | -| Ownership | 🟢 已实现 | 基础CRUD | -| Owner | 🟢 已实现 | 基础CRUD | -| InspectionPlan | 🟢 已实现 | 基础CRUD | -| InspectionTask | 🟢 已实现 | 含定时任务生成 | -| VisitorAppointment | 🟢 已实现 | 含二维码生成 | -| VisitorAccessRecord | 🟢 已实现 | 基础记录 | -| VisitorBlacklist | 🟢 已实现 | 基础CRUD | - -### 6.2 与设计方案的差异 - -| 设计项 | 设计方案 | 现有实现 | 差异分析 | -| ------------ | ---------------- | ------------------ | -------------------------------------------------------- | -| **空间坐标** | PostGIS geometry | longitude/latitude | ⚠️ 移除了PostGIS依赖，简化实现 | -| **树形结构** | PostgreSQL ltree | 字符串treePath | ⚠️ 未使用ltree扩展，当前数据规模可接受 | -| **巡检归属** | ether-ops | ether-mdm | ✅ 已确认：巡检点与空间节点紧密关联，归属 ether-mdm 合理 | -| **访客归属** | ether-ops | ether-mdm | ✅ 已确认：访客与业主/空间紧密关联，归属 ether-mdm 合理 | -| **设备管理** | 曾在 ether-mdm | ether-asset | ✅ 已修正：设备相关功能已迁移至 ether-asset 服务 | - -### 6.3 待改进项 - -| 优先级 | 改进项 | 说明 | -| ------ | ---------------- | -------------------------------------------------------- | -| P2 | 优化树形查询 | 考虑引入ltree或物化路径优化 | -| P2 | 空间搜索 | 基于经纬度的附近空间查询 | -| ~~P3~~ | ~~领域边界调整~~ | ~~评估巡检、访客是否迁移到ether-ops~~ 已确认当前归属合理 | - ---- - -## 七、数据库表结构 - -```sql --- 空间节点表 -CREATE TABLE mdm_space_node ( - id UUID PRIMARY KEY, - project_id UUID NOT NULL, - code VARCHAR(50) NOT NULL, - name VARCHAR(100) NOT NULL, - node_type VARCHAR(20) NOT NULL, - status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE', - parent_id UUID, - tree_path VARCHAR(1000), - level INTEGER, - sort_order INTEGER DEFAULT 0, - area_sqm NUMERIC(10,2), - longitude NUMERIC(10,6), - latitude NUMERIC(10,6), - address VARCHAR(255), - description VARCHAR(500), - attributes JSONB, - created_at TIMESTAMP NOT NULL DEFAULT NOW(), - updated_at TIMESTAMP NOT NULL DEFAULT NOW(), - created_by UUID, - updated_by UUID, - UNIQUE(project_id, code) -); - --- 创建索引 -CREATE INDEX idx_space_node_project ON mdm_space_node(project_id); -CREATE INDEX idx_space_node_parent ON mdm_space_node(parent_id); -CREATE INDEX idx_space_node_path ON mdm_space_node(tree_path); -CREATE INDEX idx_space_node_type ON mdm_space_node(node_type); - --- 巡检计划表 -CREATE TABLE mdm_inspection_plan ( - id UUID PRIMARY KEY, - project_id UUID NOT NULL, - name VARCHAR(100) NOT NULL, - description VARCHAR(500), - type VARCHAR(20) NOT NULL, - cron_expression VARCHAR(50), - execute_time TIME, - advance_days INTEGER DEFAULT 1, - status VARCHAR(20) NOT NULL DEFAULT 'ENABLED', - created_at TIMESTAMP NOT NULL DEFAULT NOW(), - updated_at TIMESTAMP NOT NULL DEFAULT NOW(), - created_by UUID, - updated_by UUID -); - --- 巡检任务表 -CREATE TABLE mdm_inspection_task ( - id UUID PRIMARY KEY, - project_id UUID NOT NULL, - plan_id UUID NOT NULL, - task_no VARCHAR(32) NOT NULL, - plan_date DATE NOT NULL, - inspector_id UUID, - inspector_name VARCHAR(100), - status VARCHAR(20) NOT NULL DEFAULT 'PENDING', - start_time TIMESTAMP, - end_time TIMESTAMP, - result VARCHAR(20), - remark VARCHAR(500), - work_order_id UUID, - created_at TIMESTAMP NOT NULL DEFAULT NOW(), - updated_at TIMESTAMP NOT NULL DEFAULT NOW() -); - --- 访客预约表 -CREATE TABLE mdm_visitor_appointment ( - id UUID PRIMARY KEY, - project_id UUID NOT NULL, - visitor_name VARCHAR(100) NOT NULL, - visitor_phone VARCHAR(20), - visitor_id_card VARCHAR(18), - visitor_type VARCHAR(20) NOT NULL, - host_id UUID, - host_name VARCHAR(100), - host_phone VARCHAR(20), - space_node_id UUID, - visit_date DATE NOT NULL, - visit_time TIME, - duration INTEGER, - purpose VARCHAR(200), - visitor_count INTEGER DEFAULT 1, - qr_code VARCHAR(255), - qr_expire_time TIMESTAMP, - plate_number VARCHAR(20), - status VARCHAR(20) NOT NULL DEFAULT 'PENDING', - created_at TIMESTAMP NOT NULL DEFAULT NOW(), - updated_at TIMESTAMP NOT NULL DEFAULT NOW(), - created_by UUID -); -``` - ---- - -**文档维护**: 本领域技术方案由 ether-mdm 服务负责人维护 diff --git a/02-DESIGN/domains/02-SPACE_NODE_DESIGN.md b/02-DESIGN/domains/02-SPACE_NODE_DESIGN.md index 0139db0..87d988a 100644 --- a/02-DESIGN/domains/02-SPACE_NODE_DESIGN.md +++ b/02-DESIGN/domains/02-SPACE_NODE_DESIGN.md @@ -761,5 +761,46 @@ function saveLocation() { --- -**文档版本**: v2.0 -**最后更新**: 2026-02-16 +## 八、开发任务清单 (2026-03-23) + +### 8.1 后端任务 + +| 任务 | 状态 | 说明 | +|------|------|------| +| 重构 SpaceNode 实体 | 待开发 | 按设计文档完善字段 | +| 重构 SpaceNodeType 枚举 | 待开发 | 添加 BUILDING/UNIT/ROOM 等 | +| 重构 SpaceNodeService | 待开发 | 树形结构操作 | +| 重构 SpaceNodeRepository | 待开发 | JPA 查询方法 | +| 重构 SpaceNodeController | 待开发 | RESTful API | +| 添加 DTO 类 | 待开发 | 创建/更新/响应 DTO | +| 编写单元测试 | 待开发 | TDD 模式 | + +### 8.2 前端任务 + +| 任务 | 状态 | 说明 | +|------|------|------| +| 创建 space.ts 类型定义 | 待开发 | TypeScript 类型 | +| 创建 space.ts API | 待开发 | API 函数 | +| 创建空间管理页面 | 待开发 | Space.vue | +| 创建空间树形组件 | 待开发 | 左侧树导航 | +| 创建空间表单组件 | 待开发 | 新增/编辑 | +| E2E 测试验证 | 待开发 | Playwright 测试 | + +### 8.3 API 接口清单 + +| 接口 | 方法 | 路径 | 说明 | +|------|------|------|------| +| 获取空间树 | GET | /api/v1/mdm/space-nodes/tree | 项目空间树 | +| 获取根节点 | GET | /api/v1/mdm/space-nodes/roots | 项目下根节点 | +| 获取节点详情 | GET | /api/v1/mdm/space-nodes/{id} | 节点详情 | +| 创建节点 | POST | /api/v1/mdm/space-nodes | 创建空间节点 | +| 更新节点 | PUT | /api/v1/mdm/space-nodes/{id} | 更新节点 | +| 删除节点 | DELETE | /api/v1/mdm/space-nodes/{id} | 删除节点 | +| 获取子节点 | GET | /api/v1/mdm/space-nodes/{id}/children | 子节点列表 | +| 批量创建 | POST | /api/v1/mdm/space-nodes/batch | 批量创建 | +| 批量导入 | POST | /api/v1/mdm/space-nodes/import | Excel导入 | + +--- + +**文档版本**: v2.0 +**最后更新**: 2026-03-23 diff --git a/02-DESIGN/standards/DEVELOPMENT_STANDARDS.md b/02-DESIGN/standards/DEVELOPMENT_STANDARDS.md index 7f1d54e..de3e6a1 100644 --- a/02-DESIGN/standards/DEVELOPMENT_STANDARDS.md +++ b/02-DESIGN/standards/DEVELOPMENT_STANDARDS.md @@ -1,8 +1,8 @@ # Ether 智慧物业管理平台 - 开发规范 -**文档版本**: v1.3 -**最后更新**: 2026-02-13 -**适用范围**: 所有微服务模块 +**文档版本**: v2.0 +**最后更新**: 2026-03-28 +**适用范围**: ether-pms 单体应用 --- @@ -874,32 +874,7 @@ management: show-details: always ``` -#### 8.3.3 网关重试配置 - -**必须配置网关重试机制**，提高服务容错能力： - -```yaml -spring: - cloud: - gateway: - routes: - - id: ether-auth - uri: lb://ether-auth - predicates: - - Path=/api/v1/auth/** - filters: - - name: Retry - args: - retries: 3 - statuses: BAD_GATEWAY,SERVICE_UNAVAILABLE - methods: GET,POST - backoff: - firstBackoff: 100ms - maxBackoff: 500ms - factor: 2 -``` - -#### 8.3.4 日志配置 +#### 8.3.3 日志配置 **必须配置文件日志输出**，便于问题排查： @@ -916,274 +891,7 @@ logging: file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n" ``` -#### 8.3.5 服务发现配置 - -**必须配置 Nacos 服务发现**，支持服务动态注册： - -```yaml -spring: - cloud: - nacos: - discovery: - enabled: true - server-addr: localhost:8848 - namespace: dev -``` - -#### 8.3.6 服务管理脚本 - -使用项目提供的脚本管理服务： - -```bash -# 健康检查 -./scripts/health-check.sh - -# 启动所有服务 -./scripts/service-manager.sh start - -# 停止所有服务 -./scripts/service-manager.sh stop - -# 重启所有服务 -./scripts/service-manager.sh restart - -# 查看服务状态 -./scripts/service-manager.sh status -``` - -### 8.4 跨业务数据访问规范 - -#### 8.4.1 架构原则 - -Ether 项目采用 **Database-per-Service** 架构，每个微服务拥有独立的数据库： - -| 数据库 | 对应服务 | 业务范围 | -| --------------- | ------------- | -------------------------------- | -| `ether_auth` | ether-auth | 用户认证、权限管理 | -| `ether_mdm` | ether-mdm | 主数据管理（项目、空间、业主等） | -| `ether_ops` | ether-ops | 运营管理（工单、巡检等） | -| `ether_finance` | ether-finance | 财务管理（收费、账单等） | - -**禁止直接跨库查询**，必须通过以下方案实现跨业务数据访问。 - -#### 8.4.2 方案一：API 组合（推荐） - -**适用场景**：实时性要求高、数据量小、调用频率低 - -```java -@Service -@RequiredArgsConstructor -public class WorkOrderClientServiceImpl implements WorkOrderClientService { - - private final RestTemplate restTemplate; - - private static final String WORK_ORDER_SERVICE_URL = "http://ether-ops/api/v1/ops/work-orders"; - - @Override - public UUID createWorkOrderFromInspection( - UUID projectId, - UUID equipmentId, - String pointName, - String abnormalDesc, - String suggestion, - String photos, - UUID inspectorId, - String inspectorName) { - - try { - HttpHeaders headers = new HttpHeaders(); - headers.setContentType(MediaType.APPLICATION_JSON); - - // 传递项目上下文 - if (ProjectContextHolder.getProjectId() != null) { - headers.set("X-Project-Id", ProjectContextHolder.getProjectId().toString()); - } - - Map workOrderRequest = new HashMap<>(); - workOrderRequest.put("orderType", "REPAIR"); - workOrderRequest.put("source", "INSPECTION"); - workOrderRequest.put("priority", "HIGH"); - workOrderRequest.put("title", "巡检异常处理 - " + pointName); - workOrderRequest.put("description", buildDescription(pointName, abnormalDesc, suggestion)); - workOrderRequest.put("equipmentId", equipmentId); - workOrderRequest.put("reporterId", inspectorId); - workOrderRequest.put("reporterName", inspectorName); - workOrderRequest.put("images", photos); - - HttpEntity> request = new HttpEntity<>(workOrderRequest, headers); - - @SuppressWarnings("unchecked") - Map response = restTemplate.postForObject( - WORK_ORDER_SERVICE_URL, - request, - Map.class - ); - - if (response != null && response.get("data") != null) { - @SuppressWarnings("unchecked") - Map data = (Map) response.get("data"); - String orderId = (String) data.get("id"); - log.info("成功创建巡检异常工单: {}, 巡检点: {}", orderId, pointName); - return UUID.fromString(orderId); - } - } catch (Exception e) { - log.error("创建巡检异常工单失败, 巡检点: {}", pointName, e); - } - return null; - } -} -``` - -**配置 RestTemplate**： - -```java -@Configuration -public class RestTemplateConfig { - - @Bean - @LoadBalanced - public RestTemplate restTemplate() { - return new RestTemplate(); - } -} -``` - -#### 8.4.3 方案二：事件驱动 - -**适用场景**：异步处理、削峰填谷、最终一致性可接受 - -```java -// 事件发布方 -@Service -@RequiredArgsConstructor -public class InspectionService { - - private final RabbitTemplate rabbitTemplate; - - @Value("${ether.mq.exchange.inspection}") - private String inspectionExchange; - - public void reportAbnormality(InspectionResult result) { - InspectionAbnormalEvent event = new InspectionAbnormalEvent(); - event.setProjectId(result.getProjectId()); - event.setEquipmentId(result.getEquipmentId()); - event.setAbnormalDesc(result.getAbnormalDesc()); - event.setTimestamp(LocalDateTime.now()); - - rabbitTemplate.convertAndSend( - inspectionExchange, - "inspection.abnormal", - event - ); - - log.info("发布巡检异常事件: {}", event); - } -} - -// 事件消费方 -@Component -@RequiredArgsConstructor -@RabbitListener(queues = "ops.inspection.abnormal") -public class InspectionAbnormalHandler { - - private final WorkOrderService workOrderService; - - @RabbitHandler - public void handleAbnormalInspection(InspectionAbnormalEvent event) { - log.info("接收巡检异常事件: {}", event); - - WorkOrderCreateRequest request = new WorkOrderCreateRequest(); - request.setOrderType("REPAIR"); - request.setSource("INSPECTION"); - request.setPriority("HIGH"); - request.setTitle("巡检异常处理 - " + event.getPointName()); - request.setEquipmentId(event.getEquipmentId()); - - workOrderService.create(request); - } -} -``` - -**RabbitMQ 配置**： - -```yaml -spring: - rabbitmq: - host: localhost - port: 5672 - username: ${MQ_USERNAME:ether} - password: ${MQ_PASSWORD:ether123} - -ether: - mq: - exchange: - inspection: ether.inspection.exchange -``` - -#### 8.4.4 方案三：数据冗余（慎用） - -**适用场景**：高频查询、实时性要求极高、数据变更频率低 - -```java -// 在 MDM 服务中冗余存储用户基本信息 -@Entity -@Table(name = "mdm_user_snapshot") -public class UserSnapshot { - - @Id - private UUID userId; - - private String username; - private String realName; - private String phone; - - @LastModifiedDate - private LocalDateTime updatedAt; - - // 冗余字段，通过事件同步更新 -} - -// 监听用户变更事件，同步更新冗余数据 -@Component -@RequiredArgsConstructor -@RabbitListener(queues = "mdm.user.sync") -public class UserSyncHandler { - - private final UserSnapshotRepository userSnapshotRepository; - - @RabbitHandler - public void handleUserChange(UserChangedEvent event) { - UserSnapshot snapshot = new UserSnapshot(); - snapshot.setUserId(event.getUserId()); - snapshot.setUsername(event.getUsername()); - snapshot.setRealName(event.getRealName()); - snapshot.setPhone(event.getPhone()); - snapshot.setUpdatedAt(LocalDateTime.now()); - - userSnapshotRepository.save(snapshot); - } -} -``` - -**注意**：数据冗余方案会增加数据一致性维护成本，**仅在高频查询场景使用**。 - -#### 8.4.5 方案选择指南 - -| 场景 | 推荐方案 | 理由 | -| ---------------------- | -------- | ------------------ | -| 低频调用、实时性要求高 | API 组合 | 简单可靠、数据实时 | -| 异步处理、批量操作 | 事件驱动 | 解耦、削峰填谷 | -| 高频查询、数据变更少 | 数据冗余 | 查询高效、减少调用 | -| 复杂报表、数据分析 | CQRS | 读写分离、独立优化 | - -#### 8.4.6 禁止事项 - -| 禁止行为 | 原因 | 替代方案 | -| ---------------------- | ---------------------- | --------------------- | -| 直接跨库 JOIN | 破坏服务边界、耦合严重 | API 组合或事件驱动 | -| 直接访问其他服务数据库 | 安全风险、难以维护 | 通过服务 API 访问 | -| 分布式事务（XA） | 性能差、复杂度高 | 最终一致性 + 补偿机制 | -| 循环调用服务 API | 性能问题、死锁风险 | 批量接口或事件驱动 | +#### 8.3.4 健康检查配置 --- diff --git a/plans/2026-03-23-equipment-enhancement-plan.md b/plans/2026-03-23-equipment-enhancement-plan.md new file mode 100644 index 0000000..40d99d9 --- /dev/null +++ b/plans/2026-03-23-equipment-enhancement-plan.md @@ -0,0 +1,1461 @@ +# 设施设备管理增强功能开发计划 + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** 实现非居物业设施设备管理增强功能（M02-13~18），包括设备技术参数扩展、预防性维护引擎、能耗监控、备件库存、故障预测、点检标准库 + +**Architecture:** 基于现有 ether-pms 单体架构，在 module-mdm 模块新增设备管理相关实体和服务，前端新增设备管理页面。能耗监控和故障预测作为独立功能模块开发。 + +**Tech Stack:** Spring Boot 3.x + JPA + PostgreSQL + Vue3 + TypeScript + Ant Design Vue + +--- + +## 开发阶段总览 + +``` +阶段一（M02-13）：设备技术参数扩展 - 约3天 +阶段二（M02-14）：预防性维护引擎 - 约5天 +阶段三（M02-15）：能耗监控管理 - 约4天 +阶段四（M02-16）：备件库存管理 - 约4天 +阶段五（M02-17）：设备故障预测 - 约3天 +阶段六（M02-18）：设备点检标准库 - 约3天 +───────────────────────────────────────── +总计 约22天 +``` + +--- + +## 阶段一：M02-13 设备技术参数扩展 + +### 数据库迁移 + +**文件:** `ether-pms/src/main/resources/db/migration/V10__add_equipment_extension_fields.sql` + +```sql +-- 添加设备扩展字段到 mdm_space_node 表（设备关联空间节点） +ALTER TABLE mdm_space_node ADD COLUMN design_life_years INTEGER; +ALTER TABLE mdm_space_node ADD COLUMN rated_power DECIMAL(10,2); +ALTER TABLE mdm_space_node ADD COLUMN rated_voltage VARCHAR(20); +ALTER TABLE mdm_space_node ADD COLUMN rated_current DECIMAL(10,2); +ALTER TABLE mdm_space_node ADD COLUMN maintenance_vendor VARCHAR(100); +ALTER TABLE mdm_space_node ADD COLUMN maintenance_vendor_contact VARCHAR(50); +ALTER TABLE mdm_space_node ADD COLUMN maintenance_vendor_phone VARCHAR(20); +ALTER TABLE mdm_space_node ADD COLUMN maintenance_contract_no VARCHAR(50); +ALTER TABLE mdm_space_node ADD COLUMN maintenance_contract_start DATE; +ALTER TABLE mdm_space_node ADD COLUMN maintenance_contract_end DATE; +ALTER TABLE mdm_space_node ADD COLUMN special_equipment_type VARCHAR(50); +ALTER TABLE mdm_space_node ADD COLUMN special_equipment_cert VARCHAR(100); +ALTER TABLE mdm_space_node ADD COLUMN inspection_cycle INTEGER; +ALTER TABLE mdm_space_node ADD COLUMN next_inspection_date DATE; +ALTER TABLE mdm_space_node ADD COLUMN last_inspection_date DATE; +ALTER TABLE mdm_space_node ADD COLUMN last_inspection_result VARCHAR(20); +ALTER TABLE mdm_space_node ADD COLUMN common_spare_parts JSONB; +ALTER TABLE mdm_space_node ADD COLUMN energy_consumption_standard DECIMAL(12,2); +ALTER TABLE mdm_space_node ADD COLUMN installation_environment VARCHAR(50); +ALTER TABLE mdm_space_node ADD COLUMN protection_level VARCHAR(20); +``` + +--- + +### Task 1.1: 创建设备分类枚举 + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/enums/EquipmentCategory.java` + +```java +package com.ether.pms.mdm.enums; + +public enum EquipmentCategory { + HVAC("暖通空调"), + ELECTRICAL("电气设备"), + FIRE("消防设备"), + ELEVATOR("电梯设备"), + SECURITY("安防设备"), + 给排水("给排水设备"), + LIGHTING("照明设备"), + SPECIAL("特种设备"); + + private final String desc; + EquipmentCategory(String desc) { this.desc = desc; } + public String getDesc() { return desc; } +} +``` + +**Step 1:** 创建枚举类 +**Step 2:** 验证编译通过 +**Step 3:** Commit: `feat: add equipment category enum` + +--- + +### Task 1.2: 创建设备类型枚举 + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/enums/EquipmentType.java` + +```java +package com.ether.pms.mdm.enums; + +public enum EquipmentType { + CENTRAL_AC("中央空调", EquipmentCategory.HVAC), + AIR_CONDITIONER("分体空调", EquipmentCategory.HVAC), + AIR_HANDLING_UNIT("空气处理机组", EquipmentCategory.HVAC), + FAN_COIL("风机盘管", EquipmentCategory.HVAC), + LOW_VOLTAGE_CABINET("低压配电柜", EquipmentCategory.ELECTRICAL), + TRANSFORMER("变压器", EquipmentCategory.ELECTRICAL), + GENERATOR("发电机", EquipmentCategory.ELECTRICAL), + UPS("不间断电源", EquipmentCategory.ELECTRICAL), + FIRE_PUMP("消防泵", EquipmentCategory.FIRE), + SPRINKLER("喷淋系统", EquipmentCategory.FIRE), + FIRE_ALARM("火灾报警系统", EquipmentCategory.FIRE), + ELEVATOR("电梯", EquipmentCategory.ELEVATOR), + CCTV("监控系统", EquipmentCategory.SECURITY), + ACCESS_CONTROL("门禁系统", EquipmentCategory.SECURITY), + WATER_PUMP("给水泵", EquipmentCategory.WATER_DRAINAGE), + DRAINAGE_PUMP("排水泵", EquipmentCategory.WATER_DRAINAGE), + LED_LIGHT("LED灯具", EquipmentCategory.LIGHTING), + HIGH_BAY_LIGHT("工矿灯", EquipmentCategory.LIGHTING); + + private final String desc; + private final EquipmentCategory category; + EquipmentType(String desc, EquipmentCategory category) { + this.desc = desc; + this.category = category; + } + public String getDesc() { return desc; } + public EquipmentCategory getCategory() { return category; } +} +``` + +**Step 1:** 创建枚举类 +**Step 2:** 验证编译通过 +**Step 3:** Commit: `feat: add equipment type enum` + +--- + +### Task 1.3: 更新SpaceNode实体 + +**Files:** +- Modify: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/SpaceNode.java` + +在现有实体末尾添加扩展字段： + +```java +// ========== 设备扩展字段 ========== +@Column(name = "is_equipment") +private Boolean isEquipment = false; + +@Column(name = "design_life_years") +private Integer designLifeYears; + +@Column(name = "rated_power", precision = 10, scale = 2) +private BigDecimal ratedPower; + +@Column(name = "rated_voltage", length = 20) +private String ratedVoltage; + +@Column(name = "rated_current", precision = 10, scale = 2) +private BigDecimal ratedCurrent; + +@Column(name = "maintenance_vendor", length = 100) +private String maintenanceVendor; + +@Column(name = "maintenance_vendor_contact", length = 50) +private String maintenanceVendorContact; + +@Column(name = "maintenance_vendor_phone", length = 20) +private String maintenanceVendorPhone; + +@Column(name = "maintenance_contract_no", length = 50) +private String maintenanceContractNo; + +@Column(name = "maintenance_contract_start") +private LocalDate maintenanceContractStart; + +@Column(name = "maintenance_contract_end") +private LocalDate maintenanceContractEnd; + +@Column(name = "special_equipment_type", length = 50) +private String specialEquipmentType; + +@Column(name = "special_equipment_cert", length = 100) +private String specialEquipmentCert; + +@Column(name = "inspection_cycle") +private Integer inspectionCycle; + +@Column(name = "next_inspection_date") +private LocalDate nextInspectionDate; + +@Column(name = "last_inspection_date") +private LocalDate lastInspectionDate; + +@Column(name = "last_inspection_result", length = 20) +private String lastInspectionResult; + +@Column(name = "common_spare_parts", columnDefinition = "TEXT") +private String commonSpareParts; + +@Column(name = "energy_consumption_standard", precision = 12, scale = 2) +private BigDecimal energyConsumptionStandard; + +@Column(name = "installation_environment", length = 50) +private String installationEnvironment; + +@Column(name = "protection_level", length = 20) +private String protectionLevel; +// ========== 设备扩展字段结束 ========== +``` + +**Step 1:** 添加扩展字段到 SpaceNode 实体 +**Step 2:** 运行 `cd ether-pms && mvn compile` 验证 +**Step 3:** Commit: `feat: add equipment extension fields to SpaceNode` + +--- + +### Task 1.4: 创建SpaceNode DTO + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/dto/SpaceNodeEquipmentDTO.java` + +```java +package com.ether.pms.mdm.dto; + +import lombok.Data; +import lombok.EqualsAndHashCode; +import java.math.BigDecimal; +import java.time.LocalDate; +import java.util.List; + +@Data +@EqualsAndHashCode(callSuper = true) +public class SpaceNodeEquipmentDTO extends SpaceNodeDTO { + + private Boolean isEquipment; + private Integer designLifeYears; + private BigDecimal ratedPower; + private String ratedVoltage; + private BigDecimal ratedCurrent; + private String maintenanceVendor; + private String maintenanceVendorContact; + private String maintenanceVendorPhone; + private String maintenanceContractNo; + private LocalDate maintenanceContractStart; + private LocalDate maintenanceContractEnd; + private String specialEquipmentType; + private String specialEquipmentCert; + private Integer inspectionCycle; + private LocalDate nextInspectionDate; + private LocalDate lastInspectionDate; + private String lastInspectionResult; + private List commonSpareParts; + private BigDecimal energyConsumptionStandard; + private String installationEnvironment; + private String protectionLevel; + + @Data + public static class SparePartInfo { + private String name; + private String model; + private Integer quantity; + } +} +``` + +**Step 1:** 创建 DTO 类 +**Step 2:** 运行 `cd ether-pms && mvn compile` 验证 +**Step 3:** Commit: `feat: add SpaceNodeEquipmentDTO` + +--- + +### Task 1.5: 更新SpaceNodeService + +**Files:** +- Modify: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/SpaceNodeService.java` + +添加设备相关方法： + +```java +public SpaceNodeEquipmentDTO getEquipmentById(UUID id) { + SpaceNode node = spaceNodeRepository.findById(id) + .orElseThrow(() -> new BusinessException("EQUIPMENT_NOT_FOUND")); + return convertToEquipmentDTO(node); +} + +public List getSpecialEquipmentList(UUID projectId) { + List list = spaceNodeRepository.findByProjectIdAndIsEquipmentAndSpecialEquipmentTypeIsNotNull( + projectId, true); + return list.stream().map(this::convertToEquipmentDTO).collect(Collectors.toList()); +} + +public List getExpiringInspectionEquipment(UUID projectId, Integer daysAhead) { + LocalDate threshold = LocalDate.now().plusDays(daysAhead); + List list = spaceNodeRepository + .findByProjectIdAndIsEquipmentAndNextInspectionDateBefore(projectId, true, threshold); + return list.stream().map(this::convertToEquipmentDTO).collect(Collectors.toList()); +} +``` + +**Step 1:** 添加服务方法 +**Step 2:** 添加单元测试 +**Step 3:** 运行测试验证 +**Step 4:** Commit: `feat: add equipment service methods` + +--- + +### Task 1.6: 更新SpaceNodeController + +**Files:** +- Modify: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/controller/SpaceNodeController.java` + +添加设备相关API： + +```java +@GetMapping("/{id}/equipment") +public ApiResponse getEquipment(@PathVariable UUID id) { + return ApiResponse.success(spaceNodeService.getEquipmentById(id)); +} + +@GetMapping("/special-equipment") +public ApiResponse> getSpecialEquipment( + @RequestParam UUID projectId) { + return ApiResponse.success(spaceNodeService.getSpecialEquipmentList(projectId)); +} + +@GetMapping("/expiring-inspection") +public ApiResponse> getExpiringInspection( + @RequestParam UUID projectId, + @RequestParam(defaultValue = "90") Integer daysAhead) { + return ApiResponse.success(spaceNodeService.getExpiringInspectionEquipment(projectId, daysAhead)); +} +``` + +**Step 1:** 添加控制器端点 +**Step 2:** 使用 curl 测试端点 +**Step 3:** Commit: `feat: add equipment API endpoints` + +--- + +### Task 1.7: 前端 - 创建设备管理页面 + +**Files:** +- Create: `ether-admin/src/views/equipment/EquipmentList.vue` +- Create: `ether-admin/src/views/equipment/EquipmentDetail.vue` +- Create: `ether-admin/src/api/equipment.ts` + +**Step 1:** 创建 API 模块 `ether-admin/src/api/equipment.ts` + +```typescript +import request from '@/utils/request' + +export interface EquipmentForm { + id?: string + code: string + name: string + nodeType: string + locationDesc?: string + designLifeYears?: number + ratedPower?: number + ratedVoltage?: string + maintenanceVendor?: string + maintenanceVendorPhone?: string + specialEquipmentType?: string + inspectionCycle?: number + nextInspectionDate?: string + [key: string]: any +} + +export function getEquipmentList(params: any) { + return request({ + url: '/api/v1/mdm/space-nodes/equipment', + method: 'get', + params + }) +} + +export function getEquipmentDetail(id: string) { + return request({ + url: `/api/v1/mdm/space-nodes/${id}/equipment`, + method: 'get' + }) +} + +export function getSpecialEquipment(projectId: string) { + return request({ + url: '/api/v1/mdm/space-nodes/special-equipment', + method: 'get', + params: { projectId } + }) +} + +export function getExpiringInspection(projectId: string, daysAhead?: number) { + return request({ + url: '/api/v1/mdm/space-nodes/expiring-inspection', + method: 'get', + params: { projectId, daysAhead } + }) +} +``` + +**Step 2:** 创建设备列表页面 `EquipmentList.vue` + +**Step 3:** 创建设备详情页面 `EquipmentDetail.vue` + +**Step 4:** 运行 `npm run build` 验证前端编译 + +**Step 5:** Commit: `feat: add equipment management pages` + +--- + +## 阶段二：M02-14 预防性维护引擎 + +### Task 2.1: 创建维保计划实体 + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/MaintenancePlan.java` + +```java +package com.ether.pms.mdm.entity; + +import jakarta.persistence.*; +import lombok.Data; +import java.time.LocalDateTime; +import java.util.UUID; + +@Entity +@Table(name = "ops_maintenance_plan") +@Data +public class MaintenancePlan { + + @Id + @GeneratedValue(strategy = GenerationType.UUID) + private UUID id; + + @Column(name = "project_id", nullable = false) + private UUID projectId; + + @Column(name = "plan_code", nullable = false, unique = true) + private String planCode; + + @Column(name = "plan_name", nullable = false) + private String planName; + + @Column(name = "equipment_type") + private String equipmentType; + + @Column(name = "trigger_type", nullable = false) + @Enumerated(EnumType.STRING) + private TriggerType triggerType; + + public enum TriggerType { + TIME_BASED, // 时间触发 + HOURS_BASED, // 运行小时触发 + CYCLES_BASED, // 次数触发 + CONDITION_BASED // 条件触发 + } + + @Column(name = "trigger_value") + private Integer triggerValue; + + @Column(name = "trigger_unit") + private String triggerUnit; + + @Column(name = "maintenance_items", columnDefinition = "TEXT") + private String maintenanceItems; + + @Column(name = "estimated_duration") + private Integer estimatedDuration; + + @Column(name = "assigned_to") + private UUID assignedTo; + + @Column(name = "sla_response_hours") + private Integer slaResponseHours; + + @Column(name = "sla_complete_hours") + private Integer slaCompleteHours; + + @Column(nullable = false) + @Enumerated(EnumType.STRING) + private Status status = Status.ACTIVE; + + public enum Status { + ACTIVE, INACTIVE + } + + @Column(name = "created_at") + private LocalDateTime createdAt; + + @Column(name = "updated_at") + private LocalDateTime updatedAt; + + @PrePersist + public void prePersist() { + createdAt = LocalDateTime.now(); + updatedAt = LocalDateTime.now(); + } + + @PreUpdate + public void preUpdate() { + updatedAt = LocalDateTime.now(); + } +} +``` + +**Step 1:** 创建实体类 +**Step 2:** 运行 `mvn compile` 验证 +**Step 3:** Commit: `feat: add MaintenancePlan entity` + +--- + +### Task 2.2: 创建维保任务实体 + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/MaintenanceTask.java` + +```java +package com.ether.pms.mdm.entity; + +import jakarta.persistence.*; +import lombok.Data; +import java.math.BigDecimal; +import java.time.LocalDateTime; +import java.util.UUID; + +@Entity +@Table(name = "ops_maintenance_task") +@Data +public class MaintenanceTask { + + @Id + @GeneratedValue(strategy = GenerationType.UUID) + private UUID id; + + @Column(name = "project_id", nullable = false) + private UUID projectId; + + @Column(name = "task_code", nullable = false, unique = true) + private String taskCode; + + @Column(name = "plan_id") + private UUID planId; + + @Column(name = "equipment_id") + private UUID equipmentId; + + @Column(name = "task_type") + @Enumerated(EnumType.STRING) + private TaskType taskType = TaskType.PREVENTIVE; + + public enum TaskType { + PREVENTIVE, // 预防性维护 + CORRECTIVE // 纠正性维护 + } + + @Column(name = "trigger_type") + @Enumerated(EnumType.STRING) + private MaintenancePlan.TriggerType triggerType; + + @Column(name = "maintenance_items", columnDefinition = "TEXT") + private String maintenanceItems; + + @Column(nullable = false) + @Enumerated(EnumType.STRING) + private Status status = Status.PENDING; + + public enum Status { + PENDING, // 待接受 + ACCEPTED, // 已接受 + IN_PROGRESS, // 执行中 + COMPLETED, // 已完成 + CANCELLED // 已取消 + } + + @Column(name = "assigned_to") + private UUID assignedTo; + + @Column(name = "scheduled_date") + private LocalDateTime scheduledDate; + + @Column(name = "actual_start_date") + private LocalDateTime actualStartDate; + + @Column(name = "actual_end_date") + private LocalDateTime actualEndDate; + + @Column(name = "labor_hours", precision = 10, scale = 2) + private BigDecimal laborHours; + + @Column(name = "materials_cost", precision = 12, scale = 2) + private BigDecimal materialsCost; + + @Column(columnDefinition = "TEXT") + private String remarks; + + @Column(name = "created_at") + private LocalDateTime createdAt; + + @Column(name = "updated_at") + private LocalDateTime updatedAt; + + @PrePersist + public void prePersist() { + createdAt = LocalDateTime.now(); + updatedAt = LocalDateTime.now(); + } + + @PreUpdate + public void preUpdate() { + updatedAt = LocalDateTime.now(); + } +} +``` + +**Step 1:** 创建实体类 +**Step 2:** 运行 `mvn compile` 验证 +**Step 3:** Commit: `feat: add MaintenanceTask entity` + +--- + +### Task 2.3: 创建维保Repository + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/repository/MaintenancePlanRepository.java` +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/repository/MaintenanceTaskRepository.java` + +```java +package com.ether.pms.mdm.repository; + +public interface MaintenancePlanRepository extends JpaRepository { + List findByProjectIdAndStatus(UUID projectId, MaintenancePlan.Status status); + Optional findByPlanCode(String planCode); +} + +public interface MaintenanceTaskRepository extends JpaRepository { + List findByProjectIdAndStatus(UUID projectId, MaintenanceTask.Status status); + List findByAssignedToAndStatus(UUID assignedTo, MaintenanceTask.Status status); + List findByEquipmentIdAndStatusNot(UUID equipmentId, MaintenanceTask.Status status); + Optional findByTaskCode(String taskCode); +} +``` + +**Step 1:** 创建 Repository +**Step 2:** 添加查询方法单元测试 +**Step 3:** Commit: `feat: add maintenance repositories` + +--- + +### Task 2.4: 创建维保Service + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/MaintenancePlanService.java` +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/MaintenanceTaskService.java` +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/impl/MaintenancePlanServiceImpl.java` +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/impl/MaintenanceTaskServiceImpl.java` + +**Service核心方法：** + +```java +// MaintenancePlanService +UUID createPlan(MaintenancePlan plan); +List getActivePlansByProject(UUID projectId); +void updatePlan(UUID id, MaintenancePlan plan); +void deactivatePlan(UUID id); + +// MaintenanceTaskService +List getTasksByAssignee(UUID assignee, String status); +void acceptTask(UUID taskId, UUID userId); +void startTask(UUID taskId); +void completeTask(UUID taskId, BigDecimal laborHours, BigDecimal materialsCost, String remarks); +List getOverdueTasks(); +``` + +**Step 1:** 创建 Service 接口和实现 +**Step 2:** 添加单元测试 +**Step 3:** 运行测试验证 +**Step 4:** Commit: `feat: add maintenance service` + +--- + +### Task 2.5: 创建维保Controller + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/controller/MaintenancePlanController.java` +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/controller/MaintenanceTaskController.java` + +**API 设计：** + +| 方法 | 路径 | 描述 | +|------|------|------| +| POST | /api/v1/ops/maintenance-plans | 创建维保计划 | +| GET | /api/v1/ops/maintenance-plans | 获取维保计划列表 | +| PUT | /api/v1/ops/maintenance-plans/{id} | 更新维保计划 | +| DELETE | /api/v1/ops/maintenance-plans/{id} | 删除维保计划 | +| GET | /api/v1/ops/maintenance-tasks | 获取维保任务列表 | +| POST | /api/v1/ops/maintenance-tasks/{id}/accept | 接受任务 | +| POST | /api/v1/ops/maintenance-tasks/{id}/start | 开始执行 | +| POST | /api/v1/ops/maintenance-tasks/{id}/complete | 完成维保 | + +**Step 1:** 创建 Controller +**Step 2:** 使用 curl 测试 API +**Step 3:** Commit: `feat: add maintenance controllers` + +--- + +### Task 2.6: 创建定时任务 - 维保触发检查 + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/scheduler/MaintenanceScheduler.java` + +```java +package com.ether.pms.mdm.scheduler; + +@Component +@RequiredArgsConstructor +public class MaintenanceScheduler { + + private final MaintenancePlanService planService; + private final MaintenanceTaskService taskService; + + @Scheduled(cron = "0 0 1 * * ?") // 每天凌晨1点 + public void checkTimeBasedMaintenance() { + log.info("检查时间触发的维保计划..."); + List plans = planService.getTimeBasedActivePlans(); + plans.forEach(plan -> taskService.generateTasksFromPlan(plan)); + } + + @Scheduled(cron = "0 0 * * * ?") // 每小时 + public void checkHourlyMaintenance() { + log.info("检查运行小时触发的维保计划..."); + // 检查运行小时触发的计划 + } +} +``` + +**Step 1:** 创建定时任务类 +**Step 2:** 在 PmsApplication 添加 `@EnableScheduling` +**Step 3:** 测试定时任务执行 +**Step 4:** Commit: `feat: add maintenance scheduler` + +--- + +## 阶段三：M02-15 能耗监控管理 + +### Task 3.1: 创建能耗相关实体 + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/EnergyMeter.java` +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/EnergyConsumption.java` + +```java +@Entity +@Table(name = "ops_energy_meter") +@Data +public class EnergyMeter { + @Id + @GeneratedValue(strategy = GenerationType.UUID) + private UUID id; + + @Column(name = "project_id", nullable = false) + private UUID projectId; + + @Column(name = "meter_code", nullable = false, unique = true) + private String meterCode; + + @Column(name = "meter_name", nullable = false) + private String meterName; + + @Column(name = "energy_type", nullable = false) + @Enumerated(EnumType.STRING) + private EnergyType energyType; + + public enum EnergyType { + LIGHTING, // 照明插座用电 + HVAC, // 空调用电 + POWER, // 动力用电 + SPECIAL, // 特殊用电 + WATER, // 给排水 + GAS // 燃气 + } + + @Column(name = "space_node_id") + private UUID spaceNodeId; + + @Column(name = "installation_location") + private String installationLocation; + + @Column(name = "unit_price", precision = 10, scale = 4) + private BigDecimal unitPrice; + + @Column(nullable = false) + @Enumerated(EnumType.STRING) + private Status status = Status.ACTIVE; + + public enum Status { ACTIVE, INACTIVE } +} + +@Entity +@Table(name = "ops_energy_consumption") +@Data +public class EnergyConsumption { + @Id + @GeneratedValue(strategy = GenerationType.UUID) + private UUID id; + + @Column(name = "project_id", nullable = false) + private UUID projectId; + + @Column(name = "meter_id", nullable = false) + private UUID meterId; + + @Column(name = "consumption_date", nullable = false) + private LocalDate consumptionDate; + + @Column(name = "previous_reading", precision = 12, scale = 2) + private BigDecimal previousReading; + + @Column(name = "current_reading", precision = 12, scale = 2) + private BigDecimal currentReading; + + @Column(nullable = false, precision = 12, scale = 2) + private BigDecimal consumption; + + @Column(precision = 10, scale = 2) + private BigDecimal amount; + + @Column(name = "recorded_by") + private UUID recordedBy; + + @Column(name = "record_method") + @Enumerated(EnumType.STRING) + private RecordMethod recordMethod = RecordMethod.MANUAL; + + public enum RecordMethod { MANUAL, IOT } +} +``` + +**Step 1:** 创建实体 +**Step 2:** 运行编译验证 +**Step 3:** Commit: `feat: add energy management entities` + +--- + +### Task 3.2: 创建能耗Service + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/EnergyMeterService.java` +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/EnergyConsumptionService.java` +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/EnergyStatisticsService.java` + +```java +// EnergyConsumptionService +void recordConsumption(UUID meterId, BigDecimal currentReading, UUID recordedBy); +List getConsumptionByMeter(UUID meterId, LocalDate startDate, LocalDate endDate); + +// EnergyStatisticsService +Map getConsumptionByType(UUID projectId, LocalDate month); +BigDecimal getUnitConsumption(UUID projectId, LocalDate month); // kWh/m² +Map getConsumptionTrend(UUID projectId, Integer months); +List getAlerts(UUID projectId); +``` + +**Step 1:** 创建 Service +**Step 2:** 添加单元测试 +**Step 3:** Commit: `feat: add energy service` + +--- + +### Task 3.3: 创建能耗Controller + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/controller/EnergyController.java` + +**API 设计：** + +| 方法 | 路径 | 描述 | +|------|------|------| +| GET | /api/v1/ops/energy-meters | 获取计量点列表 | +| POST | /api/v1/ops/energy-meters | 创建计量点 | +| POST | /api/v1/ops/energy-consumption | 录入能耗数据 | +| GET | /api/v1/ops/energy-statistics/by-type | 按分项统计 | +| GET | /api/v1/ops/energy-statistics/unit-consumption | 单方能耗统计 | +| GET | /api/v1/ops/energy-statistics/trend | 能耗趋势 | + +**Step 1:** 创建 Controller +**Step 2:** 测试 API +**Step 3:** Commit: `feat: add energy controller` + +--- + +## 阶段四：M02-16 备件库存管理 + +### Task 4.1: 创建备件实体 + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/SparePart.java` +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/SparePartRecord.java` + +```java +@Entity +@Table(name = "ops_spare_part") +@Data +public class SparePart { + @Id + @GeneratedValue(strategy = GenerationType.UUID) + private UUID id; + + @Column(name = "project_id", nullable = false) + private UUID projectId; + + @Column(name = "spare_part_code", nullable = false, unique = true) + private String sparePartCode; + + @Column(name = "spare_part_name", nullable = false) + private String sparePartName; + + @Column(name = "category_id") + private UUID categoryId; + + @Column + private String specification; + + @Column(nullable = false) + private String unit; + + @Column(name = "safe_stock") + private Integer safeStock; + + @Column(name = "current_stock") + private Integer currentStock; + + @Column(name = "unit_price", precision = 10, scale = 2) + private BigDecimal unitPrice; + + @Column + private String supplier; + + @Column(name = "location") + private String location; + + @Column + @Enumerated(EnumType.STRING) + private Status status = Status.ACTIVE; +} + +@Entity +@Table(name = "ops_spare_part_record") +@Data +public class SparePartRecord { + @Id + @GeneratedValue(strategy = GenerationType.UUID) + private UUID id; + + @Column(name = "record_code", nullable = false, unique = true) + private String recordCode; + + @Column(name = "record_type", nullable = false) + @Enumerated(EnumType.STRING) + private RecordType recordType; + + public enum RecordType { + IN, // 入库 + OUT, // 出库 + CHECK, // 盘点 + ADJUST // 调整 + } + + @Column(name = "spare_part_id", nullable = false) + private UUID sparePartId; + + @Column(nullable = false) + private Integer quantity; + + @Column(nullable = false) + private Integer balance; + + @Column(name = "related_order_id") + private UUID relatedOrderId; + + @Column(name = "recorded_by") + private UUID recordedBy; + + @Column(name = "record_date") + private LocalDateTime recordDate; +} +``` + +**Step 1:** 创建实体 +**Step 2:** 编译验证 +**Step 3:** Commit: `feat: add spare part entities` + +--- + +### Task 4.2: 创建备件Service + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/SparePartService.java` + +```java +public interface SparePartService { + SparePart create(SparePart sparePart); + void updateStock(UUID sparePartId, Integer quantity, SparePartRecord.RecordType type, UUID relatedOrderId); + List getLowStockParts(UUID projectId); + List getRecordsByPart(UUID sparePartId); +} +``` + +**Step 1:** 创建 Service +**Step 2:** 添加库存扣减逻辑（事务处理） +**Step 3:** 添加单元测试 +**Step 4:** Commit: `feat: add spare part service` + +--- + +### Task 4.3: 创建备件Controller + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/controller/SparePartController.java` + +**API 设计：** + +| 方法 | 路径 | 描述 | +|------|------|------| +| GET | /api/v1/ops/spare-parts | 获取备件列表 | +| POST | /api/v1/ops/spare-parts | 创建备件 | +| GET | /api/v1/ops/spare-parts/{id} | 获取备件详情 | +| GET | /api/v1/ops/spare-parts/low-stock | 获取低库存备件 | +| POST | /api/v1/ops/spare-part-records | 创建备件记录 | +| GET | /api/v1/ops/spare-part-records/{sparePartId} | 获取备件记录 | + +**Step 1:** 创建 Controller +**Step 2:** 测试 API +**Step 3:** Commit: `feat: add spare part controller` + +--- + +## 阶段五：M02-17 设备故障预测 + +### Task 5.1: 创建故障历史实体 + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/EquipmentFailureHistory.java` +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/EquipmentHealthScore.java` + +```java +@Entity +@Table(name = "ops_equipment_failure_history") +@Data +public class EquipmentFailureHistory { + @Id + @GeneratedValue(strategy = GenerationType.UUID) + private UUID id; + + @Column(name = "equipment_id", nullable = false) + private UUID equipmentId; + + @Column(name = "failure_date", nullable = false) + private LocalDateTime failureDate; + + @Column(name = "failure_type") + private String failureType; + + @Column(name = "failure_cause") + private String failureCause; + + @Column(name = "failure_description", columnDefinition = "TEXT") + private String failureDescription; + + @Column(name = "repair_start_time") + private LocalDateTime repairStartTime; + + @Column(name = "repair_end_time") + private LocalDateTime repairEndTime; + + @Column(name = "repair_duration", precision = 10, scale = 2) + private BigDecimal repairDuration; + + @Column(name = "repair_cost", precision = 12, scale = 2) + private BigDecimal repairCost; + + @Column(name = "spare_parts_used", columnDefinition = "TEXT") + private String sparePartsUsed; + + @Column(name = "work_order_id") + private UUID workOrderId; +} + +@Entity +@Table(name = "ops_equipment_health_score") +@Data +public class EquipmentHealthScore { + @Id + @GeneratedValue(strategy = GenerationType.UUID) + private UUID id; + + @Column(name = "equipment_id", nullable = false) + private UUID equipmentId; + + @Column(name = "score_date", nullable = false) + private LocalDate scoreDate; + + @Column(name = "health_score", precision = 5, scale = 2) + private BigDecimal healthScore; + + @Column(precision = 10, scale = 2) + private BigDecimal mtbf; + + @Column(precision = 10, scale = 2) + private BigDecimal mttr; + + @Column(name = "failure_count") + private Integer failureCount; + + @Column(name = "maintenance_completion_rate", precision = 5, scale = 2) + private BigDecimal maintenanceCompletionRate; + + @Column(name = "alert_level") + @Enumerated(EnumType.STRING) + private AlertLevel alertLevel; + + public enum AlertLevel { NORMAL, WARNING, CRITICAL } +} +``` + +**Step 1:** 创建实体 +**Step 2:** 编译验证 +**Step 3:** Commit: `feat: add equipment health entities` + +--- + +### Task 5.2: 创建故障预测Service + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/EquipmentHealthService.java` + +```java +public interface EquipmentHealthService { + + // 计算设备健康度 + EquipmentHealthScore calculateHealthScore(UUID equipmentId); + + // 获取设备MTBF + BigDecimal calculateMTBF(UUID equipmentId, Integer days); + + // 获取设备MTTR + BigDecimal calculateMTTR(UUID equipmentId, Integer days); + + // 获取设备健康度历史 + List getHealthHistory(UUID equipmentId); + + // 获取预警设备列表 + List getAlertEquipmentIds(UUID projectId, AlertLevel level); + + // 记录故障 + void recordFailure(EquipmentFailureHistory failure); +} +``` + +**健康度算法实现：** +```java +public EquipmentHealthScore calculateHealthScore(UUID equipmentId) { + // 基础分 = 100 + BigDecimal baseScore = new BigDecimal("100"); + + // 故障率扣分 = 故障次数 × 5（近30天） + int failureCount = failureHistoryRepository.countByEquipmentIdAndFailureDateAfter( + equipmentId, LocalDateTime.now().minusDays(30)); + BigDecimal failureDeduction = new BigDecimal(failureCount * 5); + + // 维保扣分 = (1 - 维保完成率) × 20 + BigDecimal maintenanceRate = maintenanceTaskService.getCompletionRate(equipmentId); + BigDecimal maintenanceDeduction = new BigDecimal("1").subtract(maintenanceRate) + .multiply(new BigDecimal("20")); + + // 年龄扣分 = 投入使用年限 × 2（最高扣10分） + SpaceNode equipment = spaceNodeRepository.findById(equipmentId).orElseThrow(); + int yearsInService = calculateYearsInService(equipment.getCreatedAt()); + BigDecimal ageDeduction = new BigDecimal(Math.min(yearsInService * 2, 10)); + + BigDecimal healthScore = baseScore + .subtract(failureDeduction) + .subtract(maintenanceDeduction) + .subtract(ageDeduction); + + return healthScore; +} +``` + +**Step 1:** 创建 Service 接口 +**Step 2:** 实现计算逻辑 +**Step 3:** 添加单元测试 +**Step 4:** Commit: `feat: add equipment health service` + +--- + +## 阶段六：M02-18 设备点检标准库 + +### Task 6.1: 创建点检模板实体 + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/entity/InspectionTemplate.java` + +```java +@Entity +@Table(name = "ops_inspection_template") +@Data +public class InspectionTemplate { + @Id + @GeneratedValue(strategy = GenerationType.UUID) + private UUID id; + + @Column(name = "project_id", nullable = false) + private UUID projectId; + + @Column(name = "template_code", nullable = false, unique = true) + private String templateCode; + + @Column(name = "template_name", nullable = false) + private String templateName; + + @Column(name = "equipment_type") + private String equipmentType; + + @Column(name = "inspection_items", columnDefinition = "TEXT") + private String inspectionItems; + + @Column(name = "estimated_duration") + private Integer estimatedDuration; + + @Column(nullable = false) + @Enumerated(EnumType.STRING) + private Status status = Status.ACTIVE; + + public enum Status { ACTIVE, INACTIVE } + + @Column + private Integer version; + + @Column(name = "created_by") + private UUID createdBy; + + @Column(name = "created_at") + private LocalDateTime createdAt; + + @PrePersist + public void prePersist() { + createdAt = LocalDateTime.now(); + if (version == null) version = 1; + } +} +``` + +**Step 1:** 创建实体 +**Step 2:** 编译验证 +**Step 3:** Commit: `feat: add inspection template entity` + +--- + +### Task 6.2: 创建点检Service + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/service/InspectionTemplateService.java` + +```java +public interface InspectionTemplateService { + InspectionTemplate create(InspectionTemplate template); + InspectionTemplate copyTemplate(UUID templateId, String newName); + List getTemplatesByType(String equipmentType); + void updateTemplate(UUID id, InspectionTemplate template); +} +``` + +**点检项目JSON结构：** +```json +{ + "items": [ + { + "itemCode": "I001", + "itemName": "电机温度检查", + "inspectionPoint": "电机外壳", + "inspectionMethod": "HAND_FEEL", + "standard": "温度正常，无明显过热", + "normalValue": "≤60°C", + "abnormalValue": ">70°C", + "handlingMethod": "停机检查，联系维修", + "isRequired": true + } + ] +} +``` + +**Step 1:** 创建 Service +**Step 2:** 添加 JSON 解析/存储逻辑 +**Step 3:** Commit: `feat: add inspection template service` + +--- + +### Task 6.3: 创建点检Controller + +**Files:** +- Create: `ether-pms/module-mdm/src/main/java/com/ether/pms/mdm/controller/InspectionTemplateController.java` + +**API 设计：** + +| 方法 | 路径 | 描述 | +|------|------|------| +| GET | /api/v1/ops/inspection-templates | 获取点检模板列表 | +| POST | /api/v1/ops/inspection-templates | 创建点检模板 | +| GET | /api/v1/ops/inspection-templates/{id} | 获取模板详情 | +| PUT | /api/v1/ops/inspection-templates/{id} | 更新模板 | +| POST | /api/v1/ops/inspection-templates/{id}/copy | 复制模板 | +| GET | /api/v1/ops/inspection-templates/by-type/{equipmentType} | 按设备类型获取 | + +**Step 1:** 创建 Controller +**Step 2:** 测试 API +**Step 3:** Commit: `feat: add inspection template controller` + +--- + +## 前端页面开发（统一在最后） + +### Task F.1: 设备管理页面 + +**Files:** +- Create: `ether-admin/src/views/equipment/EquipmentList.vue` +- Create: `ether-admin/src/views/equipment/EquipmentDetail.vue` +- Create: `ether-admin/src/views/equipment/EquipmentForm.vue` +- Modify: `ether-admin/src/views/Layout.vue` - 添加设备管理菜单 + +**Step 1:** 创建设备列表页面 +**Step 2:** 创建设备详情页面 +**Step 3:** 添加设备表单组件 +**Step 4:** 更新 Layout 添加菜单 +**Step 5:** 运行 `npm run build` 验证 +**Step 6:** Commit: `feat: add equipment management frontend` + +--- + +### Task F.2: 维保管理页面 + +**Files:** +- Create: `ether-admin/src/views/maintenance/PlanList.vue` +- Create: `ether-admin/src/views/maintenance/TaskList.vue` + +**Step 1:** 创建维保计划列表 +**Step 2:** 创建维保任务列表 +**Step 3:** 编译验证 +**Step 4:** Commit: `feat: add maintenance management frontend` + +--- + +### Task F.3: 能耗监控页面 + +**Files:** +- Create: `ether-admin/src/views/energy/EnergyMeterList.vue` +- Create: `ether-admin/src/views/energy/EnergyStatistics.vue` + +**Step 1:** 创建计量点管理页面 +**Step 2:** 创建能耗统计页面 +**Step 3:** 编译验证 +**Step 4:** Commit: `feat: add energy monitoring frontend` + +--- + +### Task F.4: 备件管理页面 + +**Files:** +- Create: `ether-admin/src/views/sparepart/SparePartList.vue` +- Create: `ether-admin/src/views/sparepart/SparePartRecord.vue` + +**Step 1:** 创建备件列表页面 +**Step 2:** 创建备件记录页面 +**Step 3:** 编译验证 +**Step 4:** Commit: `feat: add spare part management frontend` + +--- + +## 测试验证 + +### Task T.1: 后端单元测试 + +为每个 Service 创建单元测试： +- `SpaceNodeServiceTest` +- `MaintenancePlanServiceTest` +- `MaintenanceTaskServiceTest` +- `EnergyConsumptionServiceTest` +- `SparePartServiceTest` +- `EquipmentHealthServiceTest` + +```bash +cd ether-pms && mvn test -Dtest=*ServiceTest +``` + +--- + +### Task T.2: 后端集成测试 + +```bash +# 使用 H2 内存数据库进行集成测试 +cd ether-pms && mvn verify +``` + +--- + +### Task T.3: 前端构建验证 + +```bash +cd ether-admin && npm run build +``` + +--- + +### Task T.4: E2E 测试 + +使用 Playwright 进行 E2E 测试： + +```bash +# 设备管理 E2E +npx playwright test tests/equipment.spec.ts + +# 维保管理 E2E +npx playwright test tests/maintenance.spec.ts +``` + +--- + +## 数据库迁移脚本汇总 + +**文件列表：** +1. `V10__add_equipment_extension_fields.sql` - 设备扩展字段 +2. `V11__create_maintenance_tables.sql` - 维保计划和任务表 +3. `V12__create_energy_tables.sql` - 能耗表 +4. `V13__create_spare_part_tables.sql` - 备件表 +5. `V14__create_equipment_health_tables.sql` - 设备健康表 +6. `V15__create_inspection_template_table.sql` - 点检模板表 + +--- + +## 部署检查清单 + +- [ ] 数据库迁移脚本执行 +- [ ] 后端编译通过 +- [ ] 后端单元测试通过 +- [ ] 前端编译通过 +- [ ] API 端点验证 +- [ ] E2E 测试通过 +- [ ] 文档更新 + +--- + +## 风险与缓解 + +| 风险 | 影响 | 缓解措施 | +|------|------|----------| +| 定时任务性能 | 维保检查任务执行慢 | 使用 @Async 或分布式任务 | +| 能耗数据量大 | 查询性能问题 | 添加索引，分区表 | +| IoT 数据接入 | 协议兼容问题 | 预留适配器接口 | +| 历史数据不足 | 故障预测不准 | 初期使用规则判断 | + +--- + +*计划版本: v1.0* +*最后更新: 2026-03-23*