cnc_wams/完善wasm/working/02-项目程序开发详细步骤.md

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

每轮固定流程

1. 选择任务：从 04-任务矩阵.md 选择一个任务编号，不直接无编号改代码。
2. 定位基准：记录对应 LinuxCNC 源码目录、上游测试、nc_files 或 configs/sim 资产。
3. 判断边界：标记为源码复用、WASM 边界、OPFS 边界、浏览器 UI 边界、full-process 边界或硬件边界。
4. 接入源码或资产：更新 vendor 提取、source manifest、source reuse map，禁止手写替代语义。
5. 建立 Native 证据：优先 native probe、native rs274 输出或上游 test.sh 对比。
6. 建立 WASM 证据：通过 C ABI、Node runner 或 SDK 执行相同行为，并与 Native 比较。
7. 建立浏览器证据：涉及 OPFS/UI/Worker 的功能必须跑真实浏览器测试。
8. 更新文档：同步 compatibility、test tracker、blocked table、推进台账、验收证据。
9. 运行回归门禁：按改动类型运行最小验收包，跨模块改动运行 host aggregate smoke。
10. 收口结论：把状态推进到 L0-L5 或 Blocked，不使用模糊的“基本完成”。

基线阶段

Step 0: 锁定上游基线

目标：

• 确认 /home/mes123456/cnc_wams/linuxcnc 存在且 commit 为 60597ee0718873d2449058c824262a275e5e4bad。
• 确认 wasm-port/tools/upstream-baseline.txt 与 wasm-port/docs/scope-and-baseline.md 一致。

必跑命令：

cd /home/mes123456/cnc_wams/wasm-port
./tools/verify_upstream_baseline.sh
./tools/verify_vendor_sync.sh
./tools/verify_no_standalone_cnc_semantics.sh

完成条件：命令通过，输出写入 05-验收证据.md，异常写入任务矩阵的阻塞或不通过原因。

Step 1: 现有能力盘点

目标：

• 盘点 wasm-port 已有 Native/WASM/Browser/host smoke。
• 把已有完成项映射到 LinuxCNC 功能树，不能只按项目模块归类。

建议命令：

cd /home/mes123456/cnc_wams/wasm-port
find tests -maxdepth 3 -type f | sort
find tools -maxdepth 1 -type f | sort

完成条件：任务矩阵中每个功能域有初始状态、证据入口和下一步。

功能推进顺序

A. 解释器与文件执行

1. 从 tests/interp、tests/ccomp、tests/remap、nc_files 选择上游资产。
2. 原样 vendored 或通过脚本提取，加入同步校验。
3. 为纯解释器项建立 Native canonical event 或错误对比。
4. 将同一 fixture 纳入 WASM Node。
5. 对能在浏览器运行的项纳入 verify_interp_browser.sh 或等价真实浏览器 smoke。
6. 错误文本允许路径、空白、行尾归一化，但错误类别、触发行、关键提示必须一致。

最小验收包：

./tests/native/verify_native_probes.sh
./tests/wasm/node/verify_interp_wasm.sh
./tests/browser/verify_interp_browser.sh

B. configs/sim、INI 与 OPFS

1. 按机床族选择代表配置，保留 INI、tool.tbl、var、subroutine、USER_M_PATH 等上下文。
2. 区分纯解释器可执行、NGC remap、Python remap、HAL/UI/full-process 依赖。
3. 对 standalone 不能覆盖的项标 expected_fail 或 Blocked，不降级成解释器通过。
4. 浏览器侧必须证明 OPFS 文件可导入、保存、恢复、导出对比。

最小验收包：

./tests/native/verify_sim_configs.sh
./tests/wasm/node/verify_sim_configs_wasm.sh
./tests/wasm/node/verify_sim_configs_inventory_wasm.sh
./tests/opfs/node/verify_file_service.sh
./tests/browser/verify_ini_panel_browser.sh

C. Task、NML 与运行控制

1. 对照 src/emc/task、src/emc/nml_intf，确认每个 UI/SDK 命令的 LinuxCNC 状态机归属。
2. 程序打开、run、pause、resume、step、abort、MDI、倍率必须从结构化 task/status snapshot 验证。
3. full-process 依赖未完成时，必须保留阻塞说明，不用解释器测试替代。

最小验收包：

./tests/wasm/node/verify_task_hal_wasm.sh
./tests/wasm/node/verify_task_state_matrix.mjs
./tools/verify_task_status_json_contract.sh

D. TP、Motion、Kinematics

1. TP 和运动学必须用 LinuxCNC 源码入口或 vendored probe 计算，不用浏览器动画替代。
2. 对轨迹规划、多轴同步、五轴、switchkins、RTCP 建立输入、输出、容差和失败原因。
3. motion full-process 项无法拆 API 时，记录阻塞依赖和恢复路径。

最小验收包：

./tests/wasm/node/verify_tp_wasm.sh
./tests/wasm/node/verify_kinematics_wasm.sh
./tests/wasm/node/verify_motion_hal_sync.sh

E. HAL、IO、Tool、Spindle

1. tooldata、HAL 组件、主轴、冷却、M62-M68 先明确源码归属。
2. OPFS 只能做存储介质，不解析或改写刀具语义。
3. 硬件驱动、实时内核、动态 loadrt、外部 DB 程序按条件通过或阻塞验收。

最小验收包：

./tests/native/verify_native_probes.sh
./tests/wasm/node/verify_hal_runtime.sh
./tests/wasm/node/verify_tool_db_process_port_wasm.sh

F. 浏览器 UI 产品化

1. UI 坐标、模态、刀具、主轴、程序状态必须来自底层快照。
2. 浏览器 smoke 必须验证 C ABI、OPFS 或状态 JSON 结果，不能只验证按钮存在。
3. 截图只能作为 P5 辅证，不能单独证明 CNC 语义。

最小验收包：

./tests/ui/node/verify_ui_node_smokes.sh
./tests/browser/verify_real_simulation_browser.sh
./tests/browser/verify_real_simulation_axis_screenshot_browser.sh

发布前完整验收包

完整验收至少运行：

cd /home/mes123456/cnc_wams/wasm-port
./tools/verify_upstream_baseline.sh
./tools/verify_vendor_sync.sh
./tools/verify_no_standalone_cnc_semantics.sh
./tests/native/verify_native_probes.sh
./tests/native/verify_nc_files.sh
./tests/native/verify_sim_configs.sh
./tests/wasm/node/verify_ini_wasm.sh
./tests/wasm/node/verify_interp_wasm.sh
./tests/wasm/node/verify_sim_configs_wasm.sh
./tests/wasm/node/verify_sim_configs_inventory_wasm.sh
./tests/wasm/node/verify_nc_files_wasm.sh
./tests/wasm/node/verify_tp_wasm.sh
./tests/opfs/node/verify_file_service.sh
./tests/ui/node/verify_ui_node_smokes.sh
./tests/browser/verify_ini_panel_browser.sh
./tests/browser/verify_interp_browser.sh
./tests/host/verify_host_smokes.sh

完成条件：全部命令通过，unexpected_fail=0，所有 expected_fail 和 Blocked 均有固定原因、源码归属和解除条件。