Update MiniSW modeling features and tests

EDGE_TREATMENT_CAPABILITY_REPORT.md

@@ -0,0 +1,87 @@
+# M08/M09 F0：Manifold 内核能力探测报告
+
+日期：2026-08-10  
+范围：只读检查 `vendor/manifold/manifold.js`、`js/geometry.js` 与本地 Node/WASM 运行时；未修改生产源码，未启动浏览器、未下载依赖。
+
+## 结论
+
+**建议继续 F1（受限、纯网格的凸直棱倒角）进行原型验证；不建议直接进入 F2（实体圆角）的生产实现。**
+
+当前封装的 Manifold 能可靠执行网格构造、封闭性校验、布尔运算、切片和细分/平滑，但不提供可供 JavaScript 消费的 B-rep 拓扑面、拓扑棱边或原生 3D fillet/chamfer 算子。因此，真实倒角只能由 MiniSW 在 `MeshData` 层自行提取拓扑并重建网格；真实圆角还需要自行生成相切过渡面、处理边链与顶点角补片，风险显著更高。不得把 `smoothOut()` 当作实体圆角。
+
+本地 vendor 文件不含可识别的 npm/package 版本元数据，因此本报告以实际导出和运行时行为为准，不猜测版本号。
+
+## 基线与最小复现
+
+- 执行：`node --loader ./tests/loader.mjs ./tests/test.mjs`
+- 结果：64 通过、0 失败；几何内核初始化和既有实体布尔链路正常。
+- 运行时最小复现：`Manifold.cube([20,20,20], true)`，再调用 `getMesh()`、`decompose()`、`slice(0)`、`smoothOut()`、`refine(1)`，并在探测结束时手动释放全部创建的 WASM 对象。
+- 结果：立方体状态为 `NoError`，网格 8 顶点/12 三角形；`decompose()` 返回 1 个连通实体；`slice(0)` 返回 1 个二维多边形；`smoothOut()` 与 `refine(1)` 都返回 `NoError`。
+
+## 已确认能力
+
+| 能力 | 运行时接口/证据 | 对 M08/M09 的意义 |
+|---|---|---|
+| 网格读出 | `manifold.getMesh()` 返回 `vertProperties`、`triVerts`，并带可选 `faceID`、run/merge 数据 | 足以从 `MeshData` 合并共面三角形，自建拓扑面/边和稳定引用 |
+| 网格构造与校验 | `new mod.Mesh({...})` + `new mod.Manifold(mesh)`；`status()` | 重建后的倒角/圆角网格可交由 Manifold 拒绝非流形结果 |
+| 实体布尔 | `Manifold.union/difference/intersection`；现有 `geometry.js:booleanOp` 已统一封装 | 可用作工具体裁剪/并集的后备验证路线；不是原生边处理 |
+| 组件分解 | `manifold.decompose()` | 仅按连通组件拆分，**不是**面/边分解，不能直接用于边选择 |
+| 水平切片 | `manifold.slice(height)` 返回 `CrossSection`；`toPolygons()` 可读 | 可用于诊断或某些轴对齐特例；不能泛化为任意空间棱边圆角 |
+| 细分/简化 | `refine`、`refineToLength`、`refineToTolerance`、`simplify` | 可改善离散网格质量，但不创建保持半径的圆角 |
+| 平滑 | `smoothOut`、`smoothByNormals`、静态 `Manifold.smooth(mesh, sharpenedEdges)` | 是网格平滑/法线相关操作，非可控的几何圆角；不能用于 M09 验收 |
+| 其他几何诊断 | `numVert/numEdge/numTri`、`volume`、`surfaceArea`、`genus`、`rayCast`、`boundingBox` | 可支持结果验证、性能统计及视口边拾取的射线辅助 |
+| 二维偏移 | `CrossSection.offset(delta, joinType, ...)` | 只适用于 2D 截面；可服务某些专用工具体方案，不等于 3D 边偏移 |
+
+## 缺失能力与阻塞
+
+1. **没有 B-rep 面/边枚举或邻接 API。** `numEdge()` 仅给数量；运行时没有 `faces()`、`edges()`、`faceID()` 等可遍历三维拓扑接口。`getMesh().faceID` 是可选来源/运行标识，不能作为完整稳定的几何边引用。
+2. **没有原生 3D chamfer/fillet/offset API。** 在 `manifold.js` 的导出和 Manifold 原型中未发现 `chamfer`、`fillet`、三维 `offset` 或曲面过渡算子。
+3. **`decompose()` 不是拓扑分面。** 它返回连通 Manifold 组件，无法定位“立方体的一条棱”。
+4. **`slice(height)` 仅限全局 Z 高度。** 它不能围绕任意选中边产生局部截面。
+5. **平滑不保特征语义。** `smoothOut()`/`smoothByNormals()` 无半径、目标边链、相切条件或顶点补片参数；用它冒充 R5 会改变不该处理的面且无法保证尺寸。
+
+## 建议的 F1 可行路线：纯网格凸直棱倒角
+
+前提：首版只接受封闭、方向一致、凸多面体上的直边；先做单条棱，再扩展相互不接触的多条平行棱。算法由 `js/features/edge-treatment.js` 独立实现，主代理随后负责注入 `geometry.js/doc.js/UI`。
+
+1. 对 `MeshData` 以量化顶点坐标建立无向三角边表；合并共面的相邻三角形，得到逻辑平面与候选逻辑棱。
+2. 以相邻面法向、端点量化坐标、长度、二面角和凸性构造稳定边签名；重建时签名唯一匹配才解析，歧义或缺失必须明确报错。
+3. 对一条凸直棱，将其两侧面沿各自面内法向收缩，生成两条偏移边；以四边形（再三角化）替换原棱邻域，并处理端点局部拓扑。
+4. 严格检查倒角距离小于两侧可用面宽、未与其他待处理边冲突、输出无零面积三角形；构造后通过 `new mod.Manifold(new mod.Mesh(...)).status()` 做流形验收。
+5. 输出 `MeshData` 和边线段；WASM 对象只在主代理注入的上下文中创建和释放。
+
+该路线可产生真实 STL 几何，但端点补片、多个相交选择边和凹边会迅速增加组合复杂度；首版不应承诺它们。
+
+## F2 圆角评估
+
+圆角在同一拓扑框架上还需：按半径生成圆弧截面、沿直棱扫出相切曲面、替换两侧面条带、在端点/边链转角处生成角补片，并保证共享顶点、面朝向和流形性。Manifold 可验证并布尔组合结果，却不替代这些构造步骤。
+
+- **可验证的后备方案：** 仅对“贯穿整个实体、两端开放或端点可由明确平面封闭”的单条凸直棱，使用解析圆柱/四分之一圆柱工具体结合布尔差/并实现，并以截面、体积、流形状态验证。该方案仍需先可靠定位两相邻面与边局部坐标系。
+- **不可接受的方案：** 调用平滑 API、增加法线、仅在 Three.js 渲染高亮圆弧、或将草图圆角矩形改名。这些都不保证 STL 中存在真实 R 面。
+- **生产建议：** 在 F1 的拓扑提取、稳定引用、单边倒角、10 次重建稳定和独立网格流形测试完成前，暂停 F2。F2 首版范围应明确限制为立方体单条凸直棱 R 值，不承诺一般边链。
+
+## 风险、复杂度与继续条件
+
+| 项目 | 评估 |
+|---|---|
+| F1 单凸直棱倒角 | 中高复杂度；约 2–4 个实现/测试迭代，主要风险是端点补片和三角网格方向 |
+| F1 多边选择 | 高复杂度；必须先检测相邻/相交选择边，否则偏移区域会重叠 |
+| F2 单凸直棱圆角 | 高复杂度；需要圆柱曲面、两端补片、相切与半径上限校验 |
+| F2 共线边链/一般边链 | 很高复杂度；需链识别、交界拼接和顶点角策略，当前不宜在同一轮承诺 |
+| 性能 | 小型立方体可望低于 1 秒；必须设置三角数/分段数上限，避免无界细分 |
+
+继续 F1 的门槛：主代理认可“纯 MeshData 拓扑层”是 M08/M09 的正式基础，并允许先交付受限凸直棱功能。继续 F2 的门槛：F1 已通过闭合、体积、无退化三角形、稳定引用和 10 次重建测试；否则应以本报告记录技术阻塞，不做视觉伪实现。
+
+## 对主代理的接入提示
+
+F0 没有新增运行时代码或接口。若批准 F1，建议由子模块导出任务书中约定的 `extractTopology`、`makeStableEdgeRef`、`resolveEdgeRef`、`buildChamferMesh`；主代理再在 `geometry.js` 中以唯一已初始化的 `mod` 把 `MeshData` 转回 Manifold，并接入文档模型、拾取与序列化。
+
+## 后续实施结果
+
+本报告完成后，F1 的全部继续门槛已经通过，因此项目按报告建议继续了受限 F2：
+
+- M08 已实现凸多面体单条直棱的真实截切倒角、稳定引用和视口拾取。
+- M09 已实现凸多面体单条直棱的恒定半径多段圆柱过渡面；没有使用平滑 API。
+- 两者输出都使用共享索引的封闭 `MeshData`，并通过项目唯一 Manifold 内核的 `NoError`、正体积、无退化三角形和重复构建测试。
+- M08、M09 独立测试各 `5/5`，核心文档/AI/保存重建集成测试也已覆盖。
+- 安全范围仍严格限制为单条凸直棱；多边选择、边链、凹边和非凸实体按本报告风险结论明确拒绝。

