# 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`。