# 配置驱动与恢复改造接续入口

最新教学交付（R09/E13）：[工件坐标与RTCP初学者完整PDF](docs/teaching/rtcp-beginners/五轴RTCP与工件坐标-初学者完整讲义.pdf)，72页A4，详解原点/方向/G54/G代码逐字逐行和关节运动；源稿、数据及复现命令见[教材索引](docs/teaching/rtcp-beginners/README.md)。原31页投影片保留。最近两轮仅新增教学资料和生成脚本，未改应用功能。

2026-09-18 新需求接续：AC/BC 单文件 GLB + URDF 机床导入已在独立子项目实现并专项验收。新入口为 [`docs/glb-machine/README.md`](docs/glb-machine/README.md)，最新台账 R07（Jog 限位后的事件序列和反向恢复、阴影警告；R06 桁架示例，R05 参数编辑保留GLB，R04 切换不跳动）；两项已复核的旧测试失败见 E11，本轮改动尚未提交/推送。旧 event_sequence_gap 浏览器会话需刷新重建。下文为原配置/恢复专项历史接续状态，原有本地改动继续保留。

更新时间：2026-09-18。用户已确认清理自有代码的机床参数、轴配置、路径、可调界面设置硬编码，保留数学/协议常量和上游 LinuxCNC；之后要求接续 CFG-R01、TRT-R01。以上专项均已收口。

## 当前状态

- 任务矩阵：`docs/trt-parametric/04-任务矩阵.md`；CFG-01/02/03、CFG-R01、TRT-R01 均为已验收。
- 最新台账 R09（重启接续准备）、证据 E08/E09/E10、决策 D13/D14/D15；R06 配置改造的历史证据仍保留。
- **R06 配置改造与 R07 精确恢复的完整依赖已提交并推送**：`4a568f1f4c7df43ce9f71e7646d1306957dc9367`，分支 `main`。已用 `git ls-remote origin refs/heads/main` 核验远端一致；随后提交只更新接续文档，最新 HEAD 以 Git 为准。
- 验收汇总：`coverage/recovery/acceptance.report.json`；包含真实 WASM SHA、native 构建指纹和证据文件 SHA。
- 本专项暂无未完成任务。后续按新需求推进；不要重跑已通过整轮测试，也不要自动认领其他历史发布轨道的阻塞任务。

## 实现与验证落点

1. 配置：`web/workspace/machine-catalog.json`、`simulation-resources.json`、`web-settings.json` 和 `trt-configuration.mjs`；完整说明见 `07-配置驱动改造.md`。INI 输入包含运行参数及回零信息的完整 hash；Worker 从文件重新解析。
2. 三轴：`web/app/axis-contract.mjs` 和 `test_axis3_selected_case.mjs`。工具准备/换刀在开机、空闲、操作者模式、队列为空时交由 IO 状态机处理；运行、急停、故障等拒绝，未删除旧断言。
3. 恢复：自有 C 适配层新增 TP/TC、解释器/程序、HAL、核心及协议/事件快照 API；`web/worker/native-checkpoint.mjs` 做带构建指纹、长度/hash 校验的稀疏块编解码；数学计算仍来自 WASM。
4. 程序恢复：保存参数、调用栈及冻结子程序源，验证候选程序后替换；TP 原生队列/进度/混合状态直接恢复。`sim-session.mjs` 保存待处理运动/切换等交接信息；HAL 不再重复 step。
5. 幂等/内存：checkpoint 回执剔除递归旧快照，保留操作身份；恢复后重复 M428 不重新执行，返回当前机床投影。
6. 浏览器：OPFS 按机型隔离，只有冷启动自动采用兼容缓存；配置重载不覆盖当前输入。省去可重建预览，重建后验证 hash；App 保留恢复出来的程序而非重新加载船体示例。
7. 新发现并修复：identity Jog 的增量响应使用当前 WASM 规划器关节，避免最后采样落后。

## 已完成验证

- `bash scripts/build-wasm.sh`：WASM 测试通过，native 23/23；native TP 保存后继续 100 个伺服步逐步对比，HAL tick/函数计数和字节恢复验证。日志 `coverage/recovery/build.log`。
- `node web/worker/test_trt_checkpoint_exact.mjs`：两机型五阶段共120个连续任务tick全状态hash一致，另12个 Jog 样本；覆盖不同堆地址、暂停/子程序/圆弧/结束、空程序、trace、新传输会话、冻结子程序、损坏块和不同构建拒绝。
- `node web/worker/test_xyzac_recovery.mjs`：同一恢复点完整hash相同，实际重发 M428 不重复切换。
- `node web/worker/test_axis3_selected_case.mjs`、`node web/app/test_axis_contract.mjs`、`node web/worker/test_wasm_motion_checkpoint.mjs`：通过。
- `node web/worker/test_xyzac_runtime_followups.mjs`、`node web/worker/test_opfs_ui_state.mjs`、`node web/worker/test_opfs_worker_bridge.mjs`、`node web/worker/test_trt_configuration.mjs`：通过。
- `scripts/test_checkpoint_reload_browser.mjs`：真实 OPFS 关机保存/页面重载恢复，两机型位置严格相同，原程序/预览保留，之后 Jog 正常。XYZBC 使用 `RECOVERY_MACHINE=xyzbc-trt`。
- `scripts/test_trt_rtcp_jog_browser.mjs`：两机型 A/B/C Jog 回归通过；产物已归档 `coverage/recovery/`。
- `npm --prefix web/react run build`：通过，已有大 chunk 提示保留。
- Playwright 环境：`PLAYWRIGHT_MODULE=/home/mes006/.npm/_npx/e41f203b7505f1fb/node_modules/playwright/index.mjs`；Chrome `/usr/bin/google-chrome`。

