cdsl-cad/docs/engine_diagnostics_test_plan.md

# engine 诊断 → 测试方法 → 修改前后对比

## 1. 截图核对结论

`backend\engine` 等价于 `backend/engine/cdsl_engine/`。对截图 10 行逐一比对代码（行号均能命中），结论是 **全部成立**。证据索引如下：

| # | 截图描述 | 代码位置（已核） |
|---|---|---|
| 1 | PlaneSpec 静默丢弃 y_dir，只用 origin/x_dir/normal 重建 | `runtime_types.py:173-180` `PlaneSpec.from_mapping`；`sketch_solver.py:43-52` `_to_3d` |
| 2 | draft 被 schema 接受但 runtime 未执行 | `cdsl_schema.json:94-99` extrudeParams.draft；`runtime.py:338-342` `_shape_from_primary` |
| 3 | revolve.reverse 未进入旋转方向计算 | `runtime.py:344-349` `_shape_from_primary` 分支；`cdsl_schema.json:100-105` |
| 4 | Hole host-face schema/runtime 合同自相矛盾 | `runtime.py:469-483` 支持 frame + selector 两条路径；`cdsl_schema.json:229-243` 仅 selectorRef |
| 5 | 高级终止条件要求整张 profile 同一距离 | `runtime.py:157-211` `_targeted_extent_vector` 拒绝 non_uniform_extent_target |
| 6 | Pattern 严禁 source selector/host selector/extent selector | `capabilities.py:68-91` `pattern_transform_blocker` |
| 7 | ExecutionSession 单 active body | `runtime.py:81-91`（#7 已完成：多体 body_id + 前缀匹配） |
| 8 | Selector 持久性依赖几何等价匹配 | `runtime_types.py` `_unique_equivalent_predecessor` / `_geometry_equivalent`（#8 已完成：演化后继映射 `_evolved_equivalent` / `_successors`，stable_id 跨 body 解析） |
| 9 | HoleSpec 仅支持简单圆柱、沉头、沉孔 | `runtime_types.py:191-250` `HoleSpec` 字段表；`capabilities.py:305-308` thread 拒绝 |
| 10 | Profile 支持链断裂（circles/annulus 未接入 CDSL-only） | `profile_schema.json:8` 仅 3 类；`cdsl_importer/solidworks_to_cdsl.py:113-142` 历史 importer 分类器 |

## 2. 测试方法（四层 + phase 分桶）

### 2.1 单元层
新增 `backend/tests/test_engine_diagnostics_baseline.py`，对应 10 条问题写 14 个 testcase（含正反两面）：
- 问题 1：正交 y_dir 保留 / 偏斜 y_dir 显式警告或正交化
- 问题 2：draft 实体拔模 / 或 schema 拒绝
- 问题 3：revolve.reverse 重心落在正确半侧
- 问题 4：hole_wizard.host_face.frame 通过 schema
- 问题 5：up_to_surface 非均匀 profile 被裁剪而非拒绝
- 问题 6：pattern_linear 重放带 host_face.frame 的孔；pattern_linear 重放 up_to_surface 拉伸
- 问题 7：multi-body fixture 出现 ≥ 2 个独立 body_id
- 问题 8：fillet 后原 edge selector 仍可 resolve（实现于 `backend/tests/test_engine_selector_persistence.py`，含被波及边可解析、被完整消费边保持保守、未受影响边不受干扰三个契约）
- 问题 9：thread hole executable 或 schema 显式拒绝
- 问题 10：importer 将 circles 降为 analytic_contours；schema 拒绝 legacy profile

### 2.2 数据层
新增 `backend/tests/test_engine_diagnostics_corpus.py`，扫描 `json_to_cdsl/output/*.cdsl.json`（共 5763 份），统计：
- `workplane.x_dir · workplane.y_dir` 与 ‖x‖·‖y‖·cosθ 的偏差分布
- `profile.type ∈ {circles, annulus}` 计数（已部分修复，应单调下降）
- `hole_wizard` 含 `thread` 的特征数
- `params.draft` 出现次数
- `params.reverse=true` 的 revolve_* 出现次数

### 2.3 批量层（已有，零成本复用）
```bash
PYTHONPATH=backend/engine python -m cdsl_engine.batch_rebuild \
  json_to_cdsl/output /tmp/batch-before --build --build-timeout 15
```
产物：
- `manifest.json`：part_count、runtime_eligible_count、built_count、geometry_verified_count、failure_category_counts
- `summary-by-atomic.json`：atomic 频次
- `summary-by-blocker.json`：blocker code 频次
- `parts/<id>.report.json`：每个 part 完整报告（selector_resolution、numeric_comparison）

