# Ether 主数据域（MDM）功能详细设计文档

**版本**: v1.0（反推自代码）  
**生成日期**: 2026-04-23  
**数据来源**: module-mdm 实际代码反推  
**代码路径**: `ether-pms/module-mdm`

---

## 一、领域概述

### 1.1 领域职责

主数据域（Master Data Management）是 Ether 系统的基础数据层，负责管理物业项目全生命周期的核心主数据，为所有业务域（工单、收费、巡检、维保等）提供统一的数据基座。

核心职责：
- **项目管理**：项目创建、状态流转、成员管理、功能配置
- **空间节点管理**：统一空间体系，树形结构管理楼栋/单元/房间/车位/设备房等
- **巡检标准管理**：巡检标准项库、巡检模板管理
- **巡检记录管理**：设备巡检记录、巡检结果跟踪
- **备件库存管理**：备件台账、分类管理、出入库操作、低库存预警
- **能耗计量管理**：计量点管理、能耗抄表记录、能耗统计分析

### 1.2 核心概念

| 概念 | 说明 | 对应实体 |
|------|------|----------|
| **项目** | 物业管理的基本单元，所有业务数据的归属 | Project |
| **空间节点** | 统一的空间体系，支持树形层级 | SpaceNode |
| **项目配置** | 项目级别的功能开关 | ProjectConfig |
| **项目统计** | 项目维度的汇总统计 | ProjectStatistics |
| **状态历史** | 项目状态变更记录 | ProjectStatusHistory |
| **巡检标准项** | 设备巡检的检查标准库 | InspectionItem |
| **巡检模板** | 按设备类型组织的巡检检查项集合 | InspectionTemplate |
| **巡检记录** | 实际巡检执行记录 | InspectionRecord |
| **备件** | 维修用备品备件 | SparePart |
| **备件分类** | 备件的分类体系 | SparePartCategory |
| **备件记录** | 备件出入库流水 | SparePartRecord |
| **计量点** | 能源计量仪表 | EnergyMeter |
| **能耗记录** | 能源消耗抄表记录 | EnergyConsumption |

### 1.3 领域边界

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                        主数据域（MDM）边界                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  项目管理  │  │ 空间节点  │  │ 巡检标准  │  │ 备件库存  │  │ 能耗计量  │    │
│  │ Project  │  │SpaceNode │  │InspectItem│  │SparePart │  │  Energy  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│       │              │              │              │              │         │
│       ▼              ▼              ▼              ▼              ▼         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │ 项目配置  │  │ 设备扩展  │  │ 巡检模板  │  │ 备件分类  │  │ 计量点   │    │
│  │  Config  │  │Equipment │  │ Template │  │ Category │  │  Meter   │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│                                                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  依赖关系：                                                                 │
│  - 所有实体均以 projectId 为核心维度                                         │
│  - SpaceNode 是空间基座，设备/计量点/巡检均关联空间节点                       │
│  - 巡检模板引用巡检标准项                                                    │
│  - 备件记录关联备件和工单                                                    │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 二、数据结构设计

### 2.1 实体总览

| # | 实体 | 表名 | 模块 | 说明 |
|---|------|------|------|------|
| 1 | Project | mdm_project | 项目管理 | 项目基础信息 |
| 2 | ProjectConfig | mdm_project_config | 项目管理 | 项目功能配置 |
| 3 | ProjectStatistics | mdm_project_statistics | 项目管理 | 项目统计快照 |
| 4 | ProjectStatusHistory | mdm_project_status_history | 项目管理 | 状态变更历史 |
| 5 | SpaceNode | mdm_space_node | 空间管理 | 统一空间节点（含设备扩展） |
| 6 | InspectionItem | mdm_inspection_item | 巡检标准 | 巡检标准项 |
| 7 | InspectionTemplate | ops_inspection_template | 巡检模板 | 巡检检查模板 |
| 8 | InspectionRecord | mdm_inspection_record | 巡检记录 | 巡检执行记录 |
| 9 | SparePart | ops_spare_part | 备件管理 | 备件台账 |
| 10 | SparePartCategory | ops_spare_part_category | 备件管理 | 备件分类 |
| 11 | SparePartRecord | ops_spare_part_record | 备件管理 | 出入库记录 |
| 12 | EnergyMeter | ops_energy_meter | 能耗管理 | 计量点 |
| 13 | EnergyConsumption | ops_energy_consumption | 能耗管理 | 能耗记录 |

### 2.2 Project（项目）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | 是 | 主键，自动生成 |
| code | String(50) | 是 | 项目编码，唯一，正则 `^[a-zA-Z0-9_-]+$`，2-50位 |
| name | String(100) | 是 | 项目名称，2-100位 |
| description | String(500) | 否 | 项目描述 |
| address | String(100) | 否 | 项目地址 |
| projectType | Enum(ProjectType) | 否 | 项目类型，默认 RESIDENTIAL |
| province | String(50) | 否 | 省 |
| city | String(50) | 否 | 市 |
| district | String(50) | 否 | 区 |
| longitude | Double | 否 | 经度 |
| latitude | Double | 否 | 纬度 |
| status | String(20) | 是 | 项目状态，默认 ACTIVE |
| buildingCount | Integer | 否 | 楼栋数 |
| unitCount | Integer | 否 | 单元数 |
| roomCount | Integer | 否 | 房间数 |
| floorCount | Integer | 否 | 楼层数 |
| logo | String(200) | 否 | 项目Logo |
| contact | String(200) | 否 | 联系人 |
| contactPhone | String(20) | 否 | 联系电话，正则 `^1[3-9]\d{9}$` |
| createdAt | LocalDateTime | 是 | 创建时间，自动填充 |
| updatedAt | LocalDateTime | 是 | 更新时间，自动填充 |

**枚举：ProjectType**

| 值 | 描述 |
|----|------|
| RESIDENTIAL | 住宅 |
| OFFICE | 办公 |
| INDUSTRIAL_PARK | 产业园区 |

**项目状态值（String类型，非枚举）**

| 值 | 描述 | 前端颜色 |
|----|------|----------|
| ACTIVE | 正常 | success |
| DISABLED | 禁用 | error |
| PENDING | 待审核 | warning |
| ARCHIVED | 已归档 | default |

