# OCCT 几何出口与显示边界

2026-09-09 核对。用户要求是固定执行边界，不是新建另一套 CAD：OCCT WASM 已提供，几何算法统一到这一内核出口；Three.js 只负责显示，优先复用现成产物。

2026-09-12 强制补充：模型算法来源于 OCCT WASM 唯一接口。凡是权威几何、拓扑、布尔、曲面、网格化结果，必须有实际 OCCT WASM 调用链；FreeCAD WASM 只负责文档与特征语义，Three.js 不得生成权威模型。静态链接、WASM 文件存在或前端显示不构成调用链证明。

## 职责

| 层 | 必须负责 | 不得替代 |
|---|---|---|
| OCCT WASM | CAD 几何、拓扑、布尔、曲面及原生几何网格化 | 不新增第二套几何内核，不用前端近似结果冒充 |
| FreeCAD WASM | 桌面文档、对象、特征、约束、事务和格式业务适配，衔接 OCCT | 不把文档/对象语义删掉后换成固定模型 |
| Facade / Worker | 参数校验、路由、取消、错误、序列化和资源生命周期 | 不实现替代 CAD 算法，不跨独立 WASM 传原生指针 |
| Three.js | 显示 native 网格、材质、光照、相机、拾取、显示裁剪与高亮 | 不用 CSG、ExtrudeGeometry 等生成权威 CAD 结果 |
| React / OPFS | 交互编排 / 实际文档文件持久化 | 不用页面状态或 localStorage 元数据冒充 native 文档保存 |

显示用的 Vector、Box3、Raycaster、包围球计算不等于另建几何内核。显示裁剪不能冒充真实切割，显示网格不能冒充 BREP/特征树。TechDraw 原生二维 SVG 作为显示结果使用，不由浏览器重算投影几何。

## 已核对的实际链路

| 业务 | 当前执行链 | 显示边界 |
|---|---|---|
| 既有 STEP 查看 | `main.ts` → `kernel.worker.ts` → `FreeCADWebKernel` → `FreeCADWebBridge.cpp` 的 OCCT STEP/BRep/网格化 | native positions/normals → BufferGeometry |
| 默认工作区文档 | `project-shell.tsx` → 模块路由 → `part-save.worker.ts` → `DocumentProbe` → FreeCAD Part/OCCT | `documentObjectMesh` 校验并打包 native 网格，Three.js 显示 |
| Part 参数业务 | `part-facade.ts` → `part.worker.ts` → `PartBoxProbe` → 原生 Part/OCCT | 结果、体积由 native 返回，不由 JS 尺寸乘积充当计算结果 |
| TechDraw 当前文档 | 生成路由 → 同一 `techdraw-python.worker.ts` → 已有 TechDraw runtime/OCCT 依赖 | native SVG/图像显示；创建、任务、保存不跨文档实例 |

现成 `web/public/kernel/FreeCADWebKernel.js` 为 165701 字节，`.wasm` 为 15206151 字节。本次检查了存在性、WASM 文件头及对应源码调用，没有重新编译或上传源码。现有模块 manifest 和已核对的构建目录仍是唯一产物选择依据，不新增重复注册表。

## 当前不能宣称的部分

- 当前架构有多个独立模块 WASM。复用同一 OCCT 技术与拥有同一个统一运行实例是两回事，不能仅凭静态链接就宣称所有几何入口已经统一。
- Mesh/STL 等路径还含 FreeCAD 原生 Mesh 读写或格式适配。必须按真实业务区分解析/适配与几何计算，核对实际 OCCT 调用和序列化交接；不能先删除这些已完成实现或以格式转换损失替代原生语义。
- 不强行拼接已编译 WASM，不擅自切换共享内存/side-module 架构。未核对的入口保留待贯通状态，后续只补明确缺口。

## 构建检查

`cd web` 后运行 `npm run check:geometry-boundary`；`npm run build` 的 `prebuild` 自动执行相同检查。

- 用 TypeScript AST 检查 `web/src` 中的 TS/TSX/JS 模块；当前 364 个文件。
- Three.js 的运行时导入只允许在已核对的四个显示文件中；新增显示文件须先核对职责，再调整检查白名单。
- 拦截已知前端 CSG/替代内核导入及 Three.js 实体/拉伸造型构造器；相机、拾取、材质和 native BufferGeometry 保留。
- 缺少现成内核文件或 WASM 文件头不正确时失败，不自动重新编译内核。

本次检查无命中，耗时 0.371 秒；7 项正反例测试通过。检查报告显式保留 `singleRuntimeVerified: false`。静态检查不是完整调用图证明，不能排除所有动态生成代码或任意手写数学旁路，不能计作新增业务完成。具体业务仍需实际输入、原生调用、错误/取消和结果验证。

## 后续执行

每个几何业务工作包列明：现成产物、Facade/Worker、真实 native/OCCT 入口、对象归属、结果和显示消费位置。优先用既有实现和有效证据；缺接线补接线，缺断言补必要断言。只有产物缺失、相关依赖变化或原生首错要求修复时，才增量构建受影响模块。

复用规则和实际业务解阻证据分别见 `WEB_BUSINESS_MIGRATION_RULES.md`、`current/part-mesh-business-unblock.md`、`current/techdraw-route-unblock.md`。历史报告或检查通过不得覆盖用户的唯一几何出口要求。