# 02-项目程序开发详细步骤

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

## 1. 开发原则

1. 以 `通用机器人编程语法规范.md` 为覆盖源，不以现有测试数量作为完成标准。
2. ABB120 URDF 使用仓库内稳定 fixture，不引入未验证机器人模型。
3. happy path 必须可执行；error path 必须可诊断；post path 必须可报告。
4. 虚拟控制器只执行 Semantic IR，不直接解释品牌文本。
5. 所有新增程序都要保留 source map，报告必须能定位到 GRL 文件行列。

## 2. 阶段 0：规范覆盖矩阵

### W2-SPEC-001：解析语法规范章节

步骤：

1. 从 `work/doc/通用机器人编程语法规范.md` 抽取章节、关键语法、示例和语义规则。
2. 建立 coverage item，字段包含 `spec_section`、`syntax`、`runtime_level`、`program_id`、`test_id`、`evidence`。
3. 把覆盖矩阵写入 `working2/programs/manifest.md`。

验收：章节 4 到 23 均有覆盖项；章节 25 的 P0 项全部映射到 runtime 或 static 测试。

### W2-SPEC-002：定义执行边界

步骤：

1. 标记虚拟控制器必须执行的 Runtime 语义。
2. 标记只做 semantic diagnostic 的 Static 语义。
3. 标记只做后处理/导入报告的 Post 语义。
4. 对 trap、interrupt、task、brand metadata 等非 P0 执行项写清楚边界。

验收：覆盖矩阵中每项都有 `Runtime/Static/Post` 分类，不允许空白。

## 3. 阶段 1：ABB120 程序集

### W2-PROG-001：建立 spec-programs 目录

建议目录：

```text
kdl-wasm/web/tests/fixtures/abb120/spec-programs/
  runtime/
  static/
  error/
  post/
  expected/
```

验收：测试 helper 可以枚举所有 `.grl` 并读取 manifest。

### W2-PROG-010：Runtime 程序

步骤：

1. 创建 `W2_00` 到 `W2_90` 十个 runtime 程序，并以 `W2_99_FullSpecExample` 覆盖第 24 章完整示例。
2. 所有运动目标使用 ABB120 标准关节位或 FK 固化 pose。
3. 每个程序顶部注释写明覆盖的 spec section。
4. 每个程序必须可 parse、compile、load 到虚拟控制器。

验收：runtime 程序全部生成 AST/IR/source map snapshot。

### W2-PROG-020：Static/error 程序

步骤：

1. 创建表达式、语义、运动、控制流、runtime timeout 五类 error 程序。
2. 每个 error 程序只聚焦一类错误，避免多个错误互相遮蔽。
3. expected diagnostic 固化 `code/severity/message/sourceRange`。

验收：diagnostic snapshot 稳定，新增或消失的错误会导致测试失败。

### W2-PROG-030：Post/import 程序

步骤：

1. 创建品牌 hint 和跨品牌 motion 程序。
2. 覆盖 ABB/FANUC/KUKA speed、zone、IO、wait、operation 输出。
3. 固化 roundtrip 输入和差异报告。

验收：三品牌输出非空，近似和不支持项进入 report。

## 4. 阶段 2：编译和 KDL 验证

### W2-RUN-001：统一 suite runner

步骤：

1. 扩展或新增 `runAbb120SpecSuite`。
2. 输入：program root、suite id、ABB120 fixture、output root。
3. 输出：`job_id`、程序 manifest、每个程序的 compile/run/post 结果。
4. job id 格式：`W2-JOB-YYYYMMDD-HHMMSS-<short-hash>`。

验收：单条命令可生成完整 suite 证据目录。

### W2-RUN-010：编译链路

步骤：

1. `parseGrl` 生成 AST。
2. `compileSemanticProgram` 生成 IR。
3. 对 data/target/path/operation 建 source map 索引。
4. 保存 AST/IR 摘要，不保存过大的重复文本。

验收：每个 runtime/post 程序 compile 无 error；每个 error 程序 compile 输出预期 diagnostic。

### W2-RUN-020：ABB120 KDL 检查

步骤：

1. 加载 ABB120 URDF。
2. 对所有 joint target 做 limit check。
3. 对所有 pose target 做 IK 或记录当前实现边界 diagnostic。
4. 对每条 motion/path 生成 planner request。

验收：happy path 没有关节限位错误；不可达或不支持 IK 只能出现在 error suite。

## 5. 阶段 3：虚拟控制器执行

### W2-RUN-030：状态机命令覆盖

步骤：

