# Ether 物业管理系统 - 概要设计文档

**文档版本**: v1.0
**编制日期**: 2026-05-18
**数据来源**: REVERSE-AUTH/MDM/ASSET/OPS/FINANCE 反推设计文档 + BEST-PRACTICES-REPORT + CONSISTENCY-REPORT
**系统版本**: ether-pms v1.x (Spring Boot 3.x)

---

## 一、系统架构设计

### 1.1 总体架构

Ether 物业管理系统采用**单体模块化**架构，后端为 Spring Boot 3.x 单体应用，通过 Maven 多模块组织业务边界；前端为 Vue3 SPA 应用，按角色拆分为三套独立前端。

**技术栈总览**：

| 层次 | 技术选型 | 说明 |
|------|---------|------|
| 后端框架 | Spring Boot 3.x + Spring Security 6 | Java 17+，Servlet 容器 |
| 持久层 | Spring Data JPA + Hibernate | ORM 框架，自动建表 |
| 数据库 | PostgreSQL 15+ | JSONB/UUID/ltree 扩展 |
| 缓存 | Redis | 登录锁定、Session、热数据 |
| 认证 | JWT (HMAC-SHA256) | 无状态 Token 认证 |
| 前端框架 | Vue3 + TypeScript + Vite | Composition API + `<script setup>` |
| UI 组件库 | Ant Design Vue 4.x | 统一视觉风格 |
| 状态管理 | Pinia | Composition API 风格 |
| HTTP 客户端 | Axios | 请求/响应拦截器封装 |
| 构建工具 | Maven (后端) / npm (前端) | 多模块构建 |

**架构图**：

```
┌──────────────────────────────────────────────────────────────────────┐
│                          客户端层                                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │ ether-admin  │  │ether-app-    │  │ether-app-    │              │
│  │  (管理后台)   │  │ employee     │  │ owner        │              │
│  │  :5175       │  │ (员工H5)     │  │ (业主H5)     │              │
│  │  Vue3+AntD   │  │ :5174        │  │ :5176        │              │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘              │
│         │                 │                 │                       │
│         └─────────────────┼─────────────────┘                       │
│                           │ RESTful API (JSON)                      │
│                           │ Authorization: Bearer {JWT}            │
│                           │ X-Project-ID: {projectId}              │
└───────────────────────────┼──────────────────────────────────────────┘
                            │
┌───────────────────────────┼──────────────────────────────────────────┐
│                     后端服务层 (ether-pms :8080)                      │
│                           │                                          │
│  ┌────────────────────────┼────────────────────────────────────┐    │
│  │              Spring Security Filter Chain                    │    │
│  │  JwtAuthenticationFilter → LoginAttemptFilter → ...         │    │
│  └────────────────────────┼────────────────────────────────────┘    │
│                           │                                          │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐          │
│  │module- │ │module- │ │module- │ │module- │ │module- │          │
│  │common  │ │auth    │ │mdm     │ │asset   │ │wo      │          │
│  │        │ │        │ │        │ │        │ │        │          │
│  │公共工具│ │认证授权│ │主数据  │ │设备资产│ │运维工单│          │
│  │异常/响应│ │用户/角色│ │项目/空间│ │设备/健康│ │工单/维保│          │
│  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘          │
│                           │                                          │
│  ┌────────────────────────┼────────────────────────────────────┐    │
│  │              JPA / Hibernate / Repository                    │    │
│  └────────────────────────┼────────────────────────────────────┘    │
│                           │                                          │
└───────────────────────────┼──────────────────────────────────────────┘
                            │
┌───────────────────────────┼──────────────────────────────────────────┐
│                        数据层                                        │
│  ┌──────────────┐  ┌──────────────┐                                │
│  │ PostgreSQL   │  │   Redis      │                                │
│  │ 15+          │  │              │                                │
│  │ JSONB/UUID   │  │ 登录锁定     │                                │
│  │ B-tree/GIN   │  │ Token缓存    │                                │
│  └──────────────┘  └──────────────┘                                │
└──────────────────────────────────────────────────────────────────────┘
```

### 1.2 模块划分

| 模块 | 职责 | 核心实体 | API 前缀 |
|------|------|---------|---------|
| **module-common** | 公共工具、异常体系、统一响应、基础配置 | ErrorCode、ApiResponse | — |
| **module-auth** | 身份认证、用户管理、RBAC 权限、审计日志 | User、Role、Permission、Dept、AuditLog | `/api/auth` |
| **module-mdm** | 项目管理、空间节点、巡检标准、备件库存、能耗计量 | Project、SpaceNode、InspectionItem、SparePart、EnergyMeter | `/api/mdm`、`/api/ops` |
| **module-asset** | 设备台账、健康评分、故障历史、归属主体 | Equipment、EquipmentElevator/Hvac/Fire/Energy、EquipmentHealthScore | `/api/asset` |
| **module-wo** | 工单管理、维保计划、维保任务、巡检模板 | WorkOrder、MaintenancePlan、MaintenanceTask、InspectionTemplate | `/api/wo`、`/api/ops` |
| **module-finance** | 收费项目、账单管理、支付记录（**待实现**） | FeeItem、FeeBill、FeePayment（未实现） | `/api/finance`（待定） |

**模块依赖关系**：

```
module-common ← module-auth ← module-mdm ← module-asset
                    ↑              ↑            ↑
                    └──────────────┴────────────┘
                              module-wo
```

- module-common 是所有模块的基础依赖
- module-auth 提供用户/权限基础数据，被其他业务模块引用
- module-mdm 提供项目/空间基础数据，被 asset/wo 模块引用
- module-asset 和 module-wo 存在交叉引用（设备-工单关联）

### 1.3 前后端交互架构

**认证流程**：

```
1. 客户端 POST /api/auth/login {username, password}
2. 后端验证 → 生成 JWT Token（含 userId/username/roles）
3. 客户端存储 Token → 后续请求 Header: Authorization: Bearer {token}
4. 后端 JwtAuthenticationFilter 拦截 → 验证签名和过期 → 设置 SecurityContext
```

**项目隔离机制**：

```
1. 登录后获取用户项目列表 GET /api/auth/users/{id}/projects
2. 用户选择项目 → 后续请求携带 X-Project-ID Header
3. 后端 ProjectContextInterceptor 拦截 → 设置 ThreadLocal
4. 业务层 DataScopeService 过滤数据 → 按 projectId 限定数据范围
```

**统一响应格式**：

