171 lines
6.2 KiB
Markdown
171 lines
6.2 KiB
Markdown
# 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` 一致。
|
||
|
||
必跑命令：
|
||
|
||
```bash
|
||
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 功能树，不能只按项目模块归类。
|
||
|
||
建议命令：
|
||
|
||
```bash
|
||
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. 错误文本允许路径、空白、行尾归一化，但错误类别、触发行、关键提示必须一致。
|
||
|
||
最小验收包：
|
||
|
||
```bash
|
||
./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 文件可导入、保存、恢复、导出对比。
|
||
|
||
最小验收包：
|
||
|
||
```bash
|
||
./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 依赖未完成时，必须保留阻塞说明，不用解释器测试替代。
|
||
|
||
最小验收包：
|
||
|
||
```bash
|
||
./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 时，记录阻塞依赖和恢复路径。
|
||
|
||
最小验收包：
|
||
|
||
```bash
|
||
./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 程序按条件通过或阻塞验收。
|
||
|
||
最小验收包：
|
||
|
||
```bash
|
||
./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 语义。
|
||
|
||
最小验收包：
|
||
|
||
```bash
|
||
./tests/ui/node/verify_ui_node_smokes.sh
|
||
./tests/browser/verify_real_simulation_browser.sh
|
||
./tests/browser/verify_real_simulation_axis_screenshot_browser.sh
|
||
```
|
||
|
||
## 发布前完整验收包
|
||
|
||
完整验收至少运行：
|
||
|
||
```bash
|
||
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 均有固定原因、源码归属和解除条件。
|