346 lines
24 KiB
Markdown
346 lines
24 KiB
Markdown
# Ether PMS 行业最佳实践评估报告
|
||
|
||
> **评估日期**: 2026-04-23
|
||
> **评估范围**: Ether 物业管理系统全栈（ether-pms + ether-admin）
|
||
> **对标体系**: 物业管理行业标杆（万物云、绿城服务）、RESTful API 最佳实践、OWASP Top 10、Vue3 生态最佳实践、Clean Code 原则
|
||
> **数据来源**: 5份反推设计文档 + 实际代码审查
|
||
|
||
---
|
||
|
||
## 评估总览
|
||
|
||
| 评估维度 | 评分 | 等级 |
|
||
|---------|------|------|
|
||
| 数据模型设计 | 3.0/5 | ⭐⭐⭐ |
|
||
| API设计 | 2.5/5 | ⭐⭐½ |
|
||
| 安全设计 | 3.5/5 | ⭐⭐⭐½ |
|
||
| 业务流程 | 2.5/5 | ⭐⭐½ |
|
||
| 前端架构 | 3.0/5 | ⭐⭐⭐ |
|
||
| 代码质量 | 2.5/5 | ⭐⭐½ |
|
||
| **综合评分** | **2.8/5** | **⭐⭐⭐** |
|
||
|
||
---
|
||
|
||
## 一、数据模型设计评估
|
||
|
||
**评分: 3.0/5**
|
||
|
||
### 1.1 优点
|
||
|
||
1. **主表+扩展表模式设计合理**：设备模块采用 Equipment 主表 + 4张专业扩展表（Elevator/Hvac/Fire/Energy）的设计，既保证了公共字段的统一管理，又支持了专业参数的灵活扩展，符合物业管理行业设备分类管理的实际需求
|
||
2. **多租户项目隔离机制完善**：通过 UserProject 关联 + ProjectStaff 扩展 + X-Project-ID Header + DataScopeService 四层隔离，实现了项目级数据隔离，满足物业公司多项目运营的核心需求
|
||
3. **四级数据范围设计**：ALL / PROJECT / DEPARTMENT / SELF 四级数据范围，覆盖了物业管理行业从集团到个人的权限层级
|
||
4. **逻辑删除策略统一**：Equipment、OwnershipEntity、SpaceNode 等核心实体均采用 isDeleted 软删除，避免数据误删导致业务中断
|
||
5. **JSONB 扩展字段**：Equipment.attributes、Equipment.photos、Equipment.documents 使用 JSONB 存储，为非结构化数据提供了灵活扩展能力
|
||
6. **树形结构支持**：SpaceNode 采用 treePath 字符串路径模式，支持层级空间管理（项目→楼栋→单元→楼层→房间）
|
||
|
||
### 1.2 不足
|
||
|
||
1. **未使用 PostgreSQL JSONB 原生类型**：SpaceNode.attributes 定义为 String(2000) 而非 JSONB 类型，无法利用 PostgreSQL 的 GIN 索引和 JSON 查询能力，查询性能和灵活性受限
|
||
2. **缺少数据库索引设计文档**：除 AuditLog 外，其他实体未见明确的索引策略定义。WorkOrder、Equipment 等高频查询表缺少复合索引规划
|
||
3. **树形结构方案选型欠佳**：SpaceNode 使用 treePath 字符串（如 `/1/2/3/`），查询子孙节点需 LIKE 匹配，大数据量下性能堪忧。未考虑 PostgreSQL ltree 扩展或闭包表方案
|
||
4. **数据冗余未受控**：Equipment 表同时存储 owningEntityId 和 owningEntityName，属于非规范化的冗余设计，缺乏同步更新机制
|
||
5. **审计字段不一致**：部分实体（User、Dept）手动管理 createdAt/updatedAt，部分（SysConfig、AuditLog）使用 @CreationTimestamp/@UpdateTimestamp，策略不统一
|
||
6. **缺少唯一约束**：SpaceNode 原设计有 UNIQUE(project_id, code)，实际实现中无 code 列也无唯一约束，数据完整性依赖应用层
|
||
7. **财务域实体完全缺失**：FeeItem、FeeBill、FeePayment、FeeRefund 四大核心财务实体未实现，无法支撑收费管理业务
|
||
|
||
### 1.3 改进建议
|
||
|
||
| 优先级 | 建议 | 说明 |
|
||
|--------|------|------|
|
||
| P0 | 将 SpaceNode.attributes 改为 JSONB 类型 | 利用 PostgreSQL 原生 JSON 查询能力，添加 GIN 索引 |
|
||
| P0 | 为高频查询表添加复合索引 | WorkOrder(project_id, status)、Equipment(project_id, equipment_type)、SpaceNode(project_id, node_type) |
|
||
| P0 | 实现财务域四大核心实体 | FeeItem / FeeBill / FeePayment / FeeRefund，对标万物云收费管理模型 |
|
||
| P1 | 评估 SpaceNode 树形结构升级方案 | 考虑 ltree 扩展或闭包表，支持高效祖先/子孙查询 |
|
||
| P1 | 统一审计字段策略 | 全部采用 JPA Auditing（@CreatedDate/@LastModifiedDate + AuditorAware） |
|
||
| P1 | 消除 Equipment 冗余字段 | 移除 owningEntityName，通过 JOIN 查询获取 |
|
||
| P2 | 添加数据库唯一约束 | SpaceNode(project_id, code)、Equipment(project_id, equipment_code) |
|
||
| P2 | 引入数据库迁移工具 | 使用 Flyway/Liquibase 管理数据库版本演进 |
|
||
|
||
---
|
||
|
||
## 二、API设计评估
|
||
|
||
**评分: 2.5/5**
|
||
|
||
### 2.1 优点
|
||
|
||
1. **RESTful 风格基本遵循**：CRUD 操作使用 POST/GET/PUT/DELETE 对应创建/读取/更新/删除，资源路径命名合理（如 `/api/wo/work-orders`）
|
||
2. **统一错误响应格式**：通过 ErrorCode 枚举 + BusinessException + GlobalExceptionHandler 实现了统一的错误响应结构（code + message + data）
|
||
3. **错误码体系设计合理**：按模块分段（1xxx 认证、2xxx 用户、3xxx 角色、4xxx 权限、5xxx 项目、6xxx 空间、7xxx 文件），便于定位问题
|
||
4. **工单状态操作使用子资源**：`POST /{id}/assign`、`POST /{id}/start`、`POST /{id}/complete` 等状态变更操作采用子资源路径，语义清晰
|
||
5. **设备扩展表 API 设计优雅**：`GET /{id}/elevator`、`PUT /{id}/hvac` 通过主设备 ID 路径访问扩展表，RESTful 风格良好
|
||
|
||
### 2.2 不足
|
||
|
||
1. **无 API 版本管理**：原设计使用 `/api/v1/auth`，实际实现为 `/api/auth`，缺少版本号。API 变更时无法向后兼容，将影响所有客户端
|
||
2. **分页不统一**：WorkOrder 返回 `List<WorkOrder>` 全量数据（代码注释标注"高风险，可能导致 OOM"），而 User 使用 Page 分页。分页参数和响应格式不统一
|
||
3. **HTTP 状态码使用不当**：GlobalExceptionHandler 中，非标准 HTTP 状态码的业务错误码（如 1001、2001）默认返回 HTTP 200，客户端无法通过 HTTP 状态码判断请求是否成功
|
||
4. **缺少 HATEOAS 支持**：API 响应无链接信息，客户端需硬编码 URL 路径
|
||
5. **部分 API 绕过 Service 层**：OwnershipEntityController 直接注入 Repository，违反分层架构原则
|
||
6. **前后端 API 不一致**：维保计划存在两套前端 API（maintenance.ts + maintenance-plan.ts），触发类型枚举前后端不匹配
|
||
7. **缺少 API 文档**：未集成 Swagger/SpringDoc，API 文档依赖人工维护的反推设计文档
|
||
|
||
### 2.3 改进建议
|
||
|
||
| 优先级 | 建议 | 说明 |
|
||
|--------|------|------|
|
||
| P0 | 统一分页查询 | 所有列表接口使用 Pageable 参数 + PageResponse 响应，WorkOrder 优先改造 |
|
||
| P0 | 修复 HTTP 状态码映射 | 业务错误码 4xx/5xx 应映射为对应 HTTP 状态码，非标准码保持 200 但在 body 中体现 |
|
||
| P1 | 引入 API 版本管理 | URL 路径版本 `/api/v2/` 或 Header 版本 `Accept: application/vnd.ether.v2+json` |
|
||
| P1 | 集成 SpringDoc/OpenAPI | 自动生成 API 文档，确保文档与代码同步 |
|
||
| P1 | 修复 OwnershipEntityController 分层违规 | 补充 Service 层 |
|
||
| P2 | 统一前后端枚举定义 | 维保触发类型、设备类型等枚举前后端对齐 |
|
||
| P2 | 添加 HATEOAS 链接 | 至少在分页响应中添加 next/prev 链接 |
|
||
|
||
---
|
||
|
||
## 三、安全设计评估
|
||
|
||
**评分: 3.5/5**
|
||
|
||
### 3.1 优点
|
||
|
||
1. **BCrypt 密码加密**：使用 Spring Security PasswordEncoder（BCrypt），自动处理盐值，安全性高
|
||
2. **旧密码格式检测与强制重置**：PasswordService 检测非 BCrypt 格式密码（MD5/SHA-1），返回 false 强制用户重置，支持密码算法平滑迁移
|
||
3. **密码强度校验完善**：支持可配置的长度、大小写、数字、特殊字符要求，弱密码黑名单检测
|
||
4. **登录失败锁定机制**：基于 Redis 实现，5次失败锁定10分钟，防止暴力破解
|
||
5. **JWT 认证流程完整**：Token 生成→验证→刷新流程闭环，Claims 包含 userId/username/roles
|
||
6. **审计日志异步持久化**：通过 `@OperationLog` 注解 + AOP 切面 + 线程池异步保存，不影响业务性能
|
||
7. **密码字段 @JsonIgnore**：User.password 和 User.salt 使用 @JsonIgnore，防止序列化泄露
|
||
8. **SQL 注入防护**：使用 JPA + 参数化查询，天然防止 SQL 注入
|
||
9. **数据库异常信息脱敏**：GlobalExceptionHandler 捕获 DataAccessException 时不暴露 SQL 语句和数据库细节
|
||
|
||
### 3.2 不足
|
||
|
||
1. **JWT 无刷新 Token 机制**：仅有单一 Access Token，无 Refresh Token 体系。Token 过期后需重新登录，用户体验差且安全性不足（长有效期 Token 被窃取风险高）
|
||
2. **JWT Secret 硬编码风险**：JwtTokenProvider 的密钥配置需确认是否外置到环境变量，若硬编码在源码中则存在泄露风险
|
||
3. **审计日志可篡改**：sys_audit_log 表无防篡改机制（如签名校验、只追加约束），管理员可直接修改或删除日志
|
||
4. **90天归档策略为直接删除**：审计日志归档实际实现为删除，不符合合规要求（物业管理行业审计日志需保留3-5年）
|
||
5. **CORS 配置未明确**：未见明确的 CORS 策略配置，可能存在跨域安全风险
|
||
6. **CSRF 防护缺失**：使用 JWT + Bearer Token 方式，虽 CSRF 风险较低，但未做额外防护
|
||
7. **敏感数据未脱敏**：用户手机号、身份证号等敏感字段无脱敏处理，API 响应中明文返回
|
||
8. **DataScopeService 仅提供判断方法**：未实现 SQL 自动注入，数据过滤依赖业务层手动调用，存在遗漏风险
|
||
9. **登录响应返回角色列表**：LoginService 在响应中返回 roles 列表，信息量偏多，可能被利用进行权限探测
|
||
|
||
### 3.3 改进建议
|
||
|
||
| 优先级 | 建议 | 说明 |
|
||
|--------|------|------|
|
||
| P0 | 实现 Refresh Token 机制 | Access Token 短有效期（15-30分钟）+ Refresh Token 长有效期（7天），Redis 存储 Refresh Token |
|
||
| P0 | 审计日志改为只追加 | 数据库层面添加触发器或应用层约束，禁止 UPDATE/DELETE 审计日志 |
|
||
| P0 | 审计日志归档而非删除 | 90天后导出至对象存储（OSS/S3），保留3-5年 |
|
||
| P1 | 敏感数据脱敏 | 手机号中间4位掩码、身份证号掩码，使用 Jackson 自定义序列化器 |
|
||
| P1 | JWT Secret 外置 | 密钥存储在环境变量或 Vault 中，禁止硬编码 |
|
||
| P1 | DataScopeService 实现 SQL 自动注入 | 通过 MyBatis Interceptor 或 JPA Specification 自动拼接数据过滤条件 |
|
||
| P2 | 配置 CORS 策略 | 明确允许的 Origin、Methods、Headers |
|
||
| P2 | 登录响应精简 | 移除 roles 列表，改为独立接口查询 |
|
||
|
||
---
|
||
|
||
## 四、业务流程评估
|
||
|
||
**评分: 2.5/5**
|
||
|
||
### 4.1 优点
|
||
|
||
1. **工单状态机设计清晰**：PENDING → ASSIGNED → IN_PROGRESS → COMPLETED → VERIFIED 六状态流转，覆盖物业管理核心工单流程
|
||
2. **维保任务自动优先级判定**：基于触发类型 + 紧急关键词（困人/漏水/停电/火灾等）自动判定 URGENT/HIGH/MEDIUM 优先级，符合物业管理应急响应需求
|
||
3. **维保任务完成后联动更新设备**：完成维保后自动更新设备维保商和下次巡检日期，实现业务闭环
|
||
4. **设备健康评分算法完整**：基于故障扣分 + 维保扣分 + 年龄扣分的综合评分，含 MTBF/MTTR 计算，对标行业设备管理标准
|
||
5. **设备导入校验完善**：文件类型、大小、行数、编码四重校验，防止批量导入异常数据
|
||
6. **巡检模板管理**：支持模板复制、必检项标记、排序控制，满足标准化巡检需求
|
||
|
||
### 4.2 不足
|
||
|
||
1. **工单状态机缺少关键状态**：无 SUSPENDED（挂起）、RETURNED（退回）状态，无法处理工单暂停和退回重分配场景，这是物业管理行业常见需求
|
||
2. **无工单流转记录**：WorkOrderFlow 实体未实现，无法追溯工单状态变更历史，影响问题排查和绩效统计
|
||
3. **SLA 管理完全缺失**：无响应时间、处理时间、超时升级机制。万物云等标杆企业均有 SLA 体系（如紧急工单30分钟响应、一般工单2小时响应）
|
||
4. **消息通知系统未实现**：NotificationChannel/Template/Rule/History 四大实体均未实现，工单派单、超时、完成等关键节点无通知，严重影响运营效率
|
||
5. **财务收费流程完全缺失**：FeeItem/FeeBill/FeePayment 未实现，无账单生成、支付流程、欠费催缴能力，这是物业管理最核心的业务流程
|
||
6. **设备二维码未实现**：原需求要求设备二维码标识，实际未实现，影响设备巡检扫码和业主报修体验
|
||
7. **IoT 集成未实现**：设备监控、自动告警、数据采集等 IoT 能力缺失，无法实现预测性维保
|
||
8. **维保到期定时提醒未实现**：仅前端展示下次维保日期，无后端定时任务推送提醒
|
||
9. **健康评分算法存在 Bug**：calculateEquipmentAge() 错误使用 SpaceNode.maintenanceContractStart 而非 Equipment.installationDate；projectId 硬编码为全零 UUID
|
||
10. **前后端状态不一致**：前端维保任务含 ACCEPTED 状态，后端无此状态；前端触发类型（MANUAL/SCHEDULED/AUTOMATIC）与后端（PLAN/INSPECTION/FAULT/MANUAL）不匹配
|
||
|
||
### 4.3 改进建议
|
||
|
||
| 优先级 | 建议 | 说明 |
|
||
|--------|------|------|
|
||
| P0 | 实现财务收费核心流程 | FeeItem → FeeBill → FeePayment，支持按面积/用量/固定金额计费 |
|
||
| P0 | 实现消息通知系统 | 工单派单/超时/完成通知，支持站内信、短信、推送 |
|
||
| P0 | 修复健康评分算法 Bug | 修正设备年龄计算和 projectId 硬编码问题 |
|
||
| P1 | 添加工单挂起/退回状态 | SUSPENDED + RETURNED，支持工单暂停和退回重分配 |
|
||
| P1 | 实现工单流转记录 | WorkOrderFlow 实体，记录每次状态变更的操作人、时间、备注 |
|
||
| P1 | 实现 SLA 管理 | 定义各类型工单的响应时间和处理时间，超时自动升级 |
|
||
| P1 | 统一前后端状态和枚举 | 维保任务状态、触发类型等前后端对齐 |
|
||
| P2 | 实现设备二维码 | 生成二维码关联设备，支持扫码巡检和报修 |
|
||
| P2 | 实现维保到期定时提醒 | Spring Scheduled 任务 + 消息通知 |
|
||
| P2 | IoT 集成规划 | 设计 IoT 数据接入层，支持设备监控和自动告警 |
|
||
|
||
---
|
||
|
||
## 五、前端架构评估
|
||
|
||
**评分: 3.0/5**
|
||
|
||
### 5.1 优点
|
||
|
||
1. **Vue3 Composition API + TypeScript**：使用 `<script setup>` + TypeScript，代码风格现代，类型安全
|
||
2. **Pinia 状态管理**：使用 Pinia（Composition API 风格）管理用户状态，支持持久化（localStorage）
|
||
3. **Axios 请求封装完善**：request.ts 实现了请求/响应拦截器、Token 自动注入、错误分类处理、GET 请求自动重试（最多2次）
|
||
4. **路由守卫权限控制**：beforeEach 守卫检查登录状态和角色权限，支持白名单路由（/login）
|
||
5. **路由懒加载**：所有页面组件使用 `() => import()` 动态导入，优化首屏加载性能
|
||
6. **统一类型定义**：types/index.ts 定义了 ApiResponse、LoginRequest、LoginResponse 等核心类型，API 文件定义了业务类型
|
||
7. **Ant Design Vue 组件库**：统一使用 ant-design-vue，保证 UI 一致性
|
||
8. **错误处理工具函数**：error-handler.ts 提供 getErrorMessage 和 isValidationError 工具函数
|
||
|
||
### 5.2 不足
|
||
|
||
1. **TypeScript 类型覆盖不完整**：API 响应大量使用 `ApiResponse<WorkOrder[]>` 等泛型，但部分类型定义与后端不一致（如维保任务状态、触发类型）
|
||
2. **any 类型使用**：request.ts 响应拦截器中 `(error.response.data as any)?.message` 使用了 any，降低类型安全性
|
||
3. **Token 存储在 localStorage**：存在 XSS 攻击窃取 Token 的风险，业界推荐 HttpOnly Cookie
|
||
4. **前端角色判断仅基于 localStorage**：isLoggedIn() 通过解析 JWT payload 检查过期，但角色列表直接从 localStorage 读取，可被篡改
|
||
5. **API 文件分裂**：维保计划存在 maintenance.ts 和 maintenance-plan.ts 两套 API，功能重叠且端点不同
|
||
6. **缺少全局 Loading 状态管理**：无统一的请求加载状态管理，各页面独立处理
|
||
7. **缺少组件设计系统**：未见统一的业务组件库（如 ProTable、ProForm），各页面组件复用度不高
|
||
8. **401 处理使用 window.location.href**：硬跳转而非 router.push，丢失 Vue Router 状态管理
|
||
|
||
### 5.3 改进建议
|
||
|
||
| 优先级 | 建议 | 说明 |
|
||
|--------|------|------|
|
||
| P0 | 合并维保计划 API 文件 | 统一为 maintenance-plan.ts，删除重复的 maintenance.ts |
|
||
| P0 | 统一前后端类型定义 | 基于后端枚举生成前端类型，或使用 OpenAPI Generator 自动生成 |
|
||
| P1 | Token 迁移至 HttpOnly Cookie | 配合后端 Set-Cookie + SameSite 属性，防止 XSS 窃取 |
|
||
| P1 | 消除 any 类型 | 定义完整的 API 错误响应类型 |
|
||
| P1 | 401 处理改用 router.push | 保持 Vue Router 状态，支持登录后回跳 |
|
||
| P2 | 建立业务组件库 | ProTable（列表页）、ProForm（表单页）、StatusTag（状态标签）等 |
|
||
| P2 | 全局 Loading 状态 | 基于 Axios 拦截器 + Pinia 管理全局加载状态 |
|
||
| P2 | 角色权限前端防篡改 | 角色信息从 JWT Token 解析而非 localStorage 读取 |
|
||
|
||
---
|
||
|
||
## 六、代码质量评估
|
||
|
||
**评分: 2.5/5**
|
||
|
||
### 6.1 优点
|
||
|
||
1. **分层架构基本遵循**：Controller → Service → Repository 三层架构清晰，依赖注入使用 @RequiredArgsConstructor
|
||
2. **Lombok 减少样板代码**：@Data、@Builder、@RequiredArgsConstructor 等注解减少 getter/setter 样板代码
|
||
3. **异常处理体系完整**：BusinessException + ErrorCode + GlobalExceptionHandler 三层异常处理，业务异常不暴露堆栈
|
||
4. **JPA 实体校验**：使用 @NotNull、@Size、@Pattern 等 Bean Validation 注解，在实体层进行数据校验
|
||
5. **配置外置**：密码策略通过 @ConfigurationProperties(prefix = "password") 外置，支持运行时配置
|
||
6. **事务管理**：关键业务方法使用 @Transactional 注解，保证数据一致性
|
||
|
||
### 6.2 不足
|
||
|
||
1. **命名规范不一致**：Equipment 使用 equipmentCode/equipmentName，而 WorkOrder 使用 workNo，SpaceNode 无 code 字段。字段命名风格不统一
|
||
2. **异常处理不一致**：WorkOrderServiceImpl 使用 `throw new RuntimeException("工单不存在")` 而非 BusinessException + ErrorCode，绕过了统一异常处理
|
||
3. **全量查询风险**：WorkOrderServiceImpl.getAllWorkOrders() 返回全量数据，代码注释标注"高风险，可能导致 OOM"，但未修复
|
||
4. **分层架构违规**：OwnershipEntityController 直接注入 Repository，跳过 Service 层
|
||
5. **单元测试覆盖不足**：仅 EnergyMeterServiceTest 存在测试代码，其他核心服务（WorkOrderService、LoginService、EquipmentHealthService）无单元测试
|
||
6. **代码注释过度**：PasswordService 等文件注释占比过高（Javadoc + 行内注释超过代码量的50%），部分注释与代码重复
|
||
7. **Magic Number**：健康评分算法中的扣分系数（5、20、2、10）和维保默认周期（30天）硬编码在代码中，未提取为配置
|
||
8. **删除策略不一致**：WorkOrder 使用物理删除（deleteById），MaintenanceTask 使用逻辑删除（设为 CANCELLED），策略不统一
|
||
9. **TODO 标记未处理**：维保完成率计算标记 TODO 暂返回 1.0，影响健康评分准确性
|
||
10. **工单编号生成非线程安全**：generateWorkNo() 使用 findMaxWorkNoByPrefix 查询最大编号 +1，并发场景可能生成重复编号
|
||
|
||
### 6.3 改进建议
|
||
|
||
| 优先级 | 建议 | 说明 |
|
||
|--------|------|------|
|
||
| P0 | 修复 WorkOrderServiceImpl 异常处理 | 将 RuntimeException 替换为 BusinessException + ErrorCode |
|
||
| P0 | 修复工单全量查询 | 改为分页查询，添加 Pageable 参数 |
|
||
| P0 | 修复工单编号并发安全 | 使用数据库序列或 Redis INCR 生成编号 |
|
||
| P1 | 统一删除策略 | 核心业务实体统一使用逻辑删除，添加 isDeleted 字段 |
|
||
| P1 | 补充核心服务单元测试 | WorkOrderService、LoginService、EquipmentHealthService 优先 |
|
||
| P1 | 提取 Magic Number 为配置 | 健康评分系数、维保默认周期等提取为 @ConfigurationProperties |
|
||
| P2 | 统一字段命名规范 | 制定命名规范文档，逐步重构不一致的命名 |
|
||
| P2 | 修复维保完成率 TODO | 实现真实的维保完成率计算逻辑 |
|
||
|
||
---
|
||
|
||
## 七、改进路线图
|
||
|
||
### Q2 2026（紧急修复 + 核心补全）
|
||
|
||
| 周次 | 改进项 | 维度 | 优先级 |
|
||
|------|--------|------|--------|
|
||
| W1-2 | 修复 WorkOrderServiceImpl 异常处理和全量查询 | 代码质量 | P0 |
|
||
| W1-2 | 修复健康评分算法 Bug（设备年龄、projectId 硬编码） | 业务流程 | P0 |
|
||
| W3-4 | 统一所有列表接口分页查询 | API设计 | P0 |
|
||
| W3-4 | SpaceNode.attributes 改为 JSONB + GIN 索引 | 数据模型 | P0 |
|
||
| W5-6 | 实现 Refresh Token 机制 | 安全设计 | P0 |
|
||
| W5-6 | 审计日志改为只追加 + 归档而非删除 | 安全设计 | P0 |
|
||
| W7-8 | 实现财务域核心实体（FeeItem/FeeBill/FeePayment） | 数据模型 | P0 |
|
||
| W7-8 | 实现消息通知系统（工单派单/超时/完成通知） | 业务流程 | P0 |
|
||
|
||
### Q3 2026（架构增强 + 业务完善）
|
||
|
||
| 周次 | 改进项 | 维度 | 优先级 |
|
||
|------|--------|------|--------|
|
||
| W1-2 | 引入 API 版本管理 + SpringDoc | API设计 | P1 |
|
||
| W1-2 | 添加工单挂起/退回状态 + 流转记录 | 业务流程 | P1 |
|
||
| W3-4 | 实现 SLA 管理（响应时间/处理时间/超时升级） | 业务流程 | P1 |
|
||
| W3-4 | DataScopeService 实现 SQL 自动注入 | 安全设计 | P1 |
|
||
| W5-6 | 敏感数据脱敏 + JWT Secret 外置 | 安全设计 | P1 |
|
||
| W5-6 | 统一前后端枚举和类型定义 | 前端架构 | P1 |
|
||
| W7-8 | 合并维保计划 API + 修复前后端状态不一致 | 前端架构 | P1 |
|
||
| W7-8 | 补充核心服务单元测试 | 代码质量 | P1 |
|
||
|
||
### Q4 2026（体验优化 + 扩展能力）
|
||
|
||
| 周次 | 改进项 | 维度 | 优先级 |
|
||
|------|--------|------|--------|
|
||
| W1-2 | Token 迁移至 HttpOnly Cookie | 前端架构 | P2 |
|
||
| W1-2 | 建立业务组件库（ProTable/ProForm/StatusTag） | 前端架构 | P2 |
|
||
| W3-4 | 实现设备二维码 | 业务流程 | P2 |
|
||
| W3-4 | 实现维保到期定时提醒 | 业务流程 | P2 |
|
||
| W5-6 | 评估 SpaceNode 树形结构升级（ltree/闭包表） | 数据模型 | P2 |
|
||
| W5-6 | 统一审计字段策略 + 删除策略 | 代码质量 | P2 |
|
||
| W7-8 | 引入 Flyway 数据库迁移 | 数据模型 | P2 |
|
||
| W7-8 | IoT 集成架构设计 | 业务流程 | P2 |
|
||
|
||
### Q1 2027（智能化 + 行业对标）
|
||
|
||
| 周次 | 改进项 | 维度 | 优先级 |
|
||
|------|--------|------|--------|
|
||
| W1-4 | 支付网关对接（微信/支付宝） | 业务流程 | P2 |
|
||
| W1-4 | 财务报表（收费统计/欠费分析/收入趋势） | 业务流程 | P2 |
|
||
| W5-8 | 智能派单算法（基于技能/距离/负载） | 业务流程 | P2 |
|
||
| W5-8 | 预测性维保（基于设备健康评分 + IoT 数据） | 业务流程 | P2 |
|
||
|
||
---
|
||
|
||
## 八、关键发现总结
|
||
|
||
### 8.1 最大亮点
|
||
|
||
1. **安全基础扎实**：BCrypt 加密、登录锁定、密码强度校验、审计日志等安全机制完善，在同类物业管理系统中属于中上水平
|
||
2. **设备管理超越需求**：健康评分算法、MTBF/MTTR、专业扩展表、归属管理等超出原需求设计，体现了对物业管理行业设备管理的深入理解
|
||
3. **多租户隔离完善**：四级数据范围 + 项目上下文传递 + 双层角色分配，满足物业公司多项目运营需求
|
||
|
||
### 8.2 最大风险
|
||
|
||
1. **财务域完全缺失**：收费管理是物业管理最核心的业务流程，当前 FeeItem/FeeBill/FeePayment 均未实现，系统无法支撑实际收费运营
|
||
2. **消息通知缺失**：工单派单、超时、完成等关键节点无通知，严重影响运营效率和业主体验
|
||
3. **工单全量查询 OOM 风险**：WorkOrderServiceImpl.getAllWorkOrders() 返回全量数据，随着工单数据增长将导致内存溢出
|
||
|
||
### 8.3 与行业标杆的差距
|
||
|
||
| 对标维度 | 万物云/绿城服务 | Ether 当前 | 差距 |
|
||
|---------|---------------|-----------|------|
|
||
| 收费管理 | 完整的账单-支付-催缴-对账闭环 | 仅能耗计量，无收费流程 | 🔴 重大差距 |
|
||
| SLA 管理 | 响应时间/处理时间/超时升级 | 无 | 🔴 重大差距 |
|
||
| 消息通知 | 多渠道（短信/推送/微信/站内信） | 无 | 🔴 重大差距 |
|
||
| 设备管理 | 全生命周期 + IoT + 预测性维保 | 健康评分 + 故障记录，无 IoT | 🟡 中等差距 |
|
||
| 工单管理 | 7状态 + 流转记录 + 智能派单 | 6状态 + 无流转记录 | 🟡 中等差距 |
|
||
| 安全设计 | 等保2.0三级 + 数据脱敏 + 审计防篡改 | BCrypt + 登录锁定 + 审计日志 | 🟢 差距较小 |
|
||
|
||
---
|
||
|
||
> **报告结论**: Ether 系统在安全设计和设备管理方面表现良好，但在财务收费、消息通知、SLA 管理等物业管理核心业务流程上存在重大缺失。建议按路线图优先补全财务域和通知系统，同时修复已知的代码质量和性能风险。
|