```json
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

**错误响应格式**：

```json
{
  "code": 1001,
  "message": "用户名或密码错误",
  "data": null
}
```

**错误码分段规则**：

| 段号 | 模块 | 示例 |
|------|------|------|
| 1xxx | 认证 | 1001 用户名或密码错误 |
| 2xxx | 用户 | 2001 用户不存在 |
| 3xxx | 角色 | 3001 角色代码已存在 |
| 4xxx | 权限 | 4001 权限代码已存在 |
| 5xxx | 项目 | 5001 项目编码已存在 |
| 6xxx | 空间/能耗 | 6101 仪表不存在 |
| 7xxx | 文件 | 7001 文件格式不支持 |

### 1.4 部署架构

| 组件 | 端口 | 部署方式 | 说明 |
|------|------|---------|------|
| ether-pms | 8080 | JAR 包部署 | 后端单体服务 |
| ether-admin | 5175 | Nginx 静态托管 | 管理后台前端 |
| ether-app-employee | 5174 | Nginx 静态托管 | 员工 H5 前端 |
| ether-app-owner | 5176 | Nginx 静态托管 | 业主 H5 前端 |
| ether-app-commercial | 5177 | Nginx 静态托管 | 商办 H5 前端 |
| PostgreSQL | 5432 | 独立部署 | 主数据库 |
| Redis | 6379 | 独立部署 | 缓存/登录锁定 |

**启动脚本**：项目根目录提供 `start-services.sh` / `stop-services.sh` 统一管理服务启停。

---

## 二、业务域划分与边界

### 2.1 六大业务域定义

| 域编号 | 域名称 | 核心职责 | 对应模块 | 核心实体数 |
|--------|--------|---------|---------|-----------|
| D1 | 身份与权限域 | 用户认证、RBAC 权限、项目隔离、审计日志 | module-auth | 14 |
| D2 | 空间与项目域 | 项目管理、空间节点树、项目配置、项目统计 | module-mdm | 13 |
| D3 | 设备与资产域 | 设备台账、专业扩展、健康评分、故障历史、归属管理 | module-asset | 8 |
| D4 | 运营与服务域 | 工单管理、维保计划/任务、巡检模板、备件库存 | module-wo + module-mdm(部分) | 6 |
| D5 | 财务与收费域 | 收费项目、账单管理、支付记录、能耗计费 | module-finance(待实现) | 0(待实现) |
| D6 | 前端交互域 | 管理后台、员工端、业主端、商办端 | ether-admin + ether-app-* | — |

### 2.2 域间依赖关系图

```mermaid
graph TD
    D1[D1 身份与权限域<br/>module-auth]
    D2[D2 空间与项目域<br/>module-mdm]
    D3[D3 设备与资产域<br/>module-asset]
    D4[D4 运营与服务域<br/>module-wo]
    D5[D5 财务与收费域<br/>module-finance]
    D6[D6 前端交互域<br/>ether-admin/apps]

    D1 -->|用户/角色/权限| D2
    D1 -->|用户/角色/权限| D3
    D1 -->|用户/角色/权限| D4
    D1 -->|用户/角色/权限| D5

    D2 -->|项目/空间节点| D3
    D2 -->|项目/空间节点| D4
    D2 -->|项目/空间节点| D5

    D3 -->|设备信息| D4
    D3 -->|设备健康数据| D5

    D4 -->|工单费用| D5

    D1 -.->|API调用| D6
    D2 -.->|API调用| D6
    D3 -.->|API调用| D6
    D4 -.->|API调用| D6
    D5 -.->|API调用| D6
```

**依赖说明**：

| 依赖关系 | 依赖内容 | 实现方式 |
|---------|---------|---------|
| D2 → D1 | 项目成员管理需要用户数据 | UserProject 关联 + ProjectStaff 扩展 |
| D3 → D2 | 设备关联空间节点 | Equipment.spaceNodeId → SpaceNode.id |
| D4 → D2 | 工单关联项目和空间 | WorkOrder.projectId / spaceId |
| D4 → D3 | 工单关联设备 | WorkOrder.equipmentId → Equipment.id |
| D4 → D3 | 维保任务完成后更新设备 | MaintenanceTask → Equipment 联动更新 |
| D5 → D2 | 账单关联项目和空间 | FeeBill.projectId / spaceNodeId |
| D5 → D3 | 能耗费用对接设备 | EnergyConsumption → Equipment |

### 2.3 域间数据流图

```mermaid
flowchart LR
    subgraph D1[身份与权限域]
        User[User]
        Role[Role]
    end

    subgraph D2[空间与项目域]
        Project[Project]
        SpaceNode[SpaceNode]
        EnergyMeter[EnergyMeter]
    end

    subgraph D3[设备与资产域]
        Equipment[Equipment]
        HealthScore[HealthScore]
        FailureHistory[FailureHistory]
    end

    subgraph D4[运营与服务域]
        WorkOrder[WorkOrder]
        MaintenancePlan[MaintenancePlan]
        MaintenanceTask[MaintenanceTask]
        SparePart[SparePart]
    end

    subgraph D5[财务与收费域]
        FeeItem[FeeItem]
        FeeBill[FeeBill]
        FeePayment[FeePayment]
    end

    User -->|项目成员| Project
    Project -->|1:N| SpaceNode
    SpaceNode -->|spaceNodeId| Equipment
    Equipment -->|equipmentId| WorkOrder
    Equipment -->|equipmentId| MaintenanceTask
    MaintenancePlan -->|planId| MaintenanceTask
    MaintenanceTask -->|完成后联动| Equipment
    WorkOrder -->|relatedOrderId| SparePart
    EnergyMeter -->|费用计算| FeeBill
    Equipment -->|健康数据| HealthScore
    Equipment -->|故障记录| FailureHistory
    FailureHistory -->|关联工单| WorkOrder
