2026-09-15 15:28:32 +08:00
# 09 数据库持久化模型方案比选与设计基线 (Database Mapping Proposal)
> **设计红线**：**本轮仅做架构比选与实体设计，禁止执行任何 DDL 脚本或修改生产数据库**。
> **设计原则**：面向未来多锁扩展与多厂商接入，保持本地宿舍台账的纯粹性，业务授权与硬件异步对账分层治理。
---
## 1. 外部资源映射模型比选 (`RESOURCE_MAPPING_RECOMMENDATION`)
### 1.1 映射关系现实挑战
1. **一个房间可能安装多把锁** ：如公寓入户门锁与套内自习室/卧室锁，单一房间可能绑定 0、1 或多把智能门锁。
2. **外部厂商多变性** ：
3. **资源解绑与重绑需求** ：房间门锁损坏更换后，仅涉及设备 SN 变更，不应引起本地宿舍主记录的历史数据污染。
### 1.2 两种设计方案对比
| 评估维度 | 方案一：在 `train_dormitory_info` 直接加列 | 方案二：独立 `train_external_resource_mapping` 表 (推荐) |
| :--- | :--- | :--- |
| **表结构改动** | 在宿管表直接加 `dms_place_id` , `dms_lock_id` , `dms_lock_sn` 等 | 物理宿舍表保持零污染；新建独立的外部资源映射关联表 |
| **一房多锁支持** | **无法支持** （单行只能记录一把锁的 SN 和 ID） | **天然支持** （一个 `dorm_id` 可对应多行锁具映射记录） |
| **多厂商与扩展性** | 差（换厂商需继续加字段，如 `hik_channel_id` ） **优秀** （通过 `vendor_code` 区分不同厂商，复用通用映射模型） |
| **设备更换生命周期** | 弱（直接覆写破坏审计历史） | **强** （可标记旧锁为 `DEPRECATED` ，新增新锁映射） |
| **迁移与实施成本** | 极低 | 低（新增一张轻量级关联表） |
### 1.3 外部资源映射推荐方案结论
**采纳方案二**：建立独立的外部资源映射模型。
- **概念模型结构设计**：
```
train_external_resource_mapping
├── mapping_id BIGINT (主键)
├── local_resource_type VARCHAR(32) ('DORMITORY_ROOM', 'DORMITORY_LOCK')
├── local_resource_id VARCHAR(32) (关联本地 dorm_id)
├── vendor_code VARCHAR(32) ('DMS_IOT')
├── external_project_id BIGINT (DMS 租户 projectId)
├── external_parent_id BIGINT (DMS 楼栋/楼层 ID)
├── external_place_id BIGINT (DMS 房间 placeId)
├── external_device_id BIGINT (DMS 门锁 lockId)
├── hardware_sn VARCHAR(64) (门锁硬件 SN / hardwareId)
├── mapping_status SMALLINT (1: 已绑定有效, 0: 待核对/失效)
├── last_sync_time TIMESTAMP (最近一次从 DMS 同步元数据的时间)
└── [标准审计列]
` ``
---
## 2. 门禁授权与操作模型三大方案深度比选
### 2.1 方案架构与评估矩阵
| 评估维度 | 方案 A: 改造并继续扩展 ` train_dorm_auth` | 方案 B: ` train_dorm_auth` 收敛为业务授权 + 独立 ` train_external_operation` (推荐) | 方案 C: 新建 ` train_door_authorization` + ` train_external_operation` |
| :--- | :--- | :--- | :--- |
| **模型设计说明** | 在现有的 ` train_dorm_auth` 表中强行塞入 ` lock_id`, ` dms_key_id`, ` operation_id`, ` password` 等列 | 保留并对齐数据库 V2 的 ` train_dorm_auth` 作为门禁授权主表；新建 ` train_external_operation` 承载所有异步轮询与重试流水 | 彻底废除 ` train_dorm_auth`，重新设计全套中立命名的门禁授权与外部操作表 |
| **一期开发复杂度** | 低（改单表） | **适中**（改主表结构 + 建流水表） | 略高（需处理原有表废弃与实体完全重构） |
| **语义与职责清晰度** | **严重混乱**（业务授权与设备单次请求纠缠，无法表达异步过程） | **良好**（业务授权状态与设备异步任务彻底解耦） | **极优**（概念完全脱离人脸/宿舍局限） |
| **一房多锁支持能力** | **无法支持**（` accommodation_id` 唯一约束导致无法为同一个住宿下发多把锁） | **支持**（主表唯一约束调整为 ` (accommodation_id, device_mapping_id)`） | **支持**（原生复合设计） |
| **异步状态与重试审计** | **丢失历史**（每次重试都会覆写 ` last_error` 和 ` operation_id`） | **完整保留**（流水表每次调用追加一行，多次轮询与超时全量追踪） | **完整保留** |
| **历史兼容与代码改动** | 兼容性最高，但长期技术负债巨大 | **平衡性最佳**（沿用 V2 数据库迁移成果，仅修正 Java 实体脱节） | 需调整较多已有引用类名 |
---
## 3. 推荐采纳模型设计基线 (` DOOR_AUTH_MODEL_RECOMMENDATION`)
综合考虑沈阳房建公寓段学员管理系统目前所处的正式 Release 阶段与 V2 数据库已经上线的实际情况，**推荐采纳【方案 B】（业务授权主表收敛 + 异步操作流水表解耦）**。
### 3.1 实体一：门禁业务授权主模型 (` TrainDormAuth` / 业务授权主表)
承担职责：表达某个学员住宿事实在某把门锁上的**长期通行权限状态**。
- ` auth_id`: BIGINT, PK
- ` accommodation_id`: BIGINT, 外键关联 ` train_accommodation` (业务事实真源)
- ` mapping_id`: BIGINT, 关联 ` train_external_resource_mapping` (目标门锁)
- ` credential_type`: VARCHAR(20) ('ONLINE_PASSWORD', 'ONLINE_CARD')
- ` credential_mask`: VARCHAR(50) (脱敏凭据摘要，如 '****34' 或 '244B****')
- ` external_key_id`: BIGINT (DMS 返回的钥匙实体 ID，用于注销撤权)
- ` auth_start`: TIMESTAMP (权限生效起始时间)
- ` auth_end`: TIMESTAMP (权限失效截止时间)
- ` auth_status`: SMALLINT (0:待下发, 1:下发中, 2:已生效, 3:下发失败, 4:撤销中, 5:已注销, 6:撤销失败)
- ` grant_version`: INT (授权版本号，换房或重新下发时自增，保障本地幂等)
- ` [标准审计列]` (` create_by`, ` create_time`, ` update_by`, ` update_time`)
### 3.2 实体二：外部异步操作流水模型 (` TrainExternalOperation` / 异步操作流水表)
承担职责：跟踪向 DMS 派发的**每一次具体 HTTP 异步任务的生命周期与轮询轨迹**。
- ` operation_local_id`: BIGINT, PK
- ` auth_id`: BIGINT, 外键关联授权主表
- ` business_action`: VARCHAR(32) ('GRANT_PASSWORD', 'REVOKE_PASSWORD', 'GRANT_CARD', 'REVOKE_CARD')
- ` vendor_code`: VARCHAR(32) ('DMS_IOT')
- ` dms_operation_id`: VARCHAR(64) (DMS 返回的 32 位 UUID 操作流水号)
- ` dms_request_type`: INT (DMS 数字请求类型，如 1=下发密码, 3=删除密码)
- ` hardware_id`: VARCHAR(64) (门锁硬件 SN)
- ` operation_status`: VARCHAR(20) ('ACCEPTED', 'UNDONE', 'SUCCESS', 'FAILED', 'TIMEOUT')
- ` poll_count`: INT (已轮询次数，初始为 0，上限通常为 3)
- ` next_poll_time`: TIMESTAMP (调度器下次拉取状态的时间，初始为 ` request_time + 10s`)
- ` request_time`: TIMESTAMP (向 DMS 发起请求的时间)
- ` complete_time`: TIMESTAMP (DMS 返回终态的时间)
- ` error_code` & ` error_message`: VARCHAR (错误摘要)
- ` sanitized_response`: VARCHAR(1000) (脱敏后的响应快照)
- ` [标准审计列]`
---
## 4. 实施阶段演进建议
在后续 R.3B 实施阶段，数据访问层的演进步骤建议为：
1. **第一步**：重构修复 Java 实体类 ` TrainDormAuth.java`，彻底移除已弃用的 ` student_id`, ` plan_id`, ` dorm_id` 字段，使其与已存在的 Kingbase 物理表字段完全对齐。
2. **第二步**：创建 ` train_external_resource_mapping` 与 ` train_external_operation` 迁移脚本（遵循系统标准 Liquibase/Flyway 规范）。
3. **第三步**：通过 Spring Data / MyBatis-Plus 完成三表关联映射。
2026-09-15 17:27:38 +08:00
### 4.1 Wave 0 Implementation Result (第一步已正式交付)
- **已完成事项**：
1. 重构并修复 ` TrainDormAuth.java`，彻底废弃了向 ` train_dorm_auth` 写入 ` student_id`, ` plan_id`, ` dorm_id`, ` bed_no`, ` create_user` 的历史假设。
2. 补齐 ` TrainAccommodation.java`、` TrainAccommodationMapper.java`、` TrainAccommodationMapper.xml`、` ITrainAccommodationService` 以及 ` TrainAccommodationServiceImpl`，完全对齐 V2 生产物理结构。
3. 严格禁止在 Wave 0 中引入任何 DMS 物理字段（如 ` lock_id`, ` place_id`, ` operation_id`），保持 Vendor-Neutral 纯净业务边界。
4. 生产 Migration 检查：` MIGRATION_REQUIRED = NO`，生产数据库零写入、零变更。
### 4.2 Wave 0.1 Accommodation History Migration (006 迁移方案与基数冻结)
- **领域基数与物理约束演进**：
- **历史模型**： Enrollment 1:N Accommodation History`，允许学员由于调房等产生多条住宿历史。
- **唯一性收敛**： Enrollment 1:0..1 Active Accommodation`，原全局唯一约束 ` UNIQUE(enrollment_id)` 阻碍了历史留痕，演进为针对有效状态（` accommodation_status IN (0, 1)`）的局部唯一索引。
- **授权关联**： Accommodation 1:0..1 DoorAuthorization`，门禁授权强引用住宿实体。
- **时间范围特性**： TIME_RANGE_SUPPORT = LIMITED`，当前物理表仅有 ` assigned_time`，未扩展起止时间列。
- **006 Migration 脚本设计与验证**：
- 文件路径：` RuoYi-Vue/sql/system/kingbase/006_accommodation_history_constraint.sql`
- 安全编号：` 006`（避免与 R.2 占用的 004/005 冲突）。
- 执行安全机制：
1. 前置重复数据检查：存在并发违规 active 记录时直接 ` RAISE EXCEPTION` 阻断。
2. 严格条件 DROP：仅当原约束 ` uq_accommodation_enroll` 确认为 ` UNIQUE (enrollment_id)` 时执行 drop。
3. 创建局部唯一索引：` CREATE UNIQUE INDEX IF NOT EXISTS uq_accommodation_enroll_active ON train_accommodation (enrollment_id) WHERE accommodation_status IN (0, 1);`
4. 幂等防护：重复执行幂等安全。
- 生产执行纪律：本脚本已在单元/契约测试中完成全量静态与逻辑校验，**禁止在生产库执行**。
2026-09-16 10:22:50 +08:00
### 4.3 Wave 1 Implementation Result (外部资源映射与操作流水持久化落地 - Wave 1 implemented)
- **阶段状态**：
- **物理模型与引用决策**：
- **资源映射表 (` train_external_resource_mapping`)**：
- 引用模型：` RESOURCE_MAPPING_REFERENCE_MODEL = DORM_ID_FK`，直接建立外键关联 ` train_dormitory_info(dorm_id)`，确保一期强完整性。
- 房间映射基数：` ROOM_MAPPING_CARDINALITY = Dormitory 1:0..1 Active Room (Dormitory 1:N History)`，局部唯一索引 ` uq_ext_res_map_active_room`。
- 锁映射基数：` LOCK_MAPPING_CARDINALITY = Dormitory 1:0..N DoorLocks`，原生支持一房多锁，` is_primary` 标记主门锁。
- 外部资源唯一性：` EXTERNAL_RESOURCE_ACTIVE_UNIQUENESS = Vendor + External Resource ID + Active Unique`，局部唯一索引 ` uq_ext_res_map_active_ext_res`。
- **操作流水表 (` train_external_operation`)**：
- 引用模型：` OPERATION_REFERENCE_MODEL = DOOR_AUTH_ID_FK`，直接建立外键关联 ` train_dorm_auth(auth_id)`。
- 授权操作基数：` DOOR_AUTH_OPERATION_CARDINALITY = DoorAuthorization 1:N ExternalOperation`，每次具体下发与重试均产生新记录。
- 本地幂等键：` IDEMPOTENCY_MODEL`，唯一索引 ` uq_ext_op_idempotency`。
- 待轮询复合索引：` idx_ext_op_poll`，高效支持状态机轮询。
- **008 迁移脚本交付 (` 008_external_resource_operation.sql`)**：
- 安全编号：` 008`（
- 纯增量与幂等设计：无 DROP TABLE，无 TRUNCATE，无 DELETE，无明文密码/Token敏感字段。
- 生产状态：` PRODUCTION_DB_MODIFIED? NO`，未在生产数据库执行。
