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 统一部署。