wangdequan/cnc_wams
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
cnc_wams/work/working4/02-program-development-steps.md

12 KiB
Raw Permalink Blame History

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 资料变成项目内可追溯输入，而不是散落引用。

主要新增或更新文件：

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 追溯记录。

验收命令：

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 拓扑。

主要新增或更新文件：

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。

验收命令：

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 仿真的通信差异。

主要新增或更新文件：

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 说明存在。

验收命令：

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。

主要新增或更新文件：

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。

验收命令：

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 和测试。

主要新增或更新文件：

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 使用。

验收命令：

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 诊断方式展示。

主要新增或更新文件：

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 存在。

验收命令：

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：浏览器证据和报告

目标：为本功能包生成可复查证据。

主要新增或更新文件：

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。

验收命令：

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。
Reference in New Issue View Git Blame Copy Permalink