Add ABB120 demo suite and docs
This commit is contained in:
wangdequan
378
working2/02-项目程序开发详细步骤.md
Normal file
378
working2/02-项目程序开发详细步骤.md
Normal file
@@ -0,0 +1,378 @@
|
||||
# 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. 提交代码并上传云仓库。
|
||||
Reference in New Issue
Block a user