Files
ViewDesignEngine/docs/design/module-packaging-split.md

58 KiB
Raw Permalink Blame History

官方模块拆仓可行性研究 + render 先导 PoC(P3-15)

日期:2026-10-29 · 状态:render PoC 已通过(main @ task-70) · 相关:architecture §7.9、 roadmap P3-15、VDE-1250/1251/1252 嵌入式反馈。 结论:官方模块已具备“同仓模块化 + 独立 install/export 包”条件;render 作为最小先导 已验证 find_package(vde-render) · vde::render + vde::kernel 独立 consumer 构建/运行; 2 处内核内 bridge TU 已于 P3-15c 迁移完成(vde_ui/vde_pdm 实现+规范头+内核兼容转发头); 剩余为各模块包规则与 consumer(P3-15e,低风险、可增量)。

1. 目标与范围

按微内核定位把官方模块(render/drafting/ui/pdm/mechanism,后续 cam/cae 与内核内的 assembly/PMI/钣金)从“同仓 target”推进到“可独立安装/发布/拆仓”的模块包:

  • 模块包 = 静态库 + 公共头 include/vde_<module>/ + CMake 包(find_package(vde-<module>), target vde::<module>),依赖内核包 vde-kernel(find_dependency);
  • 不改变默认构建/聚合行为:默认仍构建全部模块,vde::app 聚合保持兼容;
  • 拆仓后同一版本线(monorepo 同 tag),模块包与 kernel 包同 prefix 安装协同。

2. 审计方法与数据(2026-10-29,main)

审计维度:CMake 依赖表(VDE_DEPS_<module>)、公共头 Loc/文件数、源 Loc/文件数、 头文件交叉 include、内核源码 ↔ 模块头引用、安装/导出路径。

模块 CMake target 依赖(VDE_DEPS) 公共头 源 拆仓阻碍
render vde_render / vde::render brep;curves 8 文件 / 1445 行 6 文件 / 872 行 无(本任务 PoC 已通)
drafting vde_drafting brep 4 / 1705 3 / 1641 需模块包规则;无内核反向依赖
ui vde_ui brep 4 / 673 3 / 1218 内核内 bridge src/brep/geometric_snap.cpp 引用 vde_ui/
pdm vde_pdm brep;mesh 4 / 696 3 / 1248 内核内 bridge src/brep/structural_profiles.cpp 引用 vde_pdm/
mechanism vde_mechanism brep 2 / 470 2 / 662 需模块包规则;无内核反向依赖

边界扫描结果(全部通过):

  • 模块公共头之间 0 交叉 include(仅依赖 include/vde/... 内核头与 vde_platform 基础头);
  • 内核公共头 0 处 include 官方模块头(方向正确:kernel → 业务模块不存在);
  • 内核源码 include 官方模块头仅 2 处 bridge TU(均在 vde_brep target 内):
    1. src/brep/geometric_snap.cpp → #include "vde_ui/geometric_snap_ui.h"(吸附 UI 桥);
    2. src/brep/structural_profiles.cpp → #include "vde_pdm/structural_profile_catalog.h"(结构型材目录桥); 另有旧 include/vde_drafting/pmi_export.h 转发到 vde_pmi 规范头(task-129;属应用层,符合分层;旧头消费者需同时安装 vde-pmi 包);
  • 上述 2 处为编译期头耦合、无 link 依赖(已登记 cmake/check_kernel_boundary.cmake 技术债 allowlist)。

