# 06-决策记录

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

## ADR-A120-001：ABB120 基准使用仓库内 fixture，而不是新增未验证 URDF

状态：Accepted
日期：2026-06-27
关联任务：`A120-001`

### 背景

用户要求根据 ABB120 的 URDF 编写全面测试文档。当前仓库没有独立 `.urdf` 文件，但已有 `kdl-wasm/web/tests/fixtures/abbIrb120.ts`，其中包含 `ABB_IRB120_3_58_URDF`、load options、来源记录和标准关节位。

### 决策

`working1` 以当前 fixture 内嵌 URDF 作为 ABB120 基准。后续如需要独立文件，可从 fixture 导出到稳定测试资产目录，但不得引入未验证 URDF 替换基准。

### 后果

1. 文档和测试能立即对齐当前代码。
2. 后续 fixture 抽取不会改变机器人基准。
3. 如果未来引入完整 mesh/inertial URDF，需要作为独立任务评审。

## ADR-A120-002：全面测试以 GRL/IR 为中心，品牌程序是输入输出格式

状态：Accepted
日期：2026-06-27
关联任务：`A120-010`、`A120-050`、`A120-051`

### 背景

需求要求编写通用机器人程序、运行程序、转换为其他品牌程序，并做离线编程全面测试。如果直接围绕 ABB RAPID 或其他品牌语法构建运行链路，会导致虚拟控制器和报告被品牌细节绑定。

### 决策

标准链路为：

```text
GRL -> AST -> Semantic IR -> KDL / Virtual Controller / Reports -> ABB/FANUC/KUKA post
```

品牌导入链路为：

```text
ABB/FANUC/KUKA text -> importer -> OLP patch + GRL + Semantic IR -> reports
```

### 后果

1. 同一测试程序可跨品牌输出。
2. 虚拟控制器只执行统一 IR。
3. 品牌差异通过 post/import report 解释。

## ADR-A120-003：pose target 优先由 ABB120 FK 生成

状态：Accepted
日期：2026-06-27
关联任务：`A120-010`、`A120-031`

### 背景

ABB120 是 6 轴机械臂。手写笛卡尔 pose 可能因为姿态、工具、base 或 IK 初值导致不可达，从而让 happy path 测试不稳定。

### 决策

happy path 的 pose target 优先由标准关节位 FK 生成。不可达点、限位点和奇异点只放入 error diagnostic suite。

### 后果

1. MOVEL/MOVEC happy path 更稳定。
2. 诊断测试不会污染主流程。
3. FK 结果变化会通过 snapshot 明确暴露。

## ADR-A120-004：跨品牌输出必须配套转换报告和回读差异

状态：Accepted
日期：2026-06-27
关联任务：`A120-050`、`A120-051`

### 背景

ABB RAPID、FANUC LS 和 KUKA KRL 的速度、zone、工具、frame、等待和工艺语义不完全一致。

### 决策

每次后处理必须输出品牌程序和转换报告；每次品牌导入或回读必须输出 roundtrip diff。

### 后果

1. 近似语义不会静默丢失。
2. 用户能判断程序是否适合现场控制器复核。
3. 后续新增品牌时必须遵守同样报告格式。

## ADR-A120-005：HTML 虚拟控制器对标 RobotStudio 工作流，不复制 ABB 视觉资产

状态：Accepted
日期：2026-06-27
关联任务：`A120-090` 到 `A120-094`

### 背景

用户要求对标 ABB 既有仿真器界面，并使用 HTML 编写本项目虚拟控制器。ABB RobotStudio 是 ABB 的离线编程与仿真平台，公开资料包括 RobotStudio Suite 官方页面、RobotStudio Operating Manual 2026.2 和 ABB Robotics downloads。需求参考 Virtual Controller、RAPID 编辑、Station 图形窗口、Simulation 和 Virtual FlexPendant 等工作流。

### 决策

本项目 HTML 界面对标信息架构和操作流程：

1. Station 对象树。
2. 机器人/路径 viewport。
3. 程序编辑器和 source map。
4. 控制器状态和运行控制。
5. Virtual FlexPendant 风格的状态、Jog、IO 和报警面板。
6. 报告和后处理出口。

不复制 ABB 商标、图标、配色、截图或专有资源。

### 后果

1. UI 满足用户熟悉的离线编程工作流。
2. 降低品牌侵权和误导风险。
3. 视觉语言可按本项目设计系统独立演进。

## ADR-A120-006：HTML UI 必须消费 runtime/facade snapshot，不重写运行时

状态：Accepted
日期：2026-06-27
关联任务：`A120-090` 到 `A120-093`

### 背景

当前仓库已有 `VirtualController`、`MotionQueue`、`IoImageRuntime`、`WorkbenchFacade` 和 `DebugFacade`。如果 UI 中重复实现程序运行、IO、Wait 或 source map，会造成行为分叉。

### 决策

HTML UI 只负责展示和触发命令，业务状态来自 runtime/facade snapshot。

### 后果

1. UI 与测试共用同一运行时行为。
2. 自动化测试可以先验证 facade，再验证页面绑定。
3. 后续替换 UI 框架时不影响核心运行逻辑。

## ADR-A120-007：证据优先使用 job_id 和 report_id 串联

状态：Accepted
日期：2026-06-27
关联任务：`A120-033`、`A120-071`、`A120-900`

### 背景

全面测试会产生多种证据：轨迹、trace、诊断、品牌程序、报告、截图、PDF 和交付包。如果只靠文件名追踪，后续很难定位一次完整运行。

### 决策

每次 ABB120 suite 运行生成 `job_id`；每份报告生成 `report_id`。所有产物 manifest 必须包含这两个字段或其中一个字段。

