151 lines
5.8 KiB
Markdown
151 lines
5.8 KiB
Markdown
# 06-决策记录
|
||
|
||
本文件记录关键技术决策。后续如需变更，必须新增记录说明原因、影响和替代方案，不直接覆盖旧决策。
|
||
|
||
## 记录模板
|
||
|
||
```text
|
||
## 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` 必须保留 inventory `29/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 核心语义通过。
|