开发环境 · 2026-09-10 — 2026-09-11 · 顺序实施与回归

作业指导正式接口与教学闭环

已完成编辑器接入、教学阅读记录、真实 HTTP 联调三项实施。正式发布工程 412，版本 V3.0.0（版本 ID 472）。

58/58E2E 检查点通过

391后端测试通过

17关键截图

3保留复核工程

实施内容

顺序	落地结果	验证方式
1. 内容、资源、版本	完整编辑文档写入正式内容服务；上传资源进入受控存储；模板、模型和场景从正式接口加载；保存、发布、历史版本及恢复使用服务端版本。场景资源固定到发布版本，修改草稿不改变已发布教学内容。	新建、模板生成、保存重开、GLB/图片/视频上传、固定场景引用、修订与发布、OFD 和离线 ZIP 实际下载。
2. 教学阅读闭环	教学端消费正式发布文档与受控资源；阅读位置、笔记、收藏按用户和发布版本独立保存；记录开始/完成、反馈与处理，提供授权聚合统计。	翻页恢复、笔记增改删、收藏取消、动态步骤同步进度、学员权限及数据隔离、反馈回复、完成记录。
3. 真实 HTTP 联调	接口页面通过统一 HTTP 客户端调用 Gateway/业务服务，展示真实响应。涵盖内容、资源、版本、教学、个人阅读记录、统计与交付物。	浏览器实际 GET/PUT；旧版本返回 409；错误方法返回 405；未经授权内容和统计接口返回 403。

接口沿用平台统一登录会话与权限体系。第三方系统需取得平台会话；数字人开放应用 APPID 不用于这组作业指导接口。

本轮修复

完整文档校验及正式资源 URI 保留；教学投影转换为受控下载地址，避免文件存储地址直接暴露或刷新后丢失。
大 GLB 流式下载被默认 30 秒中断；异步流响应超时调整为可配置的 30 分钟。
保存与发布并发造成旧版本冲突；发布前等待自动保存队列完成。
阅读器初始化零页记录、只读目录/动画选择被拦截、动态页进度未同步、笔记删除后编辑框残留。
离线模型切换后的矩阵与镜头适配错误，导致场景偏出画面。
图片、视频海报的正式 URI 被过滤；视频完成加载后动态预览未刷新。已验证受控视频实际播放。
发布弹窗与动态白纸内容的暗色主题文字对比度。

测试结果

浏览器为 Edge / Playwright，主要视口 1920×1080。管理操作使用内部维护账号；教学权限使用临时学员账号，测试后已清理。HTTP 通过 Web 6180 → Gateway 6100 → Tran 6102。

mvn -pl ut_tran -am test package：391 项通过，0 失败、0 错误、0 跳过。
pnpm run build：类型检查、Vite 构建与模型编辑器发布资源校验通过；保留既有 chunk 大小及运行时资源 URL 警告。

正式工程新建 JSON 证据

检查点	结果
新建请求实际进入内容服务真实 HTTP 请求成功；响应内容已脱敏。	通过
正式后台可查询新工程	通过

模型资源上传与恢复 JSON 证据

检查点	结果
上传 09-Fox.glb 真实 HTTP 请求成功；响应内容已脱敏。	通过
上传 08-CesiumMilkTruck.glb 真实 HTTP 请求成功；响应内容已脱敏。	通过
刷新后受控模型资源恢复显示	通过

固定场景版本与修订 JSON 证据

检查点	结果
新修订保持原发布版本可阅读	通过
狐狸与卡车场景固定版本已保存 {"old":"469","published":"469","assets":7,"bindings":["160@463","159@209"],"version":12}	通过

正式发布与交付物 JSON 证据

检查点	结果
正式发布事务完成真实 HTTP 请求成功；响应内容已脱敏。	通过
教学指导书列表出现正式发布工程	通过
发布版本提供 OFD 与离线 ZIP	通过
下载正式交付物 OFD	通过
下载正式交付物 OFFLINE_HTML	通过

教学阅读及真实 HTTP 查询 JSON 证据

检查点	结果
发布版本提供两份正式交付物	通过
阅读位置、收藏、笔记真实写入	通过
旧乐观锁版本被拒绝	通过
旧发布版本不能覆盖当前阅读记录	通过
收藏和笔记进入真实统计	通过
浏览器笔记保存请求成功	通过
浏览器翻页位置已同步	通过
教学动态阅读显示三维画布	通过
对外接口面板返回真实工程数据	通过
浏览器无脚本异常	通过

权限、私人记录与反馈 JSON 证据

