blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
18a3bfb50e87e70b276b7a831fa5ee6833396bba
railwaysystem/docs/development/dms-r3/10_api_and_ui_proposal.md
T

8.5 KiB
Raw Blame History

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 房源对齐工作流

flowchart TD
    Step1["管理员进入“门锁资源映射”界面"] --> Step2["点击“从 DMS 拉取房源目录”"]
    Step2 -->|"适配器调用 POST /rest/place/room/list"| Step3["系统解析出 DMS 的 Building, Floor, Room, placeId, 挂载的 lockId, 硬件SN"]
    Step3 --> Step4["系统依据“楼栋-楼层-房间”名称执行规则预匹配"]
    Step4 --> Step5["管理员在界面核对预配对结果，确认手动微调后点击“确认持久化绑定”"]
    Step5 --> Step6["写入 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 统一部署。
Reference in new issue View Git Blame Copy Permalink