317 lines
12 KiB
Markdown
317 lines
12 KiB
Markdown
# 02 程序开发详细步骤
|
||
|
||
生成日期：2026-06-26
|
||
|
||
## 1. 开发原则
|
||
|
||
- 先复用现有 `app/src` 架构：`profiles`、`runtime`、`state`、`ui`、`visualization`、`tests`。
|
||
- 不引入 React/Vue 等 UI 框架。
|
||
- 不把 gmoccapy native Python/GTK 代码作为浏览器依赖。
|
||
- 图标资产可以使用 `working3/gmoccapy_button_icons/files/`，但按钮控制语义必须由现有 store/task policy/runtime 驱动。
|
||
- 每个阶段必须同步更新 `04-task-matrix.md` 和 `03-progress-ledger.md`。
|
||
|
||
当前状态：阶段 A 到 G 已按 `04-task-matrix.md` 收口为 `done`。本文件保留为复现步骤和后续变更清单。
|
||
|
||
## 2. 阶段 A：资料和资产落库
|
||
|
||
目标：把 `working3` 资料变成项目内可追溯输入，而不是散落引用。
|
||
|
||
主要新增或更新文件：
|
||
|
||
```text
|
||
web-rtcp-5axis-sim-plan/docs/gmoccapy-xyzab-reference.md
|
||
web-rtcp-5axis-sim-plan/app/src/ui-reference/gmoccapy-button-icons.json
|
||
web-rtcp-5axis-sim-plan/app/src/assets/gmoccapy-icons/
|
||
web-rtcp-5axis-sim-plan/docs/traceability-matrix.md
|
||
```
|
||
|
||
实施步骤：
|
||
|
||
1. 新建 `docs/gmoccapy-xyzab-reference.md`，摘要吸收 `gmoccapy_XYZAB_execution_analysis.md`。
|
||
2. 将 `button_icon_inventory.csv` 转换为 JSON manifest，保留字段：分类、button_id、label、tooltip、icon_name、requested_size、source_type、copied_file、signals、notes。
|
||
3. 将核心按钮图标复制到 `app/src/assets/gmoccapy-icons/`，至少覆盖：estop、power、manual、mdi、auto、settings、home、tool、touch、open、run、stop、pause、step、reload、fullscreen、spindle、coolant、view/zoom。
|
||
4. 在 manifest 中记录原始来源和 `working3` 复制文件路径。
|
||
5. 更新 `docs/traceability-matrix.md`，新增 gmoccapy_XYZAB 和按钮 icon 追溯记录。
|
||
|
||
验收命令：
|
||
|
||
```bash
|
||
find web-rtcp-5axis-sim-plan/app/src/assets/gmoccapy-icons -maxdepth 1 -type f | wc -l
|
||
node -e "JSON.parse(require('fs').readFileSync('web-rtcp-5axis-sim-plan/app/src/ui-reference/gmoccapy-button-icons.json','utf8')); console.log('icon_manifest_json=ok')"
|
||
git diff --check -- web-rtcp-5axis-sim-plan
|
||
```
|
||
|
||
验收标准：
|
||
|
||
- JSON manifest 可解析。
|
||
- 图标文件存在，文件名稳定，不依赖 `working3` 运行时路径。
|
||
- 文档明确图标只证明 UI 资产来源，不证明按钮控制语义。
|
||
|
||
## 3. 阶段 B：新增 gmoccapy_XYZAB reference profile
|
||
|
||
目标：在 Web 项目中建立 XYZAB/gmoccapy 参考 profile，表达 native INI/HAL 拓扑。
|
||
|
||
主要新增或更新文件：
|
||
|
||
```text
|
||
web-rtcp-5axis-sim-plan/app/src/profiles/gmoccapy-xyzab.js
|
||
web-rtcp-5axis-sim-plan/app/src/profiles/index.js
|
||
web-rtcp-5axis-sim-plan/app/src/profiles/source-reference-map.js
|
||
web-rtcp-5axis-sim-plan/tests/node/verify_gmoccapy_xyzab_profile.mjs
|
||
```
|
||
|
||
实施步骤：
|
||
|
||
1. 新增 profile id：`gmoccapy-xyzab`。
|
||
2. 设置坐标：`["X", "Y", "Z", "A", "B"]`。
|
||
3. 设置 kinematics：`trivkins coordinates=xyzab`，并标记 `tcpCapable=false`、`rtcpProof=false`。
|
||
4. 记录 INI 来源：`linuxcnc/configs/sim/gmoccapy/gmoccapy_XYZAB.ini`。
|
||
5. 记录 HALFILE：`core_sim_XYZAB.hal`、`spindle_sim.hal`、`simulated_home.hal`。
|
||
6. 记录 POSTGUI_HALFILE：`gmoccapy_postgui.hal`。
|
||
7. 记录 `TASK=milltask`、`EMCMOT=motmod`、`HALUI=halui`、`CYCLE_TIME=100`、`SERVO_PERIOD=1000000`。
|
||
8. 加入 `fiveAxisProfiles` 列表，但 UI 文案必须显示它是 gmoccapy/trivkins 参考机型。
|
||
9. Node 测试断言 profile 坐标、joint 数、HAL files、postgui、no-force-homing gate、semantic boundary。
|
||
|
||
验收命令：
|
||
|
||
```bash
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_gmoccapy_xyzab_profile.mjs
|
||
npm --prefix web-rtcp-5axis-sim-plan/app run build
|
||
```
|
||
|
||
验收标准：
|
||
|
||
- `gmoccapy-xyzab` 可通过 profile selector 选择。
|
||
- 信息面板显示 `XYZAB`、`trivkins`、`gmoccapy_XYZAB.ini`、HALFILE、POSTGUI_HALFILE。
|
||
- 不显示 `RTCP proof ready`，除非后续接入真实 source-derived TCP 运动学。
|
||
|
||
## 4. 阶段 C：NML/HAL 通信边界诊断
|
||
|
||
目标：让 Web UI 能解释 gmoccapy native 与 Web 仿真的通信差异。
|
||
|
||
主要新增或更新文件：
|
||
|
||
```text
|
||
web-rtcp-5axis-sim-plan/app/src/runtime/gmoccapy-communication-model.js
|
||
web-rtcp-5axis-sim-plan/app/src/ui/gmoccapy-shell.js
|
||
web-rtcp-5axis-sim-plan/app/src/styles/gmoccapy.css
|
||
web-rtcp-5axis-sim-plan/tests/node/verify_gmoccapy_communication_model.mjs
|
||
```
|
||
|
||
实施步骤：
|
||
|
||
1. 建立 communication model 数据结构：
|
||
- native command path：`gmoccapy -> linuxcnc.command -> NML emcCommand -> milltask`。
|
||
- native status path：`milltask -> NML emcStatus/emcError -> stat/error poll`。
|
||
- native HAL path：`gmoccapy.* pins <-> HAL shared memory`。
|
||
- Web path：`button -> store dispatch -> task policy/runtime -> status snapshot -> UI/Three.js`。
|
||
2. 在 info tabs 中新增 `gmoccapy comms` 或合并到 RTCP diagnostics。
|
||
3. 对每个 action 显示 native equivalent command，例如 `STATE_ON`、`MODE_AUTO`、`AUTO_RUN`、`JOG_CONTINUOUS`。
|
||
4. 显示 postgui 顺序：`halcomp.ready()` 后才能执行 POSTGUI_HALFILE。
|
||
5. Node 测试断言主要命令链路和 HAL/postgui 说明存在。
|
||
|
||
验收命令：
|
||
|
||
```bash
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_gmoccapy_communication_model.mjs
|
||
```
|
||
|
||
验收标准：
|
||
|
||
- UI 能区分 NML command、NML status/error、HAL pin、Web runtime feedback。
|
||
- 文案不暗示浏览器直接连接 native NML buffer 或 HAL shared memory。
|
||
|
||
## 5. 阶段 D：按钮图标和语义映射
|
||
|
||
目标：将当前文字按钮升级为 gmoccapy 风格 icon button，同时保持 task policy gate。
|
||
|
||
主要新增或更新文件：
|
||
|
||
```text
|
||
web-rtcp-5axis-sim-plan/app/src/ui/gmoccapy-icon-registry.js
|
||
web-rtcp-5axis-sim-plan/app/src/ui/gmoccapy-shell.js
|
||
web-rtcp-5axis-sim-plan/app/src/styles/gmoccapy.css
|
||
web-rtcp-5axis-sim-plan/tests/node/verify_gmoccapy_icon_manifest.mjs
|
||
web-rtcp-5axis-sim-plan/tests/browser/gmoccapy_shell_smoke.html
|
||
```
|
||
|
||
实施步骤：
|
||
|
||
1. 从 JSON manifest 建立 `getGmoccapyIcon(buttonId, stateVariant)`。
|
||
2. 右侧主状态栏接入：
|
||
- `tbtn_estop`：`main_switch_on/off`。
|
||
- `tbtn_on`：`power_off/on`。
|
||
- `rbt_manual`、`rbt_mdi`、`rbt_auto`：inactive/active 图标。
|
||
- `tbtn_setup`、`tbtn_user_tabs`。
|
||
3. 底部栏接入：
|
||
- exit、homing、tool、touch、fullscreen、open、reload、run、stop、pause、step。
|
||
4. Spindle/Coolant 接入：
|
||
- spindle forward/reverse/stop active 状态。
|
||
- flood/mist active/inactive 状态。
|
||
5. Preview toolbar 接入：
|
||
- view x/y/z/p、zoom in/out、toolpath、dimensions。
|
||
6. 保留按钮 `aria-label`、title 和 disabled reason，不能只显示图标。
|
||
7. browser smoke 增加断言：核心按钮存在 `data-icon-name`、active variant 和 disabled reason。
|
||
|
||
验收命令：
|
||
|
||
```bash
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_gmoccapy_icon_manifest.mjs
|
||
npm --prefix web-rtcp-5axis-sim-plan/app run build
|
||
bash web-rtcp-5axis-sim-plan/tests/browser/verify_gmoccapy_shell_browser.sh
|
||
```
|
||
|
||
验收标准：
|
||
|
||
- 核心按钮有图标、tooltip 或 aria-label。
|
||
- active/inactive 状态随 store 状态变化。
|
||
- RUN disabled 时仍显示 blocked reason。
|
||
- 图标未加载时有稳定文本 fallback。
|
||
|
||
## 6. 阶段 E：G-code 执行互锁和按钮 gate 扩展
|
||
|
||
目标：按 gmoccapy_XYZAB 的执行条件补齐 Web gate 和测试。
|
||
|
||
主要新增或更新文件：
|
||
|
||
```text
|
||
web-rtcp-5axis-sim-plan/app/src/state/linuxcnc-task-policy.js
|
||
web-rtcp-5axis-sim-plan/app/src/state/store.js
|
||
web-rtcp-5axis-sim-plan/tests/node/verify_gmoccapy_xyzab_gates.mjs
|
||
web-rtcp-5axis-sim-plan/tests/browser/gmoccapy_shell_smoke.html
|
||
```
|
||
|
||
实施步骤：
|
||
|
||
1. RUN gate 覆盖：
|
||
- INI loaded。
|
||
- machine-file opened。
|
||
- not estop。
|
||
- machine on。
|
||
- all homed when `NO_FORCE_HOMING=0`。
|
||
- mode auto。
|
||
- interpreter idle。
|
||
- task/HAL runtime ready when required。
|
||
2. MDI gate 覆盖：
|
||
- machine on。
|
||
- all homed when `NO_FORCE_HOMING=0`。
|
||
- mode mdi 或可安全切换 MDI。
|
||
- interpreter idle 或允许队列追加。
|
||
3. JOG gate 覆盖：
|
||
- machine on。
|
||
- mode manual。
|
||
- not running。
|
||
- axis/joint available。
|
||
4. HOME gate 覆盖：
|
||
- machine on。
|
||
- not running。
|
||
- no joint already homing。
|
||
5. SPINDLE/COOLANT/OVERRIDE gate 覆盖：
|
||
- estop/off 状态禁用。
|
||
- auto/mdi reading/waiting 时限制手动覆盖主轴方向。
|
||
6. Stop/Abort 必须在多数状态下可用，并清理 pause/start_line/active UI 状态。
|
||
7. 增加每个 gate 的 operatorMessage，供按钮 title 和证据 JSON 使用。
|
||
|
||
验收命令：
|
||
|
||
```bash
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_gmoccapy_xyzab_gates.mjs
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_run_preconditions.mjs
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_run_feedback_loop.mjs
|
||
```
|
||
|
||
验收标准：
|
||
|
||
- 非法状态有明确 blocked reason。
|
||
- 合法状态 RUN/MDI/JOG/HOME 可通过。
|
||
- 原有 `verify_run_preconditions.mjs` 不回归。
|
||
|
||
## 7. 阶段 F：HAL pin/postgui 诊断面板
|
||
|
||
目标：把 gmoccapy_XYZAB 的 HAL pin 和 postgui 连接以 Web 诊断方式展示。
|
||
|
||
主要新增或更新文件：
|
||
|
||
```text
|
||
web-rtcp-5axis-sim-plan/app/src/runtime/gmoccapy-hal-model.js
|
||
web-rtcp-5axis-sim-plan/app/src/ui/gmoccapy-shell.js
|
||
web-rtcp-5axis-sim-plan/tests/node/verify_gmoccapy_hal_model.mjs
|
||
```
|
||
|
||
实施步骤：
|
||
|
||
1. 建立 HAL model 分类：
|
||
- hard buttons：`gmoccapy.h-button.*`、`gmoccapy.v-button.*`。
|
||
- jog pins：`gmoccapy.jog.axis.*`、`gmoccapy.jog.jog-inc-*`。
|
||
- override pins：feed/spindle/jog/rapid counts 和 direct-value。
|
||
- tool pins：tooloffset、toolchange、diameter。
|
||
- program pins：length、current-line、progress。
|
||
- error/message pins。
|
||
2. 建立 postgui nets：
|
||
- spindle feedback bar。
|
||
- spindle at-speed LED。
|
||
- tooloffset x/z。
|
||
- simulated tool-change loop。
|
||
3. UI 显示 `native pin name`、`web source`、`current value`、`semantic boundary`。
|
||
4. Node 测试断言关键 pins 和 postgui nets 存在。
|
||
|
||
验收命令：
|
||
|
||
```bash
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_gmoccapy_hal_model.mjs
|
||
```
|
||
|
||
验收标准：
|
||
|
||
- 诊断面板清楚显示哪些是 native gmoccapy pins，哪些是 Web runtime 映射。
|
||
- tool-change loop 被标记为 simulation loop，不表示真实人工换刀。
|
||
|
||
## 8. 阶段 G：浏览器证据和报告
|
||
|
||
目标：为本功能包生成可复查证据。
|
||
|
||
主要新增或更新文件：
|
||
|
||
```text
|
||
qa/web-rtcp-5axis-site-test/
|
||
qa/web-rtcp-5axis-site-test/output/gmoccapy-xyzab-function-report.json
|
||
qa/web-rtcp-5axis-site-test/output/gmoccapy-xyzab-function-report.pdf
|
||
qa/web-rtcp-5axis-site-test/output/gmoccapy-xyzab/
|
||
work/working4/05-acceptance-evidence.md
|
||
```
|
||
|
||
实施步骤：
|
||
|
||
1. 增加页面自动化用例：
|
||
- profile 切换到 `gmoccapy-xyzab`。
|
||
- 检查 DRO 显示 X/Y/Z/A/B。
|
||
- 检查 `trivkins`、`NO_FORCE_HOMING=0`、HALFILE、POSTGUI_HALFILE。
|
||
- 检查按钮图标 active/inactive。
|
||
- 检查 RUN blocked reason。
|
||
- 完成一次合法状态 RUN 或模拟 RUN。
|
||
2. 保存截图：
|
||
- loaded。
|
||
- profile selected。
|
||
- run blocked。
|
||
- run ready。
|
||
- running。
|
||
- HAL diagnostics。
|
||
3. 保存 JSON report。
|
||
4. 输出 JSON 和 PDF 报告；本阶段已生成 `gmoccapy-xyzab-function-report.json` 和 `.pdf`。
|
||
5. 更新 `05-acceptance-evidence.md`。
|
||
|
||
验收命令：
|
||
|
||
```bash
|
||
npm --prefix web-rtcp-5axis-sim-plan/app run build
|
||
npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
|
||
bash web-rtcp-5axis-sim-plan/tests/browser/verify_gmoccapy_shell_browser.sh
|
||
node qa/web-rtcp-5axis-site-test/capture-gmoccapy-xyzab-function-cases.mjs
|
||
```
|
||
|
||
验收标准：
|
||
|
||
- JSON report 中所有 case 为 PASS。
|
||
- 截图文件存在且页面非空。
|
||
- PDF 或替代报告路径写入 `05-acceptance-evidence.md`。
|