docs: feedback from ViewDesign integration (VDE-001~013)

2026-07-27 22:13:00 +08:00
parent 1aa753ba50
commit 5eb11fa501
14 changed files with 442 additions and 0 deletions
@@ -0,0 +1,17 @@
+# ViewDesignEngine 问题反馈
+
+> 此目录由 ViewDesign 工程自动生成。每个文件对应一个来自 ViewDesign 集成测试中发现的 VDE 问题。
+> 
+> 文件命名规则: `VDE-{编号}.md`
+> 
+> 处理完成后，请在文件中更新 `status` 字段。
+
+## 状态图例
+
+| 状态 | 含义 |
+|------|------|
+| `open` | 待处理 |
+| `in_progress` | 处理中 |
+| `fixed` | 已修复 |
+| `wont_fix` | 不予修复 |
+| `deferred` | 延期 |
@@ -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 字段。*
@@ -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: $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../include>
+3. 支持作为子目录被 add_subdirectory 引入
+4. 考虑提供 CMake package config 文件
+
+---
+*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。*
@@ -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++ 的 <bits/ios_base.h> 定义了 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<streamoff>(fpos) 消除歧义
+
+---
+*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。*
@@ -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 字段。*
@@ -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 字段。*
@@ -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 字段。*
@@ -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 字段。*
@@ -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<float, 3, 1>。访问坐标需要使用 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 字段。*
@@ -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 字段。*
@@ -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 字段。*
@@ -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<StlTriangle>& tris);
+```
+
+## 影响文件
+
+- include/vde/foundation/io_stl.h
+
+## ViewDesign 侧 Workaround
+
+调用后假定成功，返回 true。
+
+## 建议修复方向
+
+1. 改为返回 bool（或 std::expected<void, Error> 在 C++23）
+2. 像 read_stl 一样在失败时抛出 std::runtime_error
+3. 至少应在文档中说明该函数如何报告写入失败
+
+---
+*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。*
@@ -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<double>(v0.x), static_cast<double>(v0.y), static_cast<double>(v0.z)};
+```
+
+读回时再转回 float。
+
+## 建议修复方向
+
+1. 考虑提供 StlTrianglef（float 精度）和 StlTriangled（double 精度）两种类型
+2. 使用模板 StlTriangle<T> 支持两种精度
+
+---
+*此文件由 ViewDesign 工程自动生成。处理完成后请更新 status 字段。*
@@ -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 字段。*