ute2e/reports/review-20260905/frontend-review.md

前端增量 Code Review

范围：unreal_tran_web 的 0aac918..1576728，以及新增正式入口所依赖的运行页与通用内容编辑器。按资料、产品原型、设计、开发、测试核对；审查完成后按用户授权提交为 3c7f295。

资料与产品原型

• 原始资料与确认原型的详细比对由本次资料审查分工提供，见同目录汇总报告。本分工未独立宣称核读全部 PDF。
• 已完整阅读前端 AGENTS.md：正式教学页面必须消费 API；训练编排复用已发布场景目标；工程修改须保持教员身份门槛；保留原型工作台与接口工作台已有入口。
• 保留既有功能与页面结构，只修复排序、保存兼容和错误遮罩。实装默认离线回放、正式虚拟训练与原型交互能力的差异属于汇总报告中的功能确认事项，本分工未改路由或扩建交互。

设计合同

• unreal_tran_api/wiki/19-训练定义渠道合同.md：一份公共步骤、多渠道差异配置；默认渠道必须启用；modeConfig 与默认渠道 profile 一致。
• unreal_tran_api/wiki/20-教学命令幂等.md：四类命令 body/header 使用同一 commandId；结果未知时复用原命令号与冻结载荷。
• unreal_tran_api/wiki/21-教学步骤运行事实.md：新运行展示服务端步骤状态；空列表仅兼容历史运行；全部步骤完成方可提交。
• 后端 TeachingAssignmentService.validateRuntimeDefinition 明确要求实装步骤进度按顺序严格递增，末步 100%。

已修复问题

编号	问题与影响	根因	最小修复
WEB-01	实装步骤倒序、删除或复制后，保存保留旧序号和旧进度，导致排序事实不一致、发布被拒。多渠道工程同样受影响。	新 resequenceSteps 直接调用归一化函数，而归一化优先保留已有 order/progressPercent。例如三步反转产生序号 3,2,1 与进度 100,67,33。	按编辑后的数组重算连续序号、实装严格递增进度；保留稳定 stepCode 及已有事件规则扩展字段。
WEB-02	通用编辑器修改默认配置后仅更新旧 modeConfig，与已有 channelProfiles 冲突；在接口编排器重开后新值被旧 profile 覆盖。切换默认渠道也未同步正式字段。	通用编辑器未跟进新渠道合同，只读写单个旧配置对象；对抗时长仍只写旧字段。	各渠道按对应 profile 回填；保存同步默认渠道、启用渠道、profile 和兼容镜像；保留其他渠道。对抗时长新旧字段同步，兼容历史 roundDuration，避免 45 分钟被默认 30 分钟替代。
WEB-03	普通虚拟训练、实装、对抗以及执行中的正式考核，可能错误显示“正式考核执行场景已关闭”。该问题在正式虚拟页面成为默认入口后更容易暴露。	遮罩的 v-else 实际绑定紧邻的“虚拟拆卸存放区”条件，而非正式考核生命周期。	改为显式判断“正式考核且运行不在 IN_PROGRESS”，其他训练与执行中的考核不显示关闭遮罩。
WEB-04	当前步骤失败后聚合运行仍为 IN_PROGRESS，页面没有可进入正式重试状态的入口。	原“开始训练”仅在 ACCEPTED 显示，未覆盖新步骤事实的 FAILED→IN_PROGRESS 重试合同。	仅当学员的运行仍在 IN_PROGRESS 且当前步骤事实为 FAILED 时显示“重试当前步骤”，复用原 start 命令及幂等 tracker；已提交、归档和已完成步骤不显示。
WEB-05	真实 E2E 截图显示场景只占视口上方约 315px，其下安全确认区在深色场景底色上显示深色文字，难以阅读。	场景组件 scoped position: relative 覆盖全局绝对定位，运行页缺少预览页已有的填充规则；runtime-safety-gate 没有任何对应样式。	仅在运行视口下补场景 absolute/inset 定位；安全区使用已有主题 surface/text 颜色，补齐卡片间距、14px 复选框文字和底部定位，不修改安全规则或推进逻辑。
WEB-06	离线回放默认视频被替换成约 32 秒的新片，但候选与抓拍仍对应约 45 秒已验收片；34 秒与 45.2 秒两个候选不可达。	当前默认文件实际 31.973991 秒；旧 12 候选时间轴不按 metadata 缩放，视频结束却会把五阶段标记为已回放。既有视频 SHA 契约实际失败。	默认引用改为仓库保留的 pose1.mp4，该文件 42,865,492 字节、SHA-256 为 B588101115196061E0D2BCE4B0BD0CB1B01CAEB7561B31D0F26F5C0E980696D4，与既有已验收视频契约完全一致，实际 45.422 秒。新 32 秒文件原样保留，是否换用新片及重标候选/抓拍列 F5 待确认，不猜测新时间轴。