```

### 2.4 域间接口契约

| 接口 | 提供方 | 消费方 | 契约内容 |
|------|--------|--------|---------|
| 用户项目列表 | D1 (auth) | D2 (mdm) | `GET /api/auth/users/{id}/projects` → `List<UserProject>` |
| 项目成员管理 | D2 (mdm) | D1 (auth) | `GET/POST/DELETE /api/mdm/projects/{id}/members` |
| 空间节点查询 | D2 (mdm) | D3 (asset) | Equipment.spaceNodeId → SpaceNode.id，通过 JPA 关联 |
| 设备查询 | D3 (asset) | D4 (wo) | WorkOrder.equipmentId → Equipment.id，通过 JPA 关联 |
| 维保完成后设备更新 | D4 (wo) | D3 (asset) | MaintenanceTask 完成时更新 Equipment.maintenanceVendor/nextInspectionDate |
| 备件出库关联工单 | D4 (wo) | D2 (mdm) | SparePartRecord.relatedOrderId → WorkOrder.id |
| 能耗数据对接账单 | D2 (mdm) | D5 (finance) | EnergyConsumption.amount → FeeBill 数据来源（待实现） |

---

## 三、核心技术实现路径

### 3.1 多租户数据隔离

**隔离策略**：共享数据库 + projectId 字段隔离

**实现机制**：

| 层次 | 机制 | 实现细节 |
|------|------|---------|
| 数据层 | projectId 字段 | 所有业务表均含 project_id 列，索引覆盖 |
| 请求层 | X-Project-ID Header | 前端每次请求携带当前项目 ID |
| 拦截层 | ProjectContextInterceptor | 拦截请求，将 projectId 存入 ThreadLocal |
| 服务层 | DataScopeService | 提供 canAccessAllData()、getPermittedProjectIds() 等判断方法 |
| 查询层 | Repository 方法 | findByProjectIdAndXxx() 系列方法，强制带项目条件 |

**数据范围过滤**：

```java
// 四级数据范围
ALL         → 不做数据过滤，可查看所有项目数据
PROJECT     → 过滤 project_id = 当前项目
DEPARTMENT  → 过滤 project_id + dept_id = 用户部门
SELF        → 过滤 assigned_to / creator = 当前用户
```

**已知不足与改进方向**：

- 当前 DataScopeService 仅提供判断方法，未实现 SQL 自动注入，数据过滤依赖业务层手动调用，存在遗漏风险
- 改进方案：通过 JPA Specification 或 MyBatis Interceptor 自动拼接数据过滤条件

### 3.2 RBAC 权限模型

**模型结构**：User ←M2M→ Role ←M2M→ Permission

**三级角色体系**：

| 角色类型 | 枚举值 | 说明 | 数据范围 |
|---------|--------|------|---------|
| 系统级 | SYSTEM | 跨项目全局角色 | ALL |
| 项目级 | PROJECT | 绑定特定项目的角色 | PROJECT |
| 部门级 | DEPARTMENT | 部门范围角色 | DEPARTMENT |

**双层角色分配**：

```
用户所有角色 = 用户直接角色(auth_user_role) ∪ 项目员工角色(ProjectStaffRole)
```

- 用户直接角色：通过 `auth_user_role` 中间表关联，用户创建时或 UserController.assignRoles 分配
- 项目员工角色：通过 `ProjectStaffRole` 关联，项目成员管理时分配

**权限类型**：

| 类型 | 说明 | 示例 |
|------|------|------|
| MENU | 菜单权限 | 系统管理、设备管理 |
| BUTTON | 按钮权限 | 新增设备、删除工单 |
| API | 接口权限 | POST /api/asset/equipment |

**权限代码格式**：`module:resource:action`，如 `asset:equipment:create`

**四级数据范围**：

| 数据范围 | 编码 | 过滤逻辑 |
|---------|------|---------|
| 全部数据 | ALL | 不做数据过滤 |
| 本项目数据 | PROJECT | WHERE project_id = ? |
| 本部门数据 | DEPARTMENT | WHERE project_id = ? AND dept_id = ? |
| 仅本人数据 | SELF | WHERE assigned_to = ? OR created_by = ? |

### 3.3 树形结构管理

**适用实体**：SpaceNode（空间节点）、Dept（部门）、SparePartCategory（备件分类）

**实现方案**：treePath 字符串路径 + parentId 自引用

**核心字段**：

| 字段 | 类型 | 说明 |
|------|------|------|
| parentId | UUID | 父节点 ID（NULL=顶级） |
| treePath | String(1000) | 物理路径，格式 `id1.id2.id3` |
| treePathName | String(1000) | 名称路径，格式 `项目/楼栋/单元/房间` |
| level | Integer | 层级深度，根节点为 0 |

**SpaceNode 空间层级**：

```
项目 (Project)
├── 楼栋 (BUILDING)       ← NodeCategory.BUILDING, level=1
│   ├── 单元 (UNIT)       ← NodeCategory.BUILDING, level=2
│   │   ├── 楼层 (FLOOR)  ← NodeCategory.BUILDING, level=3
│   │   │   └── 房间 (ROOM) ← NodeCategory.BUILDING, level=4
│   │   └── 房间 (ROOM)   ← 可跳过楼层直接挂房间
│   └── 公共用房 (PUBLIC_ROOM)
├── 商铺 (SHOP)           ← NodeCategory.BUILDING, level=2
├── 车库 (GARAGE)         ← NodeCategory.PARKING, level=1
│   ├── 停车区域 (PARKING_AREA) ← level=2
│   │   └── 车位 (PARKING_SPACE) ← level=3
├── 设备房 (EQUIPMENT_ROOM) ← NodeCategory.FACILITY, level=1
├── 公共区域 (PUBLIC_AREA) ← NodeCategory.AREA, level=1
└── 绿化区域 (GREEN_AREA) ← NodeCategory.AREA, level=1
```

**查询模式**：

| 查询需求 | 实现方式 | SQL 示例 |
|---------|---------|---------|
| 查子节点 | parentId 查询 | `WHERE parent_id = ?` |
| 查所有子孙 | treePath LIKE | `WHERE tree_path LIKE 'parentPath.%'` |
| 查祖先链 | treePath 解析 | 应用层拆分 treePath 获取祖先 ID 列表 |
| 构建完整树 | 扁平列表 + 递归 | Controller 层递归构建树形 VO |

**索引设计**：

```sql
idx_space_node_tree_path (tree_path)        -- 路径前缀查询
idx_sn_project_parent (project_id, parent_id) -- 项目+父节点
idx_sn_project_type (project_id, node_type)   -- 项目+类型
```

**已知不足**：treePath LIKE 查询在大数据量下性能不佳，未使用 PostgreSQL ltree 扩展或闭包表方案。后续可评估升级。

### 3.4 设备扩展表模式

**设计原则**：主表存储公共字段，扩展表存储专业参数，通过 equipmentType 决定扩展表。

**模式结构**：

```
Equipment (主表, ~40个公共字段)
├── EquipmentElevator (电梯扩展) ← equipment_id UNIQUE
├── EquipmentHvac (暖通扩展)     ← equipment_id UNIQUE
├── EquipmentFire (消防扩展)     ← equipment_id UNIQUE
└── EquipmentEnergy (能源计量扩展) ← equipment_id UNIQUE
```

**设备类型与扩展表映射**：

| 设备类型 | 枚举值 | 扩展表 | 无扩展表时 |
|---------|--------|--------|-----------|
| 电梯系统 | ELEVATOR | EquipmentElevator | — |
| 暖通空调 | HVAC | EquipmentHvac | — |
| 消防系统 | FIRE_PROTECTION | EquipmentFire | — |
| 能源计量 | ENERGY_METER | EquipmentEnergy | — |
| 给排水系统 | PLUMBING | — | 使用 attributes JSON |
| 电气系统 | ELECTRICAL | — | 使用 attributes JSON |
| 弱电系统 | SECURITY | — | 使用 attributes JSON |
| 景观绿化 | LANDSCAPE | — | 使用 attributes JSON |
| 厨余设备 | KITCHEN | — | 使用 attributes JSON |
| 其他设备 | OTHER | — | 使用 attributes JSON |

**扩展表服务接口模式**：

```java
public interface EquipmentElevatorService {
    Optional<EquipmentElevator> getByEquipmentId(UUID equipmentId);
    EquipmentElevator saveOrUpdate(EquipmentElevator elevator);
}
```

**扩展表 API 路径**：

```
GET  /api/asset/equipment/{id}/elevator   → 获取电梯扩展
PUT  /api/asset/equipment/{id}/elevator   → 更新电梯扩展
GET  /api/asset/equipment/{id}/hvac       → 获取暖通扩展
PUT  /api/asset/equipment/{id}/hvac       → 更新暖通扩展
GET  /api/asset/equipment/{id}/fire       → 获取消防扩展
PUT  /api/asset/equipment/{id}/fire       → 更新消防扩展
GET  /api/asset/equipment/{id}/energy     → 获取能源扩展
PUT  /api/asset/equipment/{id}/energy     → 更新能源扩展
```

**已知问题**：module-mdm 的 SpaceNode 也内嵌了设备扩展字段（isEquipment 标记），与 module-asset 的独立 Equipment 实体形成双体系并存，需统一。

### 3.5 工单状态机

**WorkOrder 状态机（6 状态）**：

```
┌─────────────┐
│   PENDING   │ ← 创建工单（默认状态）
│   (待分配)   │
└──────┬──────┘
       │ assign (派单)
       ▼
