# CADFS 全量重建目标与验收计划

## 目标

将 CADFS FeatureScript 历史稳定转换为 CDSL，由 engine 重建 STEP，并与
原始 STEP 做工程几何比较。近期交付门槛是 17 个代表性样本全部达到工程相似；
最终交付门槛是当前 CADFS 全量语料中的每个可比较模型都完成同一条链路。

这里的“重建成功”指 `comparison.json` 的 `rp.passed == true`，不是仅生成
`rebuild.step`。`strict.passed` 保留为高精度诊断指标：它用于发现源历史精度、
内核拓扑和局部几何差异，不再作为工程可用模型的唯一验收门槛。

本文件记录目标、阶段门槛和验收口径。实现进度、能力边界和每次代码变更
后的证据记录在本地台账
`ENGINE_CAPABILITY_GAPS_PROGRESS.local.md`；两者必须保持一致。

## 当前基线

- 全量输出快照：9,347 个 CADFS 样本，见 `output/summary.json`。产品目标可
  称为“一万条全量数据”，但验收时必须以本次扫描得到的实际样本总数为分母，
  不能将 10,000 写成未验证的固定数量。
- 代表性回归池：17 个样本，见 `regression/manifest.json`。它覆盖当前观察到的
  FeatureScript 操作、草图实体、已 lower 的 engine atomic 和未支持能力变体。
- 本地能力台账记录该池已有 `17/17 rebuilt` 的可执行 STEP 证据；当前 checked-in
  manifest 保留的是历史选择时的 `3` 个 engine baseline / `17` 个 conversion
  样本分类。因此，开始工程回归前必须重新生成并核对 manifest，不能将旧分类
  当作当前通过结果。
- 当前全量报告中仍有 `rebuild_failed`、`rebuild_timeout`、`comparison_timeout` 和
  `comparison.json.decision = rejected`。这些都是待消除的问题；`approximate_pass`
  是已重建且工程相似的模型，仍应保留 strict 差异证据供后续能力完善。

## 验收口径

一个样本必须同时具备以下工件和结果，才计入工程重建成功：

1. `candidate.cdsl.json` 通过 schema 和语义验证，且没有以跳过后续几何换取成功。
2. `bound.cdsl.json`（若样本需要 selector 绑定）可复现产生，绑定证据可追溯到
   feature、owner 和 topology snapshot。
3. `rebuild.step` 由完整的 CDSL feature history 生成；中间失败不能被最终可执行
   前缀掩盖。
4. `comparison.json` 的 `decision` 为 `strict_pass` 或 `approximate_pass`，并满足
   RP 工程阈值：`surface_max <= 0.02 mm`、`surface_p99 <= 0.02 mm`、
   `bbox_max_delta <= 0.02 mm`、体积和表面积相对误差均不超过 `0.005`，以及实体数相等。
5. `status.json`、转换诊断、重建报告和比较报告保存于该样本目录；可执行但不相似
   的模型必须保留，而不能在失败时删除。

严格比较失败不自动表示 engine 或 converter 失败。缺失原始 STEP、源数据损坏或
外部资产不可取得时，必须单独列为 source exception，附原始证据；不得伪装成
engine 或 converter 已完成。

## 第一阶段：17 个代表样本

阶段完成条件：下面 17 个样本全部以 `--compare-mode rp` 重新执行并达到工程相似，
同时 manifest 的覆盖标签与当前输出一致。每次修复只针对实际失败根因扩展能力；
一个样本可能由多个能力共同阻塞。