3. 模块包约定(拆仓契约)

  1. 包名/target:vde-<module> / vde::<module>;export 不含 kernel 具体 target, 只通过 $<INSTALL_INTERFACE:vde::kernel> 暴露内核依赖(与 VDE-1250 Eigen 处理同思路, 避免跨 export set 引用 kernel 内部 target);
  2. config:先 find_dependency(vde-kernel CONFIG REQUIRED),再加载 vde-<module>-targets.cmake;版本文件 SameMajorVersion,与内核同版本线;
  3. 安装布局:<prefix>/lib/libvde_<module>.a、<prefix>/include/vde_<module>/*.h、 <prefix>/lib/cmake/vde-<module>/;内核头/库由 vde-kernel 包提供(同 prefix);
  4. 兼容:默认 monorepo 构建与 vde::app 聚合不变(模块仍作为其组件);模块包只是新增 独立消费路径,不移除旧 target/头路径;C++ ABI 仅保证同编译器/同 CRT/同版本(静态库); 模块级 C ABI 留待后续(参照 io_capi 拆分模式);
  5. 版本/发布:拆仓前 monorepo 同 tag 构建;拆仓后模块仓 pin 内核版本(兼容矩阵入 CI)。

4. render 先导 PoC(已完成)

为什么选 render:依赖少(brep/curves)、无跨模块状态、公共头小(8 文件)、构建快、 消费场景明确(视口布局/剖视/边线样式)。

实现(根 CMakeLists.txt 内核 SDK 安装段内新增,受 VDE_INSTALL/VDE_INSTALL_SDK 控制):

# vde_render 导出为 vde::render;build 接口保持现有内核依赖,安装接口只暴露 vde::kernel
set_target_properties(vde_render PROPERTIES
    EXPORT_NAME render
    INTERFACE_LINK_LIBRARIES
        "$<BUILD_INTERFACE:vde_brep>;$<BUILD_INTERFACE:vde_curves>;$<BUILD_INTERFACE:vde_compile_options>;$<INSTALL_INTERFACE:vde::kernel>")
install(TARGETS vde_render EXPORT vde-render-targets ...)
install(DIRECTORY include/vde_render/ DESTINATION include/vde_render ...)
install(EXPORT vde-render-targets NAMESPACE vde:: DESTINATION lib/cmake/vde-render ...)
# vde-renderConfig.cmake:find_dependency(vde-kernel CONFIG REQUIRED) + include targets

安装产物实测(build-fb-split/install):

  • lib/cmake/vde-render/{vde-renderConfig,vde-renderConfigVersion,vde-render-targets*}.cmake;
  • lib/libvde_render.a + include/vde_render/*.h(8 个);与 vde-kernel 包同 prefix(14 个内核/平台库);
  • exported targets 中 INTERFACE_LINK_LIBRARIES "@vde::kernel",Config 中 find_dependency(vde-kernel CONFIG REQUIRED);
  • configure 输出 VDE P3-15: vde-render package install/export enabled。

独立 consumer(build-fb-split/consumer,只 find_package、不 add_subdirectory):

  • CMake:find_package(vde-render CONFIG REQUIRED) + find_package(vde-kernel CONFIG REQUIRED), target_link_libraries(... vde::render vde::kernel);
  • 运行:内核 create box → render 视口布局/剖视 API;
  • 结果:RENDER_CONSUMER_PASS faces=6 volume=6000.0 viewports=1 section=0 planes=1 fov=45.0。

默认构建不受影响:build-fb-split 默认全量 build 0 error;ctest 子集 (Render|KernelAggregate|DependencyDirection|Capi)81/81 PASS;vde::app 聚合与既有 target 关系未变(render 仍为 vde_app 组件)。

5. 后续拆分顺序与阻碍处置

阶段 模块 动作 预估风险
P1(先导) render 已完成(install/export + consumer) 低
P1 drafting / mechanism 复制 render 包规则;无内核桥 → 直接可拆 低
P1 ui 已完成(P3-15c):src/brep/geometric_snap.cpp(+依赖 snap_ext.cpp)迁入 vde_ui;规范头 include/vde_ui/ + 内核兼容转发头 中
P1 pdm 已完成(P3-15c):src/brep/structural_profiles.cpp 迁入 vde_pdm;规范头 include/vde_pdm/ + 内核兼容转发头 中
P2 cam / cae 模块包规则;CAM 策略/求解器保持插件/外部服务路径 中
P3 assembly / PMI / 钣金 先从 vde_brep 拆头/源到独立模块,再建包 高

桥 TU 迁移要点:模块侧接收实现后,内核保留 deprecated 转发头(一个 minor 周期)并 在 CHANGELOG/文档注明“需显式链接 vde_ui/vde_pdm”;守卫更新 allowlist 后移除技术债; 迁移前后跑全量 ctest + 内核 SDK 消费者回归。

其它风险:模块包与 kernel 包版本必须配套(同 tag/pin);render API 存在进程级全局状态 (视口布局/剖面平面),拆 DLL 时语义为单进程单实例;MSVC 需同编译器/CRT/警告策略(参考 cross-platform §9);模块测试暂留 monorepo(拆仓后随模块仓)。

6. 验收与后续任务

  • render 包 install/export + 独立 consumer 构建/运行(本任务);
  • 模块依赖/边界审计与阻碍清单(drafting/render/ui/pdm/mechanism + 2 内核桥 TU);
  • 默认 build/ctest 子集绿、不改默认聚合行为;
  • drafting/mechanism 模块包(P3-15b:通用 cmake/vde_module_package.cmake + 两个独立包 + consumer PASS,见 §7);
  • ui/pdm 的 2 处 bridge TU 迁移(P3-15c,见 §8)→ [ ] ui/pdm 模块包/consumer(P3-15e) → [ ] cam/cae 包 → [ ] assembly/PMI/钣金拆分(P3);
  • 模块包 CI(每个模块独立 install+consumer)与拆仓后跨仓兼容矩阵。

7. P3-15b:drafting / mechanism 模块包(已完成)

在 render 先导经验上,将模块包规则抽成通用实现,并新增两个独立包:

  • 通用实现:cmake/vde_module_package.cmake(函数 vde_install_module_package(<module> <build-dep>...))+ cmake/vde-module-packageConfig.cmake.in(configure_file @ONLY 生成包 Config):
    • 导出 target vde::<module>(EXPORT_NAME <module>);build 接口保留具体内核依赖 (BUILD_INTERFACE),install 接口仅 vde::kernel;
    • Config 先 find_dependency(vde-kernel CONFIG REQUIRED) 再加载 targets;模块头安装到 include/vde_<module>;版本 SameMajorVersion;默认构建/聚合不变(仅在 VDE_INSTALL 与 VDE_INSTALL_SDK 下新增包)。
  • 包清单:vde-render(P3-15)、vde-drafting、vde-mechanism(本任务); 安装到 <prefix>/lib/cmake/vde-<module>/、lib/libvde_<module>.a、 include/vde_<module>/*.h(drafting 4 头 / mechanism 2 头),与 vde-kernel 包同 prefix。
  • 独立 consumer 实测(build-fb-split2,只 find_package,不 add_subdirectory):
    • drafting(box → generate_views → 图纸布局/标题栏): DRAFTING_CONSUMER_PASS faces=6 views=4 placements=4 title=consumer-smoke;
    • mechanism(四杆位置/全周期求解 + MotionSimulation): MECHANISM_CONSUMER_PASS faces=6 valid=1 cycle=36 joints=1;
    • 两个包的 export target 均为 INTERFACE_LINK_LIBRARIES "vde::kernel",Config 均含 find_dependency(vde-kernel CONFIG REQUIRED)。
  • 默认构建回归:build-fb-split2 全量 build exit 0(0 error);ctest 子集 (Render|Drafting|Mechanism|KernelAggregate|DependencyDirection|Capi)90/90 PASS; vde::app 聚合/既有 target 关系不变。

7.1 P3-15e:ui / pdm 模块包(已完成)

复用 §7 通用 helper(本次未改 helper/模板,根 CMake 仅新增 2 行调用):

  • vde_install_module_package(ui vde_brep vde_compile_options)
  • vde_install_module_package(pdm vde_brep vde_mesh vde_compile_options)

包清单/产物:vde-ui / vde-pdm(与 vde-render/drafting/mechanism 并列,共 5 个 模块包):libvde_ui.a / libvde_pdm.a、include/vde_ui/*.h(4)/ include/vde_pdm/*.h(4)、<prefix>/lib/cmake/vde-ui|vde-pdm/;export target 的 INTERFACE_LINK_LIBRARIES "vde::kernel",Config 均含 find_dependency(vde-kernel CONFIG REQUIRED)。

独立 consumer 实测(build-fb-split3,只 find_package,不 add_subdirectory):

  • ui(box → bounding_sphere / compute_view_layout(FourQuad) / SelectionManager::pick_select / gizmo_transform): UI_CONSUMER_PASS faces=6 radius=18.71 layouts=4 picked=1;
  • pdm(init_native_material_db / material_search / profile_library::all_profiles / BomTable + bom_export_csv): PDM_CONSUMER_PASS faces=6 materials=21 metals=15 profiles=32 searched=20 bom_csv=1。

验证:在 git archive HEAD + 仅叠加本任务根 CMake 2 行改动 的 clean 快照 (/D:/3_Source/vde_clean_c64dbf00)上全量 build exit 0(0 error)、install 成功; ctest 子集(Render|Drafting|Mechanism|Ui|Pdm|KernelAggregate|DependencyDirection|Capi) 96/96 PASS。(说明:验证期间仓库工作树处于 task-77 bridge TU 迁移中间态, src/CMakeLists.txt 尚未同步删除的源文件导致工作树 configure 暂时失败;clean 快照 排除该进行中状态。task-77 完成后工作树 cmake -S . -B build-fb-split3 已重新 configure 通过, 根 CMake 改动与 bridge 迁移无冲突。)

7.2 P3-15d:cam / cae 模块包(已完成)

复用 §7 通用 helper(未改 helper/模板;根 CMake 仅新增 2 行调用 + cae 头安装):

  • vde_install_module_package(cam vde_core vde_brep vde_curves vde_mesh vde_compile_options)
  • vde_install_module_package(cae vde_brep vde_mesh vde_curves vde_core vde_compile_options)
  • cae 公共头位于 include/vde/cae(P3-10 内核 SDK 显式排除官方模块头):模块包同时安装 include/vde_cae(模块约定)与 include/vde/cae(既有包含路径);cam 头由 helper 从 include/vde_cam 安装。

包清单/产物(build-fb-split4/install):

  • vde-cam:libvde_cam.a、include/vde_cam/*.h(7:cam_toolpath/strategies/advanced/ optimization/5axis/mesh/gcode_import)、lib/cmake/vde-cam/;
  • vde-cae:libvde_cae.a、include/vde_cae/*.h(2:fea_mesh/fluid_domain)+ include/vde/cae/*.h(2,既有路径)、lib/cmake/vde-cae/;
  • 两个包 export target 的 INTERFACE_LINK_LIBRARIES "vde::kernel";Config 均含 find_dependency(vde-kernel CONFIG REQUIRED);版本 SameMajorVersion;默认构建/聚合不变 (仅在 VDE_INSTALL 与 VDE_INSTALL_SDK 下新增包)。

独立 consumer 实测(build-fb-split4/consumers,只 find_package,不 add_subdirectory):

  • cam(NurbsCurve::rectangle → contour_toolpath → export_gcode): CAM_CONSUMER_PASS segments=1006 gcode_lines=1011 name=consumer-contour;
  • cae(tetrahedral_mesh + fea_quality_report;make_external_domain + classify_patches): CAE_CONSUMER_PASS faces=6 tet_elements=384 tet_vertices=125 avg_jacobian=0.8660 domain_volume=1192000.000 domain_exact=1 patches=6(diag:exact boolean difference, 实体严格包含于远场盒);
  • 两个 consumer configure/build/run 均 exit 0。

默认构建/聚合:build-fb-split4 全量 build 0 error、install exit 0;相关 ctest 子集 (Cam|Cae|VDE1241|VDE1242|KernelAggregate|DependencyDirection|Capi|ModulePackage) 253/253 PASS;根 CMake 改动仅在 VDE_INSTALL/VDE_INSTALL_SDK 块,默认 vde::app 聚合不变。

限制:cae 头同时提供两种目录(历史 <vde/cae/...> 与模块约定 <vde_cae/...>); 包为静态库(与 kernel 同口径);MSVC/跨平台 consumer 未实机验证(本机 MinGW); cam 包 build 接口依赖 core/brep/curves/mesh,cae 依赖 brep/mesh/curves/core(按实际 VDE_DEPS); 模块包 CI(每模块独立 install+consumer)与拆仓跨仓兼容矩阵仍待后续(§6)。

8. ui/pdm 拆仓受阻:内核 2 处 bridge TU 迁移步骤与影响评估(P3-15c 已完成)

8.1 现状

  • include/vde_ui 被 src/brep/geometric_snap.cpp include(该 TU 编译进 vde_brep);
  • include/vde_pdm 被 src/brep/structural_profiles.cpp include(同样编译进 vde_brep);
  • 两处均为编译期头耦合、无 link 依赖,已登记 cmake/check_kernel_boundary.cmake allowlist(brep/geometric_snap.cpp:vde_ui/、brep/structural_profiles.cpp:vde_pdm/)。
  • 影响:ui/pdm 模块包规则可复制 drafting/mechanism,但必须先解耦,否则模块包导出后内核仍 编译期依赖模块头(拆仓方向倒置、SDK 依赖不可控)。

8.2 迁移步骤(每个 bridge TU 独立执行)

  1. 实现迁移:把 src/brep/<bridge>.cpp 移到目标模块目录(src/vde_ui/ / src/vde_pdm/),namespace/符号保持不变;先双构建验证行为一致;
  2. 内核头兼容:两处 API 声明(include/vde/brep/geometric_snap.h、 include/vde/brep/structural_profiles.h)保留一个 minor 周期为 deprecated 转发头, 实现符号由模块库提供;内核 target 不再编译该 TU;
  3. CMake:从 vde_brep 源列表删除对应条目;模块 target 补必要内核依赖(方向仍为 模块→内核,合法);模块包规则套用 vde_install_module_package;
  4. 测试与守卫:bridge 相关单测迁移/双跑;更新 cmake/check_kernel_boundary.cmake allowlist(移除对应技术债条目);kernel SDK consumer 回归(仅链接内核时仍可编译内核头; 调用这些 API 需显式链接模块包);
  5. 兼容与文档:CHANGELOG/模块手册注明“1.0.x 起 需显式链接 vde_ui/vde_pdm”; 一个 minor 后删除内核转发头。

8.3 影响评估

维度 影响
符号/API 两处函数实现移出 vde_brep:仅链接 vde::kernel 的消费者调用这些 API 会 undefined symbol(预期改为显式链接模块包);内核 SDK 不再导出这些符号(需文档标注)
构建/测试 vde_brep 编译期依赖减少;ui/pdm 可独立 install/consumer;默认 monorepo 全量构建仍含模块,vde::app 聚合无行为变化
ABI/版本 静态库层面为“符号搬家”,同版本 monorepo 全量构建无 ABI 影响;拆仓后模块包/kernel 包版本需配套
风险/顺序 中风险(跨 target 符号迁移 + 测试/文档更新);建议顺序 ui → pdm;每步跑全量 build + ctest 子集 + KernelAggregateBoundary 守卫

8.4 完成记录(P3-15c,本任务)

迁移结果:

原子 迁移后位置 规范头 内核兼容转发头(一个 minor)
src/brep/geometric_snap.cpp src/vde_ui/geometric_snap.cpp(纯几何查询 + vde::ui::live_cursor_snap 包装) include/vde_ui/geometric_snap.h include/vde/brep/geometric_snap.h
src/brep/snap_ext.cpp(依赖 geometric snap,仅 UI/测试使用) src/vde_ui/snap_ext.cpp include/vde_ui/snap_ext.h include/vde/brep/snap_ext.h
src/brep/structural_profiles.cpp src/vde_pdm/structural_profiles.cpp include/vde_pdm/structural_profiles.h include/vde/brep/structural_profiles.h
  • namespace/符号保持不变(vde::brep),链接 ABI 与源码 API 兼容;include/vde_ui/geometric_snap_ui.h、 include/vde_ui/snap_ext.h 内部 include 改为规范路径;
  • src/CMakeLists.txt:vde_brep 移除 3 个 TU,vde_ui 增加 2 个、vde_pdm 增加 1 个; vde_ui/vde_pdm 均为“模块→内核”依赖方向(已 link vde_brep,功能依赖由内核提供);
  • cmake/check_kernel_boundary.cmake:_soft_include_allow 清零;kernel SDK 头安装追加 3 个 转发头 PATTERN ... EXCLUDE(geometric_snap.h / snap_ext.h / structural_profiles.h);
  • tests/brep/CMakeLists.txt:test_structural_profiles 按 VDE_ENABLE_pdm、 test_geometric_snap / test_proposal_ext 按 VDE_ENABLE_ui 门控(模块关闭时不构建)。

验证(build-fb-bridge / build-fb-bridge-kernelonly):

  • 默认全量 build:0 error / 0 FAILED;
  • 相关测试:test_geometric_snap 13/13、test_structural_profiles 50/50、 test_proposal_ext 35/35(含 snap_ext)、test_topo_naming 15/15; vde_ui/vde_pdm 模块测试保持全绿:gizmo 4、selection 8、viewport 22、bom 16、material 23、quality 21;
  • 定向 ctest(Snap|StructuralProfile|ProposalExt|KernelAggregateBoundary):170/170 PASS;
  • -DVDE_BUILD_UI=OFF -DVDE_BUILD_PDM=OFF(BUILD_TESTS=ON): 配置成功(disabled modules: pdm;ui),全量构建 971 步 / 0 FAILED / 0 undefined reference (libvde_ui.a / libvde_pdm.a 不构建;315 个测试可执行;被迁移符号不再属于 kernel 闭包), 内核子集 ctest(KernelAggregateBoundary|TopoNaming|BrepPosition)25/25 PASS; 三个相关测试 target 在 UI/PDM OFF 时正确门控(不构建);
  • cmake -DSOURCE_DIR=... -P cmake/check_kernel_boundary.cmake:PASS(技术债清零: _soft_include_allow 空;内核转发头已从 kernel SDK 安装排除)。

后续(P3-15e):vde-ui/vde-pdm 模块包(vde_install_module_package)+ 独立 consumer; 迁移后的模块头/实现已具备独立打包条件(模块→内核依赖单向)。

9. P3-15f:assembly 官方模块拆分(已完成)

结论:vde_assembly 模块已完成(阵列/约束/实例/柔性/大装配 LOD/装配特征与装配级 PMI 6 个 TU 迁出,规范头 + 内核兼容转发头 + 守卫/测试门控 + 模块包/consumer 全部完成); Assembly 核心数据模型(assembly.cpp/h)与 PMI 数据模型(pmi_types/pmi_mbd)按收口决策保留内核 (几何/文档数据类型 + vde_format 值类型/序列化依赖,拆出破坏 ABI/API 且收益有限,见 §9.3.4)。

9.1 审计结论

源/头 迁移判定 依据
assembly_patterns.{h,cpp} 迁入 vde_assembly 仅依赖 Assembly 核心类型;无内核 .cpp 消费者(仅测试/示例)
assembly_constraints.{h,cpp} 迁入 vde_assembly 同上(apply_constraint 为应用层便捷 API,内核 constraint_solver.cpp 自带求解器不调用它)
assembly_instance.{h,cpp} 迁入 vde_assembly 被 large_assembly/render 使用,无内核消费者
flexible_assembly.{h,cpp} 迁入 vde_assembly 仅测试/示例使用
large_assembly.{h,cpp} 迁入 vde_assembly 消费者为 vde_render(业务模块)与测试;无内核 .cpp 使用
assembly.{h,cpp} 留内核(阻塞) 内核 foundation/vde_format.cpp(SECTION_ASSEMBLY 序列化)、brep/step_import.cpp/iges_*/modeling.cpp/pattern_ext.cpp、interference_check.cpp、explode_view.cpp、constraint_solver.cpp、capi/vde_capi.cpp 直接使用 Assembly/AssemblyNode 及其成员函数;且 assembly.cpp 还提供内核公开的 mesh_to_brep_model(STEP/格式导入桥)
assembly_feature.{h,cpp} 迁入 vde_assembly(P3-15f-3b) task-88 已解除 step_import 头耦合(PMI DTO → pmi_types.h);实现仅依赖内核类型/桥(Assembly 遍历、pmi_mbd、interference_check),无内核 .cpp 消费者

