12 KiB
资料 → 产品原型 → 设计追溯审查
审查日期：2026-09-05。范围：后端 3307c23 → b683bb7，前端 0aac918 → 1576728。本附录为资料、原型和静态代码证据；运行测试结果以同目录主报告为准。
结论
本次多渠道定义、命令幂等和逐步骤留痕与资料的“同一任务贯穿训练、错误可重试、全过程留痕”方向一致。应按现有正式设计修复可复现缺陷，不把资料中尚未接入的功能直接补成新业务。
有四项需要产品确认：默认实装页面仍是离线识别回放；混合现实与现有三渠道的关系尚无直接映射；“全部步骤完成才可提交”与电气脚本的“未收尾提交后扣分”口径不同；脚本的自动评分、分级和训练后复盘是否应成为此次交付范围。以下均没有作为 bug 自动修改。
1. 原始资料与阅读证据
实际工作区为 E:/work/edit_3d，用户文本中的 edit\_3d 按该目录解释。两份 PDF 都没有可提取的文本层，已用 Poppler 将全部 11 页渲染为 PNG 并逐页查看。页码指 PDF 文件页序。
| 来源 | 页数 | SHA-256 | 本次采用的产品要求 |
|---|---|---|---|
| 维修训练内容设计.pdf | 6 | 8B5B0730D82CB6285A678584869B0B8E26C3C5A76817A7A52ABAD4BEBE46F2E8 |
P1-2：虚拟、混合现实、AI 指导实装三种方式；同任务贯穿；教员构建场景/任务、分组、下达，学员训练，数据记录分析。P3-6为具体案例，本次不扩展其中的维修操作内容。 |
| 电器控制系统故障维修脚本.pdf | 5 | A68BEB52E14FC6A39D6F81064B986DC00A868F695B30E9FBD5A309F30E60FD33 |
P1：15分钟、分步计分、容错、操作留痕、AI助教。P2-4：五阶段；P5：计分、成绩等级、重试、复盘及知识拓展。 |
references/training-design-1.png 至 training-design-6.png、references/electrical-script-1.png 至 electrical-script-5.png 保存了原始页面渲染。它们是资料截图，不是应用 E2E 截图。维修设计 P6 下半页流程图的扫描原件过淡，不能可靠逐字识别，未据此推导执行规则。
关键页预览：
维修设计 P1：训练方式与全流程
电气脚本 P5：评分、重试和复盘
2. 产品原型的实际来源
unreal_tran_web/AGENTS.md:7 指定相邻 unreal_tran_demo 为当前交互参考，同时明确 unreal_tran 已废弃。本工作区没有 unreal_tran_demo，不能把现存旧目录默认为最新产品定稿。本次以正式代码中的已移植原型、适配层、当前路由和 API wiki 的已确认决策追溯。
| 实际来源 | 证据与解释 |
|---|---|
unreal_tran_web/src/features/guide-legacy/demo-src/ |
原型源码的整树副本，不只包含作业指导书。physical-training-runtime.js:152-339,492-501 含电气训练五阶段，参考时长15分钟，阶段分值15/20/30/20/15。与电气脚本的结构相符，证明同事已经实现过相关原型。 |
unreal_tran_web/src/features/virtual-training-legacy/upstream/ |
虚拟训练兼容原型副本。adapter/runtime.ts:22-25,97-101 明确本地演示数据不入正式库。其页面成功不能单独证明正式 API 训练闭环。 |
unreal_tran_web/src/router/index.ts:275-326 |
本次虚拟训练主入口已改为正式 TeachingTaskCenterView/TeachingRunView/TeachingPreviewView；旧 /api 入口重定向；本地版保留于显式 /legacy。应优先验收正式主入口与旧链接重定向。 |
unreal_tran_web/src/features/physical-legacy/runtime.ts:12-21,64-85 |
当前实装宿主固定注入离线回放：45秒左右的视频，零分值，不写正式训练事件、不自动完成步骤。 |
unreal_tran_web/src/views/teaching/LegacyPhysicalTrainingPageView.vue:137-150 |
实际传入 legacyPhysicalOfflineReplay.task、formalExam: false、空 edgeUrl，而非将已发布任务完整步骤交给真实训练运行域。 |
unreal_tran_api/wiki/11-内容制作模块.md:35-44 |
训练编排默认本地原型工作台；正式可入库发布的接口工作台并存。这是既有产品取舍，不能在本轮顺手合并两个工作台。 |
3. 资料、设计、实现和测试映射
| 资料目标 | 产品/设计依据 | 当前实现证据 | 审查判断与验收重点 |
|---|---|---|---|
| 同一任务贯穿多种训练方式（维修设计 P1-2） | wiki19 第1-5节：公共步骤及场景依赖唯一，各渠道 profile 分开，旧单渠道兼容，任务固定快照 | src/features/training/trainingDocument.ts、TrainingChannelContract.java、TeachingSceneSnapshotService.java |
方向一致。E2E需检查多渠道保存/重开和任务渠道选择；创建任务后修改草稿不能改变已运行快照。不能将“混合现实”直接替换成“对抗”。 |
| 教员建任务/分组，学员执行（维修设计 P1） | wiki14 第1、2节；本次角色合同收敛为教员、学员、管理员；内容写入需有效教员身份 | CoreRoleContract.java、ContentAuthorizer.java、src/config/roles.ts、src/stores/auth.ts |
资料不定义管理员可绕过教员身份。按当前权限合同测试教员写入、学员拒绝、管理员纯管理身份不冒充教员；不自行放宽权限。 |
| 逐步骤计时、错误容错、全程留痕（电气脚本 P1-5） | wiki21：PENDING/IN_PROGRESS/FAILED/COMPLETED事实；尝试、失败、时间、证据；历史不补假数据 | TeachingStepRunService.java、TeachingAssignmentService.java、src/views/teaching/TeachingRunView.vue |
新事实表支持这一需求。验收应覆盖首次开始、逐步推进、失败/重试、完成后提交、历史空事实纯读取、越权读取。 |
| 正确操作只推进一次，重试不重复加分/留痕（电气脚本 P2-5的容错目标） | wiki20：开始/推进/提交/评定四命令；同一意图复用 commandId，同载荷重放，异载荷409 | src/api/teaching.ts:120-148、TeachingCommandReceiptService.java、TeachingController.java |
幂等是实现该目标的技术约束，PDF没有直接规定 commandId。验收需有断网/超时重试证据和服务端事件/事实不重复证据；不能只看按钮禁用。 |
| 五阶段15分钟、阶段分值15/20/30/20/15（电气脚本 P1-5） | 已移植原型 physical-training-runtime.js:152-339,492-501 |
该模板存在，但默认实装宿主用离线45秒回放；本次032是前泵互救的另一份五步任务，见 wiki14:610-617 | 模板存在不等于正式任务已接通；前泵五步不等于电气五阶段。测试报告应明确所测任务，避免把不同课目覆盖率合并。 |
| AI全程提示、错误预警、成绩与报告（电气脚本 P1、P5） | wiki14:101-106普通虚拟训练可配置数字教员；正式考核/非虚拟通道限制不同；wiki14:228-229客户端自动结果不是权威成绩 | AI Person绑定、正式考核投影和现有教员评定接口；实装离线候选需教员复核 | 不能通过恢复前端本地打分来补“自动评分”。应分别验收普通训练提示和正式考核隔离；是否扩大实装AI、自动结算、复盘范围需产品确认。 |
| 任务状态和结果可解释（维修设计 P1、电气脚本 P5） | wiki14 第8节：中文状态、真实成员、考场/对抗监控、结束/归档前置 | TeachingTaskCenterView.vue、TeachingConfrontationMonitorView.vue、TeachingExamMonitorView.vue |
E2E需检查已接收记录详情与进行中观察的不同入口，结束/未开始记录不请求只允许进行中的execution投影。 |
4. 需要用户确认的功能差异
下表列的是资料与当前产品边界的差异，不是已经认定的本轮回归 bug。本附录没有修改业务代码、状态机、种子数据或 DDL。
| 编号 | 现状与证据 | 需要确认的具体选择 | 确认前的处理 |
|---|---|---|---|
| F1 | 电气脚本要求完整训练；现默认实装运行/预览固定离线回放（physical-legacy/runtime.ts:12-21；LegacyPhysicalTrainingPageView.vue:137-150）。原型电气模板已有五阶段。 |
此次交付继续保留售前回放，还是另立功能任务将电气模板发布为正式内容、接入真实事件/步骤事实、提交与评定？若接入，需要明确所选训练版本与设备/人工证据来源。 | 只验收回放明确标识及现有API合同，不把候选视频当真实训练完成。 |
| F2 | 维修设计 P1-2的方式为虚拟/混合现实/AI实装；wiki19渠道为虚拟/实装/对抗。现有 WebXR 能力见 wiki14:392-405；设备面板明确健康检查不等于现场硬件已连接。 | 混合现实是否作为VIRTUAL渠道下的呈现能力/独立沉浸入口，还是需要新渠道？对抗是否是另一维度的组织形式？ | 保留现有渠道，单独列硬件未验收边界，不新增枚举/菜单/表。 |
| F3 | 电气脚本 P5允许未完成收尾时提交并扣分；wiki21:26要求新运行全部COMPLETED。实现 TeachingAssignmentService.java:734-735 明确拒绝未完成提交。 |
是否保持全部完成的强制流程，或新增“提前交卷/放弃并结算”语义？若允许提前结算，需要定义未完成、失败、超时各自的成绩及审计规则。 | 按当前设计测试“未完成提交被拒绝”；不伪造完成事实，不放开现有submit。 |
| F4 | 电气脚本 P5规定自动结算、四档成绩（90/80/70门槛）、全过程复盘与知识拓展；现有正式权威结果依服务端规则/教员评定，当前实装回放明确不自动计分。 | 这些是否属于此次交付的必验功能？若纳入，需要确认自动评分规则、等级文案、复盘证据与知识资源来源。 | 不把旧原型评分直接恢复为正式成绩；列为后续功能任务，与F1一并评审可减少重复工作。 |
5. 主测试报告应保留的证据
- 真实登录进入正式虚拟入口、任务详情/预览、学员运行；保留带任务标题的截图。
- 多渠道编辑保存与重开；确认默认渠道仍在启用集合内，停用渠道配置不会被任务误用。
- 首次开始和一次推进前后步骤表/界面；重试同命令不重复创建事件或递增次数；异载荷重用命令被拒绝。
- 未完成提交被拒绝，完成全部步骤后提交成功；教员评定可见且刷新一致。
- 正式考核不暴露提示、故障答案、评分私有规则与数字教员；他人运行/步骤访问被拒绝。
- 实装页截图必须包含“离线识别回放/需教员复核/不自动计分”边界；不能将其写成现场AI或实装闭环验收通过。
- 本轮数据库实际采用 033 → 新增035：035针对当前KingbaseES以真正的UNIQUE约束满足步骤事实表组合外键要求，历史034保留，同步更新全量DDL。执行、重跑、恢复快照和一致性核对见数据库审查及迁移执行记录。本附录的资料审查过程只读设计，未直接连接或执行数据库。
浏览器截图、HTTP结果、自动化测试结果由主审查任务补入主报告；本资料审查不宣称任何尚未执行的 E2E 已通过。
6. 补充素材选择待确认（F5）
F5来自本轮视频素材合同检查，与上文四项PDF资料差异分开记录。原默认回放视频被替换为约31.974秒的新片，但页面的12条候选及抓拍仍对应原约45秒视频。仓库中的 china-military-repair-workshop-hd-45s-system-pose1.mp4 与原验收素材SHA一致，实测约45.422秒；本轮最小修复已将默认映射恢复到匹配素材，约32秒新片保留。
需要确认：后续继续采用匹配现有阶段、候选和抓拍的原视频，还是采用新片并重新标定阶段时间、识别候选与抓拍？这不是PDF提出的新要求，也不表示视频回放已成为现场AI或正式实装训练。修复证据、视频就绪验收及最终素材确认项以主报告和前端审查为准。