### 2.3 ProjectConfig（项目配置）

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| id | UUID | 是 | - | 主键 |
| projectId | UUID | 是 | - | 项目ID，唯一 |
| enableReservation | Boolean | 否 | false | 预约功能 |
| enableVisitor | Boolean | 否 | false | 访客功能 |
| enableComplaint | Boolean | 否 | true | 投诉功能 |
| enablePayment | Boolean | 否 | false | 缴费功能 |
| enableAnnouncement | Boolean | 否 | true | 公告功能 |
| enableSurvey | Boolean | 否 | false | 问卷功能 |
| enableVote | Boolean | 否 | false | 投票功能 |
| enableMaintenance | Boolean | 否 | true | 报修功能 |
| enableAsset | Boolean | 否 | false | 资产功能 |
| customConfig | String(5000) | 否 | - | 自定义配置JSON |
| createdAt | LocalDateTime | - | 自动 | 创建时间 |
| updatedAt | LocalDateTime | - | 自动 | 更新时间 |

### 2.4 ProjectStatistics（项目统计）

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| id | UUID | - | 主键 |
| projectId | UUID | - | 项目ID，唯一 |
| memberCount | Integer | 0 | 成员数 |
| buildingCount | Integer | 0 | 楼栋数 |
| unitCount | Integer | 0 | 单元数 |
| roomCount | Integer | 0 | 房间数 |
| ownerCount | Integer | 0 | 业主数 |
| tenantCount | Integer | 0 | 租户数 |
| lastSyncedAt | LocalDateTime | - | 最后同步时间 |
| createdAt | LocalDateTime | 自动 | 创建时间 |
| updatedAt | LocalDateTime | 自动 | 更新时间 |

### 2.5 ProjectStatusHistory（状态变更历史）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | 是 | 主键 |
| projectId | UUID | 是 | 项目ID |
| fromStatus | String(20) | 否 | 原状态 |
| toStatus | String(20) | 是 | 新状态 |
| reason | String(500) | 否 | 变更原因 |
| operatorId | UUID | 否 | 操作人ID |
| operatorName | String(50) | 否 | 操作人姓名 |
| createdAt | LocalDateTime | 自动 | 创建时间 |

### 2.6 SpaceNode（空间节点）— 核心实体

SpaceNode 是 MDM 域最复杂的实体，采用统一空间模型 + 设备扩展字段的设计。

#### 2.6.1 基础字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | 是 | 主键 |
| projectId | UUID | 是 | 项目ID（注意：列名为 project_code） |
| name | String(100) | 是 | 节点名称，1-100位 |
| fullName | String(500) | 否 | 全路径名称 |
| shortName | String(50) | 否 | 简称 |
| nodeCategory | Enum(NodeCategory) | 是 | 节点大类 |
| nodeType | Enum(NodeType) | 是 | 节点类型 |
| usageType | String(30) | 否 | 用途类型 |
| parentId | UUID | 否 | 父节点ID |
| treePath | String(1000) | 否 | 物理路径 id.id.id |
| treePathName | String(1000) | 否 | 名称路径 项目/楼栋/单元/房间 |
| level | Integer | 否 | 层级深度，默认0 |
| sortOrder | Integer | 否 | 排序号，默认0 |
| status | String(20) | 否 | 状态，默认 ACTIVE |
| deliveryStatus | String(20) | 否 | 交付状态 |
| decorationStatus | String(20) | 否 | 装修状态 |

#### 2.6.2 面积信息

| 字段 | 类型 | 说明 |
|------|------|------|
| buildingArea | BigDecimal(10,2) | 建筑面积(㎡) |
| usableArea | BigDecimal(10,2) | 使用面积(㎡) |
| sharedArea | BigDecimal(10,2) | 公摊面积(㎡) |
| landArea | BigDecimal(10,2) | 占地面积(㎡) |

#### 2.6.3 地理信息

| 字段 | 类型 | 说明 |
|------|------|------|
| longitude | BigDecimal(10) | 经度 |
| latitude | BigDecimal(10) | 纬度 |
| altitude | BigDecimal(8,2) | 海拔 |
| floorNumber | Integer | 楼层号(正数地上,负数地下) |

#### 2.6.4 地址信息

| 字段 | 类型 | 说明 |
|------|------|------|
| province | String(50) | 省 |
| city | String(50) | 市 |
| district | String(50) | 区 |
| street | String(100) | 街道 |
| address | String(255) | 详细地址 |

#### 2.6.5 扩展属性

| 字段 | 类型 | 说明 |
|------|------|------|
| attributes | String(2000) | 类型特定属性（JSON格式） |

#### 2.6.6 设备扩展字段（isEquipment=true 时使用）

| 字段 | 类型 | 说明 |
|------|------|------|
| isEquipment | Boolean | 是否为设备节点，默认false |
| designLifeYears | Integer | 设计寿命(年) |
| ratedPower | BigDecimal(10,2) | 额定功率 |
| ratedVoltage | BigDecimal(10,2) | 额定电压 |
| ratedCurrent | BigDecimal(10,2) | 额定电流 |
| maintenanceVendor | String(100) | 维保厂商 |
| maintenanceVendorContact | String(50) | 维保联系人 |
| maintenanceVendorPhone | String(20) | 维保电话 |
| maintenanceContractNo | String(50) | 维保合同号 |
| maintenanceContractStart | LocalDate | 合同开始日期 |
| maintenanceContractEnd | LocalDate | 合同结束日期 |
| specialEquipmentType | String(50) | 特种设备类型 |
| specialEquipmentCert | String(100) | 特种设备证书 |
| inspectionCycle | Integer | 巡检周期(天) |
| nextInspectionDate | LocalDate | 下次年检日期 |
| lastInspectionDate | LocalDate | 上次年检日期 |
| lastInspectionResult | String(20) | 上次年检结果 |
| commonSpareParts | String(2000) | 常用备件(JSON) |
| energyConsumptionStandard | BigDecimal(12,2) | 能耗标准 |
| installationEnvironment | String(50) | 安装环境 |
| protectionLevel | String(20) | 防护等级 |

#### 2.6.7 系统字段

| 字段 | 类型 | 说明 |
|------|------|------|
| createdAt | LocalDateTime | 创建时间 |
| updatedAt | LocalDateTime | 更新时间 |
| createdBy | UUID | 创建人 |
| updatedBy | UUID | 更新人 |
| isDeleted | Boolean | 软删除标记，默认false |

#### 2.6.8 NodeCategory 枚举（节点大类）

| 值 | 描述 |
|----|------|
| BUILDING | 建筑空间 |
| PARKING | 停车空间 |
| FACILITY | 设施空间 |
| AREA | 区域空间 |

#### 2.6.9 NodeType 枚举（节点类型）— 含分类和层级