1. 对每个 runtime 程序执行 `load/start/step/hold/resume/stepMotion/stop/resetFault`。
2. 记录每次命令前后状态。
3. 非法命令转移必须产生明确 diagnostic。

验收：状态机转换符合控制器规则，trace 可回放。

### W2-RUN-040：Motion Queue 和轨迹

步骤：

1. 将 `movej/movel/movec/run_path/run_operation` 展开到 motion queue。
2. 记录 queue item、activeIndex、duration、planner result。
3. 对轨迹采样点做 limit 和 singularity 检查。

验收：motion queue 与程序 source map 对齐；轨迹结果可进入报告。

### W2-RUN-050：IO、wait、pulse 和报警

步骤：

1. 为 `W2_60_IOWaitPulse` 注入 DI 脚本。
2. 覆盖 wait satisfied、waiting、timeout、on_timeout alarm/call。
3. 覆盖 pulse 自动复位。
4. 覆盖 all/any/rising/falling/changed。

验收：trace 中可看到 IO 写入、DI 变化、wait 状态、pulse reset 和 alarm。

### W2-RUN-060：流程控制和调用栈

步骤：

1. 执行 if/elseif/else、while、for、switch。
2. 记录局部变量、循环变量、call stack、return。
3. out/inout 参数回写进入变量快照。

验收：最终变量状态符合预期，source map 可定位当前执行语句。

## 6. 阶段 4：后处理和导入回读

### W2-POST-010：三品牌 post

步骤：

1. 对 runtime/post 程序调用 `postProcessAllBrands`。
2. 保存 ABB `.mod`、FANUC `.ls`、KUKA `.src/.dat`。
3. 保存 post report，记录近似和 unsupported。

验收：所有品牌输出包含对应 motion、IO、wait 和 proc 结构。

### W2-POST-020：roundtrip

步骤：

1. 将三品牌输出重新导入。
2. 对比 motion 顺序、target 数量、path/operation 结构。
3. 对差异生成 `roundtrip.json`。

验收：happy path 结构等价；不可逆项全部进入 diff。

## 7. 阶段 5：HTML 虚拟控制器验收

### W2-UI-010：加载最新 job

步骤：

1. HTML 页面支持选择或加载 `W2-JOB-*` 证据。
2. 显示程序列表、当前程序、controller snapshot、queue、trace、diagnostics。
3. 点击 trace/source map 能定位 GRL 行。

验收：页面能展示 working2 suite 证据，不只展示静态 mock 数据。

### W2-UI-020：截图验证

步骤：

1. 使用现有 `verify-virtual-controller.mjs` 或新增参数打开 working2 job。
2. 截桌面和移动视口。
3. 检查 command bar、object tree、viewport、pendant、editor、bottom panel 可见。
4. 检查无横向溢出和文字重叠。

验收：生成 desktop/mobile 截图和 `evidence.json`。

## 8. 阶段 6：全量 CI

建议命令：

```powershell
cd E:\Work\kdl_work
npm run typecheck
npm test -- grl abb120 virtual controller runtime post import
npm run verify:virtual-controller
```

如果需要 WASM native 验证：

```powershell
cmake --build kdl-wasm/build-wasm -j16
```

验收：所有命令通过，`working2/05-验收证据.md` 记录实际命令、时间、job_id、report_id 和产物路径。

## 9. 阶段 7：服务器演示包和 HTTPS 发布

### W2-DEPLOY-001：生成演示包 manifest

步骤：

1. 读取 `kdl-wasm/web/tests/fixtures/abb120/spec-programs/manifest.json`。
2. 读取最新 `kdl-wasm/web/test-results/abb120-spec/W2-JOB-*`。
3. 读取 `kdl-wasm/web/test-results/virtual-controller/evidence.json`。
4. 生成 `demo-manifest.json`，字段至少包含：
   - `release_id`
   - `generated_at`
   - `suite_id`
   - `job_id`
   - `program_count`
   - `programs`
   - `report_json`
   - `virtual_controller_entry`
   - `screenshots`
   - `docs`
5. manifest 中路径必须是相对发布根目录的 URL 路径，不能写本机绝对路径。

验收：`demo-manifest.json` 可被浏览器直接打开，能定位 19 个程序、最新报告和截图。

### W2-DEPLOY-010：收集演示包文件

建议目录：

```text
kdl-wasm/web/test-results/deploy/kdl-olp-demo-<release_id>/
  app/
  spec-programs/
  test-results/
  docs/
  index.html
  demo-manifest.json
  README.md
```

步骤：