## 已确定的恢复边界

- 原生记录只允许匹配构建和配置。旧缺失原生状态的记录不能近似恢复；自动缓存不兼容时提示并按当前配置启动，原缓存不删除。
- TRT checkpoint 后的事件不能静默忽略：须恢复后显式执行后续命令。公开 RECOVER 向更早逻辑tick回退需要新传输会话，避免改写历史；原生状态可在新会话重设传输序号后继续执行。
- OPFS 原有1MiB限制仍在，超限须报告quota；不宣称物理断电崩溃和全浏览器矩阵完成。
- 本次是专项验收，不等于全 LinuxCNC parity，不更改历史 release gate/context lock。

## 工作区与保存

- 工作目录：`/home/mes006/linuxcncWebWASM`；继续使用现有目录，原有未提交文件也在这里。
- 开发地址 `http://127.0.0.1:5174/`；不存在时运行 `npm --prefix web/react run dev -- --port 5174 --strictPort`。
- 本轮重启准备时该地址返回 HTTP 200；重启后重新检查，不假设服务进程仍然存活。浏览器 OPFS 与浏览器配置目录及 origin 绑定，要体验先前保存的状态，应使用相同浏览器配置及地址。
- 最新代码必须与重建的 WASM 配套；构建产物在 Git ignore 中，保存源码后其他环境需运行 build-wasm.sh。
- `coverage/configuration/`、`coverage/recovery/` 是本轮证据；`coverage/trt-parametric/` 保持先前已提交历史版本，不破坏历史哈希。
- 两份大型 tick trace、linuxcnc 子模块原有本地改动、`scripts/.tmp_test_nc_files_xyzac.mjs`、用户 Copy.png 不属于本轮，保留原样，不混入提交。
- 指定远程为 `https://gitea.meswork.com/wangdequan/linuxcncWebWASM.git`。保存已获授权；账号口令不写入仓库或接续文件。

## 重启后的第一轮

1. 先读本文件，再读 `docs/trt-parametric/README.md`、`04-任务矩阵.md` 和 `03-推进台账.md` 最新记录；涉及方案变更时读 `06-决策记录.md`。
2. 执行 `git status --short --branch`、`git log -3 --oneline`、`git -C linuxcnc status --short`，核对现有改动。不要执行 `git reset --hard`、`git clean` 或覆盖子模块；不要用 `git add .` 混入原有文件。
3. 现有专项全部已验收，没有正在运行的开发任务或需要接着等的测试。用户只说“继续”而未给新目标时，先报告当前状态，再明确新目标；不要重新实现已验收任务。
4. 若要本地体验，先检查 5174 服务，再按需启动。仅重启 Codex 不需要重建；换环境或修改 C/WASM 源码后运行 `bash scripts/build-wasm.sh`。变更后只运行相关检查，原验收见 E07–E10。
5. 完成新任务后同步更新台账、任务矩阵、验收证据及本接续文件；功能修复与原有本地改动分别处理。

重启后可直接发送：

> 请在 /home/mes006/linuxcncWebWASM 接续工作。先读取 nextTask-hardcoding.md，再按 docs/trt-parametric/README.md 和任务矩阵核对状态。配置改造、三轴门控、五轴精确恢复已验收并推送；保留原有子模块、trace 和临时文件改动，不重复已完成任务。先报告接续状态，再按我提供的新目标执行。

## 本地保留项清单

主仓库：`coverage/xyzac-native-tick-trace.report.json`、`coverage/xyzac-wasm-tick-trace.report.json`、`docs/linuxcnc-axis-web-control-panel-source-logic (Copy).png`、`scripts/.tmp_test_nc_files_xyzac.mjs`，以及 dirty 的 `linuxcnc` 子模块。两份 trace 很大，检查时避免输出完整 diff。

子模块内原有修改包括三轴/XYZAC/XYZBC INI、`lib/hallib/sim_lib.tcl`、`control.c`、`emc.cc`、`emc_nml.hh`、`emctaskmain.cc`、`taskintf.cc`、`emcmodule.cc`；另有 corexy/tool.tbl、axis/tool.tbl、rotate/、3axis-tutorial.old/、scorbot/ 未跟踪文件或目录。以 `git -C linuxcnc status --short` 为准；它们未随专项推送，不要删除或自动提交。重启使用现有工作区能保留这些文件，远端仓库不能替代它们的本地副本。