railwaysystem/docs/development/dms-r3/10_api_and_ui_proposal.md

# 10 门禁集成内部 API 与 UI 交互设计方案 (API and UI Proposal)

> **设计声明**：本设计中所列出的 API 接口、UI 原型与权限标识均为 **R.3A 设计提案**。
> **纪律铁律**：**当前系统中上述 API 与前端页面均未实现，严禁声称接口已存在，严禁在本轮修改前端 Vue 代码或向数据库插入 `sys_menu` 记录**。

---

## 1. RailwaySystem 内部 RESTful API 设计提案

后续在 `TrainDoorAccessController` 中统一发布的中立门禁管理接口：

### 1.1 授权管理接口
| 方法 | 路径 | 权限标识提案 | 描述与行为 |
| :--- | :--- | :--- | :--- |
| `GET` | `/train/access/status/{accommodationId}` | `train:access:query` | 查询指定住宿安排的门锁授权状态与钥匙摘要（脱敏） |
| `POST` | `/train/access/grant` | `train:access:grant` | 手动/自动为住宿安排触发门锁授权下发（支持指定密码或卡号） |
| `POST` | `/train/access/revoke/{authId}` | `train:access:revoke` | 主动撤销指定门锁的开门权限（退宿、换房、退训） |
| `POST` | `/train/access/retry/{authId}` | `train:access:retry` | 对状态处于 `ISSUE_FAILED` 或 `TIMEOUT` 的授权记录发起重新下发 |
| `GET` | `/train/access/operations/{authId}` | `train:access:operation` | 查看指定授权记录关联的全部异步操作流水与 DMS 轮询结果 |
| `POST` | `/train/access/remote-unlock` | `train:access:remoteUnlock` | **高危应急**：远程紧急开锁（必填操作原因、两票审批号） |

### 1.2 资源映射管理接口
| 方法 | 路径 | 权限标识提案 | 描述与行为 |
| :--- | :--- | :--- | :--- |
| `GET` | `/train/access/mapping/list` | `train:access:mapping` | 查询本地宿舍与 DMS 房间/门锁的绑定映射列表 |
| `POST` | `/train/access/mapping/sync-dms-rooms`| `train:access:mapping` | 从 DMS 平台拉取楼栋/房间列表，辅助管理员快速配对 |
| `POST` | `/train/access/mapping/bind` | `train:access:mapping` | 将本地 `dorm_id` 显式绑定至 DMS `placeId` 及 `lockId` |

---

## 2. 权限体系提案 (`Permission Proposal`)

> **并行开发纪律**：当前 R.2 团队正在分支 `feature/rbac-r2` 上进行 RBAC 体系重构，本轮**禁止修改任何 R.2 代码，严禁操作 `sys_menu`**。以下权限标识仅作为待合并提案：

### 2.1 角色权限分配矩阵
| 权限标识 (Proposal) | 超级管理员 (Admin) | 公寓宿管员 (DormManager) | 任课教师 (Teacher) | 参训学员 (Student) |
| :--- | :---: | :---: | :---: | :---: |
| `train:access:query` (状态查看) | ✅ | ✅ | ❌ | ✅ (仅本人数据) |
| `train:access:grant` (下发钥匙) | ✅ | ✅ | ❌ | ❌ |
| `train:access:revoke` (撤销钥匙) | ✅ | ✅ | ❌ | ❌ |
| `train:access:retry` (失败重试) | ✅ | ✅ | ❌ | ❌ |
| `train:access:operation` (查看流水) | ✅ | ✅ | ❌ | ❌ |
| `train:access:mapping` (房源映射) | ✅ | ❌ | ❌ | ❌ |
| `train:access:remoteUnlock` (应急开锁) | ✅ (受控两票制) | ❌ (默认禁止) | ❌ | ❌ |

---

## 3. 管理端 UI 界面原型与交互设计 (`Admin UI Proposal`)

### 3.1 住宿安排与门禁状态整合视图 (`Accommodation View`)
在后期的学员住宿管理页面，住宿列表表格中增加【门禁授权状态】一列，以彩色徽标直观展现：

```
+---------------------------------------------------------------------------------------------------------+
| 学员姓名 | 班级计划      | 分配宿舍  | 床位 | 住宿状态 | 门锁权限状态    | 门锁凭据摘要 | 操作列               |
+---------------------------------------------------------------------------------------------------------+
| 张三     | 铁道信号第03期 | 1号楼-201 | 1号床| 已入住   | [绿色] 已生效   | 密码: ****34 | [查看流水] [撤销权限] |
| 李四     | 铁道信号第03期 | 1号楼-201 | 2号床| 预分配   | [黄色] 下发中   | 密码: ****** | [刷新状态]           |
| 王五     | 铁道车辆第01期 | 2号楼-102 | 1号床| 已入住   | [红色] 下发失败 | 密码: ****** | [重新下发] [修改排宿] |
| 赵六     | 供电检修第05期 | 2号楼-105 | 2号床| 已退宿   | [灰色] 已注销   | (已清除)     | [查看历史]           |
+---------------------------------------------------------------------------------------------------------+
```