┌─────────────┐
│  ASSIGNED   │ ← 分配负责人/服务商
│   (已派单)   │
└──────┬──────┘
       │ start (开始执行)
       ▼
┌─────────────┐
│ IN_PROGRESS │ ← 记录 actualStart
│   (执行中)   │
└──────┬──────┘
       │ complete (完成)
       ▼
┌─────────────┐
│  COMPLETED  │ ← 记录故障原因/解决方案/费用
│   (已完成)   │
└──────┬──────┘
       │ verify (验收)
       ▼
┌─────────────┐
│  VERIFIED   │ ← 记录验收人/评分/备注
│   (已验收)   │
└─────────────┘

特殊: CANCELLED ← PENDING/ASSIGNED/IN_PROGRESS 可取消
      COMPLETED/VERIFIED 不可取消
```

**状态流转约束**：

| 当前状态 | 允许操作 | 下一状态 | 自动处理 |
|---------|---------|---------|---------|
| PENDING | assign | ASSIGNED | 设置 assignedTo/assignedVendor/assignedDate |
| ASSIGNED | start | IN_PROGRESS | 设置 actualStart = now() |
| IN_PROGRESS | complete | COMPLETED | 设置 actualEnd = now()，自动计算 actualHours |
| COMPLETED | verify | VERIFIED | 设置 verifiedBy/verifiedDate/rating |
| PENDING/ASSIGNED/IN_PROGRESS | cancel | CANCELLED | — |

**MaintenanceTask 状态机（6 状态，与工单类似但有差异）**：

| 差异点 | WorkOrder | MaintenanceTask |
|--------|-----------|-----------------|
| 完成方式 | 仅一种 complete | 两种：complete（简版）+ complete-details（详版） |
| 评分方式 | 验收时评分 | 验收时评分 + 独立 rate 接口 |
| 删除策略 | 物理删除 | 逻辑删除（设为 CANCELLED） |
| 完成后联动 | 无 | 自动更新设备维保记录 |

**工单编号生成规则**：

| 类型 | 格式 | 示例 |
|------|------|------|
| 工单 | WO-YYYYMMDD-XXXX | WO-20260518-0001 |
| 维保任务 | EQ-YYYYMMDD-XXXX | EQ-20260518-0001 |

**已知风险**：编号生成使用 findMaxWorkNoByPrefix 查询最大编号 +1，并发场景可能生成重复编号，需改用数据库序列或 Redis INCR。

### 3.6 健康评分算法 [Beta]

**评分公式**：

```
健康度 = 基础分(100) - 故障扣分 - 维保扣分 - 年龄扣分
最低分 = 0（不会为负数）
```

**三维扣分规则**：

| 扣分项 | 计算公式 | 参数 | 上限 |
|--------|----------|------|------|
| 故障扣分 | 故障次数(近30天) x 5 | FAILURE_DEDUCTION_PER_COUNT = 5 | 无上限 |
| 维保扣分 | (1 - 维保完成率) x 20 | MAINTENANCE_DEDUCTION_FACTOR = 20 | 20 分 |
| 年龄扣分 | 设备年龄(年) x 2 | AGE_DEDUCTION_PER_YEAR = 2 | 10 分 (MAX_AGE_DEDUCTION) |

**5 级健康等级**：

| 等级 | 枚举值 | 分数范围 | 前端颜色 |
|------|--------|---------|---------|
| 优秀 | EXCELLENT | [90, 100) | 绿色 |
| 良好 | GOOD | [75, 90) | 青色 |
| 一般 | FAIR | [60, 75) | 橙色 |
| 较差 | POOR | [40, 60) | 红色 |
| 危急 | CRITICAL | [0, 40) | 红色 |

**MTBF 计算（平均故障间隔时间）**：

```
MTBF = 运行时间(小时) / 故障次数
```

- 计算周期：默认 30 天，可自定义
- 运行时间：从第一个故障到最后一个故障的时间跨度
- 仅 1 次故障：使用默认期间天数 x 24 小时
- 无故障时返回 0

**MTTR 计算（平均修复时间）**：

```
MTTR = 总修复时间(小时) / 修复次数
```

- 仅统计已完成修复的故障记录（repairDurationHours 不为空）
- 无修复记录时返回 0

**已知问题**：

1. calculateEquipmentAge() 错误使用 SpaceNode.maintenanceContractStart 而非 Equipment.installationDate
2. projectId 硬编码为全零 UUID `00000000-0000-0000-0000-000000000000`
3. 维保完成率固定返回 1.0（TODO 标记）
4. 扣分系数（5、20、2、10）硬编码在代码中，未提取为配置

**Beta → 正式演进路径**：

| 阶段 | 时间 | 目标 |
|------|------|------|
| Beta（当前） | 2026 Q2 | 修复已知 Bug，提取配置项 |
| V1 | 2026 Q3 | 完善维保完成率计算，积累真实数据校准系数 |
| V2 | 2026 Q4 | 引入 IoT 数据，增加运行参数扣分维度 |
| V3 | 2027 Q1 | 机器学习模型，基于历史数据预测故障概率 |

### 3.7 审计日志

**记录方式**：`@OperationLog` 注解 + AOP 切面

```java
@OperationLog(operation = "创建用户", module = "USER", action = AuditLog.ActionType.CREATE)
public User createUser(User user) { ... }
```

**异步持久化**：通过 `auditLogExecutor` 线程池异步保存，避免影响业务性能

**核心字段**：

| 字段 | 说明 |
|------|------|
| userId / username | 操作人 |
| operation | 操作描述 |
| module | 模块标识（USER/ROLE/PERMISSION/PROJECT/AUTH/DEPT） |
| action | 操作类型（CREATE/UPDATE/DELETE/QUERY/VIEW/LOGIN/LOGOUT/EXPORT/IMPORT/ASSIGN/REVOKE） |
| targetType / targetId | 操作目标 |
| content | 操作内容 |
| params / result | 请求参数 / 操作结果 |
| executionTimeMs | 执行耗时 |
| status | SUCCESS / FAIL |

**查询窗口**：强制限制 30 天，超过 30 天的查询自动截断起始时间

**归档策略**：90 天以上日志归档（当前实现为直接删除，TODO: 导出至对象存储保留 3-5 年）

**索引设计**：

```sql
idx_audit_log_created_at (created_at)
idx_audit_log_user_id (user_id)
idx_audit_log_module (module)
idx_audit_log_action (action)
idx_al_user_createdat (user_id, created_at DESC)
```

**已知不足**：

1. 审计日志可篡改（无防篡改机制），需改为只追加
2. 90 天归档实为删除，不符合合规要求（物业行业需保留 3-5 年）
3. 改进方案：数据库触发器禁止 UPDATE/DELETE + 90 天后导出至 OSS/S3

### 3.8 编码生成规则

| 实体 | 编码格式 | 生成方式 | 唯一性保障 |
|------|---------|---------|-----------|
| 项目编码 | 正则 `^[a-zA-Z0-9_-]+$` | 后端 generateCode() | 数据库 UNIQUE |
| 空间编码 | **未实现** | — | — |
| 设备编码 | equipmentCode | 创建时指定 | 数据库 UNIQUE |
| 工单编号 | WO-YYYYMMDD-XXXX | findMaxWorkNoByPrefix + 1 | 应用层（有并发风险） |
| 维保任务编号 | EQ-YYYYMMDD-XXXX | 同上 | 应用层（有并发风险） |
| 计划编码 | planCode | 创建时指定 | 数据库 UNIQUE |
| 备件编码 | sparePartCode | 创建时指定 | 数据库 UNIQUE |
| 计量点编码 | EM + yyyyMMddHHmmss | generateMeterCode() | 冲突时追加后缀 |
| 记录编码 | recordCode | 创建时指定 | 数据库 UNIQUE |

**改进方向**：

1. 空间编码需实现自动生成规则（如 项目编码-楼栋号-单元号-房号）
2. 工单/任务编号改用数据库序列或 Redis INCR 保障并发安全
3. 统一编码生成服务，避免各模块各自实现

---

## 四、难点识别与应对

### 4.1 跨域业务流程的一致性保障

**难点描述**：维保任务完成后需联动更新设备信息（维保商、下次巡检日期），工单完成后需关联备件出库，能耗数据需对接账单生成。这些跨域操作需要保证数据一致性。

**应对方案**：

| 方案 | 适用场景 | 实现方式 | 一致性级别 |
|------|---------|---------|-----------|
| 同步调用 + 事务 | 强一致性要求 | @Transactional 跨模块 Service 调用 | 强一致 |
| 事件驱动 + 最终一致性 | 弱一致性可接受 | Spring ApplicationEvent + 异步监听 | 最终一致 |
| 补偿事务 | 需要回滚能力 | Saga 模式，失败时执行补偿操作 | 最终一致 |

**当前实现**：维保任务完成后同步调用 EquipmentService 更新设备，异常容错（更新设备失败不影响工单完成）。

**改进计划**：

1. 短期（Q2 2026）：保持同步调用，增加重试机制（@Retryable）
2. 中期（Q3 2026）：引入 Spring ApplicationEvent，关键操作发布领域事件
3. 远期（Q4 2026）：评估引入消息队列（RabbitMQ/Kafka）解耦跨域通信

### 4.2 工单状态机的并发控制

**难点描述**：多个用户可能同时对同一工单执行状态变更操作（如同时派单、同时完成），需要保证状态流转的正确性和幂等性。

**应对方案**：

| 机制 | 实现方式 | 说明 |
|------|---------|------|
| 乐观锁 | version 字段 + @Version | JPA 自动版本控制，更新时检查版本号 |
| 状态校验 | 业务层前置检查 | 状态变更前校验当前状态是否允许该操作 |
| 幂等性 | 幂等键 + 去重 | 重复请求返回当前状态而非报错 |
| 分布式锁 | Redis SETNX | 防止同一工单被并发操作 |

**当前实现**：仅业务层前置状态校验，无乐观锁和分布式锁。

**改进计划**：

1. 为 WorkOrder 和 MaintenanceTask 添加 version 字段（@Version）
2. 状态变更操作使用 Redis 分布式锁（key: `work_order:lock:{id}`）
3. 状态变更接口设计为幂等：重复操作返回当前状态

### 4.3 树形结构的高效查询

**难点描述**：SpaceNode 使用 treePath 字符串路径（如 `uuid1.uuid2.uuid3`），查询子孙节点需 LIKE 匹配，大数据量下性能堪忧。

**应对方案**：

| 方案 | 查询性能 | 维护成本 | 适用场景 |
|------|---------|---------|---------|
| treePath LIKE（当前） | O(n) 全表扫描 | 低 | 数据量 < 1万 |
| PostgreSQL ltree 扩展 | O(log n) 索引扫描 | 中 | 数据量 1-10万 |
| 闭包表 (Closure Table) | O(1) 直接查询 | 高（需额外表） | 数据量 > 10万 |
| 递归 CTE | O(depth) | 低 | 深度有限（< 10层） |

**当前实现**：treePath LIKE + B-tree 索引

**改进计划**：

1. 短期（Q2 2026）：确保 treePath 索引存在，添加 GIN 索引支持前缀查询
2. 中期（Q3 2026）：评估迁移至 PostgreSQL ltree 扩展，利用专用的 ltree 索引
3. 远期（Q4 2026）：若数据量超过 10 万节点，考虑闭包表方案

**递归 CTE 查询示例**（当前可用的优化方案）：

```sql
WITH RECURSIVE space_tree AS (
    SELECT * FROM mdm_space_node WHERE id = :rootId
    UNION ALL
    SELECT n.* FROM mdm_space_node n
    JOIN space_tree st ON n.parent_id = st.id
)
SELECT * FROM space_tree;
```

### 4.4 健康评分的数据积累与算法迭代

**难点描述**：健康评分算法当前为 Beta 版，扣分系数基于经验设定，缺乏真实数据校准。维保完成率固定为 1.0，影响评分准确性。

**应对方案**：

| 阶段 | 目标 | 具体措施 |
|------|------|---------|
| Beta → V1 | 修复 Bug + 提取配置 | 修正设备年龄计算、projectId 硬编码；提取扣分系数为 @ConfigurationProperties |
| V1 → V2 | 数据校准 + 完善计算 | 实现维保完成率真实计算；积累 3 个月数据后用线性回归校准系数 |
| V2 → V3 | 引入 IoT + 预测模型 | 增加运行参数扣分维度；基于历史数据训练故障预测模型 |

**配置化改进**：

```yaml
# application.yml
equipment:
  health:
    failure-deduction-per-count: 5
    maintenance-deduction-factor: 20
    age-deduction-per-year: 2
    max-age-deduction: 10
    calculation-period-days: 30
    default-inspection-cycle-days: 30