| 值 | 描述 | 所属大类 | 层级序号 |
|----|------|----------|----------|
| BUILDING | 楼栋 | BUILDING | 1 |
| UNIT | 单元 | BUILDING | 2 |
| FLOOR | 楼层 | BUILDING | 3 |
| ROOM | 房间 | BUILDING | 4 |
| SHOP | 商铺 | BUILDING | 2 |
| GARAGE | 车库 | PARKING | 1 |
| PARKING_AREA | 停车区域 | PARKING | 2 |
| PARKING_SPACE | 车位 | PARKING | 3 |
| EQUIPMENT_ROOM | 设备房 | FACILITY | 1 |
| PROPERTY_OFFICE | 物业用房 | FACILITY | 1 |
| SECURITY_ROOM | 门岗 | FACILITY | 1 |
| PUBLIC_ROOM | 公共用房 | FACILITY | 1 |
| PUBLIC_AREA | 公共区域 | AREA | 1 |
| GREEN_AREA | 绿化区域 | AREA | 1 |
| ROAD | 道路 | AREA | 1 |

#### 2.6.10 索引设计

| 索引名 | 列 | 说明 |
|--------|-----|------|
| idx_space_node_project | project_id | 按项目查询 |
| idx_space_node_parent | parent_id | 查子节点 |
| idx_space_node_type | node_type | 按类型查询 |
| idx_space_node_tree_path | tree_path | 路径查询 |
| idx_sn_project_parent | project_id, parent_id | 项目+父节点 |
| idx_sn_project_type | project_id, node_type | 项目+类型 |
| idx_sn_project_isequipment | project_id, is_equipment | 项目+设备 |
| idx_sn_project_nextinspection | project_id, next_inspection_date | 年检预警 |

### 2.7 InspectionItem（巡检标准项）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | 是 | 主键 |
| equipmentType | String(50) | 否 | 设备类型 |
| systemType | String(50) | 否 | 系统类型 |
| itemName | String(200) | 是 | 检查项名称 |
| checkMethod | String(200) | 否 | 检查方法 |
| standardValue | String(100) | 否 | 标准值 |
| isRequired | Boolean | 否 | 是否必检，默认true |
| remark | String(500) | 否 | 备注 |
| sortOrder | Integer | 否 | 排序号 |
| status | Enum(Status) | 否 | 状态，默认ACTIVE |
| createdAt | LocalDateTime | 自动 | 创建时间 |
| updatedAt | LocalDateTime | 自动 | 更新时间 |

**枚举：Status**

| 值 | 描述 |
|----|------|
| ACTIVE | 启用 |
| INACTIVE | 停用 |

### 2.8 InspectionTemplate（巡检模板）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | 是 | 主键 |
| projectId | UUID | 是 | 项目ID |
| templateCode | String | 是 | 模板编码，唯一 |
| templateName | String | 是 | 模板名称 |
| equipmentType | String | 是 | 设备类型 |
| inspectionItems | String(5000) | 否 | 检查项(JSON) |
| estimatedDuration | Integer | 否 | 预计耗时(分钟) |
| status | Enum(Status) | 否 | 状态，默认ACTIVE |
| version | Integer | 否 | 版本号，默认1 |
| createdBy | String | 否 | 创建人 |
| createdAt | LocalDateTime | 自动 | 创建时间 |
| updatedAt | LocalDateTime | 自动 | 更新时间 |

### 2.9 InspectionRecord（巡检记录）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | 是 | 主键 |
| planId | UUID | 否 | 巡检计划ID |
| equipmentId | UUID | 是 | 设备ID |
| inspectionDate | LocalDate | 是 | 巡检日期 |
| inspector | String(200) | 是 | 巡检人 |
| status | Enum(CheckStatus) | 否 | 检查状态，默认NORMAL |
| checkInTime | LocalDateTime | 否 | 签到时间 |
| checkInLocation | String(100) | 否 | 签到位置 |
| checkInPhoto | String(200) | 否 | 签到照片 |
| items | JSONB | 否 | 检查项结果列表 |
| problems | JSONB | 否 | 异常问题列表 |
| completed | Boolean | 否 | 是否完成，默认false |
| completedTime | LocalDateTime | 否 | 完成时间 |
| createdAt | LocalDateTime | 自动 | 创建时间 |

**枚举：CheckStatus**

| 值 | 描述 |
|----|------|
| NORMAL | 正常 |
| WARNING | 预警 |
| ABNORMAL | 异常 |

**items JSONB 结构示例**：
```json
[
  { "itemId": "uuid", "itemName": "检查项", "value": "实测值", "result": "PASS/FAIL", "remark": "备注" }
]
```

**problems JSONB 结构示例**：
```json
[
  { "desc": "问题描述", "photo": "照片URL", "severity": "LOW/MEDIUM/HIGH" }
]
```

**索引设计**：

| 索引名 | 列 |
|--------|-----|
| idx_ir_equipment_date | equipment_id, inspection_date |
| idx_ir_inspectiondate | inspection_date |

### 2.10 SparePart（备件）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | 是 | 主键 |
| projectId | UUID | 是 | 项目ID |
| sparePartCode | String | 是 | 备件编码，唯一 |
| sparePartName | String | 是 | 备件名称 |
| categoryId | UUID | 否 | 分类ID |
| specification | String(500) | 否 | 规格型号 |
| unit | String(50) | 是 | 计量单位 |
| safeStock | Integer | 否 | 安全库存，默认0 |
| currentStock | Integer | 否 | 当前库存，默认0 |
| unitPrice | BigDecimal(10,2) | 否 | 单价 |
| supplier | String(200) | 否 | 供应商 |
| supplierContact | String | 否 | 供应商联系方式 |
| location | String(200) | 否 | 存放位置 |
| remarks | String(1000) | 否 | 备注 |
| status | Enum(Status) | 否 | 状态，默认ACTIVE |
| createdAt | LocalDateTime | 自动 | 创建时间 |
| updatedAt | LocalDateTime | 自动 | 更新时间 |

**枚举：Status**

| 值 | 描述 |
|----|------|
| ACTIVE | 启用 |
| INACTIVE | 停用 |

**索引**：`idx_sp_project_status(project_id, status)`

### 2.11 SparePartCategory（备件分类）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | 是 | 主键 |
| parentId | UUID | 否 | 父分类ID（支持树形） |
| categoryCode | String | 是 | 分类编码，唯一 |
| categoryName | String | 是 | 分类名称 |
| description | String(500) | 否 | 描述 |
| sortOrder | Integer | 否 | 排序号 |
| createdAt | LocalDateTime | 自动 | 创建时间 |

