feat: add per-part CAD model specs

2026-07-23 15:12:28 +08:00
parent 304911a69f
commit a2f3ba6a90
35 changed files with 1351 additions and 85 deletions
@@ -72,6 +72,14 @@ Write `cad-task.json` beside the task artifacts with this minimum shape:
 ```

 Paths are relative to the task directory unless an external input must remain absolute.
+Do not store authoritative model parameters in `cad-task.json`. Every part must
+have a sibling `model-spec.json` that owns its parameter values, reconstruction
+mode, parametric modification layer, and output paths. See `model-spec.md`.
+
+For an imported STEP, use `exact_step_base`: copy the explicitly supplied file
+into the task directory, record its checksum and geometry signature, and keep
+the imported B-Rep unchanged when the modification list is empty. This is an
+exact geometric base contract, not recovery of the original CAD feature tree.

 ## Backend adapter requirements

@@ -0,0 +1,95 @@
+# Per-part model specification
+
+Use one `model-spec.json` per generated or imported part. Treat it as the
+editable geometry contract. Keep `cad-task.json` separate for routing,
+experience use, validation results, and viewer links.
+
+## Native generator
+
+Use `native_generator` when the part has editable Python source:
+
+```json
+{
+  "schema_version": "1.0",
+  "model_spec_kind": "parametric_cad_model",
+  "model_id": "example_part",
+  "units": "mm",
+  "reconstruction": {
+    "mode": "native_generator",
+    "generator": {
+      "path": "example_part.py",
+      "entrypoint": "gen_step"
+    }
+  },
+  "parameters": {
+    "width": {
+      "value": 40,
+      "unit": "mm",
+      "role": "overall_width"
+    }
+  },
+  "modifications": [],
+  "outputs": {
+    "step": "example_part.step",
+    "stl": "example_part.stl"
+  }
+}
+```
+
+The generator must read its sibling `model-spec.json`. Do not duplicate
+authoritative parameter values as editable constants in both files.
+
+## Imported STEP
+
+Convert an explicitly supplied STEP into a task-local exact-base specification:
+
+```bash
+python scripts/model_spec.py import-step input.step \
+  --task-dir models/cad-router-v1/imported_part \
+  --model-id imported_part
+```
+
+This copies the source to `source.step`, records its SHA-256 and geometry
+signature, writes `model-spec.json`, and exports regenerated STEP/STL files.
+With an empty modification list, `verify` requires the imported B-Rep to retain
+the same bounds, center, topology counts, solid count, and volume.
+
+STEP normally contains final B-Rep geometry, not the original sketches,
+constraints, names, or feature history. Therefore:
+
+- `exact_step_base` guarantees an unchanged imported base, not recovered native
+  design history.
+- Add later edits as named parametric modifications.
+- Use semantic native reconstruction only when the feature family can be
+  reliably recognized and validate it independently against the source.
+- Never claim arbitrary STEP-to-JSON conversion recovers the author’s original
+  parameters or construction order.
+
+## Parametric modification layer
+
+Supported V1 operations are `add_box`, `cut_box`, `add_cylinder`, and
+`cut_cylinder`. Values may be literals or parameter references:
+
+```json
+{
+  "id": "central_bore",
+  "operation": "cut_cylinder",
+  "axis": "z",
+  "center": [0, 0, 0],
+  "diameter": {"parameter": "bore_diameter"},
+  "length": {"parameter": "bore_length"},
+  "enabled": true
+}
+```
+
+Change a named value and rebuild:
+
+```bash
+python scripts/model_spec.py set path/to/model-spec.json bore_diameter 18
+python scripts/model_spec.py build path/to/model-spec.json
+python scripts/model_spec.py verify path/to/model-spec.json
+```
+
+Use `apply_patch` when adding or structurally editing parameters and features so
+the modification remains reviewable. After every visible rebuild, run the CAD
+inspection and snapshot workflow and update `cad-task.json`.