1. 复制 `kdl-wasm/web/app/virtual-controller.html/css/js` 到 `app/`。
2. 复制 `spec-programs/manifest.json` 和所有 `.grl` 程序。
3. 复制最新 W2 job 目录。
4. 复制虚拟控制器截图和 `evidence.json`。
5. 复制 Word 手册和测试文档：
   - `work/doc/GRL功能语法逻辑与程序创建使用手册.docx`
   - `work/doc/通用机器人离线编程系统测试文档.docx`
6. 生成 `index.html`，至少提供：
   - 虚拟控制器入口
   - 最新 job 报告入口
   - 程序清单入口
   - 截图入口
   - 文档下载入口

验收：本地打开发布包根目录时，所有链接不依赖开发机绝对路径。

### W2-DEPLOY-020：打包发布归档

步骤：

1. 将演示包目录压缩为 `kdl-olp-demo-<release_id>.zip`。
2. 计算 zip 文件大小和 hash。
3. 将 zip、release_id、job_id 写入 `working2/05-验收证据.md`。

验收：zip 可解压，解压后包含 `index.html`、`demo-manifest.json`、19 个 `.grl` 和最新 job。

### W2-DEPLOY-030：上传到服务器

目标：

```text
https://82.156.24.101:8095/
/opt/kdl-olp-demo/8095/releases/<release_id>
/opt/kdl-olp-demo/8095/current -> releases/<release_id>
```

步骤：

1. 使用 `scp` 或等效方式上传 zip 到服务器临时目录。
2. 在服务器创建 release 目录并解压。
3. 更新 `current` 软链接指向新 release。
4. 确认 Web 服务根目录指向 `current`。
5. 不在仓库文档中记录服务器密码；凭据只保留在部署人员本地。

验收：服务器上存在 release 目录，`current` 指向最新 release。

### W2-DEPLOY-040：HTTPS 服务验证

步骤：

1. 打开 `https://82.156.24.101:8095/`。
2. 验证 `index.html` 能加载。
3. 验证以下 URL 可访问：
   - `/demo-manifest.json`
   - `/app/virtual-controller.html`
   - `/test-results/abb120-spec/<job_id>/report.json`
   - `/test-results/abb120-spec/<job_id>/report.html`
   - `/test-results/virtual-controller/virtual-controller-desktop.png`
   - `/spec-programs/manifest.json`
4. 在浏览器中进入虚拟控制器页面，检查页面显示 suite/job/program/trace/queue/IO/diagnostics。
5. 如证书为自签名，记录浏览器安全提示为环境说明，不作为功能失败；如页面资源 404 或 JS 错误，则发布失败。

验收：远程页面可演示 19 个程序和最新 job 证据。

### W2-DEPLOY-050：远程 smoke test

建议命令：

```powershell
$base = "https://82.156.24.101:8095"
curl.exe -k "$base/"
curl.exe -k "$base/demo-manifest.json"
curl.exe -k "$base/spec-programs/manifest.json"
curl.exe -k "$base/app/virtual-controller.html"
curl.exe -k "$base/test-results/abb120-spec/<job_id>/report.json"
```

检查：

1. HTTP 状态为 200。
2. `demo-manifest.json` 中 `program_count` 为 19。
3. `report.json` 中 `fail` 为 0。
4. 页面资源无 404。

验收：命令输出摘要写入 `working2/05-验收证据.md`。

### W2-DEPLOY-060：回滚

步骤：

1. 服务器保留至少最近 2 个 release。
2. 新版本验证失败时，将 `current` 重新指向上一个 release。
3. 再次访问 `https://82.156.24.101:8095/` 验证旧版本恢复。
4. 在 `working2/03-推进台账.md` 记录回滚原因和 release_id。

验收：回滚后远程页面恢复到上一个可用版本。

## 10. 后续完善程序时的固定流程

每次新增或修改虚拟测试程序，都按以下顺序推进：

1. 修改 `.grl` 程序和 `spec-programs/manifest.json`。
2. 更新 `working2/programs/manifest.md` 的覆盖矩阵。
3. 执行 `npm run typecheck`。
4. 执行 `npm test`。
5. 执行 `npm run suite:abb120-spec`，生成新 `W2-JOB-*`。
6. 执行 `npm run verify:virtual-controller`，刷新截图。
7. 重新生成 Word 测试文档和 GRL 使用手册，如内容发生变化。
8. 重新生成服务器演示包并发布到 HTTPS。
9. 更新 `working2/03-推进台账.md`、`04-任务矩阵.md`、`05-验收证据.md`。
10. 提交代码并上传云仓库。