### 2.12 SparePartRecord（备件出入库记录）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | 是 | 主键 |
| recordCode | String | 是 | 记录编码，唯一 |
| recordType | Enum(RecordType) | 是 | 记录类型 |
| sparePartId | UUID | 是 | 备件ID |
| quantity | Integer | 是 | 数量 |
| balance | Integer | 是 | 余额（操作后库存） |
| relatedOrderId | UUID | 否 | 关联工单ID |
| recordedBy | UUID | 否 | 操作人ID |
| recordDate | LocalDateTime | 否 | 操作时间，默认当前 |
| remarks | String(1000) | 否 | 备注 |

**枚举：RecordType**

| 值 | 描述 |
|----|------|
| IN | 入库 |
| OUT | 出库 |
| CHECK | 盘点 |
| ADJUST | 调整 |

### 2.13 EnergyMeter（计量点）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | 是 | 主键 |
| projectId | UUID | 是 | 项目ID |
| meterCode | String | 是 | 计量点编码，唯一 |
| meterName | String | 是 | 计量点名称 |
| energyType | Enum(EnergyType) | 是 | 能源类型 |
| spaceNodeId | UUID | 否 | 关联空间节点 |
| installationLocation | String | 否 | 安装位置 |
| ratedCapacity | BigDecimal(10,2) | 否 | 额定容量 |
| unitPrice | BigDecimal(10,4) | 否 | 单价 |
| status | Enum(Status) | 否 | 状态，默认ACTIVE |
| createdAt | LocalDateTime | 自动 | 创建时间 |
| updatedAt | LocalDateTime | 自动 | 更新时间 |

**枚举：EnergyType**

| 值 | 描述 |
|----|------|
| LIGHTING | 照明插座用电 |
| HVAC | 空调用电 |
| POWER | 动力用电 |
| SPECIAL | 特殊用电 |
| WATER | 给排水 |
| GAS | 燃气 |

### 2.14 EnergyConsumption（能耗记录）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | 是 | 主键 |
| projectId | UUID | 是 | 项目ID |
| meterId | UUID | 是 | 计量点ID |
| consumptionDate | LocalDate | 是 | 消耗日期 |
| previousReading | BigDecimal(12,2) | 否 | 上次读数 |
| currentReading | BigDecimal(12,2) | 否 | 本次读数 |
| consumption | BigDecimal(12,2) | 是 | 消耗量 |
| amount | BigDecimal(10,2) | 否 | 金额 |
| recordedBy | UUID | 否 | 记录人 |
| recordMethod | Enum(RecordMethod) | 否 | 记录方式，默认MANUAL |
| remarks | String(1000) | 否 | 备注 |
| createdAt | LocalDateTime | 自动 | 创建时间 |

**枚举：RecordMethod**

| 值 | 描述 |
|----|------|
| MANUAL | 手动录入 |
| IOT | IoT自动采集 |

**索引**：

| 索引名 | 列 |
|--------|-----|
| idx_ec_meter_date | meter_id, consumption_date |
| idx_ec_project_date | project_id, consumption_date |

### 2.15 实体关系图

```
Project (1) ──→ (N) SpaceNode          通过 projectId 关联
Project (1) ──→ (1) ProjectConfig      通过 projectId 唯一关联
Project (1) ──→ (1) ProjectStatistics   通过 projectId 唯一关联
Project (1) ──→ (N) ProjectStatusHistory 通过 projectId 关联

SpaceNode (1) ──→ (N) SpaceNode        通过 parentId 自关联（树形）
SpaceNode (1) ──→ (0..1) Equipment     通过 isEquipment 标记（设备扩展字段）

EnergyMeter (1) ──→ (N) EnergyConsumption  通过 meterId 关联
EnergyMeter ──→ SpaceNode               通过 spaceNodeId 关联

SparePartCategory (1) ──→ (N) SparePartCategory  通过 parentId 自关联（树形）
SparePartCategory (1) ──→ (N) SparePart          通过 categoryId 关联
SparePart (1) ──→ (N) SparePartRecord            通过 sparePartId 关联

InspectionItem ──→ InspectionTemplate   通过 equipmentType 逻辑关联
InspectionTemplate ──→ InspectionRecord 通过 planId 逻辑关联
InspectionRecord ──→ SpaceNode(Equipment) 通过 equipmentId 关联
```

---

## 三、API接口设计

### 3.1 ProjectController — `/api/mdm/projects`

| 编号 | 方法 | 路径 | 说明 | 请求参数 |
|------|------|------|------|----------|
| PM-001 | GET | / | 分页查询项目列表 | keyword, status, page, size, sortBy, sortDirection |
| PM-010 | GET | /selector | 获取项目选择器列表 | - |
| PM-005 | GET | /generate-code | 生成项目编码 | - |
| - | GET | /{id} | 按ID查询项目 | id(Path) |
| - | GET | /code/{code} | 按编码查询项目 | code(Path) |
| - | POST | / | 创建项目 | Project(Body) |
| - | PUT | /{id} | 更新项目 | id(Path), Project(Body) |
| - | DELETE | /{id} | 删除项目 | id(Path) |
| PM-003 | GET | /{id}/members | 获取项目成员列表 | id(Path), page, size |
| PM-003 | POST | /{id}/members | 添加项目成员 | id(Path), AddMemberRequest(Body) |
| PM-003 | DELETE | /{id}/members/{memberId} | 移除项目成员 | id(Path), memberId(Path) |
| PM-002 | GET | /{id}/statistics | 获取项目统计数据 | id(Path) |
| PM-006 | PUT | /{id}/status | 变更项目状态 | id(Path), ChangeStatusRequest(Body) |
| PM-008 | GET | /{id}/config | 获取项目配置 | id(Path) |
| PM-008 | PUT | /{id}/config | 更新项目配置 | id(Path), ProjectConfigDTO(Body) |
| PM-009 | GET | /{projectId}/delete-check | 项目删除前检查 | projectId(Path) |

**关键DTO**：

```typescript
// ProjectQueryRequest
{ keyword?: string; status?: string; page?: number; size?: number; sortBy?: string; sortDirection?: string }

// ChangeStatusRequest
{ status: string; reason?: string }

// AddMemberRequest
{ userIds: string[]; roleInProject: string }

// ProjectDeleteCheckVO
{ canDelete: boolean; reason?: string; statistics: ProjectDeleteStatistics }
```

### 3.2 SpaceNodeController — `/api/mdm/space-nodes`