9.2 已迁移内容(vde_assembly 模块)

  • target:vde_assembly(VDE_MODULES/VDE_DEPS_assembly=brep;curves;core/VDE_BUILD_ASSEMBLY 开关,默认 ON);
  • 源:src/vde_assembly/{assembly_patterns,assembly_constraints,assembly_instance,flexible_assembly,large_assembly,assembly_feature}.cpp;
  • 规范头:include/vde_assembly/*.h(namespace/符号仍为 vde::brep,源码/链接 ABI 兼容);
  • 内核兼容转发头:include/vde/brep/{assembly_patterns,assembly_constraints,assembly_instance,flexible_assembly,large_assembly,assembly_feature}.h(一个 minor 周期,kernel SDK 安装已 PATTERN ... EXCLUDE);
  • 依赖:vde_assembly → vde_brep/vde_curves/vde_core(模块→内核单向);vde_render 显式依赖 vde_assembly(assembly_lod/large_assembly_render),VDE_DEPS_render 增加 assembly 级联;
  • 聚合:vde::app 应用层聚合加入 assembly;vde::engine/内核聚合不变;
  • 测试门控:test_assembly/test_assembly_constraints/test_assembly_instance/test_assembly_patterns/test_assembly_pmi/test_interference_check/test_pmi_decouple/test_v5_features/test_vde1230_interference/test_large_assembly_e7/test_v4_1/test_v5_1/test_assembly_lod 在 VDE_ENABLE_assembly=OFF 时不构建;
  • 守卫:cmake/check_kernel_boundary.cmake 的 _biz_modules/_biz_header_markers 增加 assembly 与 vde_assembly/;内核源文件业务头耦合清单仍为空;
  • 模块包:vde_install_module_package(assembly vde_brep vde_curves vde_core vde_compile_options) → find_package(vde-assembly) + vde::assembly;独立 consumer smoke(创建 Assembly、实例/阵列/柔性装配 API 调用)见任务报告。

9.3 阻塞清单(assembly 核心/PMI,后续任务拆分建议)

更新(2026-10-29,task-92 / P3-15f-3b):第 2 项「assembly_feature 实现」已迁入 vde_assembly(头耦合由 task-88 解除、装配桥由 task-90 完成);剩余仅为 Assembly 核心数据模型 + PMI 数据模型保留内核的收口决策(§9.3.3/§9.3.4), P3-15f 收口。

  1. assembly.h/assembly.cpp(Assembly 数据模型)留内核(未变):
    • 内核消费者:foundation/vde_format.cpp(SECTION_ASSEMBLY 保存/加载)、 brep/interference_check.cpp、brep/explode_view.cpp、brep/constraint_solver.cpp、 brep/modeling.cpp/pattern_ext.cpp/pattern_ops.cpp/measure.cpp/ brep_validate.cpp/dfm_rules.cpp、brep/format_io.cpp/iges_export.cpp、 capi/vde_capi.cpp(vde_assembly_* C ABI);
    • assembly.cpp 另含内核公开的 mesh_to_brep_model(格式/STEP 导入桥,被 io/step 路径使用)。
  2. assembly_feature.{h,cpp}(PMI/MBD + 装配特征)→ 已迁入 vde_assembly(P3-15f-3b):
    • include/vde/brep/step_import.h include assembly_feature.h,形成 kernel 头 ↔ 业务头双向耦合 → 已解除:step_import.h 现只 include 独立类型头 pmi_types.h, PMIAnnotationData/PMIPropagationResult 已迁入 pmi_types.h;assembly_feature.h 保留 include pmi_types.h 以维持旧头源兼容(旧符号/结构可见性不变);
    • 剩余实现依赖:assembly.h(Assembly/AssemblyNode)、pmi_mbd.h(PMIModel/PMIAnnotation)、 interference_check.h(批量干涉)——迁移前置见 §9.3.2。
  3. assembly.h(Assembly/AssemblyNode 核心)仍内核公共头:按 §9.3.4 收口决策保留内核; assembly_feature.h 已迁模块(规范头 include/vde_assembly/assembly_feature.h + 内核兼容转发头), assembly 模块包头只提供高级特征 API,不重复声明 Assembly 核心类型(来自 vde::kernel)。

9.3.1 P3-15f-2 解耦结果(task-88,2026-10-29)

  • 依赖环/单向耦合分析:step_import.h 仅因 StepImportResult::pmi_annotations 需要 PMIAnnotationData(定义在 assembly_feature.h)而 include 整个 assembly_feature.h(其又 include assembly.h / pmi_types.h);实现侧 assembly_feature.cpp 再 include pmi_mbd.h, 形成 kernel 公开头 → 业务头(assembly/assembly_feature)的反向依赖。
  • 改动:
    • include/vde/brep/pmi_types.h:新增轻量 PMI 数据模型 PMIAnnotationData、 PMIPropagationResult(与既有 PMIType 同头);只依赖 vde/core/point.h + std 容器, 不 include 任何 vde/brep/* 头;
    • include/vde/brep/assembly_feature.h:移除两份结构定义,保留 #include pmi_types.h (旧头/旧符号源兼容;struct PMIAnnotationData 等仍经旧头可见);
    • include/vde/brep/step_import.h:#include "vde/brep/assembly_feature.h" → #include "vde/brep/pmi_types.h"。step_import.h 不再暴露/依赖 assembly.h、 assembly_feature.h、pmi_mbd.h。
  • 依赖环结论:头级依赖为 step_import.h → assembly_feature.h → {assembly.h, pmi_types.h}(单向, 但因 assembly_feature 属业务/装配特征头,构成 kernel 公开头 → 业务头的反向依赖); pmi_mbd.h → pmi_types.h(轻量,无环);pmi_mbd.cpp 仅实现侧调用 import_step()(AP242 读取桥), 头级不依赖 step_import。解耦后该反向边消失。
  • 兼容性:无符号改名/删除,namespace 不变(vde::brep);旧头与旧调用点无需修改 (src/brep/step_import.cpp、pmi_mbd.cpp、pmi_export.cpp、assembly_feature.cpp 及 14 个含 step_import.h 的测试 TU 均编译通过)。ABI:仅头文件结构归属变化,符号未变。
  • 回归守卫:新增 tests/brep/test_pmi_decouple.cpp(CMake 定义 VDE_SOURCE_DIR): 编译期验证「仅 step_import.h + pmi_types.h 即可使用 PMIAnnotationData」,运行期扫描真实头 断言依赖方向(step_import.h 不得 include assembly_feature/assembly/pmi_mbd;pmi_types.h 不含任何 vde/brep include;assembly_feature.h 不重复定义 PMI 结构且仍 include pmi_types.h)。

9.3.2 迁移清单与进度(assembly.cpp / assembly_feature.cpp)

文件/符号 状态 当前内核依赖 / 后续动作
mesh_to_brep_model(原 assembly.cpp) ✅ 已迁移(task-90) 已抽到内核独立头 include/vde/brep/mesh_to_brep.h + 独立 TU src/brep/mesh_to_brep.cpp(vde_brep 源列表);9 个调用点改 include 新头(step_import/format_io/industrial_formats/io_3dm/io_3dxml/io_vda/prc_import/host_services_geometry/cam_toolpath);step_import.cpp 不再 include assembly.h;assembly.h include 新头保持旧调用点源兼容
vde_format.cpp SECTION_ASSEMBLY 序列化 ✅ 已桥接(task-90) payload 写/读实现迁入装配核心 src/brep/assembly.cpp,内核经 include/vde/brep/assembly_services.h 的 assembly_section_codec() 调用;未注册时 vde_format 抛显式 runtime_error(assembly core unavailable);字节布局不变(test_vde_format roundtrip/幂等断言通过)
capi/vde_capi.cpp 的 vde_assembly_* ✅ 已桥接(task-90) 改为 assembly_capi_ops() 委托(create/add_part/part_count/destroy);capi 不再 include assembly.h;未注册时返回空 handle/0(显式降级);C ABI 符号/签名不变
assembly.h/assembly.cpp(Assembly/AssemblyNode 核心数据模型) 留内核(下一步) 消费者已盘点(§9.3.3 表);迁移前置只剩:vde_format.h assembly API 头拆分 + 其余 Assembly 参数 API 随模块/转发;assembly.cpp 现另含 SECTION_ASSEMBLY codec 与 capi ops 实现(迁模块时一并带走)
assembly_feature.{h,cpp}(特征/PMI/干涉 batch) 留内核(后续) 见 9.3 第 2 项:apply_assembly_feature(Assembly&)、PMI 传播(pmi_mbd 转换)、interference_check_batch;待 Assembly 数据模型迁出后随模块迁或改轻量 DTO
include/vde/brep/assembly_feature.h(兼容头) 后续 迁出后改兼容转发头(同 §9.2 策略,保留一个 minor 周期)
pmi_export.{h,cpp}(3D-PDF 导出 / 自动生成 PMI) ✅ 已迁移(task-129 / WP-P4-09 Plan A) 规范头 include/vde_pmi/pmi_export.h;实现迁 src/vde_pmi/(模块 vde_pmi,依赖 vde_brep+vde_io;VDE_BUILD_PMI 可关);旧 include/vde_drafting/pmi_export.h 兼容转发一个 minor 周期;PMI 数据模型(pmi_mbd/PMIModel)按 §9.3.4 留内核。独立模块包 vde-pmi + consumer;限制:export_3d_pdf 依赖 vde_io(不在 vde-kernel 包),独立 consumer smoke 用 auto_generate_pmi(见 §9.3.4a)
pmi_mbd.cpp AP242 读取桥(import_step()) 后续(数据模型留内核后不再迁) 见 §9.3.4a:pmi_mbd/PMIModel 按决策留内核;PMI 导出操作已迁 vde_pmi(task-129),AP242 读写随数据模型留内核

9.3.3 P3-15f-3a 解耦结果(task-90,2026-10-29)

1) mesh_to_brep_model 抽取(内核独立 TU)

  • 新头 include/vde/brep/mesh_to_brep.h:独立声明 + 语义文档;只依赖 brep.h/halfedge_mesh.h。
  • 新 TU src/brep/mesh_to_brep.cpp:实现自 assembly.cpp 原样迁移(三角面 → 平面 NURBS 面、单封闭壳、body=mesh_body,顶点不去重),并加入 vde_brep 源列表。
  • assembly.h:include 新头并保留同名声明(旧调用点 #include "vde/brep/assembly.h" 继续可用,源兼容);assembly.cpp 移除实现与本地 make_triangle_surface 辅助。
  • 调用点更新(9 个):step_import.cpp、format_io.cpp、industrial_formats.cpp、io_3dm.cpp、io_3dxml.cpp、io_vda.cpp、prc_import.cpp、host_services_geometry.cpp、vde_cam/cam_toolpath.cpp —— 全部改为 include mesh_to_brep.h;其中 step_import.cpp 因此不再依赖 assembly.h(P3-15f-3a 目标)。
  • 回归:tests/brep/test_mesh_to_brep_extract.cpp(4 用例:转换语义/空网格/头依赖边界/服务桥可用性),CMake 注入 VDE_SOURCE_DIR 扫描真实源码防回归。

2) vde_format SECTION_ASSEMBLY 可选装配核心桥

  • 新头 include/vde/brep/assembly_services.h(轻量,仅前向声明 class Assembly,不引入 Assembly 数据模型):
    • AssemblySectionCodec{write_payload, read_payload, available()} + assembly_section_codec();
    • AssemblyCapiOps{create, add_part, part_count, destroy, available()} + assembly_capi_ops()。
  • 实现位置:src/brep/assembly.cpp(装配核心,随 assembly 迁移一并走);SECTION_ASSEMBLY payload 写/读代码(实例去重表 + DFS 节点表 + 嵌套 BrepModel 子编码)自 vde_format.cpp 迁入,字节布局与迁移前逐字节一致。
  • vde_format.cpp:写路径 assembly_section_codec().write_payload、读路径 read_payload;未注册时抛 runtime_error("VDE: assembly core unavailable ...")(显式诊断,不静默丢节)。
  • 兼容:serialize_vde_assembly/save_vde_assembly/load_vde_assembly/deserialize_vde_assembly 签名与字节格式不变;test_vde_format 76 用例全绿(含 assembly roundtrip 字节幂等)。

3) capi vde_assembly_* 兼容桥

  • vde_capi.cpp 不再 include assembly.h/直接 reinterpret_cast<brep::Assembly*>:4 个 C ABI 函数经 assembly_capi_ops() 委托;未注册时 create 返回 nullptr、add_part 返回 0、part_count 返回 0、free no-op(明确降级)。
  • C ABI 符号/签名不变(源兼容/ABI 兼容);test_capi/test_capi_extended/test_capi_split/test_vde_capi 共 54 用例全绿。

4) Assembly 参数 API 迁移边界(盘点)

API 位置 迁移判定 说明
brep/assembly.h:Assembly/AssemblyNode 核心 + build_assembly_from_meshes/质量属性/干涉矩阵/BOM 遍历 随 assembly 模块迁出(下一阶段) 内核消费者已改桥(mesh_to_brep/vde_format/capi),剩余为 API 级引用;迁移时旧头改兼容转发头
brep/assembly_feature.h:apply_assembly_feature、PMI 传播/绑定、interference_check_batch/check_part_interference 随 assembly/PMI 模块迁出(后续) 依赖 Assembly 遍历 + PMIModel/干涉 batch;可先抽轻量 DTO 减小耦合
brep/constraint_solver.h(Assembly&/AssemblyNode& 大量 API) 可迁(随 assembly_assembly 模块) 求解器自带求解逻辑,内核 constraint 求解器不调用该应用层 API
brep/explode_view.h(explode/un_explode/explode_to_brep) 可迁 应用层爆炸视图 API
brep/interference_check.h(Assembly 批量) 可迁 单对 body 干涉 API 可留内核;Assembly 批量随模块
brep/measure.h:assembly_mass_properties(AssemblyNode)/generate_bom(AssemblyNode) 可迁 与 assembly.h 同迁或保留薄转发
brep/pattern_ops.h:assembly_boolean(const Assembly&,...) 可迁 阵列/布尔应用层 API
foundation/vde_format.h:assembly 文档 API(serialize/save/load/deserialize_vde_assembly、VdeLoadedAssembly 含 brep::Assembly 成员) 需保留内核头依赖(下一阶段拆分) 实现已桥接;头层可拆 vde_format_assembly.h(或模块头转发),待 assembly 核心迁出时执行
capi/vde_capi.h:vde_assembly_* 保留 C ABI(已桥接) 符号稳定;模块迁出后由模块注册 ops,kernel-only 时明确降级
include/vde/plugin/geometry_host_services.h、include/vde_cam/cam_toolpath.h 已解耦 仅注释提及 mesh_to_brep;实现经新内核头

5) 验证(task-90)

  • 默认 build(build-fb-asmcore):0 error;受影响 26 个测试可执行文件 564 用例全绿(含新 test_mesh_to_brep_extract 4、test_pmi_decouple 4、test_vde_format 76、test_step_import 72、capi 54、assembly 系列 74、干涉/爆炸/约束/测量/校验/大装配等)。
  • kernel-only(-DVDE_BUILD_ASSEMBLY=OFF,build-fb-asmcore-kernelonly):配置/全量构建结果见 §9.4 追加记录(assembly 核心数据模型仍在内核,属预期:§9.3 第 1 项剩余迁移项)。

6) 剩余限制

  • vde_format.h 仍 include assembly.h(VdeLoadedAssembly 成员为 brep::Assembly 值类型)——属下一阶段头拆分项;本任务已把“实现耦合”降为“头层类型依赖”。
  • assembly 核心数据模型仍在 vde_brep,kernel-only 构型仍含 Assembly 符号(按 §9.3 预期,模块迁出后才可移除)。
  • assembly_capi_ops/assembly_section_codec 目前由内核 assembly.cpp 提供;迁模块后需模块显式注册(本头 available() 已为未注册场景定义降级行为)。

9.3.4 P3-15f-3b 收口决策(task-92,2026-10-29):Assembly 核心 + PMI 数据模型保留内核

决策:assembly.h/assembly.cpp(Assembly/AssemblyNode 核心数据模型)与 PMI 数据模型 (pmi_types.h 的轻量 DTO;pmi_mbd/PMIModel 文档/序列化值类型)保留在 vde_brep 内核, 不再迁出;vde_assembly 官方模块 = 高级装配特征与装配级操作(阵列/约束/实例/柔性装配/ 大装配 LOD/装配特征 apply_assembly_feature/PMI 传播与绑定/批量干涉)。

理由:

  1. geometry/document 数据类型 + vde_format 值类型/序列化依赖:VdeLoadedAssembly 等文档 结构以 brep::Assembly 为值类型成员,SECTION_ASSEMBLY payload 由装配核心 codec 序列化 (vde_format.h 现有 API 契约);拆出会改变头层公开类型/字节布局,破坏 ABI/API,且需新增 跨版本兼容层(PIMPL/不透明句柄),成本高。
  2. 内核消费者广:vde_format、STEP/IGES/DXF 导入导出、干涉检查、爆炸视图、约束求解、 测量/BOM、校验/DFM、kernel C API(vde_assembly_*,已桥接)等直接使用 Assembly 类型/遍历; 全改成模块回调或把内核能力一并搬走,属于大范围重构,收益(内核体积/依赖)有限。
  3. PMI 是文档/格式层共享 DTO:step_import.h/导入报告/PDM/BOM/PMI 模块共用 PMIAnnotationData; 留在轻量内核头 pmi_types.h 使格式/文档层不依赖业务模块;PMI 操作(传播/绑定)已在模块。
  4. 实测支持:assembly_feature 迁出后,kernel-only(VDE_BUILD_ASSEMBLY=OFF)构建 0 undefined reference —— 保留核心类型不再产生“内核→模块”符号依赖;模块与内核边界清晰。

未来替代方案(若出现“纯几何内核消费者需零装配类型”强需求):

  • 先拆 vde_format_assembly.h:VdeLoadedAssembly 改为不透明/指针或 PIMPL,文档 assembly API 移模块;
  • SECTION_ASSEMBLY codec/assembly_capi_ops 注册迁模块(assembly_services.h 的 codec/capi ops 已具备“未注册时显式降级”的桥接模式,可直接复用);
  • PMI 轻量 DTO 迁独立 PMI 模块头(step_import 仅前向声明/独立 DTO 头);
  • 最后 Assembly 核心类型迁 vde-assembly-core 包,内核通过 services 回调使用。 预计收益低;建议除非出现明确强需求,否则保持 §9.3.4 决策(核心/PMI 留内核)。

9.3.4a WP-P4-09 Plan A 交付(task-129):数据模型留内核,PMI 导出操作迁 vde_pmi

背景:task-126 审计确认“整文件迁 pmi_mbd.cpp/.h”被 vde_format 的 ABI 硬依赖阻塞 (include/vde/foundation/vde_format.h:60/722/753/766 以 brep::PMIModel 为值成员/参数; src/foundation/vde_format.cpp:772/829 调用 pmi_mbd.cpp 的非内联方法)。按 §9.3.4 既定决策执行 Plan A:

  • 留内核:include/vde/brep/pmi_mbd.h、src/brep/pmi_mbd.cpp(PMIModel/PMIAnnotation/PMIView 数据模型 + SECTION_PMI codec + AP242 读写);vde_format API/ABI 不变;
  • 迁模块:pmi_export(auto_generate_pmi / export_3d_pdf)→ 新官方模块 vde_pmi:
    • 规范头 include/vde_pmi/pmi_export.h;实现 src/vde_pmi/pmi_export.cpp(auto_generate_pmi,无 io 依赖) 与 src/vde_pmi/pmi_export_3dpdf.cpp(export_3d_pdf,依赖 vde_io);
    • 旧 include/vde_drafting/pmi_export.h 改为兼容转发一个 minor 周期;
    • 开关 VDE_BUILD_PMI(默认 ON;关闭时 vde_pmi/其测试不构建,VDE_DEPS_pmi=brep;io, 依赖被关闭时自动级联关闭);聚合 vde/vde::app/vde::io 关系不变(pmi 仅应用层);
    • 模块包 vde-pmi(vde_install_module_package(pmi vde_brep vde_io ...))+ 独立 consumer tests/module_packages/consumers/pmi(smoke 调用 auto_generate_pmi);
    • 测试门控:test_pmi_mbd/test_step_ap242 需 VDE_ENABLE_io AND VDE_ENABLE_pmi;新增 tests/vde_pmi/test_pmi_export.cpp。
  • 验证口径:默认全量 build 0 error;PMI/STEP AP242/架构守卫相关 ctest 绿;consumer PASS; kernel-only(-DVDE_BUILD_PMI=OFF)0 undefined。

模块包限制(诚实记录):export_3d_pdf 的 U3D/PDF 实现位于 vde_io(集成层),vde_io 不属于 vde-kernel 包;因此独立 vde-pmi 模块包当前 consumer 只验证 auto_generate_pmi。若需在只装 vde-kernel+vde-pmi 的环境使用 export_3d_pdf,需后续把 3D-PDF 导出下沉到 kernel 服务或新增 vde-io 模块包(另立 WP;不在本任务范围)。旧 include/vde_drafting/pmi_export.h 随 vde-drafting 包安装, 仅作转发;使用旧路径的消费者需同时安装 vde-pmi(或继续使用 monorepo 构建树)。

WP-P4-09 最终 scope:以本条为准——数据模型/序列化留内核;PMI 导出操作独立 vde_pmi 模块 + 包。

9.4 验证

  • 默认全量 build(build-fb-assembly):0 error / 0 FAILED;

  • assembly 相关测试(迁移后):test_assembly 24/24、test_assembly_constraints 19/19、 test_assembly_instance 6/6、test_assembly_patterns 19/19、test_assembly_lod 22/22、 test_interference_check 19/19、test_explode_view 17/17、test_assembly_pmi / test_v4_1 / test_v5_1 / test_large_assembly_e7 全绿(合计 126+ 用例,VDE 全量 ctest 由 Lead 统一复跑);

  • 模块包:cmake --install 成功生成 vde-assembly 包(vde::assembly + 依赖 vde::kernel), 独立 consumer(只 find_package、不 add_subdirectory)编译/运行 VDE_ASSEMBLY_CONSUMER_PASS parts=3 placed=1 unique=1;kernel SDK 未安装 5 个兼容转发头(已 EXCLUDE)、模块包安装 include/vde_assembly/* ✓;

  • kernel-only(-DVDE_BUILD_ASSEMBLY=OFF + BUILD_TESTS=ON,build-fb-assembly-kernelonly): 配置成功(disabled modules: render;assembly,render 按 VDE_DEPS_render 级联关闭); 全量构建 0 FAILED / 0 undefined reference(libvde_assembly.a/libvde_render.a 不构建; 312 个测试可执行;assembly 相关测试 target 全部正确门控);内核子集 ctest (KernelAggregateBoundary|TopoNaming|BrepPosition)25/25 PASS; 注:按 §9.3 阻塞清单,Assembly 核心数据模型仍在 vde_brep,故 ASSEMBLY OFF 时内核仍含 Assembly 核心符号(高级特征符号已不在内核闭包);完全“无 assembly 符号”需先完成 §9.3 的 核心/PMI 拆分。

  • 守卫:cmake -DSOURCE_DIR=... -P cmake/check_kernel_boundary.cmake → PASS (内核源文件业务头耦合清单为空;内核头转发头 11 个均已在 kernel SDK 安装 EXCLUDE; vde::app 聚合含 assembly、内核聚合不含)。

  • P3-15f-3b(task-92,2026-10-29,assembly_feature 迁移 + P3-15f 收口):

    • 迁移:include/vde/brep/assembly_feature.h → 规范头 include/vde_assembly/assembly_feature.h (旧路径改为兼容转发头,不进 kernel SDK);src/brep/assembly_feature.cpp → src/vde_assembly/assembly_feature.cpp;vde_brep 源列表移除、vde_assembly 增加; 根 CMake kernel SDK 头安装新增 PATTERN "assembly_feature.h" EXCLUDE;
    • 调用点/测试:6 个测试 TU 改 include 规范头(test_pmi_decouple 同时保留旧转发头覆盖源兼容); test_assembly_pmi/test_interference_check/test_pmi_decouple/test_v5_features/ test_vde1230_interference 按 VDE_ENABLE_assembly 门控;test_pmi_decouple 断言更新为 “规范头含 pmi_types.h + 旧 brep 路径转发到 vde_assembly”;
    • 默认 build(build-fb-asmfeature):0 error / 0 FAILED;相关测试:assembly 24、assembly_pmi 6、 pmi_decouple 4、interference 19、v5_features 30、vde1230 18、assembly_patterns 19、constraints 19、 instance 6、mesh_to_brep 4、explode 17、assembly_lod 22、vde_format 76/76 全绿;
    • 定向 ctest(Assembly|assembly|Pmi|PMI|Interference|VdeFormat|KernelAggregateBoundary|DependencyDirection): 314/314 PASS;
    • 模块包:cmake --install 生成 vde-assembly;include/vde_assembly/assembly_feature.h 安装(True)、 kernel SDK 旧转发头不安装(False);独立 consumer(只 find_package)调用 apply_assembly_feature + add_assembly_pmi/collect_assembly_pmi: VDE_ASSEMBLY_FEATURE_CONSUMER_PASS parts=1 pmi=1 features_applied=1;
    • kernel-only(-DVDE_BUILD_ASSEMBLY=OFF,build-fb-asmfeature-kernelonly):0 FAILED / 0 undefined reference(libvde_assembly.a/libvde_render.a 不构建;8 个 assembly 测试 target 正确门控 不构建);守卫 VDE_KernelAggregateBoundary+VDE_DependencyDirection_Guard 2/2 PASS;
    • 守卫直接调用:PASS(内核源文件业务头耦合为空;内核头转发头 11 个均 EXCLUDE)。
  • P3-15f-3a(task-90,2026-10-29):

    • 默认 build(build-fb-asmcore,Release/Ninja):0 error;
    • 受影响 26 个测试可执行文件、564 用例全绿,0 失败:test_mesh_to_brep_extract 4(新)、 test_pmi_decouple 4、test_assembly 24、test_assembly_pmi 6、test_assembly_patterns 19、 test_assembly_constraints 19、test_assembly_instance 6、test_interference_check 19、 test_explode_view 17、test_explode_to_brep 5、test_constraint_solver_3d 73、test_measure 35、 test_brep_validate 29、test_step_import 72、test_vde1230_interference 18、test_large_assembly_e7 10、 test_vde_format 76、test_all_formats 19、test_format_roundtrip 15、test_capi 18、 test_capi_extended 18、test_capi_split 10、test_vde_capi 8、test_cam_toolpath 13、 test_plugin_official_cad_formats 5、test_assembly_lod 22;
    • kernel-only(-DVDE_BUILD_ASSEMBLY=OFF,build-fb-asmcore-kernelonly):配置成功(disabled modules: render;assembly),全量构建 0 error / 0 FAILED;关键测试 13 个可执行文件、 327 用例全绿(test_mesh_to_brep_extract 4、test_pmi_decouple 4、test_step_import 72、 test_measure 35、test_brep_validate 29、test_interference_check 19、test_vde_format 76、 test_all_formats 19、test_format_roundtrip 15、capi 系列 54);test_assembly 等 6 个 assembly 模块测试 target 按 VDE_BUILD_ASSEMBLY=OFF 正确门控不构建;内核仍含 Assembly 核心符号 (§9.3 第 1 项预期,装配核心迁出后才移除),但 STEP/格式/PMI/内核 C API 路径已不依赖 vde_assembly 模块;
    • 头/实现边界守卫:test_mesh_to_brep_extract 扫描真实源码断言 step_import.cpp 不含 #include "vde/brep/assembly.h"、assembly.h 仍 include mesh_to_brep.h(源兼容)、 assembly.cpp 不再定义 mesh_to_brep_model、新 TU 在 vde_brep 源列表;

9.5 兼容性与限制

  • 迁移符号 namespace 不变(vde::brep),同版本 monorepo 无 ABI 影响;旧 brep 头保留兼容转发一个 minor;
  • 仅链接 vde::kernel 的消费者调用已迁走的高级装配 API 需显式 find_package(vde-assembly)/链接 vde::assembly;
  • P3-15f-3b 收口:assembly_feature 已迁 vde_assembly(规范头 + 兼容转发头,不进 kernel SDK); Assembly 核心数据模型与 PMI 数据模型按 §9.3.4 决策保留内核;-DVDE_BUILD_ASSEMBLY=OFF 时内核仍含 Assembly/PMI 核心符号(按决策属预期;全部高级特征/装配操作符号已不在内核闭包,构建/链接 0 undefined)。
  • P3-15f-2(task-88)已解除 step_import.h → assembly_feature.h 头耦合,PMI 轻量数据模型 独立到 pmi_types.h 并加头边界回归测试(§9.3.1),为后续 assembly 核心/装配特征迁出 清掉首要头依赖障碍。

10. P3-15g:sheet metal 官方模块拆分(已完成)

10.1 审计与迁移

  • 审计:src/brep/sheet_metal.cpp(约 2.9k 行)、sheet_metal_design.cpp(约 0.7k)、 sheet_metal_enhanced.cpp(约 0.1k)仅在这些 TU 之间使用;公开头 include/vde/brep/sheet_metal.h,命名空间 vde::brep 不变;依赖 brep/curves/core (及 brep 传递的 foundation),无 mesh/render 直接依赖。
  • 新增官方模块 target vde_sheetmetal:
    • 开关 VDE_BUILD_SHEETMETAL(默认 ON)/VDE_ENABLE_sheetmetal;
    • VDE_MODULES 增加 sheetmetal,VDE_DEPS_sheetmetal=brep;curves;core(级联关闭规则);
    • 源迁入 src/vde_sheetmetal/(3 个 TU),从 vde_brep 源列表移除;
    • 规范头 include/vde_sheetmetal/sheet_metal.h;旧 include/vde/brep/sheet_metal.h 改为兼容转发头(一个 minor 周期;不随 kernel SDK 安装);
    • vde::app 聚合新增 vde_sheetmetal,默认构建/聚合行为除模块归属外不变;
    • 测试门控:test_sheet_metal、test_sheet_metal_design、test_new_feedback 包在 if(VDE_ENABLE_sheetmetal) 内;kernel-boundary 守卫 _biz_modules/_biz_header_markers 增加 sheetmetal;kernel SDK 安装规则 PATTERN "sheet_metal.h" EXCLUDE。

10.2 模块包与独立 consumer

  • 模块包 vde-sheetmetal:vde_install_module_package(sheetmetal vde_brep vde_curves vde_core vde_compile_options);install 接口仅 vde::kernel,Config 含 find_dependency(vde-kernel CONFIG REQUIRED);安装 libvde_sheetmetal.a + include/vde_sheetmetal/sheet_metal.h + lib/cmake/vde-sheetmetal/(build-fb-sheet/install, install exit 0)。
  • 独立 consumer(build-fb-sheet/consumers/sheetmetal,只 find_package,不 add_subdirectory): find_package(vde-kernel) + find_package(vde-sheetmetal),调用 K-factor/折弯余量/折弯扣除/ 扣除表 + make_box 基体 + create_flange + unfold_sheet_metal: SHEETMETAL_CONSUMER_PASS faces=6 k=0.3800 ba=2.1677 bd=1.8323 table=8 flange_ok=1 flange_faces=8 unfold_ok=1 bends=1(configure/build/run 均 exit 0)。

10.3 验证

  • 默认构建(build-fb-sheet):全量 build 0 error;全量 ctest *7550/7550 PASS (0 failed,248.46s);sheetmetal + 守卫子集 59/59 PASS(SheetMetal 57 + VDE_DependencyDirection_Guard / VDE_KernelAggregateBoundary 2);
  • kernel SDK:install/include/vde/brep/sheet_metal.h 不安装(False),规范头 install/include/vde_sheetmetal/sheet_metal.h 安装(True);
  • kernel-only/OFF(build-fb-sheet-off,-DVDE_BUILD_SHEETMETAL=OFF + BUILD_TESTS): disabled modules: sheetmetal;全量 build 0 error / 0 undefined reference; SheetMetal 测试 target 不构建(ctest -N 中 0 条);守卫 VDE_DependencyDirection_Guard + VDE_KernelAggregateBoundary 2/2 PASS。

10.4 兼容性与限制

  • 迁移 symbol 命名空间保持 vde::brep,同版本 monorepo 无 ABI/API 变化;旧 brep 头保留兼容 转发一个 minor 周期(后续删除需发布说明);
  • 仅链接 vde::kernel 的消费者若使用钣金 API,需显式 find_package(vde-sheetmetal) 并链接 vde::sheetmetal(模块包不自动进入 kernel SDK);
  • 模块为静态库(与 kernel 同口径);MSVC/Linux 实机 consumer 未验证(本机 MinGW,CI 可补);
  • kernel-only OFF 时内核闭包不含钣金符号(3 个 TU 全移出);旧转发头在无 sheetmetal 模块时 不应被内核/消费者包含。

11. P4 CI 矩阵:cmake/check_module_packages.cmake

多团队并行开发后,模块包(install/export + find_package)需要常驻 CI 防回归。 新增 standalone CMake 脚本 cmake/check_module_packages.cmake + 仓库内最小 consumer (tests/module_packages/consumers/<module>/),并由 .github/workflows/ci.yml 的 module-packages job 调用。

11.1 脚本流程与覆盖

  1. configure VDE:-DVDE_INSTALL=ON -DVDE_INSTALL_SDK=ON, BUILD_TESTS/EXAMPLES/BENCHMARKS=OFF、VDE_BUILD_TOOLS/SAMPLE_PLUGINS=OFF (可用 -DEXTRA_CONFIGURE_ARGS="..." 透传离线 FetchContent 等参数);
  2. build + install 到临时 prefix(-DINSTALL_PREFIX,默认 <BUILD_ROOT>/install);
  3. 对 MODULES(默认 kernel + render/drafting/mechanism/ui/pdm/cam/cae/assembly/sheetmetal, 共 10 个)逐个检查 <prefix>/lib/cmake/vde-<module> 是否存在:
    • 存在 → 配置/编译/运行 tests/module_packages/consumers/<module>(find_package(vde-<module>)
      • find_package(vde-kernel),实际链接 vde::<module>/vde::kernel 并调用一个模块符号);
    • 不存在 → SKIP(模块被 VDE_BUILD_<MODULE>=OFF 裁剪或尚无包规则,不阻塞 CI);
    • 任意 consumer configure/build/run 失败 → FAIL,脚本 message(FATAL_ERROR) 退出非 0。
  4. 输出:每模块一行 [module-packages] PASS/SKIP/FAIL vde-<module> -> <consumer stdout>, 结尾 MODULE_PACKAGES_PASS pass=<n> skip=<n>;日志在 <BUILD_ROOT>/logs/。

11.2 本地等价命令(MinGW/Windows,离线)

cmake -DSOURCE_DIR=D:/3_Source/ViewDesignEngine ^
      -DBUILD_ROOT=D:/3_Source/ViewDesignEngine/build-fb-modci/run ^
      -DINSTALL_PREFIX=D:/3_Source/ViewDesignEngine/build-fb-modci/install ^
      -DGENERATOR=Ninja -DCMAKE_BUILD_TYPE=Release -DBUILD_JOBS=12 ^
      -DEXTRA_CONFIGURE_ARGS="-DFETCHCONTENT_FULLY_DISCONNECTED=ON -DFETCHCONTENT_SOURCE_DIR_JSON=D:/3_Source/ViewDesignEngine/json -DFETCHCONTENT_SOURCE_DIR_GOOGLETEST=D:/3_Source/ViewDesignEngine/googletest -DFETCHCONTENT_SOURCE_DIR_EIGEN3=D:/3_Source/ViewDesignEngine/eigen3" ^
      -P cmake/check_module_packages.cmake

Ubuntu(等价 CI):cmake -DSOURCE_DIR="$PWD" -DBUILD_ROOT=/tmp/module-packages -DINSTALL_PREFIX=/tmp/module-packages/install -DGENERATOR=Ninja -DCMAKE_BUILD_TYPE=Release -DBUILD_JOBS=$(nproc) -P cmake/check_module_packages.cmake (系统 libeigen3-dev 提供 Eigen3Config;本地无系统 Eigen3 时脚本传 -DEIGEN3_INCLUDE_DIR=<SOURCE_DIR>/eigen3 给 consumer,走仓库内 FindEigen3 stub。)

11.3 CI job(.github/workflows/ci.yml module-packages)

  • ubuntu-22.04;checkout(submodules recursive);apt:g++-11 cmake ninja-build libeigen3-dev;
  • 调用脚本(BUILD_JOBS=$(nproc)),日志以 module-packages-logs artifact 上传(always);
  • 该 job 与 build-and-test 并行,不占用全量 ctest 时间。

11.4 本地实测(build-fb-modci,MinGW UCRT/GCC 16.1/Release)

MODULE_PACKAGES_PASS pass=10 skip=0 fail=0(脚本 exit 0,VDE 全量 build 0 error):

模块包 consumer 输出
vde-kernel KERNEL_CONSUMER_PASS faces=6 volume=24.0
vde-render RENDER_CONSUMER_PASS faces=6 section=0
vde-drafting DRAFTING_CONSUMER_PASS faces=6 views=4 placements=4
vde-mechanism MECHANISM_CONSUMER_PASS valid=1 cycle=36 joints=1
vde-ui UI_CONSUMER_PASS faces=6 radius=18.71 layouts=4 picked=1
vde-pdm PDM_CONSUMER_PASS materials=21 metals=15 profiles=32
vde-cam CAM_CONSUMER_PASS rpm=6366.2 feed=530.5 gcode_bytes=76
vde-cae CAE_CONSUMER_PASS faces=6 vertices=2520 elements=11760
vde-assembly ASSEMBLY_CONSUMER_PASS pmi_bindings=0 checked_pairs=0 interference=0
vde-sheetmetal SHEETMETAL_CONSUMER_PASS k=0.3300 allowance=3.6600 deduction=2.3400

11.5 维护语义

  • 新增模块包(例如后续拆分 assembly 子能力)时:在根 CMakeLists.txt 增加 vde_install_module_package(...) + 在 tests/module_packages/consumers/ 增加消费者, 并把模块名加入脚本 MODULES 默认列表即可自动纳入 CI;
  • 临时裁剪模块(-DVDE_BUILD_<MODULE>=OFF)时该行 SKIP,不阻塞;
  • consumer 只验证“包可被 find_package、链接一个真实符号并运行”,不重复模块单测 (模块单测仍在 monorepo tests/<module>,由主 ctest job 覆盖)。

11.6 模块包模式矩阵(WP-P4-14,MinGW 实测)

2026-10-29 · main HEAD cb0af54f(1.0.86)· Windows 11 × MinGW UCRT GCC 16.1。 完整矩阵/复现命令见 tests/module_packages/README-mode-matrix.md;本节只记录 与模块包拆分相关的结论与 Linux/CI 阻塞。

模式 最小 configure 关键 target 构建 关键产物 结论
static ✅ 0 error vde_brep 178/178 src/libvde_brep.a 12.7 MB ✅ 静态模块包路径(§11 矩阵)
hybrid(默认) ✅ 0 error vde_brep 178/178 同上 ✅ 行为同 static
shared ✅ 0 error vde_capi_shared 216/216 src/libvde_capi.dll 7.3 MB ✅ C ABI 共享库;C++ 模块仍静态
plugin ✅ 0 error CAPI + vde_sample_vbox + vde_official_stl CAPI 7.3 MB;sample_vbox 117 KB;official_stl 97 KB ✅ shared + 插件 DLL 构建
  • 负例(configure FATAL):非法 VDE_MODULES_MODE;shared 关闭 CAPI; plugin 关闭插件管理器(详见 README-mode-matrix §2.1);
  • 旧记录「MinGW std::filesystem(fs_path.h)导致 shared 构建约 140/217 对象停止」在 1.0.86 未复现(216/216、0 error),旧结论已在 README-mode-matrix §5 更正;
  • 与模块包矩阵的关系:§11 的 find_package(vde-<module>) 静态 consumer 矩阵只覆盖 static/hybrid 模式;shared/plugin 模式的消费入口是 C ABI(vde_capi_shared)与插件 DLL,不存在“模块级 DLL 包”;shared/plugin 的模块包 consumer 未在本轮验证;
  • Linux/CI 阻塞:本机无 Linux/MSVC 工具链,hosted runner 已于 task-110 下线并归档到 docs/ci-templates/(默认不启用),因此四模式的 Linux/MSVC configure/build 均 未验证——属环境阻塞,非模式实现失败;本地可验证部分仅 MinGW 最小配置 + static consumer 10/10(§11.4,1.0.80 证据,本任务未重跑);
  • 其他限制:同前缀多模式共存/切换未验证(建议一模式一 install prefix);plugin 部署安装布局 (<prefix>/lib/vde/plugins/<id>/,需 VDE_INSTALL=ON + VDE_INSTALL_SDK=ON) 未在最小构建中执行 install;C++ 跨 DLL ABI 不在 P3/P4 范围。