Files

wangdequan 9a7c4f0335 Save FreeCAD Web workspace sources and user validation evidence

IFC native binding remains incomplete; preserve accurate test results.

2026-09-15 22:01:58 +08:00

5.6 KiB

Raw Blame History

FreeCAD Web Python API 源符号追踪路线

2026-09-06：本文件保留为源码追踪与后置审计参考。当前实现主线已切换为 WEB_IMPLEMENTATION_FIRST_STRATEGY.md 的用户功能链优先模式；不得再把 13,385/13,386 个符号逐条 gate 当作功能移植队列。

目标与边界

FreeCAD 当前 .py/.pyi 源码 inventory 有 13,385 条 Python API 记录（class 2,053、function 2,380、method 8,952，覆盖 29 个模块）；manifest 另含一个来自 C++ binding 的 Part.makeBox，所以追踪总数为 13,386。该数字不是用户功能数。后置审计可让每条记录最终获得 exposed、restricted、nonportable 或 not_implemented 结论，但不能阻断当前功能实现。

这条路线不为每个 API 手写一个 React facade。inventory 负责逐条可追溯性，生成 manifest 负责稳定身份与分类，少量运行时 adapter family 负责实际转换和调度。

去重与分层

tools/generate_python_api_manifest.py 从 docs/format-api-inventory.json 生成 docs/p6/python-api-manifest.json。稳定身份是 module + kind + fully-qualified name；源码路径和行号只作证据，不能导致重复绑定。重载或同一操作的差异保留在签名证据中，统一进入同一个家族 adapter。

当前 manifest 将所有记录压缩到有限的可复用家族：geometry-value、pure-function、property、document-graph、lifecycle-command、serialization、view-resource、gui-external 和 generic-object。家族只是生成/测试路由，不是完成状态；每条记录初始 disposition=planned，不得据此宣称已移植。

运行时层级固定为：

层级	处理内容	复用单元
Tier 0 substrate	Python/WASM 值、序列、异常、Document handle、取消和资源生命周期	一个转换与错误 ABI
Tier 1 readonly	类注册、常量、getter、资源和只读查询	生成 schema + 只读 dispatch
Tier 2 pure	无文档副作用的函数、几何/值计算	类型转换器 + 纯函数 dispatch
Tier 3 stateful	Document、Property、链接、重算、事务、序列化和命令	Document actor + 事务 adapter
Tier 4 restricted	GUI/PySide/Pivy、桌面动态模块、外部进程或浏览器禁止的 I/O	capability policy；`restricted`/`nonportable`/`not_implemented`

生成式流水线

源码 inventory
  -> normalize (stable id, name/kind/module)
  -> dedupe (exact key; retain evidence)
  -> family/tier classification
  -> generated manifest + TypeScript schema + dispatch tables
  -> one Python/WASM Worker batch request
  -> native execution + typed result/error envelope
  -> differential/replay fixtures
  -> disposition gate and release ledger

前端每次请求使用统一 envelope：requestId、apiId[]、args、documentId、capabilities、signal。同一 Worker 批量执行一组调用，共享一次解释器/原生上下文；禁止“一 API 一页面”或“一 API 一 Worker”。批量边界按事务和取消点切分，错误以 apiId 粒度返回，后续调用不会吞掉前一调用的异常。

生成物必须包含：

canonical API manifest（逐条 id、家族、层级、源码证据和 disposition）；
TypeScript 参数/返回值 schema、权限表和按家族分组的 dispatch；
C/C++/Python-WASM trampoline 的统一值转换、异常、取消和资源释放 ABI；
每个家族一组参数边界、错误语义、重放和内存释放测试；不是每个符号一套手工测试代码。

执行顺序

冻结输入：记录 inventory SHA-256、FreeCAD revision、manifest schema version；输入变更就重新生成，禁止编辑生成 JSON。
完成 substrate 和 Document actor：先让 Tier 0/3 的 handle、属性、事务、重算、Undo/Redo、恢复可批量调用，这是最多 API 的共享依赖。
生成 Tier 1/2：按模块和 adapter family 生成 dispatch，优先覆盖只读与纯函数；每个生成批次附 source path/line 证据。
实现权限策略：Tier 4 在 manifest 中逐条给出 restricted、nonportable 或 not_implemented 原因；不能用静态 JS 值冒充执行。
差分与回放：同一 fixture 在 desktop Python 与 Web Python/WASM 执行，比较类型、数值容差、文档 diff、异常类别、取消点和资源计数；失败保留最小重放包。
发布门槛：只有 13,385 条记录全部离开 planned，且生成 hash、权限审计、Chrome worker 回放和内存释放 gate 通过，FPA-F 才能关闭。

不重复的工程规则

不复制模块级 facade 逻辑；facade 只负责 envelope、批处理、取消和错误映射。
不把 path/line 当 API 身份；同名重载必须进入同一家族并携带签名证据。
不为每条 API 单独启动 Python；一个 Worker/actor 承载批次和事务边界。
不为每个 API 写重复测试；测试按转换器、家族、权限策略和代表性签名参数化生成。
缓存键必须包含 sourceRevision + inventorySha256 + manifestSha256 + runtimeAbi + schemaVersion，防止旧 binding 混入新源码。
任何未分类、无签名或无结果证据的记录保持 planned，直接阻止完整对标出口。

当前证据与下一步

当前生成器已经核对 13,385 条记录的精确键重复数，并写出逐条 manifest；这完成了 FPA-A 的 API 路线冻结，不代表 FPA-F 已完成。FPA-B/C 先提供 React 核心壳层、Document actor 和事务合同；随后 FPA-F 按 manifest 的 Tier 0 -> 1/2 -> 3/4 顺序实现，并以家族级差分回放收口。

5.6 KiB Raw Blame History Unescape Escape