| 编号 | 方法 | 路径 | 说明 | 请求参数 |
|------|------|------|------|----------|
| - | GET | / | 分页查询空间节点 | page, size |
| - | GET | /{id} | 查询节点详情 | id(Path) |
| - | GET | /project/{projectId} | 按项目查询节点列表 | projectId(Path) |
| - | GET | /project/{projectId}/tree | 获取项目空间树 | projectId(Path) |
| - | GET | /project/{projectId}/roots | 获取项目根节点 | projectId(Path) |
| - | GET | /project/{projectId}/type/{nodeType} | 按项目+类型查询 | projectId(Path), nodeType(Path) |
| - | GET | /parent/{parentId}/children | 获取子节点列表 | parentId(Path) |
| - | POST | / | 创建空间节点 | SpaceNodeCreateDTO(Body) |
| - | POST | /batch | 批量创建节点 | List\<SpaceNodeCreateDTO\>(Body) |
| - | PUT | /{id} | 更新节点 | id(Path), SpaceNodeUpdateDTO(Body) |
| - | DELETE | /{id} | 删除节点 | id(Path) |
| - | GET | /{id}/delete-check | 删除前检查 | id(Path) |
| - | DELETE | /{id}/cascade | 级联删除（含子节点） | id(Path) |
| - | GET | /{id}/equipment | 获取设备详情 | id(Path) |
| - | GET | /equipment | 获取设备列表 | projectId(Param) |
| - | GET | /special-equipment | 获取特种设备列表 | projectId(Param) |
| - | GET | /expiring-inspection | 获取即将年检设备 | projectId(Param), daysAhead(默认90) |
| - | POST | /equipment | 创建设备 | EquipmentCreateDTO(Body) |
| - | POST | /equipment/batch | 批量创建设备 | List\<EquipmentCreateDTO\>(Body) |
| - | POST | /equipment/import | Excel导入设备 | file(Multipart), projectId(Param) |
| - | GET | /{buildingId}/floor-info | 获取楼栋楼层信息 | buildingId(Path) |
| - | GET | /debug/floor-numbers | 调试：检查房间楼层号 | projectId(Param) |

**关键DTO**：

```typescript
// SpaceNodeCreateDTO / SpaceNodeUpdateForm
{ projectId, name, nodeCategory, nodeType, parentId?, buildingArea?, ... }

// SpaceNodeTreeDTO extends SpaceNode
{ ...SpaceNode, children: SpaceNodeTreeDTO[] }

// SpaceNodeDeleteCheckDTO
{ nodeId, nodeName, childCount, childTypeCount, totalDescendantCount }

// EquipmentCreateDTO
{ projectId, name, nodeType, parentId?, ...设备扩展字段 }

// FloorInfoVO
{ buildingId, buildingName, totalFloors, undergroundFloors, floors: FloorDetailVO[] }
```

### 3.3 InspectionItemController — `/api/mdm/inspection-items`

| 方法 | 路径 | 说明 | 请求参数 |
|------|------|------|----------|
| POST | / | 创建巡检标准项 | InspectionItem(Body) |
| GET | / | 查询巡检标准项列表 | equipmentType?, systemType?, activeOnly? |
| GET | /{id} | 获取标准项详情 | id(Path) |
| PUT | /{id} | 更新标准项 | id(Path), InspectionItem(Body) |
| DELETE | /{id} | 删除标准项 | id(Path) |

**查询逻辑**：activeOnly=true → 仅启用项；equipmentType+systemType → 双条件过滤；equipmentType → 单条件过滤；systemType → 系统类型过滤；无参数 → 全部。

### 3.4 InspectionTemplateController — `/api/ops/inspection-templates`

| 方法 | 路径 | 说明 | 请求参数 |
|------|------|------|----------|
| GET | / | 获取项目模板列表 | projectId(Param) |
| POST | / | 创建模板 | InspectionTemplate(Body) |
| GET | /{id} | 获取模板详情 | id(Path) |
| PUT | /{id} | 更新模板 | id(Path), InspectionTemplate(Body) |
| POST | /{id}/copy | 复制模板 | id(Path), newName(Param) |
| GET | /by-type/{equipmentType} | 按设备类型查模板 | equipmentType(Path) |

### 3.5 InspectionRecordController — `/api/mdm/inspection-records`

| 方法 | 路径 | 说明 | 请求参数 |
|------|------|------|----------|
| POST | / | 创建巡检记录 | InspectionRecord(Body) |
| GET | / | 查询巡检记录列表 | equipmentId?, planId?, inspector?, status?, startDate?, endDate? |
| GET | /{id} | 获取记录详情 | id(Path) |
| PUT | /{id} | 更新记录 | id(Path), InspectionRecord(Body) |
| DELETE | /{id} | 删除记录 | id(Path) |
| POST | /{id}/complete | 完成巡检记录 | id(Path) |

**查询逻辑**：equipmentId+日期范围 → 设备+日期；equipmentId → 设备；planId → 计划；inspector → 巡检人；status → 状态；日期范围 → 时间段；无参数 → 全部。

### 3.6 SparePartController — `/api/ops/spare-parts`

| 方法 | 路径 | 说明 | 请求参数 |
|------|------|------|----------|
| GET | /categories | 获取分类列表 | - |
| POST | /categories | 创建分类 | SparePartCategory(Body) |
| GET | / | 获取备件列表 | projectId(Param), categoryId? |
| GET | /{id} | 获取备件详情 | id(Path) |
| POST | / | 创建备件 | SparePart(Body) |
| PUT | /{id} | 更新备件 | id(Path), SparePart(Body) |
| DELETE | /{id} | 删除备件 | id(Path) |
| GET | /low-stock | 获取低库存备件 | projectId(Param) |
| POST | /in-stock | 入库操作 | StockRequest(Body) |
| POST | /out-stock | 出库操作 | OutStockRequest(Body) |
| GET | /{id}/records | 获取备件出入库记录 | id(Path) |

**关键请求体**：

```typescript
// StockRequest
{ sparePartId: UUID; quantity: Integer; recordedBy?: UUID; remarks?: String }

// OutStockRequest
{ sparePartId: UUID; quantity: Integer; relatedOrderId?: UUID; recordedBy?: UUID; remarks?: String }
```

### 3.7 EnergyController — `/api/ops/energy`

| 方法 | 路径 | 说明 | 请求参数 |
|------|------|------|----------|
| POST | /meters | 创建计量点 | EnergyMeter(Body) |
| GET | /meters | 获取计量点列表 | projectId(Param), energyType? |
| GET | /meters/{id} | 获取计量点详情 | id(Path) |
| PUT | /meters/{id} | 更新计量点 | id(Path), EnergyMeter(Body) |
| DELETE | /meters/{id} | 删除计量点 | id(Path) |
| POST | /consumption | 录入能耗记录 | RecordConsumptionRequest(Body) |
| GET | /consumption/{meterId} | 获取能耗记录 | meterId(Path), startDate?, endDate? |
| GET | /statistics/by-type | 按类型统计能耗 | projectId(Param), month(Param) |
| GET | /statistics/unit-consumption | 单位面积能耗 | projectId(Param), month(Param) |