PHASE1_M10_MANUAL_CHECKLIST.md

@@ -0,0 +1,77 @@
+# MiniSW 第一阶段 M10 手动验收清单
+
+日期：2026-08-10  
+状态：等待手动浏览器确认  
+说明：M01～M09 的代码与自动化验收已完成；本文件只保留必须由人工观察的界面、交互和课程演练项目。全部勾选后，才在 `ROADMAP.md` 中把 M10 标为完成。
+
+## 1. 启动与控制台
+
+- [ ] 双击 `启动.bat`，浏览器能打开 `http://127.0.0.1:8898/index.html`。
+- [ ] 启动页正常消失，视口、Ribbon、特征树、属性面板和 AI 面板均可见。
+- [ ] 浏览器开发者工具控制台没有红色异常；允许出现浏览器自身的性能提示。
+- [ ] 前视、上视、右视和等轴测方向与界面名称一致。
+
+## 2. AI 一句话轴承座
+
+在 AI 面板输入：
+
+> 生成一个120×80×12的轴承座，主体凸台直径60高32，中心通孔直径30，两条厚4mm加强筋，实体倒角和R4实体圆角
+
+验收：
+
+- [ ] AI 一次执行完成，不需要手工补特征。
+- [ ] 模型可见且没有错误提示，整体尺寸约为 `120×80×43 mm`。
+- [ ] 特征树依次包含：底板、实体倒角、实体圆角、主体凸台、左加强筋、右加强筋、中心通孔。
+- [ ] 参考几何中存在“筋定位基准面”。
+- [ ] 中心通孔使用“到下一面”而不是固定深度。
+- [ ] 模型上能观察到真实斜面倒角和多段圆弧过渡圆角。
+
+## 3. 参数编辑与重建
+
+- [ ] 右键左加强筋，进入特征参数编辑，把筋宽从 `4` 改为 `5`，确定后模型成功重建。
+- [ ] 编辑实体倒角距离，合法较小值能重建；过大值显示中文失败诊断而不是页面崩溃。
+- [ ] 编辑实体圆角半径或圆弧分段数，合法值能重建；过大半径显示中文失败诊断。
+- [ ] 编辑中心通孔，终止条件下拉框能看到固定深度、贯穿全部、对称、到下一面、到指定面和到实体。
+- [ ] 单击特征树中的新特征时，视口能显示对应高亮。
+
+## 4. 实体棱边拾取
+
+建议先新建一个简单长方体单独验证：
+
+- [ ] 点击“实体倒角”，再靠近长方体可见棱边单击，输入 `5` 后成功创建。
+- [ ] 点击“实体圆角”，选择另一条未处理凸直棱，输入 `5` 后成功创建。
+- [ ] 单击远离棱边的位置时，界面提示未拾取到棱边，不创建错误特征。
+- [ ] 对非凸复杂主体或不支持的多边选择，界面明确拒绝，不以光照平滑伪装成功。
+
+## 5. 保存、撤销与导出
+
+- [ ] 保存轴承座 JSON，刷新或关闭页面后重新打开，模型与特征树一致。
+- [ ] 修改一个新特征后执行撤销、重做，模型和参数能正确往返。
+- [ ] 导出 STL 成功，并能在外部查看器中打开；孔、筋、倒角和圆角均可见。
+- [ ] 打开一个第一阶段以前保存、没有 `references` 字段的旧工程，仍能正常重建。
+
+## 6. 演练记录
+
+- [ ] 完成一次从启动、AI 输入、参数编辑、保存到 STL 导出的连续课程作业演练。
+- [ ] 记录一段视频或至少四张截图：AI 输入、完整模型、特征树、STL 外部查看结果。
+- [ ] 在演练中没有持续卡顿、页面失去响应或连续重建后明显变慢。
+
+## 7. 自动化证据（已完成）
+
+- 核心综合测试：`94/94` 通过。
+- 七个第一阶段独立模块测试：`93/93` 通过。
+- 总计：`187/187` 通过。
+- AI 轴承座 Node 环境完整重建：约 `20～25ms`，预算 `<1000ms`。
+- 轴承座连续重建 `10` 次体积一致。
+- 轴承座保存/打开体积一致，STL 三角数与网格一致。
+- 旧版无 `references` 字段工程可重建。
+
+## 8. 最终签字
+
+- [ ] 上述人工项目全部通过。
+- [ ] 将 `ROADMAP.md` 中 M10 改为 `[x]`。
+- [ ] 将路线图当前状态改为“第一阶段完成，下一步进入阶段二 M11”。
+
+验收人：____________  
+验收日期：____________  
+备注：____________________________________________________________