5.8 KiB
06-决策记录
本文件记录关键技术决策。后续如需变更，必须新增记录说明原因、影响和替代方案，不直接覆盖旧决策。
记录模板
## ADR-XXX 标题
日期：
状态：
背景：
决策：
理由：
影响：
变更条件：
ADR-005 当前验收闭合采用“命令全绿 + 条件边界显式锁定”口径
日期：2026-07-09 状态：生效
背景：
本轮已让上游基线、vendor 同步、Native/WASM/Browser/OPFS/UI/Host 聚合命令通过，但 Python remap、User M 外部进程、硬件驱动和实时内核天然涉及浏览器沙箱、外部进程或实时环境限制，不能因为 smoke 全绿就宣称无条件 LinuxCNC full-process 支持。
决策：
ACC-001 到 ACC-023 的当前闭合采用“可执行命令包全绿 + 条件边界显式锁定”口径：能由 LinuxCNC 源码、Native probe、WASM Node、真实浏览器和 UI/OPFS gate 证明的部分标为完成；Python remap、User M、硬件/实时等仍保留 manual_promotion_lock、Blocked 或条件通过说明。
理由：
这样既满足当前发布前命令包 unexpected_fail=0 的可复验证据，又避免把浏览器环境无法直接承载的 LinuxCNC 外部进程/实时能力误报为已经完整实现。
影响：
04-任务矩阵.md中相关任务可以闭合，但状态使用“条件通过”而不是无条件“完成”。05-验收证据.md必须保留 inventory29/29/130/0、skip/block 分类和 Python remap manual lock 说明。- 后续如果要解除条件边界，必须新增 ACC 任务、源码归属、runtime owner、fixture 和验收 gate。
变更条件：
只有当对应 runtime 或安全边界真正实现，并且 Native/WASM/Browser/UI 证据同时通过后，才能把条件通过项升级为无条件完成。
ADR-001 以 LinuxCNC 源码和测试资产作为唯一数控语义基准
日期：2026-07-09 状态：生效
背景：
验收标准明确要求“完全对标 LinuxCNC”必须证明核心数控语义来自 LinuxCNC 源码、测试资产和运行规则，而不是界面相似或项目自研近似实现。
决策：
wasm-port 的 G 代码解释、刀补、参数、remap、刀具、轨迹规划、运动学、Task/HAL/Motion 等 CNC 语义只能来自 LinuxCNC 源码复用、vendored 同步或明确的薄封装。JS/TS、浏览器 UI 和项目自有 C/C++ 只能承担文件、调度、展示、持久化、C ABI 和边界桥接职责。
理由：
这能避免 Web 端逐渐形成第二套状态真相，也能让上游测试迁移、Native/WASM/Browser 对比和 blocked table 具备共同基准。
影响：
- 新功能必须先找到 LinuxCNC 源码归属。
- 找不到归属的功能不能宣称为 LinuxCNC 对标功能。
- 疑似自研 CNC 语义必须通过
verify_no_standalone_cnc_semantics.sh或人工审查解释清楚。
变更条件：
只有验收标准更新并允许某类非 LinuxCNC 语义作为产品扩展时，才能改变此决策；即使变更，也必须与 LinuxCNC 对标功能分开标识。
ADR-002 采用 L0-L5 加 Blocked 的晋级模型
日期：2026-07-09 状态：生效
背景：
只写“完成”无法区分源码已同步、Native 通过、WASM 通过、浏览器通过和 UI 发布，也容易把 full-process 或硬件依赖降级为解释器通过。
决策：
所有任务使用 L0 已盘点、L1 已同步、L2 Native 通过、L3 WASM 通过、L4 Browser 通过、L5 UI 发布、Blocked 表达真实进度。
理由：
该模型与验收标准的分层证据体系一致，可以防止跳级宣称，也方便后续按证据缺口继续推进。
影响：
- 任务矩阵必须记录晋级目标。
- 浏览器/UI 功能不能只凭 Native 或 WASM 结果标为 L5。
- Python remap、动态 loadrt、硬件驱动、实时内核等未闭合项应标 Blocked 或条件通过。
变更条件：
如果新增运行层级或验收标准调整证据层级，需要补充状态定义。
ADR-003 把 完善wasm/working 作为总验收推进入口
日期：2026-07-09 状态：生效
背景：
wasm-port/working 已存在 task/status JSON 等局部推进文档，并显示当前 task-HAL 工作已闭合。新的验收标准覆盖整个 LinuxCNC 功能树，需要一个更高层的总入口。
决策：
完善wasm/working 作为完整 LinuxCNC 对标推进入口，维护总任务矩阵、验收证据和决策记录；wasm-port/working 继续作为 wasm-port 内部具体阶段文档和历史证据来源。
理由：
这样可以避免把某个已闭合子方向误认为整体验收完成，同时保留既有工作成果。
影响：
- 后续总体验收先看
完善wasm/working/README.md和04-任务矩阵.md。 - 涉及具体实现时，再跳转到
wasm-port/docs、wasm-port/working和对应测试。
变更条件：
如果后续决定把总入口迁入 wasm-port/working，必须同步迁移任务编号、证据和决策记录，避免两套矩阵并行。
ADR-004 截图和 UI smoke 只能作为补充证据
日期：2026-07-09 状态：生效
背景：
验收标准明确浏览器测试不能只验证页面元素存在，UI 的坐标、模态、刀具、主轴、程序状态必须与底层 LinuxCNC 状态快照一致。
决策：
截图、录屏、DOM smoke 和页面存在性检查只作为 P5 证据。任何核心语义、OPFS、Worker、UI 状态发布都必须有 C ABI、状态 JSON、OPFS 文件或底层快照证据支撑。
理由：
UI 可以显示正确外观但底层状态错误；P4/P5 分离可以防止验收被外观证据污染。
影响：
- UI 任务必须绑定底层状态断言。
- 真实浏览器 smoke 需要检查运行结果、错误、文件或快照，而不是只检查按钮。
变更条件：
无底层状态可取的纯视觉展示功能可用截图验收，但不得宣称 LinuxCNC 核心语义通过。