```

### 4.5 备件库存的并发出入库

**难点描述**：多个工单可能同时使用同一备件，导致库存超卖或数据不一致。

**应对方案**：

| 机制 | 实现方式 | 说明 |
|------|---------|------|
| 乐观锁 | currentStock + @Version | 出库时检查版本号，冲突时重试 |
| 库存校验 | 出库前检查 currentStock >= quantity | 防止库存为负 |
| 事务隔离 | @Transactional(isolation = SERIALIZABLE) | 最高隔离级别，性能影响大 |
| Redis 原子操作 | DECRBY 命令 | 原子性扣减，性能最优 |

**当前实现**：出库时校验库存不能为负，但无乐观锁。

**改进计划**：

1. 为 SparePart 添加 version 字段（@Version）
2. 出库操作使用 Redis DECRBY 原子扣减，成功后异步同步到数据库
3. 引入库存预占机制：工单创建时预占库存，完成时确认扣减，取消时释放

### 4.6 能耗数据的 IoT 接入

**难点描述**：当前能耗数据仅支持手动录入（MANUAL），IoT 自动采集（IOT）枚举已定义但未实现对接。

**当前状态**：

```java
public enum RecordMethod {
    MANUAL,  // 手动录入 — 已实现
    IOT      // IoT自动采集 — 枚举已定义，对接未实现
}
```

**扩展路径**：

| 阶段 | 目标 | 技术方案 |
|------|------|---------|
| Phase 1（当前） | 手动录入 | 前端表单 + 后端 API |
| Phase 2 | IoT 数据接入 | MQTT Broker + Spring Integration 消费消息 |
| Phase 3 | 实时监控 | WebSocket 推送 + 时序数据库（TimescaleDB） |
| Phase 4 | 智能告警 | 规则引擎 + 异常检测算法 |

**Phase 2 架构设计**：

```
IoT 设备 → MQTT Broker → Spring Integration → EnergyConsumptionService.recordConsumption()
                                    ↓
                            recordMethod = IOT
                            自动获取 previousReading
                            自动计算 consumption 和 amount
