railwaysystem/docs/current/07-KNOWN-GAPS.md

07 - 内部已知缺口与外部阻塞清单 (Known Gaps)

最高准则：

1. 本清单仅记录经过当前真实代码、测试断言或运行时验证确认的客观事实；
2. 严禁自动修复：本轮任务为 Documentation Bootstrap，严禁擅自修改业务代码或数据库尝试修复这些问题；
3. 历史已解决的问题已移出本清单，本清单是研发团队排期解决的唯一现行缺陷总账。

---

1. 内部产品级阻断缺陷 (Internal Product Blockers)

🔴 GAP-01: ACCOM-PERM-01 — 住宿生命周期操作未授予业务角色

• 缺陷标识：ACCOM-PERM-01
• 严重等级：BLOCKER (产品级阻断)
• 发现时间：2026-09-23
• 影响场景：
  • 直接影响：SM-10 (学员入住办理 0→1)、SM-11 (预分配退宿 0→2)、SM-12 (在住退宿 1→2 及撤销门锁授权)、SM-13 (调房换宿)；
  • 间接影响：BR-11、EXT-02（依赖退宿触发外部撤权）；
  • 累计阻断 6 个业务验收场景。
• 根因技术剖析：
  1. 前端门控：ruoyi-ui/src/views/train/accommodation/index.vue 中，“入住”与“删除”按钮由 v-hasPermi="['train:accommodation:edit', 'train:accommodation:remove']" 双重权限门控；“调房”与“退宿”由 train:accommodation:edit 门控；
  2. 系统菜单缺失：数据库 sys_menu 中虽然定义了 train:accommodation:edit（menu_id: 2263），但 train:accommodation:remove 在 sys_menu 中完全不存在 (count = 0)；
  3. 角色授权不足：业务管理员角色 train_admin 在权限配置中仅被授予了 train:accommodation:list、train:accommodation:query 与 train:accommodation:add，无 :edit 与 :remove 权限；
  4. 为何前期自测未暴露：早期自动化测试脚本使用超级管理员 admin 运行，RuoYi 框架对 admin 账号默认返回 *:*:* 全放行，导致非超管角色的权限缺失被严重掩盖。
• 当前处置要求：客观记录于本清单，严禁在文档梳理轮次擅自修改 SQL 或代码；待后续产品修复阶段统一闭环。

---

2. 外部客观环境阻塞项 (External Environmental Blockers)

🟡 GAP-02: DMS 外部物理房间与通电门锁硬件缺失

• 缺陷标识：DMS-HARDWARE-01
• 严重等级：BLOCKED_EXTERNAL (外部客观阻塞)
• 客观事实：
  • 局域网内 DMS 厂商测试环境网络畅通，官方账号鉴权与 Token 获取通过（7200秒有效）；
  • 只读 API（建筑、楼层、房间、门锁）接口响应结构解析通过；
  • 但该测试环境当前挂载的物理建筑、房间与门锁数量均为 0；
  • 现场缺少实体通电门锁设备与物理沙箱，无法验证实际刷卡或密码开锁。
• 安全红线：
  • 严禁在无客户明确指定真实测试门锁前向未知外部设备发起 Mutation 写操作 (REAL_DMS_MUTATION_COUNT = 0)；
  • 生产环境严禁集成远程开锁 (Remote Unlock)。
• 解除阻塞条件：沈阳房建公寓段在现场为系统划分具体的实体测试房间，并完成智能门锁通电上云。

---

3. 研发推进中与待确认功能缺口 (In-Progress & Pending Gaps)

🔵 GAP-03: 成绩管理动态权重与评定交互闭环 (C03)

• 状态：PARTIAL (推进中)
• 现状：物理表 train_score_info 已建立，支持基础成绩录入；
• 缺口：
  • 理论与实作多科目加权汇总计算算法的前端交互尚未收敛；
  • 教师工作台专属打分视图与成绩单导出功能尚在研发收尾阶段。

🔵 GAP-04: 学员 360 度成长画像多维雷达模型 (C05)

• 状态：PARTIAL (部分能力具备)
• 现状：基础档案卡、考勤出勤统计、学习时长累计等数据展现已打通；
• 缺口：五维能力评价模型指标权重、评语自动生成算法尚未获得甲方正式确认，当前维持基础视图呈现。

🔵 GAP-05: 考勤统计指标口径待确认项 (PENDING-01 ~ PENDING-04)

• 状态：PENDING_CLIENT_CONFIRMATION
• 待确认业务规则：
  1. PENDING-01：未报到参训学员开班后是否从第一节课起计入应到出勤分母；
  2. PENDING-02：经审批合规的请假人次是否从出勤率分母中扣除；
  3. PENDING-03：放弃参训学员在放弃时间节点前后的历史课次有效性切分；
  4. PENDING-04：请假是否计入考勤异常 Top 10 预警排行榜（当前系统支持通过开关集中控制）。