115 lines
18 KiB
Markdown
115 lines
18 KiB
Markdown
# FreeCAD Web 功能业务移植铁律
|
||
|
||
## 2026-09-11 最新用户执行优先级
|
||
|
||
用户铁律原文：**全部功能先打通，现在不需要验证，等待用户使用时自己验证。** 本条覆盖下文历史的自动验收与验证优先安排，适用于人工执行、无人值守、重启及上下文续接；未经用户新的明确要求，不得恢复自动验证。
|
||
|
||
- 当前阶段只做既有成果复用、功能实现/接线、必要的增量编译链接、资源同步及路由生成；不自动运行或编写业务验收、回归、浏览器、性能及历史对账任务。
|
||
- 已有测试、验收证据、源码、WASM 和缓存全部保留，但验收失效不得重新占用功能实施队列；测试交给用户使用阶段决定。
|
||
- 接通完成记为 `implementation_ready` 或“待用户验证”，绝不伪造 `acceptance passed`。当前进度以实际接线和产物为主，历史验收比例不作为本阶段停止条件。
|
||
- 运行策略持久化在 `docs/current/execution-policy.json`；同模块共享调用链集中补齐，一次必要增量编译，不反复验证或重做已完成工作。
|
||
|
||
技术路线固定为用户此前已采用的 **OCCT WASM、FreeCAD WASM、Three.js、OPFS、React**。复用现有几何内核、原生文档能力、三维显示、浏览器文件存储和交互组件，不另换路线。计算与文档语义在 WASM 内执行，Three.js 显示、React 交互，实际文档文件由 OPFS 持久化；localStorage 元数据不能冒充 OPFS 文件保存。
|
||
|
||
职责、已核对调用链、当前未统一部分和构建检查集中在 `docs/OCCT_GEOMETRY_BOUNDARY.md`。前端构建必须执行 `npm run check:geometry-boundary`，禁止把静态检查通过当作全项目唯一运行实例已完成；未贯通的真实几何入口继续保留并修复。
|
||
|
||
2026-09-09 用户再次明确：**几何内核使用 OCCT WASM，三维显示使用 Three.js**。FreeCAD WASM 承载桌面文档、特征、约束及业务接口，并复用现有 OCCT 几何能力；不得用 Three.js 网格操作替代 CAD 内核语义。STL 读写优先复用现成 OCCT 能力，按既有功能边界接入；已链接到 FreeCAD WASM 的 OCCT 仍属于这条路线，不为名称区分重复加载独立内核或跨 WASM 传裸指针。
|
||
|
||
2026-09-08 梳理：本文件是项目铁律的统一入口，适用于人工、无人值守及优化回合。执行优先级为：用户最新明确要求、本文件、已制定方案的具体操作步骤、历史任务卡与报告。旧提示词、旧任务卡及统计口径不得覆盖用户要求；遇到冲突先按这一顺序核对，不另起一套方案。
|
||
|
||
开始任务及上下文恢复时先核对本文件和当前检查点，明确本轮复用什么、真正缺什么、准备执行什么。主线是把桌面 FreeCAD 移植到 Web FreeCAD，以实际功能及路由推进，不是重复建设调度系统或逐 API 排队。
|
||
|
||
## 现有 WASM 与本地执行优先铁律
|
||
|
||
2026-09-09 用户明确要求：**“牢记 OCCT WASM 已经提供了，尽量利用上。”** OCCT WASM 已提供是跨回合、重启和无人值守续接必须保留的既定事实。先从现有模块 manifest、`web/public/kernel` 和已核对的构建目录复用实际 OCCT 产物及既有绑定；不得重新索要、另换内核、重复实现几何算法，或仅因缺少新验收记录而重新编译。只有相关产物确实缺失、输入依赖改变或原生首错明确要求修复时，才增量处理受影响目标。
|
||
|
||
2026-09-09 用户追加铁律：**“OCCT WASM 已经提供了，几何算法要统一到这个唯一出口，这个环节要打通，并且充分利用上。”** 几何运算以已提供的 OCCT WASM 为唯一内核出口，接通现有页面/Facade/Worker 到实际 OCCT 运算和结果返回的链路；FreeCAD 的文档与特征语义保留，Three.js 只负责显示。不得新增平行几何内核、用前端算法或固定网格替代，也不得把静态链接关系当作全部入口已经统一的证明。独立模块的内存、原生对象归属和序列化交接必须核对，唯一出口的实际贯通情况按真实调用与结果逐项确认。
|
||
|
||
2026-09-12 用户再次明确：**“铁律：模型算法，来源于 occt wasm 唯一接口。”** 本条是几何实现的强制归属规则：任何模型算法、拓扑运算、布尔、曲面处理、网格化及其权威结果，必须通过已经提供的 OCCT WASM 唯一接口；FreeCAD WASM 只承载文档/特征/事务语义并衔接该出口，Three.js 只显示 native 结果。禁止以 Three.js CSG、前端数学、固定网格、Assimp 或另一个独立几何库替代，也禁止仅凭“链接 OCCT”或“编译成 WASM”宣称已经接通。发现旁路时，先回接现有 OCCT 接口；若接口缺失，记录真实依赖缺口，不用占位结果绕过。
|
||
|
||
2026-09-08 用户明确：“不需要把源码提交给你，在本地编译连接测试就可以的。”“大部分源码，我已经编译完成 wasm 了，你直接利用就可以了。” 已编译的 WASM 是当前执行起点，不能把已有移植当作未开始。
|
||
|
||
- 先使用 `web/public/modules/manifest.json` 中实际命令路由对应的现成 runtime/WASM，以及 `web/public/kernel`、`freecad-source/build-web` 的既有产物。直接接入现有 Worker/Facade、页面和针对性测试；不先重新分析或编译桌面源码。
|
||
- 已有产物和证据的输入指纹未变时直接复用。构建系统的依赖检查不等同于重新编译；保留必要检查，但不得以缺少新的回执、切换任务或新开模型会话为由重新链接。
|
||
- 仅在产物缺失、相关源码或依赖实际改变、或运行首错确认必须修改 native 实现时，增量构建受影响目标；纯前端接线和缺失业务用例不重建未变化的 WASM。
|
||
- 编译、链接与针对性测试在本机完成，不要求用户重新提交或上传源码，不以模型重审或远程仓库推送为执行前置。已有命令可直接执行时由本地流水线完成；源码只用于定位明确缺口和必要修复，不转储整库源码或完整日志。
|
||
- 必要源码片段被模型读取时仍会进入模型上下文；本地构建不意味着模型完全离线或片段零传输。不得把“无需用户提交源码”误报成此类保证。
|
||
- 现成 WASM 是可复用成果，业务结果仍按真实输入和实际执行确认；不得因缺少验收而否认产物，也不得仅凭产物存在宣称全部业务完成。
|
||
|
||
## DXF 使用已有 C++ 实现
|
||
|
||
用户已明确：DXF 已经移植完成，FreeCAD 源码中已有 DXF 的 C++ 源码，直接使用用户提供的实现与编译成果。
|
||
|
||
- 已确认源码为 `freecad-source/src/Mod/Import/App/dxf/ImpExpDxf.cpp`、`ImpExpDxf.h`、`dxf.cpp`、`dxf.h`，读写实现包括 `ImpExpDxfRead`、`ImpExpDxfWrite`。优先复用承载它们的现有 WASM，不重新编写 DXF 解析器、导出器或另做 Python 版移植。
|
||
- `AppImportPy.cpp` 的 `Import.readDXF` / `Import.writeDXFObject` 是 C++ 实现的调用绑定；不能因上层出现 Python 入口，就把已有 C++ 底层误判为缺失，更不能反复寻找旧 Python DXF 库。
|
||
- 复用 `docs/business-acceptance/Draft.json`、`tools/draft-business-cases.mjs` 与 `docs/current/business-acceptance.json` 中有效证据。DXF 的已完成实现不再作为新算法移植任务排队；其它工作台若缺少入口，只补其接线，不重做底层读写。
|
||
- 只有明确受影响的运行路径、输入、产物变化或新的真实故障，才重新确认相应业务。重复验收不是新增功能，重复刷新回执或证据不能计作新交付；已完成记录不得为刷新统计而重开。
|
||
|
||
## 项目定位与已有成果复用铁律
|
||
|
||
用户于 2026-09-08 明确要求：**“本项目是将桌面版的 FreeCAD 移植到 WEB FreeCAD，前期已经做了大部分工作，要充分利用上。”** 这是所有后续实现、优化和续接的既定前提，不是从零开发另一套 CAD。
|
||
|
||
- 以用户提供的桌面版 FreeCAD 源码和资料为业务语义依据，继续移植到 Web FreeCAD；不得用重新发明的简化算法、固定样例或模拟结果替代已有 FreeCAD 实现。
|
||
- 开始任务前先核对并复用前期已完成的桌面源码移植、原生适配、模块 WASM、增量构建目录、依赖、缓存、Facade、Worker、页面接线、用例和有效证据。入口为 `docs/current/provided-source-index.md`，已核对且指纹未变的结果直接沿用。
|
||
- 已有实现可用则接通并复用；已有功能但缺少证据则补必要用例；接口不一致则定点补接线；确有缺陷则修改受影响部分。只有确认不存在可复用实现后才新增，不得无依据推倒重来、重复扫描、重复编译或重复验证。
|
||
- “尚未取得当前业务验收证据”不等于“前期没有完成工作”。源码实现、接线、构建产物和实际业务结果分别记账；既不抹掉前期成果，也不把已有回执直接当成全部功能通过。
|
||
- 每次修复和移植应记录复用的实际路径或证据、具体剩余缺口、本次改动及实际结果；把执行时间用于补齐缺口，不能以重新分析或重复建设代替推进。
|
||
|
||
## 源码与资料优先铁律
|
||
|
||
用户于 2026-09-08 明确要求：“先搜索我提供的 FreeCAD 的源程序和相关资料”。本条适用于人工协作、无人值守业务批次及每 30 分钟的优化任务。
|
||
|
||
用户已明确确认：**“我已经提供了桌面版 FreeCAD 的源码和资料。”** 这是项目的既定前提，跨会话、重启及上下文续接均必须保留，不得重新假定用户尚未提供。
|
||
|
||
- 先复用已有 WASM、接线与有效证据；只有定位具体缺口需要源码时，才定点搜索用户已提供的 FreeCAD 源程序、依赖和资料。源码是修复依据，不是每轮重新审阅、重新编译的前置任务。
|
||
- 本地资料入口为 `docs/current/provided-source-index.md`；桌面源码主目录为 `freecad-source`。先核对索引、实际路径、相关符号和版本，不得把路径写错、一次搜索无匹配或尚未检索解释为“用户未提供源码或资料”，不得据此重复索要、空等或从零重写。
|
||
- 优先复用当前项目 `freecad-source/src`、`FreeCADBaseLib/sources`、`docs`、`tools`、`web/src` 和现有 `freecad-source/build-web` 产物。用户提供的其它本地源码与资料按已确认的目录索引继续查找。
|
||
- 已核对且指纹未变的搜索结果直接复用，记录实际路径、关键符号和发现；不得每回合重复全量扫描，也不得把路径猜错或未检索到当作源码不存在。
|
||
- 本地实现已有的，先移植或接通现有实现；本地资料不足的，先说明检查范围和具体缺口，再定向查找官方外部资料。不得跳过用户提供的源码而重新发明实现或先依赖外部搜索。
|
||
- 搜索始终服务于当前功能模块业务和功能路由，不扩大为逐 API 清查。验收失败回到对应业务修复，不能用固定样例、摘要或静态成功标记代替实际业务结果。
|
||
- 发现可在已授权项目范围内解决的问题，必须及时利用本地源码和资料定点修复，并核对实际构建或业务结果；不得只监测、登记瓶颈、调整重试参数或反复等待。外部服务异常与本地可执行工作分别处理，不能据此声称本地源码不可用。
|
||
|
||
## 完成定义
|
||
|
||
- 主线只有用户业务及其功能路由。Python API、对象、工作台、GUI、格式和依赖均由对应业务需要驱动落地，不建立逐 API 移植队列。
|
||
- 846/791 是旧清单规模，不是固定上限。遗漏的桌面命令、菜单、工具栏、格式和交互必须映射到业务记录；发现遗漏就补充，禁止通过缩小分母取得满分。
|
||
- 分开记录路由接通、实现/构建回执、业务完成。只有真实输入、当前文档状态和 FreeCAD WASM 运算产生正确结果，才能确认对应业务完成。只返回固定 fixture、参数回显、摘要、状态字符串或空成功不能算完成。
|
||
- 业务结果确认仅覆盖当前业务及其共享执行链；不启动全量 API、历史 Full Parity 或无关测试。已有业务证据与源码、产物匹配时直接复用；失效只重开受影响模块。
|
||
- 历史实现回执、源码、构建目录、WASM/data、缓存、可用 Facade/Worker 和业务用例全部保留。缺少业务证据不等于从零重写；先复用和补接线，最后才新增实现。
|
||
|
||
## 持续执行顺序
|
||
|
||
1. 承接当前检查点，先修直接阻断当前业务的真实问题；有效的已有结果直接沿用，不重新领取已完成项。
|
||
2. 按已定交付顺序贯通工作区、Document、Part、Sketcher、PartDesign 和文件业务，再推进工程工作台及其余完整范围。模块独立、业务成组，不退回逐 API 队列；优先子集不得替代全部迁移范围。
|
||
3. 使用用户文件、实际选中对象和当前文档贯通导入、编辑、重算、保存、重开、导出，以及树/属性/选择/视图、撤销重做、错误和取消。不得用临时固定样例替代用户文档。
|
||
4. 已有用例直接在本机执行或复用有效结果；缺接线则补接线，缺用例则补必要断言，发现 native 缺陷才修改对应 C++/Python 实现。实现与必要业务确认交替推进，不为验收重复重建未变化的 WASM。
|
||
|
||
## 效率与边界
|
||
|
||
- 2026-09-09 用户要求将本次解阻经验应用于后续移植。所有后续工作包遵守 `docs/UNATTENDED_WORKFLOW.md` 的“业务解阻固定流程”：复用本机成果，最小失败输入，原生阶段计时，按证据检查线程/事件循环/GIL，修共用入口，受影响目标增量构建，再确认相关组并复用有效证据。禁止仅增大超时/线程池、重跑原失败大组或重新实现已有算法；Part/Mesh 已通过结果见 `docs/current/part-mesh-business-unblock.md`，不得据此假定其它模块全部通过。
|
||
|
||
- 同模块同执行模型成批修改，共享 native dispatcher、Facade/Worker 和参数 schema；相关改动合并一次增量构建/链接。
|
||
- 模块专属的桌面命令参数、回执校验和选择同步放入已接通的 `web/src/<module>-desktop-adapter.ts`；当前 Part、TechDraw 已有适配器，直接复用。只有真实共用协议缺陷或首次接线才改共用 `desktop-command-dispatcher.ts`，避免单模块修改让全部有效证据反复失效；不能通过取消指纹校验掩盖真实共用变更。
|
||
- WASM 按模块动态加载，使用统一 `{cmd,args}` / `fc_web_dispatch_json` 与现有 Facade/Worker。页面和其它模块保持运行，只替换受影响 Worker；同一 revision 的 JS/WASM/data 配套使用，替换前处理取消与资源释放。不得逐命令建立 WASM，也不得合成单体 WASM。
|
||
- 2026-09-09 用户补充：按功能模块独立编译 WASM，根据需要预加载。直接沿用 `docs/WEB_WASM_INCREMENTAL_MODULARIZATION.md`、现有模块 manifest 和预加载入口；仅预取当前业务将使用的模块，地址去重、下载并发上限 2，缓存预取与 Worker/原生运行时初始化分别计时。已有产物不重编译，首屏不预加载全部模块；跨独立 WASM 不传递原生指针。
|
||
- 后台计算、几何、约束、文档和持久化由移植的 FreeCAD C++/Python 在 WASM 内执行；React/TypeScript 负责交互和编排。
|
||
- 失败只修当前业务首错，保留成功产物。历史失败不得无差别重放；直接关联当前业务的失败随批次修复，其余保留分类和最终对账。能在本地解决的应及时解决，不能只监测或用冷却、重启冒充修复。
|
||
- 不删除历史回执、不伪造验收、不仅删除保护判断就宣称功能完成；保护解除前必须确认实际 Worker/native contract 可执行。
|
||
- 调度器持续领取模块业务包，直到业务清单全部闭合。停止、额度耗尽、环境错误和暂时无任务必须如实显示，不得解释为全部移植完成。
|
||
- 无人值守自动修复：续接保留批次、预检和启动入口共同排除冷却业务；watchdog 独立检测违反冷却规则的新回合，记录恢复请求并在工具结束后重启、重排。已知调度故障自动处理，未知业务语义缺口继续按原业务排队，禁止以重启冒充实现进展。
|
||
|
||
## 上下文、耗时和进度
|
||
|
||
- 上下文只带当前批次、必要路径/指纹/片段、首错、剩余问题和下一步；全文、历史和构建日志留在磁盘。默认提示词上限 24000 UTF-8 字节，按完整字段和源码行选取；不能把回合累计输入 token 当作单次请求上下文，也不能因换会话重复全库检索。
|
||
- 逐步记录准备、读取、模型/接口等待、编辑、编译、链接、同步和测试耗时。事件间隔不是纯本地计算时间；发现高耗时步骤后要解决具体原因，不无限增加统计和规则文档。
|
||
- 已有实现、WASM、路由、业务验收分别汇报。重复通过、证据刷新、任务切换、文档更新及调度轮数不是新增业务交付；验收比例也不能冒充全部源码移植完成度。
|
||
- 当前业务做针对性本地测试，不在每个小批次重复全量 API、Full Parity、浏览器矩阵或无关历史测试。全量收口按既定方案和用户指令执行；不伪造通过，不删除失败或已有成果。
|
||
|
||
## 业务结果合同
|
||
|
||
`docs/business-acceptance/<Module>.json` 声明一个模块的复用用例入口：`{"command":["node","tools/<module>-business-cases.mjs"]}`，也可使用项目内 Python 脚本。入口通过 `FREECAD_BUSINESS_IDS` 只执行当前批次。
|
||
|
||
脚本 stdout 输出一个 JSON 对象：`{"schema":"freecad-web-business-cases/v1","results":[{"capabilityId":"<业务 ID>","status":"passed","cases":[{"input":{},"assertions":[{"name":"实际结果断言","passed":true}]}]}]}`。`input` 必须记录实际请求，断言必须检查运行结果；不得直接写常量通过。计算业务必须执行真实 WASM；UI 业务必须操作真实页面。可复用已有脚本及 fixture，但必须证明当前业务语义，不能用模块 smoke 覆盖整个模块。
|
||
|
||
外层运行 `tools/run_business_acceptance.py`，保存执行命令、输入/断言、源码/产物指纹及证据哈希。只有该证据有效时业务进入完成计数。实现阶段的构建回执继续独立保留。
|