```

---

## 五、跨模块跨功能实现规范

### 5.1 API 设计规范

**路径前缀**：

```
/api/{module}/{resource}
```

| 模块 | 路径前缀 | 示例 |
|------|---------|------|
| auth | /api/auth | /api/auth/users, /api/auth/roles |
| mdm | /api/mdm | /api/mdm/projects, /api/mdm/space-nodes |
| asset | /api/asset | /api/asset/equipment |
| wo | /api/wo | /api/wo/work-orders |
| ops | /api/ops | /api/ops/maintenance-tasks, /api/ops/energy |

**版本管理**（待实现）：

```
当前: /api/{module}/{resource}
目标: /api/v1/{module}/{resource}
```

**分页规范**：

```java
// 请求参数
GET /api/mdm/projects?page=0&size=20&sortBy=createdAt&sortDirection=DESC

// 响应格式
{
  "code": 0,
  "message": "success",
  "data": {
    "content": [...],
    "totalElements": 100,
    "totalPages": 5,
    "number": 0,
    "size": 20
  }
}
```

**约束**：所有列表接口必须支持分页，禁止全量返回。WorkOrder 当前返回 `List<WorkOrder>` 全量数据需改造。

**错误码规范**：

| 段号 | 模块 | 范围 |
|------|------|------|
| 1xxx | 认证 | 1000-1999 |
| 2xxx | 用户 | 2000-2999 |
| 3xxx | 角色 | 3000-3999 |
| 4xxx | 权限 | 4000-4999 |
| 5xxx | 项目 | 5000-5999 |
| 6xxx | 空间/能耗 | 6000-6999 |
| 7xxx | 文件 | 7000-7999 |
| 8xxx | 工单 | 8000-8999（待分配） |
| 9xxx | 财务 | 9000-9999（待分配） |

**统一响应封装**：

```java
public class ApiResponse<T> {
    private int code;
    private String message;
    private T data;
}
```

### 5.2 数据模型规范

**主键策略**：

```java
@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private UUID id;  // 所有实体使用 UUID 主键
```

**软删除**：

```java
private Boolean isDeleted = false;  // 核心业务实体必须有此字段

// Repository 查询方法
findByIdAndIsDeletedFalse(UUID id);
findByProjectIdAndIsDeletedFalse(UUID projectId);
```

**约束**：WorkOrder 当前使用物理删除，需统一改为逻辑删除。

**审计字段**：

```java
@CreatedDate
@Column(nullable = false, updatable = false)
private LocalDateTime createdAt;

@LastModifiedDate
@Column(nullable = false)
private LocalDateTime updatedAt;

@Column(updatable = false)
private UUID createdBy;

private UUID updatedBy;
```

**约束**：所有实体必须有 createdAt 和 updatedAt 字段，使用 JPA Auditing 自动填充。

**JSONB 使用规范**：

| 场景 | 字段类型 | 说明 |
|------|---------|------|
| 照片列表 | JSONB | `List<String>` 或 `List<EquipmentPhoto>` |
| 文档列表 | JSONB | `List<EquipmentDocument>` |
| 扩展属性 | JSONB | `Map<String, Object>` 或 String 存储 JSON |
| 检查项结果 | JSONB | 结构化 JSON 数组 |

**约束**：SpaceNode.attributes 当前为 String(2000)，需改为 JSONB 类型以支持 GIN 索引和原生 JSON 查询。

**枚举策略**：

```java
// 数据库存储为字符串，JPA 实体使用枚举类型
@Enumerated(EnumType.STRING)
private UserStatus status;

// 枚举定义
public enum UserStatus {
    ACTIVE, LOCKED, DISABLED
}
```

**约束**：禁止使用 EnumType.ORDINAL，统一使用 EnumType.STRING。

### 5.3 异常处理规范

**三层异常体系**：

```
BusinessException (业务异常)
    ├── ErrorCode (错误码枚举)
    └── GlobalExceptionHandler (全局异常处理器)
```

**BusinessException 使用规范**：

```java
// 正确用法
throw new BusinessException(ErrorCode.USER_NOT_FOUND);

// 错误用法（禁止）
throw new RuntimeException("用户不存在");
```

**约束**：WorkOrderServiceImpl 中存在 `throw new RuntimeException("工单不存在")`，需替换为 BusinessException + ErrorCode。

**GlobalExceptionHandler 处理规则**：

| 异常类型 | HTTP 状态码 | 处理方式 |
|---------|-----------|---------|
| BusinessException | 200 (body 含错误码) | 返回 ApiResponse(code, message, null) |
| MethodArgumentNotValidException | 200 | 返回参数校验错误信息 |
| DataAccessException | 200 | 脱敏后返回数据库错误 |
| Exception | 200 | 通用异常兜底 |

**改进方向**：业务错误码 4xx/5xx 应映射为对应 HTTP 状态码，非标准码保持 200 但在 body 中体现。

### 5.4 权限控制规范

**注解式权限**：

```java
@PreAuthorize("hasAuthority('asset:equipment:create')")
public Equipment createEquipment(Equipment equipment) { ... }
```

**数据范围过滤**：

```java
// Service 层手动调用
if (!dataScopeService.canAccessAllData(currentUser)) {
    List<UUID> permittedProjectIds = dataScopeService.getPermittedProjectIds(currentUser);
    // 过滤查询结果
}
```

**改进方向**：通过 JPA Specification 自动拼接数据过滤条件，避免业务层遗漏。

**菜单动态渲染**（待实现）：

```
1. 前端登录后请求 GET /api/auth/users/{id}/menus
2. 后端根据用户角色返回有权限的菜单列表
3. 前端动态生成路由和菜单
```

### 5.5 前后端协作规范

**TypeScript 类型同步**：

```typescript
// 前端类型定义必须与后端枚举一致
// equipment.ts
export enum EquipmentType {
  ELEVATOR = 'ELEVATOR',
  HVAC = 'HVAC',
  FIRE_PROTECTION = 'FIRE_PROTECTION',
  // ... 与后端 EquipmentType 枚举完全一致
}
```

**约束**：当前前端能源类型（ELECTRICITY/WATER/GAS/CENTRAL_HEATING/CENTRAL_COOLING）与后端（LIGHTING/HVAC/POWER/SPECIAL/WATER/GAS）不一致，需统一。

**枚举一致性检查清单**：

| 枚举 | 前端文件 | 后端位置 | 是否一致 |
|------|---------|---------|---------|
| EquipmentType | equipment.ts | Equipment.java | 需校验 |
| EnergyType | energy.ts | EnergyMeter.java | 不一致（需修复） |
| WorkOrderStatus | work-order.ts | WorkOrder.java | 需校验 |
| MaintenanceTaskStatus | maintenance.ts | MaintenanceTask.java | 不一致（需修复） |
| TriggerType | maintenance.ts | MaintenanceTask.java | 不一致（需修复） |

**API 调用封装**：

```typescript
// src/api/xxx.ts
import request from '@/utils/request'

