跳到主要内容

版本与迁移

CadFlow 0.1.0 当前为 Alpha。公共 API 已有文档和测试，但在稳定版前仍可能发生签名或 Schema 的不兼容变化。

固定并记录​

固定创建交付物时使用的精确 Python Package 与原生库 Build，并记录：

  • CadFlow 版本与源码 Revision；
  • 平台和原生 Backend Capability；
  • 输入资源 Hash；
  • 参数值与单位制；
  • Model JSON 或领域 JSON Schema Version；
  • 终端 Result ID 与输出 Artifact Hash。

升级顺序​

  1. 针对候选运行时重新生成或检查 API 参考。
  2. 审阅 static/api-reference-manifest.json 中新增、删除与变化的签名。
  3. 只导入现有序列化产物，暂不执行。
  4. 通过有文档的公共函数迁移带版本 Schema。
  5. 在隔离环境中严格重放。
  6. 对比终端几何、拓扑、尺寸、语义与产物。
  7. 验收证据通过后再更新版本固定。

签名漂移门禁​

在文档仓库中使用兼容 CadFlow 环境运行：

PYTHONPATH=../CadFlow/python python scripts/generate_api_reference.py --check

当生成页、公共导入、签名、领域、别名或中英文文件集合与已提交参考不一致时，检查会失败。审阅运行时变化后，不带 --check 运行即可重新生成。

序列化 Schema​

Model JSON、Scene Package、Physical Layer 与 Simulation Model 带有 Schema 身份或版本元数据。不要用临时字符串替换修改其 JSON。应通过公共 Importer 解析，转换类型化或结构化数据，再通过公共 Serializer 导出并重新验证。

非严格重放是诊断和迁移工具，不能作为产物保持等价的证据。迁移必须以严格重放和领域对比结束。

弃用处理​

公共别名被弃用时，应在移除旧版本固定前，把调用迁移到推荐 Canonical Import。即使公共函数和私有实现当前解析为同一对象，也不要用私有导入替代公共函数。