**关键请求体**：

```typescript
// RecordConsumptionRequest
{ meterId: UUID; currentReading: BigDecimal; recordedBy?: UUID }
```

---

## 四、业务规则

### 4.1 空间节点树形管理

#### 4.1.1 树形结构规则

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

#### 4.1.2 树形路径维护

- **treePath**：物理路径，格式 `id1.id2.id3`，用于快速查询所有子孙节点
- **treePathName**：名称路径，格式 `项目/楼栋/单元/房间`，用于展示
- **level**：层级深度，根节点为0，每层+1
- 创建/移动节点时自动维护 treePath 和 treePathName

#### 4.1.3 设备扩展模式

SpaceNode 通过 `isEquipment` 字段标记是否为设备节点。设备节点在基础空间字段之外，额外使用设备扩展字段（维保信息、巡检周期、特种设备证书等）。这种设计将设备信息嵌入空间节点，而非独立设备实体。

#### 4.1.4 删除规则

- 删除前必须调用 `delete-check` 接口检查子节点数量
- 普通删除：仅删除当前节点（有子节点时拒绝）
- 级联删除：删除当前节点及所有子孙节点
- 软删除：通过 `isDeleted` 标记，非物理删除

#### 4.1.5 批量操作

- 批量创建：通过 `batch` 接口，受 `BatchOperationValidator` 限制数量
- Excel导入设备：支持 .xlsx/.xls 格式，最大1000行，文件类型校验

### 4.2 项目状态流转

#### 4.2.1 状态值

| 状态 | 描述 | 可流转到 |
|------|------|----------|
| PENDING | 待审核 | ACTIVE, DISABLED |
| ACTIVE | 正常 | DISABLED, ARCHIVED |
| DISABLED | 禁用 | ACTIVE, ARCHIVED |
| ARCHIVED | 已归档 | -（终态） |

#### 4.2.2 状态变更规则

- 每次状态变更必须记录 `ProjectStatusHistory`（fromStatus, toStatus, reason, operatorId, operatorName）
- 删除项目前必须调用 `delete-check` 检查关联数据
- 存在应收未收费用时无法删除项目

#### 4.2.3 项目成员管理

- 成员角色：PROJECT_MANAGER(项目经理)、PROJECT_ADMIN(项目管理员)、OPERATION_STAFF(运营人员)、FINANCE_STAFF(财务人员)、VIEWER(查看者)
- 员工类型：SECURITY(保安)、CLEANING(保洁)、GARDEN(绿化)、MAINTENANCE(维修)、CUSTOMER_SERVICE(客服)、PROJECT_STAFF(项目人员)
- 支持批量添加成员

### 4.3 巡检标准项管理

#### 4.3.1 标准项库

- 巡检标准项按 `equipmentType`（设备类型）和 `systemType`（系统类型）分类
- 每个标准项包含：检查项名称、检查方法、标准值、是否必检
- 标准项状态：ACTIVE(启用)/INACTIVE(停用)
- 支持按 activeOnly=true 仅查询启用项

#### 4.3.2 巡检模板

- 模板按项目+设备类型组织
- 模板包含检查项列表（JSON格式存储）
- 支持模板版本管理（version字段）
- 支持模板复制（copy接口）
- 模板与标准项通过 equipmentType 逻辑关联

#### 4.3.3 巡检记录

- 记录关联设备（equipmentId）和计划（planId）
- 检查结果状态：NORMAL(正常)/WARNING(预警)/ABNORMAL(异常)
- 支持签到信息（时间、位置、照片）
- 检查项结果和异常问题以JSONB存储
- 完成操作：调用 `complete` 接口标记完成

### 4.4 备件库存管理

#### 4.4.1 库存管理规则

- 每个备件有 `currentStock`（当前库存）和 `safeStock`（安全库存）
- 当 `currentStock < safeStock` 时触发低库存预警
- 低库存查询：`low-stock` 接口返回低于安全库存的备件列表

#### 4.4.2 出入库操作

| 操作 | 说明 | 关键字段 |
|------|------|----------|
| 入库(IN) | 增加库存 | sparePartId, quantity, recordedBy, remarks |
| 出库(OUT) | 减少库存 | sparePartId, quantity, relatedOrderId, recordedBy, remarks |
| 盘点(CHECK) | 库存盘点 | sparePartId, quantity, recordedBy |
| 调整(ADJUST) | 库存调整 | sparePartId, quantity, recordedBy |

- 每次操作记录 `SparePartRecord`，包含操作后余额（balance）
- 出库可关联工单（relatedOrderId）
- 出库时校验库存不能为负

#### 4.4.3 备件分类

- 支持树形分类（parentId 自关联）
- 分类编码唯一
- 备件通过 categoryId 关联分类

### 4.5 能耗计量管理

#### 4.5.1 计量点管理

- 计量点按能源类型分类：照明插座用电、空调用电、动力用电、特殊用电、给排水、燃气
- 计量点关联空间节点（spaceNodeId）
- 计量点状态：ACTIVE(启用)/INACTIVE(停用)

#### 4.5.2 能耗记录

- 抄表记录包含：上次读数、本次读数、消耗量、金额
- 消耗量 = 本次读数 - 上次读数
- 金额 = 消耗量 × 单价（计量点的 unitPrice）
- 记录方式：MANUAL(手动录入)/IOT(IoT自动采集)

#### 4.5.3 能耗统计

- **按类型统计**：`getConsumptionByType(projectId, month)` → `Map<EnergyType, BigDecimal>`
- **单位面积能耗**：`getUnitConsumption(projectId, month)` → 总能耗/总建筑面积
- 支持按日期范围查询能耗趋势

---

## 五、前端操作流程

### 5.1 项目管理流程

```
项目列表页 → 新建项目
    │
    ├── 填写项目基本信息（编码、名称、类型、地址）
    ├── 系统自动生成项目编码（generate-code）
    ├── 创建后自动初始化 ProjectConfig（默认配置）
    └── 跳转到项目详情

项目详情页
    ├── 基本信息Tab：编辑项目信息
    ├── 成员管理Tab：
    │   ├── 查看成员列表（分页）
    │   ├── 添加成员（从企业员工中选择）
    │   └── 移除成员
    ├── 空间管理Tab：跳转到空间节点管理
    ├── 统计数据Tab：查看项目统计
    ├── 配置管理Tab：功能开关配置
    └── 状态管理：变更项目状态（需填写原因）

项目删除
    ├── 先调用 delete-check 检查关联数据
    ├── 有应收未收费用 → 无法删除
    └── 无关联数据 → 确认删除
```