export function getEquipment(id: string) {
  return request.get<ApiResponse<Equipment>>(`/api/asset/equipment/${id}`)
}
```

**约束**：维保计划存在两套前端 API（maintenance.ts + maintenance-plan.ts），需合并为统一 API 文件。

### 5.6 测试规范

**TDD 开发流程**：

```
1. 编写失败测试（Red）
2. 编写最小实现代码（Green）
3. 重构优化（Refactor）
```

**测试分层**：

| 层次 | 框架 | 覆盖范围 | 当前状态 |
|------|------|---------|---------|
| 单元测试 | JUnit 5 + Mockito | Service 层业务逻辑 | 仅 EnergyMeterServiceTest |
| API 测试 | Spring MockMvc | Controller 层接口 | 缺失 |
| 集成测试 | @SpringBootTest | 跨模块交互 | 缺失 |
| E2E 测试 | Playwright/Cypress | 前端用户流程 | 缺失 |

**优先补充的单元测试**：

1. WorkOrderService — 工单状态机流转
2. LoginService — 登录认证流程
3. EquipmentHealthService — 健康评分算法
4. SparePartService — 出入库库存校验

---

## 六、数据库设计概要

### 6.1 ER 图（核心实体关系）

```mermaid
erDiagram
    User ||--o{ Role : "auth_user_role"
    Role ||--o{ Permission : "auth_role_permission"
    User ||--|| EnterpriseUser : "共享主键1:1"
    User ||--|| ProjectStaff : "1:1"
    User ||--|| Resident : "共享主键1:1"
    ProjectStaff ||--o{ ProjectStaffRole : "1:N"
    ProjectStaffRole }o--|| Role : "N:1"
    Resident ||--o{ ResidentSpace : "1:N"
    ResidentSpace }o--|| Space : "N:1"
    User ||--o{ UserProject : "1:N"
    UserProject }o--|| Project : "N:1"
    Dept ||--o{ Dept : "parentId自引用"

    Project ||--|| ProjectConfig : "1:1"
    Project ||--|| ProjectStatistics : "1:1"
    Project ||--o{ ProjectStatusHistory : "1:N"
    Project ||--o{ SpaceNode : "1:N"
    SpaceNode ||--o{ SpaceNode : "parentId自引用"

    Equipment ||--o| EquipmentElevator : "1:1"
    Equipment ||--o| EquipmentHvac : "1:1"
    Equipment ||--o| EquipmentFire : "1:1"
    Equipment ||--o| EquipmentEnergy : "1:1"
    Equipment ||--o{ EquipmentHealthScore : "1:N"
    Equipment ||--o{ EquipmentFailureHistory : "1:N"
    Equipment }o--|| OwnershipEntity : "N:1"
    Equipment }o--o| SpaceNode : "spaceNodeId"

    MaintenancePlan ||--o{ MaintenanceTask : "1:N"
    WorkOrder ||--o{ WorkOrderItem : "1:N"
    WorkOrder }o--o| MaintenancePlan : "planId"
    WorkOrder }o--o| Equipment : "equipmentId"
    MaintenanceTask }o--o| Equipment : "equipmentId"

    SparePartCategory ||--o{ SparePartCategory : "parentId自引用"
    SparePartCategory ||--o{ SparePart : "1:N"
    SparePart ||--o{ SparePartRecord : "1:N"

    EnergyMeter ||--o{ EnergyConsumption : "1:N"
    EnergyMeter }o--o| SpaceNode : "spaceNodeId"
```

### 6.2 表命名规范

**格式**：`{模块前缀}_{实体名}`

| 模块前缀 | 示例 | 说明 |
|---------|------|------|
| auth_ | auth_user, auth_role, auth_permission | 认证授权模块 |
| mdm_ | mdm_project, mdm_space_node | 主数据模块 |
| asset_ | asset_equipment, asset_equipment_elevator | 设备资产模块 |
| ops_ | ops_work_order, ops_maintenance_plan | 运维工单模块 |
| fin_ | fin_fee_item, fin_fee_bill | 财务模块（待实现） |
| sys_ | sys_audit_log, sys_config | 系统级表 |

**列命名规范**：

- 使用 snake_case：`project_id`、`created_at`、`is_deleted`
- 外键列：`{关联实体}_id`：`equipment_id`、`space_node_id`
- 布尔列：`is_` 前缀：`is_deleted`、`is_equipment`
- 时间列：`_at` 后缀：`created_at`、`updated_at`
- 日期列：`_date` 后缀：`installation_date`、`next_inspection_date`

### 6.3 索引策略

**B-tree 索引**（等值查询、范围查询、排序）：

| 表 | 索引列 | 用途 |
|----|--------|------|
| ops_work_order | (project_id, status) | 按项目+状态查询工单 |
| ops_work_order | (status, created_at) | 按状态+时间查询 |
| ops_work_order | (created_at DESC) | 时间倒序 |
| asset_equipment | (project_id, status) | 按项目+状态查询设备 |
| asset_equipment | (project_id, equipment_type) | 按项目+类型查询设备 |
| asset_equipment | (equipment_code) UNIQUE | 编码唯一 |
| mdm_space_node | (project_id, parent_id) | 项目+父节点 |
| mdm_space_node | (project_id, node_type) | 项目+类型 |
| mdm_space_node | (tree_path) | 路径前缀查询 |
| ops_equipment_failure_history | (equipment_id, failure_time DESC) | 设备故障时间线 |
| sys_audit_log | (user_id, created_at DESC) | 用户操作时间线 |

**GIN 索引**（JSONB 查询，待添加）：

```sql
CREATE INDEX idx_equipment_attributes ON asset_equipment USING GIN (attributes);
CREATE INDEX idx_equipment_photos ON asset_equipment USING GIN (photos);
CREATE INDEX idx_space_node_attributes ON mdm_space_node USING GIN (attributes);
```

**JSONB 索引使用场景**：

| 表 | 字段 | 查询场景 |
|----|------|---------|
| asset_equipment | attributes | 按扩展属性筛选设备 |
| asset_equipment | photos | 按照片类型查询 |
| ops_maintenance_task | parts_used | 按备件 ID 查询使用该备件的工单 |
| mdm_inspection_record | items | 按检查项结果查询 |

### 6.4 数据迁移策略

**工具选型**：Flyway

**迁移脚本命名规范**：

```
V{版本号}__{描述}.sql
示例:
V1__init_auth_tables.sql
V2__init_mdm_tables.sql
V3__init_asset_tables.sql
V4__init_ops_tables.sql
V5__add_equipment_health_score.sql
V6__add_space_node_indexes.sql
```

**当前状态**：未使用 Flyway，依赖 JPA 自动建表（ddl-auto: update）。

**改进计划**：

1. 短期：在开发环境继续使用 JPA 自动建表
2. 中期：引入 Flyway，将现有 schema 导出为初始迁移脚本
3. 长期：生产环境禁止 ddl-auto: update，所有变更通过 Flyway 迁移脚本执行

---

## 七、技术选型与依赖

### 7.1 后端技术栈

| 技术 | 版本 | 用途 | 说明 |
|------|------|------|------|
| Spring Boot | 3.x | 应用框架 | Java 17+，Servlet 容器 |
| Spring Security | 6.x | 安全框架 | JWT 认证 + RBAC 授权 |
| Spring Data JPA | 3.x | ORM 框架 | Hibernate 实现，自动建表 |
| Hibernate | 6.x | JPA 实现 | 实体映射、懒加载、审计 |
| MapStruct | — | 对象映射 | Entity ↔ DTO 转换 |
| Lombok | — | 代码简化 | @Data、@Builder、@RequiredArgsConstructor |
| BCrypt | — | 密码加密 | Spring Security PasswordEncoder |
| JJWT | — | JWT 工具 | Token 生成与验证 |
| Spring AOP | — | 切面编程 | 审计日志 @OperationLog |
| Spring Validation | — | 参数校验 | @NotNull、@Size、@Pattern |
| Spring Web | — | REST API | @RestController、@RequestMapping |

### 7.2 前端技术栈

| 技术 | 版本 | 用途 | 说明 |
|------|------|------|------|
| Vue | 3.x | 前端框架 | Composition API + `<script setup>` |
| TypeScript | 5.x | 类型系统 | 类型安全 |
| Ant Design Vue | 4.x | UI 组件库 | 统一视觉风格 |
| Pinia | 2.x | 状态管理 | Composition API 风格，支持持久化 |
| Vite | 5.x | 构建工具 | 快速 HMR |
| Axios | 1.x | HTTP 客户端 | 请求/响应拦截器封装 |
| Vue Router | 4.x | 路由管理 | 路由守卫 + 权限控制 |
| ECharts | 5.x | 图表库 | 健康评分趋势图 |

### 7.3 数据库

| 技术 | 版本 | 用途 | 说明 |
|------|------|------|------|
| PostgreSQL | 15+ | 主数据库 | JSONB、UUID、ltree 扩展 |
| JSONB | — | 半结构化数据 | 照片列表、文档列表、扩展属性、检查项结果 |
| UUID | — | 主键类型 | 所有实体主键使用 UUID |
| Redis | 7+ | 缓存 | 登录失败锁定、Token 缓存 |

**PostgreSQL 特性使用**：

| 特性 | 使用场景 | 当前状态 |
|------|---------|---------|
| JSONB | Equipment.photos/documents/attributes、InspectionRecord.items/problems | 部分使用（SpaceNode.attributes 降级为 String） |
| UUID | 所有实体主键 | 已使用 |
| ltree | 空间树形结构 | 未使用（使用 treePath 字符串替代） |
| GIN 索引 | JSONB 字段查询 | 未使用（待添加） |
| PostGIS | 地图空间查询 | 未使用 |

### 7.4 开发工具

| 工具 | 用途 | 说明 |
|------|------|------|
| Maven | 后端构建 | 多模块项目管理 |
| npm | 前端构建 | 依赖管理 |
| Git | 版本控制 | 分支管理 |
| Flyway | 数据库迁移 | 待引入 |
| SpringDoc/OpenAPI | API 文档 | 待引入 |

---

## 附录 A：实现状态总览

| 功能模块 | 实现状态 | 核心实体 | 说明 |
|---------|---------|---------|------|
| 用户管理 | 已实现 | User/EnterpriseUser/ProjectStaff/Resident | 4 种用户类型扩展 |
| 角色权限 | 已实现 | Role/Permission/ProjectStaffRole | 三级角色 + 四级数据范围 |
| 部门管理 | 已实现 | Dept | 树形结构，5 种部门类型 |
| 项目管理 | 已实现 | Project/ProjectConfig/ProjectStatistics | 状态流转 + 配置 + 统计 |
| 空间节点 | 已实现 | SpaceNode | 统一空间模型 + 设备扩展字段 |
| 设备台账 | 已实现 | Equipment + 4 张扩展表 | 主表 + 扩展表模式 |
| 健康评分 | 已实现(Beta) | EquipmentHealthScore | MTBF/MTTR + 三维扣分 |
| 故障历史 | 已实现 | EquipmentFailureHistory | 4 级故障 + 4 种修复结果 |
| 归属管理 | 已实现 | OwnershipEntity | 4 种归属 + 3 种主体 |
| 工单管理 | 已实现 | WorkOrder/WorkOrderItem | 6 状态状态机 |
| 维保计划 | 已实现 | MaintenancePlan | 周期性维保调度 |
| 维保任务 | 已实现 | MaintenanceTask | 6 状态 + 自动优先级判定 |
| 巡检标准 | 已实现 | InspectionItem/InspectionTemplate | 标准项库 + 模板管理 |
| 巡检记录 | 已实现 | InspectionRecord | 签到 + JSONB 结果 |
| 备件库存 | 已实现 | SparePart/SparePartCategory/SparePartRecord | 出入库 + 低库存预警 |
| 能耗计量 | 已实现 | EnergyMeter/EnergyConsumption | 手动录入 + 简单费用计算 |
| 审计日志 | 已实现 | AuditLog | AOP + 异步 + 30 天窗口 |
| 系统配置 | 已实现 | SysConfig | 键值对配置 |
| 消息通知 | **未实现** | — | NotificationChannel/Template/Rule/History |
| 收费项目 | **未实现** | — | FeeItem |
| 账单管理 | **未实现** | — | FeeBill |
| 支付记录 | **未实现** | — | FeePayment |
| 设备二维码 | **未实现** | — | 原需求有但未实现 |
| IoT 集成 | **未实现** | — | 枚举已定义，对接未实现 |
| 地图服务 | **未实现** | — | PostGIS + 高德地图 |
| SLA 管理 | **未实现** | — | 响应时间/处理时间/超时升级 |

## 附录 B：关键风险与优先行动

| 优先级 | 风险 | 行动项 | 预估工作量 |
|--------|------|--------|-----------|
| P0 | 财务域核心功能完全缺失 | 创建 module-finance，实现 FeeItem/FeeBill/FeePayment | 5 天 |
| P0 | 消息通知系统完全缺失 | 实现 NotificationChannel/Template/Rule/History | 8 天 |
| P0 | 工单全量查询 OOM 风险 | 改为分页查询 | 1 天 |
| P0 | 健康评分算法 Bug | 修正设备年龄计算和 projectId 硬编码 | 1 天 |
| P1 | 工单状态机缺少挂起/退回 | 增加 SUSPENDED/RETURNED 状态 | 3 天 |
| P1 | 工单流转记录缺失 | 实现 WorkOrderFlow | 2 天 |
| P1 | 前后端枚举不一致 | 统一能源类型/维保状态/触发类型 | 1 天 |
| P1 | 权限相关端点缺失 | 实现权限树/权限校验/用户菜单 | 3 天 |
| P2 | API 无版本管理 | 引入 /api/v1/ 前缀 | 3 天 |
| P2 | SpaceNode.attributes 非 JSONB | 改为 JSONB + GIN 索引 | 2 天 |
| P2 | 审计日志可篡改 | 改为只追加 + 归档而非删除 | 2 天 |
| P2 | 设备模型双体系并存 | 统一 MDM SpaceNode 内嵌设备与 ASSET Equipment | 3 天 |

---

> **文档说明**：本概要设计文档基于 REVERSE-AUTH/MDM/ASSET/OPS/FINANCE 五份反推设计文档、BEST-PRACTICES-REPORT 行业最佳实践评估报告、CONSISTENCY-REPORT 需求一致性评估报告综合编制，反映 2026-05-18 代码库状态。财务域（D5）核心功能标注为"待实现"，需优先启动开发。