| 样本 | 代表的操作或几何 | 当前需要验证或补齐的门槛 |
| --- | --- | --- |
| `00002243` | extrude、hole、chamfer | 孔宿主、端盖/边 selector、倒角参数与稳定选边。 |
| `00035682` | cPlane、extrude、revolve | `line_point` 基准面及其后续特征引用。 |
| `00054089` | extrude、revolve | `swept_edge` selector。 |
| `00111611` | extrude、revolve、fillet、chamfer | 复杂草图、回转轴、圆角和倒角的拓扑稳定性。 |
| `00129362` | cPlane、extrude、revolve | 可复用基准面 frame、回转 add/cut。 |
| `00159804` | circularPattern、through-all add | 环形阵列 replay、`line_angle` 和 through-all 加料。 |
| `00192744` | circularPattern、extrude、transform | 已执行 `curve_point` 附着 frame、`up_to_next`、pattern copy deletion，以及 direct circular `COPY(BODY)` 的 multi-body transform；仍缺完整 pattern/body lifecycle 与 source/STEP 一致性证据。 |
| `00212904` | shell、two-sided cut | shell、`three_point`、双向切除终止条件。 |
| `00287955` | loft、cPlane、revolve | 多 profile loft、`cap_edge`、`mid_plane`。 |
| `00423838` | circularPattern、extrude | `up_to_vertex` 与 two-sided cut 的非盲终止。 |
| `00542223` | shell、sweep、circularPattern | sweep path/profile、shell、`plane_point`、through-all cut。 |
| `00612529` | loft、mirror、cPlane | loft profile 对齐、镜像 replay、`mid_cap_edge`。 |
| `00694309` | extrude、fillet | `up_to_body` 和 feature 后继 selector。 |
| `00710855` | extrude、chamfer | 曲面拉伸与 surface/solid 混合拓扑。 |
| `00789939` | shell、extrude、fillet | shell、`offset_face`、`swept_face`。 |
| `00835610` | booleanBodies、revolve | 多 body boolean、`cap_face`、`intersect`、revolve surface。 |
| `00925274` | mirror、through-all cut | 镜像 replay、`up_to_surface`、`line_angle`。 |

推荐的完整验收命令：

```bash
PYTHONPATH=backend:. python -m cadfs_to_cdsl regression \
  --tier all --stage pipeline --compare-mode rp --timeout-seconds 60
```

命令结束后应检查 17 个 `comparison.json`，而不是只检查 CLI 的进程退出码。

## 能力完成目标

能力的完成定义为同一能力的 CADFS lowering、CDSL contract、runtime/adapter、
selector 或 body 语义（需要时）、工程比较回归均具备。仅实现其中一层时只能记为
“部分完成”。优先级依据全量影响数和 17 样本依赖关系确定。

### P0：使特征历史成为完整实体

1. 复杂草图与 B-spline：稳定的多 wire、孔洞、闭合排序、退化诊断；开口 wire
   可作为 sweep path，闭合 wire 可作为实体 profile。
2. 显式多 body 结果模型：body ID、选择集、复制、保留和生命周期；这是
   `booleanBodies`、transform、pattern copy 的前置条件。
3. sweep、完整 loft、shell 和 booleanBodies：包含实体/曲面模式、导轨或 profile
   对齐、移除面、结果 body 和可诊断的失败边界。
4. circularPattern 与 mirror：source replay、完整轴/面引用和嵌套 pattern；实例必须
   是独立的几何结果，不能依赖隐式全局主体。

### P0：补齐拉伸终止语义

按全量影响数优先完成复杂 `extrude`，以及 through-all、two-sided、up-to-surface、
up-to-next、up-to-body、up-to-vertex 和 surface/mixed 模式。终止距离必须由目标 body
的真实相交结果或明确的源参考决定，不能用固定默认值近似。

### P1：让后续特征引用稳定

1. 记录内核拓扑 delta：`preserved`、`modified`、`generated`、`deleted` 和 feature
   输出角色；不唯一的后继必须诊断为歧义。
2. 补齐 CAP、SWEPT、OFFSET、INTERSECT、MID_CAP 的 face/edge selector，并保留
   owner 与几何签名。
3. 完成 line-angle、plane-point、three-point、mid-plane、line-point、curve-point
   基准面，覆盖曲面和曲线切线引用及退化输入。
4. 完成 fillet、chamfer、hole、revolve/revolve_surface 的参数变体、可行性预检查
   和拓扑后继处理。

### P2：清除全量语料的剩余 FeatureScript 缺口

实现 draft、thicken、split、moveFace、deleteFace、replaceFace、完整 transform，
以及 derive/import 的受控外部资产协议。任何依赖外部模型的操作只有在资产身份、
输入、版本和失败方式均可复现时，才能计入全量成功。