### 后果

1. 验收证据可追溯。
2. CI、人工页面验收和交付包能关联到同一次运行。
3. 历史证据可以长期归档和比对。

## ADR-GRL-EXPR-001：运算功能采用跨品牌公共数学子集

状态：Accepted
日期：2026-06-27
关联任务：`GRL-EXPR-001` 到 `GRL-EXPR-006`

### 背景

用户要求“运算功能，对标 ABB、FANUC、库卡”。ABB RAPID、FANUC LS/KAREL、KUKA KRL 都具备数值计算、比较、逻辑和常用数学函数，但语法细节、系统变量和控制器运行时能力不完全一致。如果首版照搬某一家品牌语法，会破坏 GRL 作为统一语言和统一 IR 的定位。

### 决策

GRL 首版运算功能采用公共数学子集：

1. 算术：`+ - * / mod`。
2. 比较：`== != < <= > >=`。
3. 逻辑：`and or not`，兼容 `&& || !` 输入别名。
4. 括号和函数调用。
5. 函数：`sin/cos/tan/asin/acos/atan/atan2/sqrt/abs/pow/min/max/clamp/floor/ceil/round`。
6. 常量：`pi/e`。

品牌专用函数、控制器系统变量和复杂运行时表达式不作为首版公共能力。

### 后果

1. GRL 语义保持跨品牌一致。
2. ABB/FANUC/KUKA 后处理器可以优先消费折叠后的 IR 数值。
3. 品牌专用能力后续通过 post_hint、import report 或品牌扩展包增量支持。

## ADR-GRL-EXPR-002：运动参数中的表达式必须编译期求值

状态：Accepted
日期：2026-06-27
关联任务：`GRL-EXPR-003`、`GRL-EXPR-004`、`GRL-EXPR-005`

### 背景

运算功能如果只停在 parser 层，真实机器人程序参数仍无法工作。例如 `speed linear(100 + 50 mm/s)`、`pose(400 + 50 mm, ...)`、`joint_target { joints: [(10 + 5) deg] }` 都必须进入 KDL planner 和品牌后处理。KDL request 和后处理器需要的是确定的数值，而不是未求值的表达式文本。

### 决策

以下位置必须在编译期求值并写入 Semantic IR / KDL request：

1. 数据声明。
2. speed、zone。
3. pose、poseq、robot_config。
4. joint_target、pose_target。
5. tool、frame。
6. path defaults/source。
7. path point 内联 motion 参数。
8. path event distance。
9. wait timeout、pulse duration。
10. operation process 中的数值常量。

需要常量的位置如果出现运行时变量或无法确定的表达式，输出 `GRL_EXPR_NON_CONSTANT`。

### 后果

1. 真实 motion/path 参数可以编译并进入规划。
2. 后处理输出为具体 ABB/FANUC/KUKA 数值，便于现场复核。
3. runtime 条件表达式需要单独建模，不能混入常量求值器。

## ADR-GRL-EXPR-003：单位采用上下文默认值加 SI 归一化

状态：Accepted
日期：2026-06-27
关联任务：`GRL-EXPR-003`

### 背景

GRL 已经支持带单位的 number token，例如 `300 mm/s`、`10 mm`、`90 deg`。用户要求支持 `linear(100 + 50 mm/s)` 这类表达式，其中 `100` 的单位依赖 `linear` 速度上下文。如果完全禁止无单位数，会让 GRL 编写繁琐；如果完全允许无单位数，会造成歧义。

### 决策

采用上下文默认单位加 SI 归一化：

1. `linear(...)` 默认 `mm/s`。
2. `z(...)` 默认 `mm`。
3. `joint(...)` 的 `%` 默认比例上下文。
4. `pose(...)` 前三项默认 `mm`，后三项默认 `deg`。
5. `joint_target.joints` 默认 `deg`。
6. `timeout/duration` 默认 `s`。
7. 明确单位的数值优先使用自身单位。
8. 同维度才能相加、相减、比较；不兼容维度报 `GRL_EXPR_UNIT_MISMATCH`。

所有进入 IR/KDL 的数值归一化为 SI：长度 m、速度 m/s、加速度 m/s2、角度 rad、时间 s、质量 kg、百分比 0 到 1。

### 后果

1. `linear(100 + 50 mm/s)` 可按用户预期编译为 `0.15 m/s`。
2. 生成器和文档示例仍推荐输出显式单位，减少人工阅读歧义。
3. 实现时必须把期望单位上下文传入常量求值器，不能只在 lexer 层处理。

## ADR-GRL-EXPR-004：复杂运行时表达式先进入报告，不强行后处理映射

状态：Accepted
日期：2026-06-27
关联任务：`GRL-EXPR-006`、`A120-050`、`A120-051`

### 背景

ABB、FANUC、KUKA 对运行时表达式、IO 条件、函数调用和控制器变量的支持差异较大。强行把所有 GRL 表达式映射到三品牌文本，容易产生看似可运行但语义不一致的程序。

### 决策

首版后处理策略：

1. 需要常量的位置全部在 GRL 编译阶段折叠为 IR 数值。
2. 后处理器只输出折叠后的具体数值。
3. wait/if/while 等运行时条件表达式如果可以保真映射，则输出品牌表达式。
4. 如果不能保真映射，输出转换报告项 `GRL_EXPR_UNSUPPORTED_RUNTIME`，必要时在品牌程序中输出注释或 unsupported 占位。

### 后果

1. 避免静默改变机器人程序行为。
2. 用户能通过 post report 判断是否需要人工调整或品牌专用扩展。
3. 后续每新增一个品牌表达式映射，都必须补 roundtrip diff 证据。