# 06-决策记录

版本：0.1
日期：2026-06-28

## ADR-W2-001：working2 以当前语法规范作为覆盖源

状态：Accepted
日期：2026-06-28
关联任务：`W2-SPEC-001`

### 背景

用户要求对标 `通用机器人编程语法规范.md` 创建机器人程序集，并全面完成虚拟控制器执行情况。`working1` 已经覆盖 ABB120 基础测试和虚拟控制器，但不是逐章按最新语法规范做覆盖矩阵。

### 决策

`working2` 以 `work/doc/通用机器人编程语法规范.md` 为唯一覆盖源。任何程序或测试是否“覆盖”，必须能追溯到规范章节、语法项和验收证据。

### 后果

1. 覆盖结论可审计。
2. 语法规范更新后可以重新生成缺口清单。
3. 不再用“已有测试通过”替代规范覆盖证明。

## ADR-W2-002：ABB120 基准继续使用仓库内稳定 fixture

状态：Accepted
日期：2026-06-28
关联任务：`W2-PROG-010`、`W2-RUN-020`

### 背景

仓库已有 `kdl-wasm/web/src/fixtures/abb120.ts` 和测试导出 `abbIrb120.ts`，其中包含 ABB IRB120 3/58 URDF、load options 和标准关节位。重新引入外部 URDF 会增加模型差异和验证成本。

### 决策

working2 继续使用仓库内 ABB120 fixture。若未来需要独立 `.urdf` 文件，只能从当前 fixture 导出，不能静默替换机器人模型。

### 后果

1. working2 结果与 existing KDL/virtual controller 测试一致。
2. FK/IK/limit snapshot 可复用。
3. 外部 mesh/inertial 完整模型另列任务。

## ADR-W2-003：语法覆盖分为 Runtime、Static、Post 三层

状态：Accepted
日期：2026-06-28
关联任务：`W2-SPEC-002`

### 背景

语法规范包含流程控制、运动、IO，也包含 trap、interrupt、task、brand metadata、post_hint 等不适合全部作为虚拟控制器 happy path 执行的语义。如果强行要求所有语法都运行，会混淆实现边界。

### 决策

覆盖分三层：

1. Runtime：虚拟控制器必须执行并输出 trace。
2. Static：parser/semantic 必须诊断或验证。
3. Post：后处理、导入回读和报告必须覆盖。

### 后果

1. happy path 稳定。
2. P1/P2 语义不会被误报为已完整执行。
3. 覆盖矩阵能清楚说明每项语法的验证方式。

## ADR-W2-004：虚拟控制器验收以证据包为准

状态：Accepted
日期：2026-06-28
关联任务：`W2-RUN-001` 到 `W2-RUN-060`

### 背景

“执行情况”不能只看单元测试通过。虚拟控制器需要证明状态机、程序指针、motion queue、IO/wait、报警、source map 和轨迹结果都正确。

### 决策

每次 suite 运行生成 `W2-JOB-*` 证据包，至少包含：

1. `job.json`
2. `compile.json`
3. `controller.json`
4. `motion-queue.json`
5. `trace.json`
6. `io.json`
7. `trajectory.json`
8. `report.json/html`

### 后果

1. 运行结果可回放和审计。
2. HTML 虚拟控制器可以消费同一证据。
3. CI 失败时能定位到具体程序、source range 和 controller 状态。

## ADR-W2-005：working2 不改写 working1 完成记录

状态：Accepted
日期：2026-06-28
关联任务：`W2-SPEC-000`

### 背景

`working1` 已记录已完成的 ABB120 基础测试、表达式功能和虚拟控制器验收。用户要求任务整合到 `working2` 并参考 `working1`，不是要求重写历史记录。

### 决策

`working2` 新建独立任务包，状态从 `Todo` 开始。`working1` 仅作为参考和可复用资产来源。

### 后果

1. 避免把旧验收直接当作新目标完成。
2. working2 可以独立追踪新增覆盖缺口。
3. 后续实现可以逐项把 Todo 推进到 Done。

## ADR-W2-006：W2 runner 使用同步 fixture planner 生成审计轨迹

状态：Accepted
日期：2026-06-28
关联任务：`W2-RUN-020`、`W2-RUN-040`

### 背景

working2 的核心目标是逐章覆盖 GRL 语法规范，并为每个程序输出稳定、可审计的 controller、motion queue、trace、IO 和 trajectory 证据。仓库已有 ABB120 KDL 集成测试负责真实 URDF FK/IK/planPath 验证。

### 决策

`runAbb120SpecSuite` 在 W2 job 中使用同步 fixture planner 生成稳定 trajectory 和 planner diagnostic；真实 ABB120 URDF/KDL 检查继续由既有 `abb120Programs.test.ts` 和 KDL 测试承担。

### 后果

1. W2 证据包生成快速、稳定、可在普通 Node/Vitest 环境执行。
2. Motion queue、source map、IO/wait/alarm 和 post/roundtrip 证据可稳定归档。
3. 若后续要求 job 内嵌真实 KDL 轨迹，可在 runner 中增加 async KDL planner 模式。

## ADR-W2-007：异常和 P1 语义采用 runtime/static 边界组合

状态：Accepted
日期：2026-06-28
关联任务：`W2-RUN-060`、`W2-PROG-010.10`

### 背景

当前语法规范定义 `try/catch/finally`、`trap`、`interrupt`、`task`。现有 parser/semantic 已有异常分析器，但控制流分析器不应把 `try` 当普通控制流执行；`trap/task` 仍是 P1 runtime 边界。

### 决策

控制流分析器将 `try` 块保留为 raw boundary，由 exception semantic 负责 alarm/raise/try/catch/finally 分析。`trap/task/interrupt` 输出 `GRL_P1_UNIMPLEMENTED` warning 或 unsupported runtime trace，不作为 happy path 完整执行。

### 后果

1. `W2_90_ExceptionAlarm.grl` 可以稳定 parse、compile、load 并输出异常语义证据。
2. P1 语义不会被误报为完整 runtime 支持。
3. 后续实现 trap/interrupt/task 时可替换 raw boundary，不影响 W2 manifest 结构。

## ADR-W2-008：服务器演示采用静态发布包加证据包模式

状态：Accepted
日期：2026-06-28
关联任务：`W2-DEPLOY-001` 到 `W2-DEPLOY-060`

### 背景

用户要求把虚拟测试程序打包到服务器，并能通过这些程序演示虚拟控制器全部功能。当前虚拟控制器页面、GRL 程序、suite job、截图和 Word 文档都可以作为静态文件发布；远程演示的重点是可访问、可审计、可重复，而不是在服务器上重新执行 Node/Vitest。

### 决策

服务器发布采用静态演示包模式：

1. 本地先执行 typecheck、test、suite 和截图验证。
2. 将虚拟控制器页面、19 个 GRL 程序、最新 `W2-JOB-*`、截图、Word 文档和 `demo-manifest.json` 打成 zip。
3. 服务器仅负责 HTTPS 静态托管。
4. 远程验收通过 `demo-manifest.json`、`report.json`、程序源码、截图和页面入口验证。
5. 服务器保留 release 目录和 `current` 链接，支持回滚。

### 后果

1. 发布包可离线审计，不依赖服务器 Node 环境。
2. 演示内容与本地测试证据一致，避免远程环境差异导致结论不稳定。
3. 后续如需在线编辑和动态运行，可在当前静态包基础上增加 API 服务，不影响现有验收链路。
4. 凭据不进入仓库文档，降低泄露风险。