修改文件：

• unreal_tran_web/src/features/training/trainingDocument.ts
• unreal_tran_web/src/views/content/ContentEditorView.vue
• unreal_tran_web/src/views/teaching/TeachingRunView.vue
• unreal_tran_web/src/styles/teaching-run-workspaces.scss
• unreal_tran_web/src/features/physical-legacy/runtime.ts
• unreal_tran_web/scripts/physical-offline-replay.contract.test.mjs
• unreal_tran_web/scripts/training-channel-profiles.contract.test.mjs
• unreal_tran_web/scripts/teaching-step-run.contract.test.mjs

验证

先加入已保存步骤排序回归：修改前 8 项测试中 2 项失败，实际观察到序号 [3,2,1] 与 [2,1]，确认不是推测问题。

修复后的命令：

node --experimental-strip-types --test scripts/physical-offline-replay.contract.test.mjs scripts/training-channel-profiles.contract.test.mjs scripts/teaching-step-run.contract.test.mjs scripts/teaching-command-idempotency.contract.test.mjs scripts/core-role-contract.test.mjs scripts/virtual-training-formal-route.contract.test.mjs scripts/training-scene-grounding.test.mjs
pnpm run build
git diff --check

• Node 回归：25/25 通过，详见 frontend-contract-tests.log。其中包含实际执行的渠道转换、已保存步骤重排、旧文档迁移、配置保存再打开、冻结命令载荷、失败步骤重试资格矩阵及离线视频 SHA/12 候选/抓拍资源等断言；路由与模板条件部分属于静态契约检查。
• 最后一轮构建通过（退出码 0）：包含 vue-tsc --noEmit、Vite 打包与旧模型 iframe 校验，详见 frontend-build.log。已有资源 URL、包体大小告警不按构建失败统计。
• git diff --check 未发现空白错误；工作区 Git 的 LF/CRLF 提醒属于换行提示。
• 浏览器 API mock 回归 15/15 通过，详见 frontend-e2e/README.md。其中军工绿/暗色两套视觉用例确认场景和 host 同为 630×583.72px；安全区标题及复选框文本对比分别为 12.00/15.30，17 张截图均保留。真实 API E2E 另见同目录汇总，不能以 mock 或 Node 检查替代。
• 视频兼容性单独核实：静态服务 HEAD 200、Range 206、video/mp4；ffprobe 显示 H.264 Main/yuv420p + AAC LC。bundled Chromium 对新旧 H.264 都返回不支持并触发 DEMUXER_ERROR_NO_SUPPORTED_STREAMS，不属于该视频的产品解码缺陷；根代理使用本机 Edge 验证 H.264 可播放，真实离线回放使用 Edge 完成。

交给 E2E 的验证点

1. 在接口编排器重排已保存的实装/多渠道步骤，保存后检查序号与实装进度；删除末步后新末步为 100%。
2. 通用编辑器修改默认配置并保存，再进接口编排器，确认新值未丢失，未修改渠道原配置保留；切默认渠道后合同字段一致。
3. 普通三渠道运行以及执行中的正式考核不出现考核关闭遮罩；未开始/提交后的正式考核显示关闭态。
4. 正式虚拟主入口、旧 /api 重定向、命令丢响应后的重放、步骤事实失败与重试、教员/管理员身份边界继续验证。
5. 失败步骤显示“重试当前步骤”；点击后通过 start 端点进入执行中、尝试次数增加、失败次数保持，重试按钮消失。
6. 等待 .teaching-three-scene 的 aria-label/.teaching-scene-status 成为“已加载发布训练场景 · N 个对象”且无资产失败提示，再检查真实资产下载响应与截图。canvas 存在不等于 GLB 就绪。场景 host 应填满运行视口；明暗主题下安全确认区均应可读。
7. 本机 Edge 播放离线素材，3 秒出现首条候选，跳转至 video.duration - 0.03 后 [data-event-timeline] [data-physical-event][data-offline-replay="true"] 应为 12 条，包含 offline-replay:replay-complete；候选仍只供教员复核，不写正式运行进度。

本分工没有数据库变更、依赖版本变更或新增产品功能。所有待确认功能范围统一列入总报告，避免分散审批。