From 5eb11fa501c7cd8042a2a43aa321bb1fe2b3a0a2 Mon Sep 17 00:00:00 2001 From: hm-thinkbook16p Date: Mon, 27 Jul 2026 22:13:00 +0800 Subject: [PATCH] docs: feedback from ViewDesign integration (VDE-001~013) --- docs/feedback/README.md | 17 +++++++++++++++++ docs/feedback/VDE-001.md | 36 ++++++++++++++++++++++++++++++++++++ docs/feedback/VDE-002.md | 37 +++++++++++++++++++++++++++++++++++++ docs/feedback/VDE-003.md | 30 ++++++++++++++++++++++++++++++ docs/feedback/VDE-004.md | 31 +++++++++++++++++++++++++++++++ docs/feedback/VDE-005.md | 31 +++++++++++++++++++++++++++++++ docs/feedback/VDE-006.md | 31 +++++++++++++++++++++++++++++++ docs/feedback/VDE-007.md | 34 ++++++++++++++++++++++++++++++++++ docs/feedback/VDE-008.md | 30 ++++++++++++++++++++++++++++++ docs/feedback/VDE-009.md | 32 ++++++++++++++++++++++++++++++++ docs/feedback/VDE-010.md | 30 ++++++++++++++++++++++++++++++ docs/feedback/VDE-011.md | 35 +++++++++++++++++++++++++++++++++++ docs/feedback/VDE-012.md | 36 ++++++++++++++++++++++++++++++++++++ docs/feedback/VDE-013.md | 32 ++++++++++++++++++++++++++++++++ 14 files changed, 442 insertions(+) create mode 100644 docs/feedback/README.md create mode 100644 docs/feedback/VDE-001.md create mode 100644 docs/feedback/VDE-002.md create mode 100644 docs/feedback/VDE-003.md create mode 100644 docs/feedback/VDE-004.md create mode 100644 docs/feedback/VDE-005.md create mode 100644 docs/feedback/VDE-006.md create mode 100644 docs/feedback/VDE-007.md create mode 100644 docs/feedback/VDE-008.md create mode 100644 docs/feedback/VDE-009.md create mode 100644 docs/feedback/VDE-010.md create mode 100644 docs/feedback/VDE-011.md create mode 100644 docs/feedback/VDE-012.md create mode 100644 docs/feedback/VDE-013.md diff --git a/docs/feedback/README.md b/docs/feedback/README.md new file mode 100644 index 0000000..9973e40 --- /dev/null +++ b/docs/feedback/README.md @@ -0,0 +1,17 @@ +# ViewDesignEngine 问题反馈 + +> 此目录由 ViewDesign 工程自动生成。每个文件对应一个来自 ViewDesign 集成测试中发现的 VDE 问题。 +> +> 文件命名规则: `VDE-{编号}.md` +> +> 处理完成后，请在文件中更新 `status` 字段。 + +## 状态图例 + +| 状态 | 含义 | +|------|------| +| `open` | 待处理 | +| `in_progress` | 处理中 | +| `fixed` | 已修复 | +| `wont_fix` | 不予修复 | +| `deferred` | 延期 | diff --git a/docs/feedback/VDE-001.md b/docs/feedback/VDE-001.md new file mode 100644 index 0000000..8cd04ec --- /dev/null +++ b/docs/feedback/VDE-001.md @@ -0,0 +1,36 @@ +--- +id: VDE-001 +status: open +severity: critical +category: compat +date: 2026-07-27 +reporter: ViewDesign +--- + +# VDE-001: brep 模块编译失败（GCC/MSVC 兼容性） + +## 问题描述 + +ViewDesignEngine 代码主要为 MSVC 编写。MSVC 默认不执行两阶段名称查找，因此模板代码中引用 AABB3D、Point3D 等类型时无需显式 using 声明。GCC/Clang 严格遵循 C++ 标准，要求两阶段查找，导致编译错误。brep 模块引用了未在当前编译单元中声明的类型（如 AABB3D 在 ssi_boolean.cpp 中通过 using namespace vde::core 间接引入），这在 GCC 下是不允许的。 + +## 影响文件 + +- src/brep/ssi_boolean.cpp +- src/brep/brep_face_split.cpp +- src/brep/brep_heal.cpp +- src/brep/tolerant_modeling.cpp +- src/mesh/halfedge_mesh.cpp + +## ViewDesign 侧 Workaround + +在 vd_geom 中仅链接 vde_foundation + vde_core，不链接 vde_brep 及其依赖项（vde_curves, vde_mesh, vde_boolean 等）。通过 cmake/vde_gcc_compat.h 强行注入 using 声明。 + +## 建议修复方向 + +1. 在 brep 模块的所有 .cpp 文件顶部添加显式 using 声明 +2. 重构代码避免在模板上下文中使用未限定的短名称 +3. 考虑使用 using namespace vde::core 或逐类型 using 声明 +4. 在 CI 中增加 GCC/Clang 编译检查 + +--- +*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。* diff --git a/docs/feedback/VDE-002.md b/docs/feedback/VDE-002.md new file mode 100644 index 0000000..9e9a640 --- /dev/null +++ b/docs/feedback/VDE-002.md @@ -0,0 +1,37 @@ +--- +id: VDE-002 +status: open +severity: high +category: build +date: 2026-07-27 +reporter: ViewDesign +--- + +# VDE-002: 子模块模式下 include 路径无法解析 + +## 问题描述 + +ViewDesignEngine 的 CMakeLists.txt 使用 ${CMAKE_SOURCE_DIR}/include 作为公共头文件搜索路径。独立构建时，CMAKE_SOURCE_DIR 指向 ViewDesignEngine 仓库根目录。但作为子模块被 ViewDesign 引入时，CMAKE_SOURCE_DIR 指向 ViewDesign 根目录，而 ViewDesign 没有 include/vde/ 目录，导致头文件找不到。 + +## 影响文件 + +- src/CMakeLists.txt +- 所有使用 ${CMAKE_SOURCE_DIR}/include 的目标 + +## ViewDesign 侧 Workaround + +在父工程 CMakeLists.txt 中手动添加 VDE 真实 include 路径： + +```cmake +target_include_directories(vde_foundation PUBLIC "${CMAKE_SOURCE_DIR}/third_party/ViewDesignEngine/include") +``` + +## 建议修复方向 + +1. 使用 ${CMAKE_CURRENT_SOURCE_DIR}/../include 代替 ${CMAKE_SOURCE_DIR}/include +2. 使用 generator expression: $ +3. 支持作为子目录被 add_subdirectory 引入 +4. 考虑提供 CMake package config 文件 + +--- +*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。* diff --git a/docs/feedback/VDE-003.md b/docs/feedback/VDE-003.md new file mode 100644 index 0000000..99bd429 --- /dev/null +++ b/docs/feedback/VDE-003.md @@ -0,0 +1,30 @@ +--- +id: VDE-003 +status: open +severity: medium +category: compat +date: 2026-07-27 +reporter: ViewDesign +--- + +# VDE-003: std::fpos 运算符歧义（GCC C++20） + +## 问题描述 + +在 GCC + C++20 模式下，std::fpos 与整型之间的加减运算产生歧义。libstdc++ 的 定义了 operator-(streamoff, fpos) 和 operator+(streamoff, fpos)，但没有 operator-(fpos, streamoff)。而在 C++20 中新增了 reversed operator candidates，导致 fpos - int 产生多个候选重载。 + +## 影响文件 + +- src/foundation/io_3mf.cpp + +## ViewDesign 侧 Workaround + +通过 cmake/vde_gcc_compat.h 注入额外的运算符重载（注入 std 命名空间是 UB，仅作为临时方案）。 + +## 建议修复方向 + +1. 在 io_3mf.cpp 中避免 fpos - int 模式，先转换为 streamoff +2. 使用 static_cast(fpos) 消除歧义 + +--- +*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。* diff --git a/docs/feedback/VDE-004.md b/docs/feedback/VDE-004.md new file mode 100644 index 0000000..dc492fa --- /dev/null +++ b/docs/feedback/VDE-004.md @@ -0,0 +1,31 @@ +--- +id: VDE-004 +status: open +severity: medium +category: compat +date: 2026-07-27 +reporter: ViewDesign +--- + +# VDE-004: posix_memalign 在 MinGW 下缺失 + +## 问题描述 + +posix_memalign() 是 POSIX 标准函数，MinGW (Windows GCC) 不提供此函数。performance_tuning.cpp 中直接调用 posix_memalign 导致链接失败。 + +## 影响文件 + +- src/core/performance_tuning.cpp + +## ViewDesign 侧 Workaround + +通过 cmake/vde_gcc_compat.h 提供 MinGW 兼容实现（使用 _aligned_malloc）。 + +## 建议修复方向 + +1. 使用 #ifdef _WIN32 + _aligned_malloc / _aligned_free 做平台抽象 +2. 使用 C11 aligned_alloc +3. 使用 C++17 std::aligned_alloc + +--- +*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。* diff --git a/docs/feedback/VDE-005.md b/docs/feedback/VDE-005.md new file mode 100644 index 0000000..2d5991a --- /dev/null +++ b/docs/feedback/VDE-005.md @@ -0,0 +1,31 @@ +--- +id: VDE-005 +status: open +severity: medium +category: compat +date: 2026-07-27 +reporter: ViewDesign +--- + +# VDE-005: GCC 两阶段名称查找失败 (AABB3D/Point3D 等) + +## 问题描述 + +ViewDesignEngine 的大多数 .cpp 文件在 #include 后直接使用 AABB3D、Point3D、Vector3D 等类型别名，但没有显式 using 声明。MSVC 默认不执行两阶段名称查找，因此这些代码在 MSVC 下可以编译。GCC/Clang 严格遵循标准。 + +## 影响文件 + +- 所有 brep 和部分 core/mesh .cpp 文件 + +## ViewDesign 侧 Workaround + +通过 cmake/vde_gcc_compat.h 注入全局 using 声明。 + +## 建议修复方向 + +1. 在每个 .cpp 文件顶部添加必要的 using vde::core::Xxx 声明 +2. 在头文件中使用完全限定名 vde::core::AABB3D +3. 增加 GCC 编译 CI 检查 + +--- +*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。* diff --git a/docs/feedback/VDE-006.md b/docs/feedback/VDE-006.md new file mode 100644 index 0000000..7fb1fa6 --- /dev/null +++ b/docs/feedback/VDE-006.md @@ -0,0 +1,31 @@ +--- +id: VDE-006 +status: open +severity: high +category: design +date: 2026-07-27 +reporter: ViewDesign +--- + +# VDE-006: vde_mesh ↔ vde_brep 循环依赖 + +## 问题描述 + +vde_mesh → 依赖 vde_core, vde_brep；vde_brep → 依赖 vde_curves, vde_mesh, vde_collision。形成 vde_mesh → vde_brep → vde_curves → (vde_core) → vde_mesh 的循环依赖。由于是 STATIC library 不会直接报链接错误，但模块拆分不够清晰。 + +## 影响文件 + +- src/CMakeLists.txt (line 111, 231) + +## ViewDesign 侧 Workaround + +vd_geom 仅链接 vde_foundation 和 vde_core，避开整个 brep/mesh/curves 依赖树。 + +## 建议修复方向 + +1. 将 vde_mesh 和 vde_brep 的共享依赖提取到独立模块 +2. 重新设计依赖关系：vde_mesh 不应依赖 vde_brep +3. 考虑引入 abstract interface / type erasure 打破循环 + +--- +*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。* diff --git a/docs/feedback/VDE-007.md b/docs/feedback/VDE-007.md new file mode 100644 index 0000000..e7acae7 --- /dev/null +++ b/docs/feedback/VDE-007.md @@ -0,0 +1,34 @@ +--- +id: VDE-007 +status: open +severity: low +category: api +date: 2026-07-27 +reporter: ViewDesign +--- + +# VDE-007: transform.h 缺少 mirror() 函数 + +## 问题描述 + +vde::core::transform.h 提供了 translate(), rotate(), rotate_x/y/z(), scale() 等变换函数，但缺少 mirror() / reflect() 镜像变换函数。这在 CAD 软件中是常用操作（如镜像零件、对称建模）。 + +## 影响文件 + +- include/vde/core/transform.h + +## ViewDesign 侧 Workaround + +在 vd_geom 的 Transform 类中用裸 Eigen 构造镜像矩阵： + +```cpp +Eigen::Matrix3d refl = Eigen::Matrix3d::Identity() - 2.0 * n * n.transpose(); +``` + +## 建议修复方向 + +1. 添加 mirror(const Vector3D& normal) 函数 +2. 添加 mirror(const Plane& plane) 函数 + +--- +*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。* diff --git a/docs/feedback/VDE-008.md b/docs/feedback/VDE-008.md new file mode 100644 index 0000000..f13c5fb --- /dev/null +++ b/docs/feedback/VDE-008.md @@ -0,0 +1,30 @@ +--- +id: VDE-008 +status: open +severity: low +category: design +date: 2026-07-27 +reporter: ViewDesign +--- + +# VDE-008: StlTriangle 使用 Point3f (Eigen Matrix) 而非结构体 + +## 问题描述 + +StlTriangle 结构的顶点成员类型为 Point3f，而 Point3f = Eigen::Matrix。访问坐标需要使用 operator[] 而非 .x, .y, .z。Eigen::Matrix 的 operator[] 访问不如 .x() 语义清晰。 + +## 影响文件 + +- include/vde/foundation/io_stl.h + +## ViewDesign 侧 Workaround + +在 FileExporter 中同时支持两种访问方式，转换时显式处理 pts[j][0]。 + +## 建议修复方向 + +1. 为 StlTriangle 提供 .v0, .v1, .v2 带 .x(), .y(), .z() 的包装 +2. 使用自定义结构体代替裸 Eigen 类型 + +--- +*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。* diff --git a/docs/feedback/VDE-009.md b/docs/feedback/VDE-009.md new file mode 100644 index 0000000..c50d9d2 --- /dev/null +++ b/docs/feedback/VDE-009.md @@ -0,0 +1,32 @@ +--- +id: VDE-009 +status: open +severity: medium +category: doc +date: 2026-07-27 +reporter: ViewDesign +--- + +# VDE-009: 缺少 C API 文档和示例 + +## 问题描述 + +ViewDesignEngine 提供了 C API (vde_capi) 用于跨语言绑定，但头文件没有详细文档注释；没有使用示例；不清楚每个函数的输入/输出约定（谁分配内存，谁释放）；集成时只能通过阅读源码理解 API 用法。 + +## 影响文件 + +- include/vde/capi/vde_capi.h +- src/capi/vde_capi.cpp + +## ViewDesign 侧 Workaround + +暂无，需要通过阅读源码理解 API。 + +## 建议修复方向 + +1. 为 vde_capi.h 添加 doxygen 文档 +2. 提供 examples/capi/ 目录下的使用示例 +3. 文档化内存管理约定（调用者 vs 库管理） + +--- +*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。* diff --git a/docs/feedback/VDE-010.md b/docs/feedback/VDE-010.md new file mode 100644 index 0000000..0a91811 --- /dev/null +++ b/docs/feedback/VDE-010.md @@ -0,0 +1,30 @@ +--- +id: VDE-010 +status: open +severity: high +category: compat +date: 2026-07-27 +reporter: ViewDesign +--- + +# VDE-010: brep 模块未适配 MSVC 两阶段查找 + +## 问题描述 + +虽然在 MSVC 下通过 /permissive- 关闭宽松模式后可以部分改善，但 ViewDesignEngine 的 CMakeLists.txt 并未设置此标志。当前的 permissive 模式使得代码在 MSVC 下编译通过但不可移植。 + +## 影响文件 + +- src/brep/*.cpp (全部) + +## ViewDesign 侧 Workaround + +不编译 vde_brep 目标，仅使用 vde_foundation + vde_core。 + +## 建议修复方向 + +1. 添加显式 using 声明，适配严格 C++ 标准 +2. 在 CMakeLists.txt 中设置 /permissive- 标志 + +--- +*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。* diff --git a/docs/feedback/VDE-011.md b/docs/feedback/VDE-011.md new file mode 100644 index 0000000..88fc096 --- /dev/null +++ b/docs/feedback/VDE-011.md @@ -0,0 +1,35 @@ +--- +id: VDE-011 +status: open +severity: medium +category: api +date: 2026-07-27 +reporter: ViewDesign +--- + +# VDE-011: write_stl / write_stl_ascii 返回 void + +## 问题描述 + +write_stl() 和 write_stl_ascii() 的返回类型为 void，调用者无法判断写入是否成功。规范的做法是返回 bool 或抛出异常（如 read_stl 所做的）。函数签名： + +```cpp +void write_stl(const std::string& filepath, const std::vector& tris); +``` + +## 影响文件 + +- include/vde/foundation/io_stl.h + +## ViewDesign 侧 Workaround + +调用后假定成功，返回 true。 + +## 建议修复方向 + +1. 改为返回 bool（或 std::expected 在 C++23） +2. 像 read_stl 一样在失败时抛出 std::runtime_error +3. 至少应在文档中说明该函数如何报告写入失败 + +--- +*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。* diff --git a/docs/feedback/VDE-012.md b/docs/feedback/VDE-012.md new file mode 100644 index 0000000..db7cffb --- /dev/null +++ b/docs/feedback/VDE-012.md @@ -0,0 +1,36 @@ +--- +id: VDE-012 +status: open +severity: low +category: design +date: 2026-07-27 +reporter: ViewDesign +--- + +# VDE-012: StlTriangle 使用 double 精度，与 float 网格顶点不匹配 + +## 问题描述 + +StlTriangle 使用 Vector3D 和 Point3D（Eigen::Vector3d，double 精度）存储法向量和顶点。但实际使用中，网格数据通常为 float 精度。从 float 到 double 再到 float 的转换需要显式 static_cast，且 Eigen 不允许 float/double 之间的隐式类型转换。 + +## 影响文件 + +- include/vde/foundation/io_stl.h + +## ViewDesign 侧 Workaround + +显式转换： + +```cpp +vde::foundation::Point3D p0{static_cast(v0.x), static_cast(v0.y), static_cast(v0.z)}; +``` + +读回时再转回 float。 + +## 建议修复方向 + +1. 考虑提供 StlTrianglef（float 精度）和 StlTriangled（double 精度）两种类型 +2. 使用模板 StlTriangle 支持两种精度 + +--- +*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。* diff --git a/docs/feedback/VDE-013.md b/docs/feedback/VDE-013.md new file mode 100644 index 0000000..6134858 --- /dev/null +++ b/docs/feedback/VDE-013.md @@ -0,0 +1,32 @@ +--- +id: VDE-013 +status: open +severity: medium +category: build +date: 2026-07-27 +reporter: ViewDesign +--- + +# VDE-013: CMake 不提供按模块控制构建的选项 + +## 问题描述 + +ViewDesignEngine 的 CMakeLists.txt 将所有模块（foundation, core, curves, mesh, brep, spatial, boolean, collision, sketch, sdf, capi）统一构建，不提供单独启用/禁用各模块的选项。当作为子模块被引入时，如果某个模块（如 brep）存在编译问题，整个父工程构建都会失败。 + +## 影响文件 + +- CMakeLists.txt +- src/CMakeLists.txt + +## ViewDesign 侧 Workaround + +在父工程 CMakeLists.txt 中设置 EXCLUDE_FROM_ALL 属性手动排除不需要的模块。 + +## 建议修复方向 + +1. 添加 VDE_BUILD_CURVES, VDE_BUILD_MESH, VDE_BUILD_BREP 等 option +2. 像 CGAL 那样提供 component-based find_package 机制 +3. 使每个模块可以独立 add_subdirectory + +--- +*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。*