修改前/后各跑一次，对比以上聚合 JSON。

### 2.4 几何层
`GJH/scriptTest.py` 已能批量走 CDSL-only 路径。参照 `GJH/exp_compare_084242.py` 思路对单零件做体积/bbox/face 数/凸包方向对比。

### 2.5 phase 分桶
```bash
python -m cdsl_engine.batch_rebuild json_to_cdsl/output /tmp/p3 --phase p3 --build
python -m cdsl_engine.batch_rebuild json_to_cdsl/output /tmp/p4 --phase p4 --build
python -m cdsl_engine.batch_rebuild json_to_cdsl/output /tmp/p6 --phase p6 --build
```
- P3：基准（拉伸/旋转/参考）
- P4：+ hole_wizard（→ 问题 9）
- P6：+ pattern（→ 问题 6）

## 3. 修改前后差异指标

| # | blocker/信号 | A 当前 | B 修复后 | 度量 |
|---|---|---|---|---|
| 1 | x_dir·y_dir 与 ‖x‖·‖y‖cosθ 偏差 | 12,033/14,908 偏差 > 1e-4 | ≤ 1e-6 或显式 warnings | 数据扫描 |
| 2 | draft 静默成功 | geometry_verified 偏低 | runtime_eligible_count ↑ 或 schema 拒绝 | 批量层 |
| 3 | revolve centroid 侧 | centroid 在错半侧 | 正确侧 | 单元 |
| 4 | schema 拒绝 host_face.frame | schema violation | 通过 | 单元 + 数据 |
| 5 | non_uniform_extent_target 频次 | 高 | 显著下降 | summary-by-blocker |
| 6 | unsupported_pattern_selector_transform 频次 | 高（截图口径） | 0 | summary-by-blocker |
| 7 | body_id 数 | =1 | ≥2 | 单元 |
| 8 | fillet 后 selector 解析成功率 | not_found | resolved（演化后继唯一时；被完整消费的边保持保守 not_found） | 单元 |
| 9 | unsupported_hole_subtype 频次 | ≈712 | 0 | summary-by-blocker |
| 10 | unsupported_profile 频次 / profile.type=circles/annulus | ≈718 | 0（importer 修复后） | 数据 + summary-by-blocker |

## 4. 最小基线流程

```bash
# 数据扫描
python backend/tests/test_engine_diagnostics_corpus.py

# 批量基线
PYTHONPATH=backend/engine python -m cdsl_engine.batch_rebuild \
  json_to_cdsl/output /tmp/batch-before --build --build-timeout 15

# phase 分桶
PYTHONPATH=backend/engine python -m cdsl_engine.batch_rebuild \
  json_to_cdsl/output /tmp/batch-p3-before --phase p3 --build
PYTHONPATH=backend/engine python -m cdsl_engine.batch_rebuild \
  json_to_cdsl/output /tmp/batch-p4-before --phase p4 --build
PYTHONPATH=backend/engine python -m cdsl_engine.batch_rebuild \
  json_to_cdsl/output /tmp/batch-p6-before --phase p6 --build

# 单测基线
python -m unittest backend.tests.test_engine_diagnostics_baseline -v
```

任意修复后重跑，diff 出 geometry_verified_count 单调不减、各 blocker 频次单调下降。

## 5. 修复 PR 强约束

按 `engine/README.md:22-30` 声明：三处必须同步修改——
1. `sketch_solver.py` / `runtime.py` / `build123d_adapter.py` 实现
2. `profile_schema.json`（人读契约）
3. `cdsl_schema.json`（机器契约）

`backend/tests/test_profile_schema.py` 是这三处同步的护栏。

## 6. 与当前修改的关系

`git diff` 显示 `json_to_cdsl/evidence_v2_to_cdsl.py` 把 `type=circles` 重写为 `type=analytic_contours`，并已应用于 070825 / 084242 两份 cdsl.json。这是 **问题 10 的入口侧修复**（importer 直接产出合规 profile）。

修复后数据扫描预期：
- `json_to_cdsl/output/*.cdsl.json` 中 `profile.type=="circles"` 计数：数百 → 0（已在新文档体现）
- `summary-by-blocker.unsupported_profile`：在新文档上 = 0
- 旧文档仍可能含 legacy profile，测试需保留 `json_to_cdsl/output.before/` 快照做对比