FreeCADWasmDev/docs/WEB_BUSINESS_MIGRATION_RULES.md

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，保存执行命令、输入/断言、源码/产物指纹及证据哈希。只有该证据有效时业务进入完成计数。实现阶段的构建回执继续独立保留。