## 实现参考与边界

`/Users/lk/Downloads/SimpleCADAPI-master 4` 可作为 OCP 调用和拓扑建模的实现
参考，而不是可直接替换的 engine：

- sweep、loft、shell 分别可参考 `BRepOffsetAPI_MakePipeShell`、
  `BRepOffsetAPI_ThruSections` 和 shell builder 的调用边界、失败处理和 shape
  输出方式。
- boolean、fillet、chamfer 应参考其内核 `Modified`、`Generated`、`IsDeleted`
  的拓扑 delta 采集方式，落实本计划要求的 feature 输出角色和 selector 后继证据。
- transform 和 pattern 应作用于明确的 shape/body 输入，并保留每个实例的独立结果。

SimpleCADAPI 强制将 boolean 结果收敛为单个 `Solid`，不满足 CADFS 的多 body、
保留工具体、复制和 body 生命周期语义。实现时只能借鉴 OCP 调用与拓扑证据模型，
必须保留本项目的 CDSL schema、runtime adapter 和显式 body-result contract。

## Source Exception Evidence

工程重建失败必须先按下表归类。只有“已验证 source exception”能够从全量
成功分母移除；候选项仍是未完成样本，必须保留 source、CDSL、STEP 和比较工件。

| 分类 | 样本 | 当前证据 | 处理要求 |
| --- | --- | --- | --- |
| 已验证 source exception | 无 | 当前 17 样本没有已经证明可豁免的 source exception。 | 不得从验收分母移除。 |
| engine / converter 缺陷（受限路径已修复） | `00710855` | F5 的 CADFS IMPRINT cut 已由错误圆盘改为 `r=19..25.5 mm` 环。对于 F10，runtime 仅在显式同轴 surface shell 在 selected plane 提供内边界证据时，才以源 `width=10 mm` 构造受限圆锥倒角；完整 history 已可执行。 | 将该受限模式扩展为一般 surface/solid split、topology delta 和后继 selector；不得缩小源倒角宽度。 |
| source / STEP 精度候选 | `00710855` | 完整 history 的 surface 最大差为 `0.0035 mm`，面积、bbox 与实体数满足 strict；但 source F8 E14 是 `r=22 mm`，gold STEP 对应圆柱是 `r=21.9965 mm`，导致体积相对误差 `7.998e-5` 超过 strict。 | 保存 source literal 与 STEP 测量证据；未获得 source export 版本证明前不得回填 gold 半径，也不得从验收分母移除。 |
| source / STEP 差异候选 | `00035682` | FeatureScript 圆柱/孔径 literal 的精度低于原 STEP 的测量值；现有拓扑类型和数量相同，但严格体积/面积不一致。 | 保存原始精度证据；复核 source 导出版本后才能定为 exception。 |
| source / STEP 差异候选 | `00192744` | F3/F5 frame、`UP_TO_NEXT`、F7/F12 `COPY(BODY)` delete 及 F15 的 direct circular COPY multi-body transform 均已完整执行，零 runtime diagnostic。F15 将 F1/F5/F6 COPY 移动约 `-10000 mm` 后，未被选择的 source `NEW` members 留在原处；当前 rebuild 有 22 个实体、gold STEP 只有 1 个，面积误差约 `3.3%`，RP 失败。 | 保留 executable STEP 和 comparison；继续完成 fused/add、nested、linear/mirror COPY 与 boolean/dress-up 后继的完整 body lifecycle。不得从 gold STEP 回推 union、transform 参数或把 source `NEW` 改为 `ADD`。 |
| source / STEP 差异候选 | `00212904` | 原 STEP 出现 source FeatureScript history 未表达的正交 cut strip。 | 保留对比工件；除非 source 能提供缺失 feature，不得在 converter 伪造几何。 |
| source / STEP 精度候选 | `00287955` | 完整 history 已执行并达到 RP。source STEP 的 F1 顶面为 `z=8.128 mm`，FeatureScript 只有 `8.13 mm`；F3、F5/F6 和 F14 的后续面偏差累计到 `0.002-0.008 mm`，最终体积相对误差为 `1.793e-4`。 | 保留 CDSL 与比较工件；不得根据 source STEP 回填未在 FeatureScript 中出现的精确尺寸。 |
| source / STEP 拓扑候选 | `00542223` | 开放 B-spline F2 已作为 reference 草图完整 lower，完整 history 无诊断并重建为 `1` 个实体、`49775.5119 mm3`。source STEP 虽声明 `MANIFOLD_SOLID_BREP` / `CLOSED_SHELL`，OCC 却导入为 `TopAbs_SHELL`、`0 solids`，并报告 `BRepCheck_NotClosed`。 | 保留严格失败；需要可信 source STEP 或中间 B-rep 后，才能验证完整 shell/mixed-body 语义。 |
| source / STEP 精度候选 | `00835610` | 完整 history 可执行且 RP 通过，严格最大表面差约 `0.014 mm`；FeatureScript 值与 STEP 存在约 `0.014 mm` 的 literal 差异。 | 不能从 gold STEP 回填尺寸；继续标为严格失败，等待 source 版本证据。 |