### 5.2 空间节点管理流程

```
空间管理页（左侧树 + 右侧详情）
    │
    ├── 左侧树形导航
    │   ├── 加载项目空间树（getSpaceTree）
    │   ├── 点击节点 → 右侧显示详情
    │   └── 展开/折叠节点
    │
    ├── 右侧详情区
    │   ├── 节点基本信息
    │   ├── 面积信息
    │   ├── 地址信息
    │   └── 子节点列表（表格）
    │
    ├── 新增节点
    │   ├── 选择父节点
    │   ├── 选择节点类型（NodeType）
    │   ├── 自动填充 NodeCategory
    │   └── 填写名称、面积等信息
    │
    ├── 批量创建
    │   ├── 批量创建楼栋/单元/房间
    │   └── 受 BatchOperationValidator 限制
    │
    ├── 设备管理
    │   ├── 创建设备（isEquipment=true）
    │   ├── 批量创建设备
    │   ├── Excel导入设备
    │   ├── 查看设备列表
    │   ├── 查看特种设备列表
    │   └── 查看即将年检设备（90天内）
    │
    └── 删除节点
        ├── 删除前检查（delete-check）
        └── 确认删除或级联删除
```

### 5.3 巡检管理流程

```
巡检标准项管理
    │
    ├── 标准项列表页
    │   ├── 按设备类型/系统类型筛选
    │   ├── 仅查看启用项（activeOnly）
    │   ├── 新增标准项
    │   ├── 编辑标准项
    │   └── 停用/启用标准项
    │
    └── 巡检模板管理
        ├── 模板列表页（按项目筛选）
        ├── 新增模板
        │   ├── 选择设备类型
        │   ├── 配置检查项（从标准项库选择）
        │   └── 设置预计耗时
        ├── 编辑模板
        ├── 复制模板
        └── 按设备类型查模板

巡检记录管理
    │
    ├── 记录列表页
    │   ├── 按设备/计划/巡检人/状态/日期筛选
    │   └── 查看记录详情
    │
    ├── 创建巡检记录
    │   ├── 选择设备
    │   ├── 填写巡检日期和巡检人
    │   ├── 逐项填写检查结果
    │   ├── 上报异常问题
    │   └── 签到（时间、位置、照片）
    │
    └── 完成巡检
        └── 调用 complete 接口标记完成
```

### 5.4 备件管理流程

```
备件分类管理
    │
    ├── 分类列表
    ├── 新增分类（支持树形层级）
    └── 编辑分类

备件台账管理
    │
    ├── 备件列表页
    │   ├── 按项目筛选
    │   ├── 按分类筛选
    │   ├── 低库存预警标识
    │   └── 新增/编辑/删除备件
    │
    ├── 入库操作
    │   ├── 选择备件
    │   ├── 输入入库数量
    │   └── 确认入库 → 更新 currentStock
    │
    ├── 出库操作
    │   ├── 选择备件
    │   ├── 输入出库数量
    │   ├── 可关联工单
    │   └── 确认出库 → 更新 currentStock
    │
    └── 出入库记录
        └── 查看备件的所有操作流水

低库存预警
    │
    └── 低库存备件列表（currentStock < safeStock）
```

### 5.5 能耗管理流程

```
计量点管理
    │
    ├── 计量点列表页
    │   ├── 按项目筛选
    │   ├── 按能源类型筛选
    │   └── 新增/编辑/删除计量点
    │
    └── 计量点详情
        ├── 关联空间节点
        ├── 额定容量、单价
        └── 状态管理

能耗抄表
    │
    ├── 录入能耗
    │   ├── 选择计量点
    │   ├── 输入本次读数
    │   ├── 系统自动计算消耗量和金额
    │   └── 选择记录方式（手动/IoT）
    │
    └── 能耗记录查询
        ├── 按计量点查询
        └── 按日期范围查询

能耗统计
    │
    ├── 按类型统计
    │   └── 指定月份各能源类型消耗量
    │
    └── 单位面积能耗
        └── 总能耗/总建筑面积
```

---

## 六、与原需求文档 02-SPACE_NODE_DESIGN.md 的差异对比

### 6.1 数据模型差异

| 对比项 | 原需求文档设计 | 实际代码实现 | 差异分析 |
|--------|---------------|-------------|----------|
| **API路径前缀** | `/api/v1/mdm/space-nodes` | `/api/mdm/space-nodes` | 去掉了v1版本号 |
| **code字段** | 有 `code` 列，`UNIQUE(project_id, code)` | 无 `code` 列，列名 `project_code` 实际存 projectId | 原设计的空间编码未实现，project_code 列名与实际存储不匹配 |
| **PostGIS字段** | `location GEOMETRY(Point)`, `boundary GEOMETRY(Polygon)` | 无PostGIS字段 | 地图服务未实现，仅保留经纬度数值字段 |
| **attributes字段** | JSONB类型 | String(2000) | 降级为字符串存储JSON，未使用PostgreSQL JSONB |
| **设备扩展字段** | 未设计（设备独立为 asset_equipment 表） | SpaceNode 内嵌设备扩展字段 | 实际采用"空间+设备"混合模型，isEquipment标记 |
| **NodeType枚举** | 无 PUBLIC_ROOM | 增加 PUBLIC_ROOM(公共用房) | 实际增加了公共用房类型 |
| **删除方式** | 未明确 | 软删除（isDeleted字段） | 实际采用软删除 |
| **唯一约束** | `UNIQUE(project_id, code)` | 无唯一约束 | 空间编码唯一性未在数据库层面约束 |
| **索引** | GIST空间索引、GIN属性索引 | 普通B-tree索引 | 无空间索引和JSON索引 |

### 6.2 API接口差异