### 3.2 异步状态前端轮询交互规则
1. 当操作员点击【下发权限】后，按钮进入 Loading 态，并立即将徽标置为【黄色 下发中】。
2. 页面前端通过 `setInterval` 每 3 秒拉取一次本地 `/train/access/status/{accommodationId}` 接口。
3. 后台轮询器完成 10 秒对账并写入数据库终态后，前端获取到最新状态自动变为【绿色 已生效】或【红色 下发失败】，并弹出 Toast 提示：“张三门锁授权已生效！”。

### 3.3 远程开锁高危交互弹窗 (`Remote Unlock Modal`)
- 若管理员点击受控的【远程应急开锁】按钮：
  - 弹出全屏遮罩红色警告框：`【高危操作警告】您正在发起沈阳房建公寓段 1号楼-201 智能门锁远程开锁！`
  - 必填项：
    1. 操作事由（下拉选择：消防逃生 / 突发医疗救治 / 机械钥匙遗失应急放行 / 现场工程检修）。
    2. 详细说明（必须录入，不少于 10 个字）。
    3. 当前登录管理员密码核验（输入正确方可点击确认）。
  - 点击提交后，后端记录完整的全要素审计日志。

---

## 4. 学员端个人中心视图设计 (`Student View Proposal`)

### 4.1 学员移动端/个人中心展示边界
- **展示要素**：
  - 本次开班信息（培训班名称、起止日期）。
  - 分配宿舍（如：沈阳房建公寓段 1号楼 2层 201室 1号床）。
  - 门锁状态（如：“门禁权限已就绪”、“有效期至 2026-09-20 18:00”）。
- **密码明文展示安全策略**：
  - **原则上不长期明文暴露完整密码**。
  - 默认展示为掩码状态：`开门临时密码：****34`。
  - 提供【显示完整密码】眼睛图标按钮：
    - 点击时弹出轻量级身份验证（如输入本人身份证后4位或手机验证码）。
    - 验证通过后展示完整密码明文（如 Pilot 采用的 6 位密码），并启动 30 秒倒计时，倒计时归零后自动恢复掩码状态。

---

## 5. DMS 资源映射与同步管理界面设计 (`Resource Sync UI`)

### 5.1 房源对齐工作流
```
[管理员进入"门锁资源映射"界面]
             │
             ▼
[点击"从DMS拉取房源目录"]
             │
             ▼ 适配器调用 POST /rest/place/room/list
[系统解析出 DMS 的 Building, Floor, Room, placeId, 挂载的 lockId, 硬件SN]
             │
             ▼
[系统依据"楼栋-楼层-房间"名称执行规则预匹配]
             │
             ▼
[管理员在界面核对预配对结果, 确认手动微调后点击"确认持久化绑定"]
             │
             ▼
[写入 train_external_resource_mapping, 完成两套系统物理基线的稳定锁定]
```
- **核心保障**：同步操作仅建立与更新映射表，**绝不自动删除或篡改本地 `train_dormitory_info` 的基础房源台账**。本地房源依然是学员管理系统的独立主数据。

---

## 6. Wave 2 Implementation Result (Wave 2 implemented against Mock DMS only)
- **阶段状态**：Wave 2 implemented against Mock DMS only。
- **Controller 与 UI 边界红线**：
  - `CONTROLLER_COUNT` = 0（本 Wave 严禁新增任何 `/train/dms/**` 控制器，所有适配层仅供 Service/Test 内部调用）。
  - `FRONTEND_MODIFIED` = 0（前端与 `build_ui` 修改文件数严格为 0）。
  - `REMOTE_UNLOCK_CONTROLLER` = 0（保持 P2/FUTURE 决策，不提供任何远程开锁入口）。
- **迁移标记**：
  - `008_RUNTIME_FIRST_RUN = NOT_EXECUTED`，`008_RUNTIME_SECOND_RUN = NOT_EXECUTED`。
  - `RUNTIME_MIGRATION_GATE_BEFORE_PRODUCTION = REQUIRED`。

---

## 7. Wave 3A Implementation Result (Wave 3A implemented against Mock DMS only)
- **阶段状态**：Wave 3A Access Authorization Orchestration Dry-Run implemented against Mock DMS only。
- **UI 与外部 API 边界纪律**：
  - `FRONTEND_MODIFIED = 0`：前端与 `build_ui` 源码变更文件数为 0，未向页面引入任何未经过评审的前端组件或菜单配置。
  - `CONTROLLER_COUNT = 0`：本阶段为纯业务编排 Dry-run 基础层，未暴露任何对外的正式或调试 Controller 端点。
  - 测试与验证完全通过 Service 层集成测试完成。管理端对账与手动干预入口（如 Manual Reconcile API）将在 Wave 3B 统一部署。