检查点	结果
学员不能进入内容编辑接口	通过
学员可以阅读正式发布版本	通过
学员投影没有文件存储 URI	通过
学员看不到其他用户的笔记和收藏	通过
学员能保存本人的阅读记录	通过
学员写入不覆盖教员记录	通过
学员不能查看教员聚合统计	通过
开始阅读产生正式记录 success	通过
阅读完成记录成功 success	通过
学员反馈写入正式服务	通过
教员回复并处理反馈 success	通过
学员通过教学接口下载 GLB	通过
临时测试学员已清理 success	通过

阅读、笔记、进度及 HTTP 写入 JSON 证据

检查点	结果
重新打开恢复上次第三页阅读位置	通过
笔记编辑保存成功	通过
笔记删除成功	通过
取消收藏写回服务器	通过
动态阅读同步第四页和百分百页进度	通过
教学只读模式允许目录定位和选择动画	通过
教学动态版式切换卡车步骤	通过
浏览器完成阅读并更新状态	通过
HTTP 面板实际 PUT 阅读记录	通过
HTTP 面板旧版本返回 409	通过
错误 HTTP 方法明确返回 405	通过
正式模板库可用	通过
无浏览器脚本异常	通过

正式模板新建 JSON 证据

检查点	结果
模板新建实际进入正式内容服务	通过
模板初稿进入编辑器并保存	通过
模板章节和步骤不丢失	通过

图片、视频及截图引用 JSON 证据

检查点	结果
图片与视频上传、截图引用保存后重开保持	通过
OFD 预览读取受控图片和截图	通过
正式视频通过受控字节恢复并实际播放	通过

正式离线包运行 JSON 证据

检查点	结果
15-offline-fox-scene 实测场景-狐狸野外训练区-20260905.glb · 186 个网格 · 拖拽旋转 / 滚轮缩放	通过
16-offline-truck-scene 实测场景-牛奶卡车检验区-20260905.glb · 37 个网格 · 拖拽旋转 / 滚轮缩放	通过
离线资源不依赖业务服务器或公网	通过
无脚本异常	通过

检查点来自分阶段脚本，覆盖关键链路，不表示所有边缘输入均已穷举。create/scenes 等早期证据对应创建及 V1→V2 阶段；最新发布、阅读和离线回归对应 V3。

关键截图

点击图片查看原图。文件名中的“fox-scene”沿用测试场景名称，不代表该场景当前实际包含狐狸。

交付与迁移

下载实测正式 OFD · 下载实测正式离线 ZIP（本地文件） · 发布摘要 · ZIP 完整性证据

离线 ZIP：71,380,256 字节；4 个 GLB 文件通过头部与长度检查。从正式 V3 下载后解压并运行，禁止访问业务服务及公网仍能加载两个场景。镜头修复代码已经包含在正式交付包中。

SHA-256：7227683a98f98e48aa31c3839fcb63782572fe6a9d9f7f48949fbae07e64f19b

开发环境迁移	说明
20260826_017_teaching_guide_reading_closed_loop.sql	补执行既有阅读与反馈表迁移，先回滚试执行再正式执行。
20260826_018_content_guide_template_library.sql	补执行既有正式模板库迁移，保留 4 个模板。
20260911_001_guide_reader_state.sql	新增按用户/项目/发布版本隔离的阅读位置、笔记、收藏及进度表；完整 DDL、数据库设计、迁移记录和 Wiki 已同步。

其他环境部署前先检查既有表，避免重复执行。新增流下载配置 UT_CONTENT_STREAM_TIMEOUT 默认 30m。本轮不代表其他环境已完成数据库迁移。

复核说明与保留数据

工程 412：正式闭环-狐狸与卡车指导书-20260910，已发布 V3.0.0 / 472。
工程 413：正式模板新建回归-20260911，保留草稿。
工程 414：正式图片视频资源回归-20260911，保留草稿。
临时学员账号已清理，正式测试阅读及反馈历史保留。阅读页进度与“完成阅读”分别记录，不等同于考核成绩。
既有内部维护账号头像存在单独的 404，属于原账号头像资源问题；本轮指导书资源、视频及交付下载检查通过。没有将该请求计入“无网络错误”的结论。
本轮未自动提交或推送 Git。大型测试 ZIP 仅保留在本地报告目录，不纳入 Git。

需要核对的数据差异：场景 160@463 名为“实测场景-狐狸野外训练区-20260905”，当前发布内容实际是维修车间与装备，不包含狐狸。已按其固定发布版本验证，未修改源场景；狐狸模型在指导书独立步骤中验证通过。牛奶卡车场景使用 159@209。

三项实施均在本次授权范围内，没有新增待批准的大幅功能调整。旧浏览器本地工程如需迁移，使用显式导入新工程；无法从服务端恢复的本地文件需重新上传。