| 对比项 | 原需求文档设计 | 实际代码实现 | 差异分析 |
|--------|---------------|-------------|----------|
| **树形查询** | `GET /tree` 全局树 | `GET /project/{projectId}/tree` 按项目 | 实际按项目维度查询，更合理 |
| **祖先节点** | `GET /{id}/ancestors` | 未实现 | 祖先链查询缺失 |
| **子孙节点** | `GET /{id}/descendants` | 未实现 | 可通过 treePath LIKE 查询替代 |
| **移动节点** | `PUT /{id}/move` | 未实现 | 节点移动功能缺失 |
| **类型快捷查询** | `/buildings`, `/rooms`, `/parking-spaces`, `/shops` | `GET /project/{projectId}/type/{nodeType}` | 统一为按类型查询，更通用 |
| **批量更新** | `PUT /batch` | 未实现 | 仅支持批量创建 |
| **批量删除** | `DELETE /batch` | 未实现 | 仅支持单个/级联删除 |
| **导入模板下载** | `GET /export/template` | 未实现 | 无模板下载接口 |
| **数据导出** | `GET /export` | 未实现 | 无导出功能 |
| **地图相关** | `/map/markers`, `/map/boundaries`, `/{id}/location`, `/{id}/boundary` | 未实现 | 地图服务完全未实现 |
| **统计分析** | `/statistics`, `/statistics/by-type`, `/statistics/by-status` | 未实现 | 空间统计接口缺失 |
| **删除前检查** | 未设计 | `GET /{id}/delete-check` | 实际增加了安全检查 |
| **级联删除** | 未设计 | `DELETE /{id}/cascade` | 实际增加了级联删除 |
| **设备管理** | 未设计（设备独立模块） | 设备CRUD集成在SpaceNodeController | 空间与设备管理合并 |
| **Excel导入** | 空间节点导入 | 仅设备导入 | 空间节点批量导入未实现 |
| **楼层信息** | 未设计 | `GET /{buildingId}/floor-info` | 实际增加了楼栋楼层信息接口 |

### 6.3 前端差异

| 对比项 | 原需求文档设计 | 实际代码实现 | 差异分析 |
|--------|---------------|-------------|----------|
| **地图模式** | 高德地图集成，支持标注/绘制/路径 | 未实现 | 地图功能完全未开发 |
| **MapEditor组件** | AMap SDK集成 | 未实现 | - |
| **空间编码** | 自动生成空间编码规则 | 未实现 | SpaceNode无code字段 |
| **批量创建房间** | 支持 startFloor/endFloor/roomsPerFloor 模板 | 仅支持 DTO 列表批量创建 | 智能批量创建未实现 |

### 6.4 业务规则差异

| 对比项 | 原需求文档设计 | 实际代码实现 | 差异分析 |
|--------|---------------|-------------|----------|
| **设备模型** | 独立 Equipment 实体（asset_equipment表） | SpaceNode 内嵌设备扩展字段 | 两种模型并存：module-mdm 用 SpaceNode 扩展，module-asset 用独立 Equipment |
| **项目统计** | 数据库视图实时计算 | ProjectStatistics 实体快照 | 实际采用快照模式，需手动同步 |
| **空间编码** | 自动生成编码规则 | 未实现 | 无自动编码机制 |
| **PostGIS** | 空间查询（范围搜索、距离计算） | 未使用 | 无空间数据库能力 |

### 6.5 差异总结

| 类别 | 已实现 | 部分实现 | 未实现 |
|------|--------|----------|--------|
| **数据模型** | 基础字段、树形结构、NodeType枚举 | 设备扩展字段（混合模型） | PostGIS、JSONB、空间编码 |
| **API接口** | 基础CRUD、树形查询、设备管理 | 批量操作 | 地图服务、统计分析、导入导出 |
| **前端** | 树形导航、表单编辑 | - | 地图模式、智能批量创建 |
| **业务规则** | 删除检查、级联删除 | - | 空间编码、空间查询 |

---

## 附录A：服务层接口清单

| 服务 | 关键方法 |
|------|----------|
| ProjectService | create, update, delete, findById, findByCode, queryProjects, getSelectorList, generateCode, changeStatus, checkProjectDelete |
| ProjectMemberService | getMembers, addMembers, removeMember |
| ProjectConfigService | getConfig, updateConfig |
| ProjectStatisticsService | getStatistics |
| SpaceNodeService | create, batchCreate, update, delete, deleteWithChildren, findById, findByProjectId, getTreeByProjectId, findRootsByProjectId, findChildren, findByProjectIdAndNodeType, checkDeleteInfo, getEquipmentById, getEquipmentList, getSpecialEquipmentList, getExpiringInspectionEquipment, createEquipment, batchCreateEquipment, importEquipmentFromExcel, getBuildingFloorInfo |
| InspectionItemService | createItem, getItemById, updateItem, deleteItem, getAllItems, getActiveItems, getItemsByEquipmentType, getItemsBySystemType, getItemsByEquipmentTypeAndSystemType |
| InspectionTemplateService | createTemplate, getTemplateById, updateTemplate, getTemplatesByProject, getTemplatesByType, copyTemplate |
| InspectionRecordService | createRecord, getRecordById, updateRecord, deleteRecord, completeRecord, getAllRecords, getRecordsByEquipment, getRecordsByEquipmentAndDateRange, getRecordsByPlan, getRecordsByInspector, getRecordsByStatus, getRecordsByDateRange |
| SparePartService | createSparePart, getSparePartById, updateSparePart, deleteSparePart, getSparePartsByProject, getSparePartsByCategory, getLowStockParts, inStock, outStock, getSparePartRecords, getCategories, createCategory |
| EnergyMeterService | createMeter, getMeterById, updateMeter, deleteMeter, getMetersByProject, getMetersByType |
| EnergyConsumptionService | recordConsumption, getConsumptionByMeter, getConsumptionByMeterAndDateRange, getConsumptionByType, getUnitConsumption |

---

## 附录B：前端API文件对照

| 前端文件 | 对应后端Controller | 说明 |
|----------|-------------------|------|
| `src/api/project.ts` | ProjectController | 项目CRUD、成员、配置、统计 |
| `src/api/space.ts` | SpaceNodeController | 空间节点CRUD、树形查询 |
| `src/api/inspection-item.ts` | InspectionItemController | 巡检标准项CRUD |
| `src/api/inspection-template.ts` | InspectionTemplateController | 巡检模板CRUD |
| `src/api/inspection-record.ts` | InspectionRecordController | 巡检记录CRUD |
| `src/api/sparepart.ts` | SparePartController | 备件CRUD、出入库 |
| `src/api/energy.ts` | EnergyController | 计量点CRUD、能耗记录 |
| `src/api/maintenance-plan.ts` | - | 维保计划（独立模块） |
| `src/types/project.ts` | - | 项目相关类型定义 |
| `src/types/space.ts` | - | 空间节点类型定义 |

---

**文档生成说明**：本文档基于 `ether-pms/module-mdm` 模块的实际代码反推生成，涵盖13个实体、7个控制器、11个服务接口的完整分析。所有字段、枚举、API端点均来源于实际代码，与原需求文档的差异已在第六章详细对比。