## 全量完成门槛

在 17 样本工程通过后，按 capability family 对全量语料滚动运行，并按失败原因选择
新的最小代表样本。最终报告必须以扫描快照中的全部样本为分母，同时满足：

1. 每个有效源样本生成语义有效、可执行的 CDSL；`parse_failed`、
   `unsupported_operation`、`unsupported_engine_capability` 和因 converter 丢失
   feature 而导致的 `converted_partial` 均为零。
2. 每个拥有原始 STEP 的样本生成完整 `rebuild.step`；`rebuild_failed` 和
   `rebuild_timeout` 均为零。
3. 每个可比较样本以 RP 工程阈值通过比较；`comparison_timeout`、
   `comparison.json.decision = rejected` 和仅有可执行 STEP 的样本均不计入完成。
4. 任何合法 source exception 都有单独清单、原始证据和可复现原因；它不进入成功
   分母，也不得吞并为“未分类失败”。
5. 生成全量 capability-gap、比较汇总和逐样本证据，确保任一退化都可定位到
   converter、engine、源数据或比较基础设施。

17 个样本覆盖了已观察到的特征类别，但不是全量正确性的数学证明。只有滚动的
全量比较通过，才能声称完成全量重建。

## 每次修复的执行规则

1. 先重跑发生退化的代表样本，并读取 `history.json`、`candidate.cdsl.json`、
   `bound.cdsl.json`、`rebuild.json` 和 `comparison.json`。
2. 将问题归类为：CADFS parser/lowering 丢失或误译、CDSL schema/contract 无表达、
   engine/adapter 几何能力不足、selector/body 引用错误、源数据异常，或比较基础设施
   问题。证据不足时不得猜测分类。
3. 只在责任层修复：转换问题修改 CADFS lowering；执行问题扩展 engine；两者都涉及
   时分开提交证据和测试。保留最新可执行 STEP/GLB 和失败诊断。
4. 每项代码改动至少重跑受影响样本、17 样本工程回归和相应单元测试；能力状态与
   证据同步到本地能力台账。全量统计变化后重新生成 `regression/manifest.json`。
5. 不以关闭诊断、跳过 feature、用未说明的默认尺寸或放宽 RP 阈值换取通过；严格
   指标的变化必须作为诊断证据单独说明。

## 阶段交付物

| 阶段 | 必须交付 | 通过条件 |
| --- | --- | --- |
| R0：证据稳定 | 刷新的 regression manifest、17 份完整工件 | 每个样本可重复运行并可定位当前失败。 |
| R1：代表样本 | 17 个工程比较报告、能力台账更新 | `17/17 rp.passed`。 |
| R2：能力扩展 | 按能力 family 的 converter/engine/selector 实现及回归 | 对应缺口不再造成该 family 的失败。 |
| R3：全量验证 | 全量 CDSL、STEP、比较结果和汇总报告 | 满足“全量完成门槛”的五项条件。 |