feat: 拆分 STEP 编辑器并完善最小系统

将原来的 main.py/step_model.py 拆分为 step_editor 包，补充测量、同域高亮、模型修复、历史导出、槽宽/凸台/边长等 MVP 编辑能力，并更新 README 和忽略规则。

README.md

@@ -12,8 +12,9 @@
 - 展示三维模型，支持旋转、缩放、平移。
 - 读取 STEP 中的零件、装配、solid 等结构。
 - 用户可以选择零件、solid、面、边和局部几何特征。
+- 用户可以做基础测量，例如把两个拾取点或对象中心设为 A/B 并计算距离。
 - 程序可以识别孔、圆角、凸台、槽、壳体局部区域等候选特征。
-- 用户可以修改可控的局部特征，比如平面推拉、孔径调整、盲孔深度调整、凸台直径调整、边倒圆、边倒角和受限直线边长度调整。
+- 用户可以修改可控的局部特征，比如平面推拉、孔径调整、槽/半孔宽度调整、盲孔深度调整、凸台直径调整、边倒圆、边倒角和第一版直接边长调整。
 - 用户可以撤销/重做修改，避免实验性编辑一步做坏。
 - 用户可以导出修改后的完整模型。
 - 如果 STEP 文件里存在多个零件，用户可以只导出选中的某个零件。
@@ -55,14 +56,19 @@
   - Edge
   - Feature
 - 鼠标悬停对象会以红色预高亮，真正选中后会以黄色高亮。
+- `Face` 模式会把属于同一几何面的连续区域一起高亮；平面会按共面且投影范围相接/重叠查找，圆柱面会按同一实体内同轴、同半径且轴向连续/重叠查找，不再要求旧段和新段必须共享同一条拓扑 edge。例如推拉后侧壁被 OCCT 拆成上下多段 face，点击任意一段时都会把整片同域区域一起高亮。
+- 推拉后程序会尽量保留侧壁面区域的 `逻辑 Face ID`：即使 OCCT 把原来的一个侧壁拓扑 face 重建成上下两段，新旧两段也会绑定回推拉前那片侧壁的逻辑 ID。属性表会同时显示 `逻辑 Face ID` 和 `拓扑 Face ID`；前者面向用户选择和按 ID 定位，后者用于调试当前 B-Rep 拓扑。
+- 操作历史会记录 `target_logical_id` 和当时的拓扑 face id。点击历史记录定位 face / feature 时，会优先用逻辑 ID 找回当前模型中的整片面区域；撤销/重做快照也会保留这层逻辑 ID 映射。
 - 鼠标选择会按当前模式做就近映射；例如 `Edge` 模式点到面时，会自动选择鼠标附近的边界 edge。
 - 支持按当前选择模式输入 ID 直接选择 Part / Solid / Face / Edge / Feature。
+- Face / Feature 按 ID 选择会优先解析 `逻辑 Face ID`。例如推拉前侧壁是 558，推拉后当前拓扑里变成 1556 和 1802，只要它们被绑定到逻辑 558，输入 558 就会选中这片面区域。
 - `鼠标选择模式` 下拉框不会响应鼠标滚轮，避免鼠标经过时误切换模式；需要点击后手动选择。
 - `按 ID 选择` 会在输入框和 `选择` 按钮之间同步显示当前鼠标选择模式。
 - `Feature` 模式现在会把点到的 face 解释为局部几何特征候选：
   - 平面会识别为可推拉平面候选。
+  - 平面会尝试查找同一 solid 内投影重叠的相对平面，用于估算薄壁/壳体局部区域厚度。
   - 圆柱面会识别为圆柱孔候选、槽/半孔候选、圆角/倒圆候选、凸台/外圆候选或未明确圆柱特征。
-  - 圆柱特征会尝试找出边界 edge、相邻 face、端面 face、开口端相邻 face 和疑似底面 face，并一起高亮相关局部区域。
+  - 圆柱特征会先把同一实体内同轴、同半径且轴向连续/重叠的完整圆柱 face 当作同一侧壁区域，再尝试找出边界 edge、相邻 face、端面 face、开口端相邻 face 和疑似底面 face，并一起高亮相关局部区域。
   - 槽/半孔候选会额外显示槽宽、圆弧长度、槽深估算和槽边界相邻 face。
   - 圆角/倒圆候选会额外显示已有圆角半径估算、圆弧角度、圆弧长度和相邻支撑 face。
 - 支持显示选中对象信息，并提供 `属性表` / `原始文本` 两种查看方式：
@@ -87,16 +93,22 @@
   - 直线 edge 的方向，圆弧 edge 的圆心、轴线、半径和直径。
 - 属性面板支持复制当前对象 ID、拾取坐标和完整信息。
 - 面/边属性查询带缓存；重复选择同一个对象会复用上次计算结果，模型编辑、撤销、重做或重新加载后缓存会自动清空。
-- 支持高亮选中的零件、solid、面、边或局部特征候选，并在鼠标悬停时用红色预览当前可选对象。
+- 支持高亮选中的零件、solid、面、边或局部特征候选，并在鼠标悬停时用红色预览当前可选对象；普通 Face 选择会对共面平面和同轴同半径圆柱面做同域区域高亮。
+- 默认模型边线渲染会隐藏同一平面或同一圆柱面内部的拓扑分割边，也会隐藏同域区域里几何位置重复的拼接边，减少布尔推拉后新旧侧壁交界处看起来像“两块拼起来”的视觉伤疤；`显示` 面板里的 `显示同域内部边` 可以临时打开完整拓扑边线。如果按 ID 或 Edge 模式专门选中这类内部 edge，仍然可以单独高亮查看。
 - 支持只显示当前选中对象、对准当前选中对象，并可一键恢复显示完整模型。
-- Feature 模式会在属性表里显示特征来源 face、侧壁 face、端面 face、疑似底面 face、开口端相邻 face、边界 edge 和当前可用操作。
+- 支持两点测量：
+  - 可以把当前选中对象的拾取点设为 A 或 B；如果没有拾取点，会退回使用对象中心、面积中心、长度中心、重心或包围盒中心。
+  - 设置 A/B 后会显示两点距离和 X/Y/Z 方向差值。
+  - 3D 视图中会显示一条青色测量线；测量结果可以复制，加载新模型时会自动清除旧测量。
+- Feature 模式会在属性表里显示特征来源 face、侧壁 face、同域圆柱范围、端面 face、疑似底面 face、开口端相邻 face、边界 edge 和当前可用操作。
 - 支持导出当前完整模型为 STEP。
 - 支持导出选中的 part 为 STEP。
 - 支持导出选中的 solid 为 STEP。
-- 支持导出选中的 face 为 STEP。
+- 支持导出选中的 face / 同域面区域为 STEP；如果当前 face 与共面或同轴同半径的相邻面一起高亮，导出也会包含整片黄色区域。
 - 支持导出选中特征区域为 STEP。
 - 支持导出选中的 edge 为 STEP。
 - 支持导出质量检查：导出前会检查 B-Rep 有效性、solid / face / edge 数量、体积和包围盒；如果发现风险，会先弹窗确认。
+- 支持一键修复当前模型或选中零件/solid：执行 ShapeFix 和同域面/边合并，修复会进入后台编辑流程，并支持撤销/重做。
 - 导出完整模型、part 或 solid 前，会先尝试执行 ShapeFix 和同域面/边合并，减少外部 CAD 打开时出现碎面、坏体或明显拼接痕迹的概率。
 - 实验性编辑按钮会根据当前选中对象自动启用或禁用，并通过悬停提示说明为什么当前操作不可用，减少 face、edge、孔、凸台、盲孔等对象混用导致的误操作。
 - 支持扫描第一版可编辑对象：
@@ -104,13 +116,14 @@
   - `深度扫描` 会尝试列出更多候选，适合默认列表里没有找到目标对象时使用。
   - 可推拉的平面 face。
   - 可调整孔径的圆柱 face 候选。
+  - 可调整槽/半孔宽度的局部圆柱孔/槽候选。
   - 可调整盲孔深度的圆柱 face 候选。
   - 可添加新圆角的直线 edge 候选。
   - 可添加倒角的直线 edge 候选。
   - 可尝试通过端面推拉调整长度的直线 edge 候选。
   - 表格会显示当前值、状态、风险、置信度和说明。
   - 盲孔深度候选会在列表阶段先确认疑似底面，列表里的深度值优先使用底面 face 轴向位置计算。
-  - 点击表格行会直接选中对应 face 或 edge，方便继续执行推拉、孔径调整、盲孔深度调整、边倒圆、边倒角或受限直线边长度调整。
+  - 点击表格行会直接选中对应 face 或 edge，方便继续执行推拉、孔径调整、槽/半孔宽度调整、盲孔深度调整、边倒圆、边倒角或直接边长调整。
 - 支持列出圆柱面候选特征。
 - 圆柱候选会显示在表格中，点击候选行可以直接选中并高亮对应 face。
 - 圆柱候选可以按类型筛选：全部、孔/槽候选、圆角候选、凸柱/外圆候选、未明确分类。
@@ -126,13 +139,15 @@
 - 实验性支持平面 face 推拉。
 - 平面推拉会自动判断面两侧的 inside / outside，输入正数表示向外加料，输入负数表示向内切削。
 - 推拉平面会先显示半透明预览体，表示推拉方向和大致范围，然后在后台执行真实 OCCT 布尔计算。
-- 推拉平面现在会从选中 face 出发，自动查找共享边且共面的相邻 face，并把它们作为同一片平面区域一起推拉。
+- 推拉平面现在会从选中 face 出发，自动查找共面且相接/重叠的相邻 face，并把它们作为同一片平面区域一起推拉。
 - 这可以减少 STEP 碎面导致的“只推了一小块，导出后像贴上去一块，中间有伤疤”的情况。
+- 如果选中的平面被识别为完整圆柱端盖，并且是向外拉长，程序会优先使用“完整旧段 + 新段圆柱”的专用 Fuse 路线，而不是只把一个短圆柱 prism 拼到端面上。简单圆柱场景下，这会让拉长结果保持为一个连续圆柱侧面，减少新旧圆柱段拼接痕迹。
 - 推拉加料时，工具体会向原实体内部保留一个很小的重叠量，再执行 Fuse，避免只靠两个面贴合导致导出后像“原模型 + 新增块”叠在一起。
 - Fuse/Cut 完成后会执行更强的推拉结果清理：按模型尺寸设置小容差，显式禁止保留 internal edges，并多轮执行 OCCT 同域面/边合并，减少第三方 CAD 中出现不必要共面分割线的概率。
+- 布尔计算前会启用 OCCT glue/fuzzy 选项，布尔后会调用 `SimplifyResult` 和同域合并；但某些 CAD/OCCT 场景仍可能保留拓扑分割边。当前程序会先在选择层把同域平面/圆柱区域作为整体高亮，并在默认边线渲染中隐藏同域内部拓扑边和几何重复拼接边；真正从 STEP/B-Rep 拓扑里消除这类分割边，还需要后续做更专门的局部圆柱/侧壁重建。
 - 如果推拉本身产生了真实台阶边界，第三方 CAD 仍会显示这条几何边；清理只能减少不必要的共面残留边，不能消除真实形状边界。
-- 推拉平面会先生成操作计划：检查距离是否为 0、方向置信度和相对 face 尺寸的风险；高风险会先弹窗确认。
-- 调整圆柱孔径也会先显示半透明预览体：红色表示切削 cutter，绿色表示缩小孔径时的补料范围。
+- 推拉平面会先生成操作计划：检查距离是否为 0、方向置信度和相对 face 尺寸的风险；能推拉时直接执行，不能推拉时会提示阻止原因。
+- 调整圆柱孔径也会先显示半透明预览体：红色表示切削 cutter，绿色表示缩小孔径时的补料范围；如果圆柱侧壁被拆成多段同域 face，工具范围会优先覆盖整段同域圆柱。
 - 支持第一版盲孔/盲槽深度调整：
   - 只对 `hole/groove candidate` 且端部类型为 `blind`、并识别到疑似底面 face 的圆柱候选开放。
   - 目标深度大于当前估算深度时，会沿开口到疑似底面方向用有限长度 cutter 加深切削。
@@ -145,6 +160,10 @@
   - 会估算槽宽、圆弧长度和槽深。
   - 会识别槽圆柱 face 和槽边界相邻 face，并在 Feature 模式下一起高亮。
   - 这些仍是 B-Rep 几何估算，不是 CAD 历史里的槽特征参数。
+- 支持第一版槽/半孔宽度调整：
+  - 只对已识别为 `partial-cylindrical-groove` 的部分圆柱孔/槽候选开放。
+  - 输入目标槽宽后，会按当前圆弧角度把槽宽换算为目标圆柱直径，再复用圆柱孔/槽重建路线执行。
+  - 这不是完整 CAD 槽参数编辑；复杂槽、非圆柱槽或圆弧角度不稳定时仍可能失败并回滚。
 - 支持第一版已有圆角/倒圆候选结构化识别：
   - 对局部小半径圆柱面，会标记为 `round/fillet candidate`。
   - 会估算已有圆角半径、圆弧角度和圆弧长度。
@@ -161,9 +180,9 @@
 - 支持第一版圆柱凸台直径调整：
   - 只对 `boss/outer-round candidate` 且角度跨度接近完整圆柱的凸台开放。
   - 不处理局部外圆角、圆角面或未明确圆柱面，避免把圆角当凸台修改。
-  - 目标直径变大时，会生成目标直径圆柱并 Fuse。
-  - 目标直径变小时，会生成环形 cutter 并 Cut。
-  - 会先显示半透明预览：绿色表示扩大补料范围，红色表示缩小切削范围。
+  - 目标直径变大时，会在同域圆柱侧壁范围内生成目标直径圆柱并 Fuse。
+  - 目标直径变小时，会先用旧外形包络体移除原凸台范围，再 Fuse 目标直径圆柱重建，避免环形 cutter 在部分场景下把实体切空。
+  - 会先显示半透明预览：绿色表示扩大/重建补料范围，红色表示缩小移除范围。
   - 当前默认模型可能没有明确凸台候选；包含完整圆柱凸台的 STEP 文件可以使用这个能力。
 - 支持第一版直线边添加圆角：
   - 只对直线 edge 开放。
@@ -178,13 +197,15 @@
   - 橙色半透明预览表示目标 edge 和输入倒角距离的大致范围。
   - 真实编辑使用 OCCT `BRepFilletAPI_MakeChamfer` 在后台执行。
   - STEP 没有建模历史，某些边仍可能被 OCCT 拒绝；失败时会自动尝试恢复编辑前状态。
-- 支持第一版受限直线边长度调整：
-  - 只对直线 edge 开放。
-  - 选中直线 edge 后，`边目标长度` 会自动填入当前边长。
-  - 输入目标长度后，程序会尝试寻找这条边端点附近、方向匹配的平面端面。
-  - 找到端面后，会把“改边长”转换成该端面的平面推拉操作，并显示蓝绿色半透明预览。
-  - 如果找不到可靠端面，或者目标长度无效，会直接阻止，不会强行修改。
-  - 这不是通用参数化边长编辑；复杂拓扑、斜面过渡、圆角链或没有明确端面的边仍可能不能改。
+- 支持第一版直接边长调整：
+  - 选中 edge 后，`边目标长度` 会自动填入当前边长。
+  - 可以选择边长基准：自动、中心、固定起点、固定终点。
+  - 直线 edge 会优先尝试寻找端点附近、方向匹配的平面端面，并把“改边长”转换成该端面的平面推拉操作。
+  - `自动` 会优先选择可局部推拉的端面；`固定起点` / `固定终点` 会优先尝试移动另一端端面。
+  - 圆形/圆弧 edge 会优先检查相邻圆柱面；如果能复用孔/槽或凸台直径编辑，就把目标边长按比例换算成目标圆柱直径再执行局部编辑。
+  - `中心`、没有明确端面、或圆边没有可复用圆柱面时，会尝试整体/轴向几何缩放 fallback，以覆盖更多任意 edge 的最小可用场景。
+  - 该 fallback 会影响所属 part/solid 的其它尺寸，因此会按高风险确认，并依赖失败回滚/撤销兜底。
+  - 这仍不是通用参数化边长编辑；复杂拓扑、斜面过渡、圆角链或布尔失败场景仍可能不能稳定修改。
 - 支持 part / solid 级平移：
   - 输入 X/Y/Z 平移量后，可以平移当前选中零件。
   - 选中 solid、或选中属于某个 solid 的 face/edge 后，可以平移当前 solid。
@@ -195,7 +216,8 @@
   - 第一版旋转中心取目标对象的包围盒中心。
   - 单 solid 零件中旋转 solid 实际等同于旋转整个 part shape，程序会按中风险提示。
   - 旋转操作会写入历史记录，并支持撤销/重做。
-- 后台编辑计算时会显示进度提示，主界面会暂时置灰，并阻止选择、扫描、导出、撤销/重做、历史详情查看或关闭窗口。
+- 后台编辑计算时不再弹出模态进度框，也不再把主界面整体置灰；UI 线程只负责渲染和响应基础视图交互，真实 B-Rep 编辑在后台线程执行。
+- 编辑计算期间，半透明预览会继续在 3D 视图里渲染，用户可以旋转或缩放查看；会改变模型状态的操作仍会暂时禁用，避免同一模型被多个后台编辑同时修改。
 - 真实 B-Rep 结果会在布尔计算完成后一次性刷新；半透明预览不等于最终几何结果。
 - 如果后台编辑失败，程序会自动尝试恢复到编辑前快照，避免出现“提示失败但模型已经被部分改动”的状态。
 - 实验性支持圆柱孔/圆柱面扩大切削。
@@ -233,6 +255,7 @@
 - 支持导出选中操作历史的差异报告，报告会包含操作参数、拓扑变化、几何变化和热力图统计。
 - 鼠标拾取模型时会显示三维拾取点坐标。
 - 实验性编辑历史会记录目标对象和当时的拾取点。
+- 支持把本软件加载后的编辑历史导出为 JSON；这不是 STEP 原始 CAD 建模历史，而是后续操作留档。
 - 点击操作历史记录时，程序会尝试重新高亮目标对象，并显示当时的拾取点标记。
 - 对非 `hole/groove candidate` 的圆柱切削会先弹出确认，避免误切外圆角或凸柱。
 - 提供 `--smoke-test` 启动检查，用于验证 Qt + VTK 窗口组件能正常初始化。
@@ -258,28 +281,27 @@ vertices: 3262
 
 - 复杂特征识别：已经有平面、圆柱、边、孔/槽候选、槽/半孔候选、已有圆角候选、圆柱凸台候选等基础候选列表，但还不是完整 CAD 语义级识别。
 - 盲孔/盲槽深度：已经能对部分可识别候选做深度估算和编辑，并会优先使用疑似底面 face 的轴向位置计算当前深度；但还不能保证所有模型都能恢复真实 CAD 语义深度。
-- 槽、凸台、壳体局部区域：已经有圆柱孔、槽/半孔候选结构化识别、完整圆柱凸台直径修改，复杂槽、复杂凸台和壳体局部区域仍需要继续做。
+- 槽、凸台、壳体局部区域：已经有圆柱孔、槽/半孔候选结构化识别、槽/半孔宽度调整、完整圆柱凸台直径修改和平面薄壁/壳体相对面厚度估算；复杂槽、复杂凸台和完整壳体区域仍需要继续做。
 - 已有圆角/倒圆面半径：已经有第一版受限修改实现，使用 defeature + refillet 路线，但复杂 blend、支撑面不明确或恢复锐边失败时仍会阻止或回滚。
 - 局部偏差分析：已经有编辑前后体积、面积、包围盒、距离热力图和差异报告，但还不是工程公差级的局部区域偏差报告。
-- 错误恢复和模型修复：已经有编辑前快照、失败回滚、基础 B-Rep 校验、同域面合并和布尔结果自动修复，但还不是完整的模型修复流水线。
+- 错误恢复和模型修复：已经有编辑前快照、失败回滚、基础 B-Rep 校验、同域面合并、布尔结果自动修复，以及一键修复当前模型或选中零件/solid，但还不是完整的模型修复流水线。
 - 多零件装配：已经有装配/零件树和单独导出入口，但还没有做大规模、多来源 STEP 装配测试。
 
 仍基本没有实现，或者 STEP 本身不一定能可靠支持：
 
-- 通用任意边长直接修改。当前只有第一版受限直线边长度调整，会尝试通过端面推拉来改变长度；没有明确可推拉端面的边仍不能改。
-- 参数化建模历史恢复。STEP 通常只保存结果几何/拓扑，不能稳定还原原 CAD 软件里的建模历史，只能在本程序里记录后续编辑历史，或做近似的特征语义识别。
+- 参数化建模历史恢复。STEP 通常只保存结果几何/拓扑，不能稳定还原原 CAD 软件里的建模历史；当前只能在本程序里记录并导出后续编辑历史，或做近似的特征语义识别。
 - 所有场景都稳定的复杂特征识别。
 
 ## 下一步要实现什么
 
 建议下一步按这个顺序推进：
 
-1. 继续加固最小可用编辑闭环：选择、预览、执行、校验、修复、回滚、导出。
-2. 继续验证平面推拉、孔径调整、盲孔/盲槽深度调整和圆柱凸台直径调整，记录哪些对象稳定、哪些对象会失败。
+1. 继续补齐更多最小可用特征入口，优先覆盖复杂槽、复杂凸台、局部薄壁/壳体区域和装配用例。
+2. 继续验证平面推拉、孔径调整、槽/半孔宽度调整、盲孔/盲槽深度调整、圆柱凸台直径调整和直接边长调整，记录哪些对象稳定、哪些对象会失败。
 3. 改进盲孔/槽底面识别，减少“看起来像 blind 但找不到可靠底面 face”的候选。
 4. 继续加固已有圆角半径修改：扩大可成功场景，记录哪些圆角能 defeature + refillet，哪些需要更复杂的重建策略。
-5. 继续增加复杂槽、复杂凸台、局部区域识别。
-6. 优化导出策略，例如导出时保留更多名称、颜色和层级信息。
+5. 完善本软件编辑历史的导入/复放能力，让后续编辑不只是导出 JSON 留档。
+6. 最后集中做性能和稳定性优化，包括首次加载后台精细化、扫描节流和高风险 OCC 操作隔离。
 
 ## 怎么运行
 
@@ -372,11 +394,24 @@ python main.py --smoke-test
 左侧 `显示` 用来临时缩小三维视图范围：
 
 - `只显示选中`：只显示当前选中的 part、solid、face、edge 或 feature 区域。
+- Face 模式下 `只显示选中` 会隔离当前黄色同域面区域，并显示这片区域的外边界 edge。
 - `对准选中`：不改变显示范围，只把相机对准当前选中的 part、solid、face、edge 或 feature，适合快速查看小孔、小边和局部特征。
 - `显示全部`：恢复显示完整模型。
+- `显示同域内部边`：默认关闭，用来隐藏同一平面/同一圆柱面内部的拓扑分割边和几何重复拼接边；打开后可以查看完整 B-Rep 拓扑边线，适合调试布尔推拉后的分面情况。
+- `导出选中面区域` 会导出当前 Face 模式黄色高亮的同域面区域，而不是只导出鼠标点到的单个拓扑 face。
 - solid / edge 的显示查询已经使用拓扑索引，避免每次隔离或高亮时反复全模型查找。
 - 这是视图操作，不会修改 STEP 几何，也不会写入操作历史。
 
+左侧 `测量` 用来做最基础的点到点距离检查：
+
+- 先在模型中点击一个对象或具体位置，然后点击 `设为 A`。
+- 再点击另一个对象或位置，然后点击 `设为 B`。
+- 如果选择来自鼠标点击，测量会优先使用实际拾取点；如果是从结构树或 ID 选择，程序会使用对象中心、面积中心、长度中心、重心或包围盒中心。
+- 设置 A/B 后会显示两点距离和 `ΔX/ΔY/ΔZ`。
+- 3D 视图里会显示一条青色测量线，方便确认测量方向。
+- `复制测量` 会复制当前测量结果；`清除测量` 会清空 A/B 和测量线。
+- 测量不会修改模型，也不会写入操作历史。
+
 左侧 `第一版可编辑对象` 是当前 MVP 的主要入口：
 
 - 点击 `扫描可编辑对象` 会列出当前第一版能尝试编辑的对象。
@@ -385,6 +420,7 @@ python main.py --smoke-test
 - 当前默认显示一批代表性的可编辑候选，详细几何判断会尽量延后到选中对象或执行编辑前，避免扫描过慢。
 - `推拉平面` 行表示这个 face 是平面，可以配合 `面偏移` 和 `推拉平面` 使用。
 - `调整圆柱孔径` 行表示这个 face 是圆柱候选，可以配合 `孔直径` 和 `调整圆柱孔径` 使用。
+- `调整槽/半孔宽度` 行表示这个 face 是槽/半孔候选，可以配合 `槽/半孔宽度` 和 `调整槽/半孔宽度` 使用。
 - `调整圆柱凸台直径` 行表示这个 face 是较明确的完整圆柱凸台候选，可以配合 `凸台直径` 和 `调整圆柱凸台直径` 使用。
 - `封堵圆柱孔` 行表示这个 face 是接近完整圆柱的孔候选，可以点击后直接使用 `封堵圆柱孔`。
 - `调整盲孔深度` 行表示这个 face 是较明确的盲孔/盲槽候选，可以配合 `孔深度` 和 `调整盲孔深度` 使用。
@@ -398,6 +434,7 @@ python main.py --smoke-test
 选择对象后：
 
 - 鼠标经过对象时会出现红色预高亮；被选对象会显示为黄色高亮。
+- 在 `Face` 模式下，如果相邻 face 属于同一几何面，并且投影范围或轴向范围相接/重叠，程序会把它们作为同域区域一起红色预高亮和黄色选中高亮；这主要用于缓解平面/圆柱推拉后视觉上被拓扑边分成多段的问题。
 - 如果处于 `Feature` 模式，程序会尽量高亮这个特征相关的局部区域，例如圆柱侧壁、相邻端面和槽边界相邻面。
 - 对槽/半孔候选，属性表会显示 `槽宽估算`、`槽圆弧长度估算`、`槽深估算` 和 `槽边界相邻 Face`。
 - 对圆角/倒圆候选，属性表会显示 `已有圆角半径估算`、`已有圆角圆弧角度`、`已有圆角圆弧长度估算` 和 `已有圆角支撑 Face`。
@@ -438,6 +475,8 @@ python main.py --smoke-test
 - `导出选中特征区域`：先切换到 `Feature` 选择模式并选中局部特征，再导出当前特征高亮的 face 集合。
 - `导出选中 edge`：先切换到 `Edge` 选择模式并选中一个 edge，再导出该 edge。
 - `检查导出质量`：检查当前选中对象；如果没有选中对象，就检查当前完整模型。
+- `修复当前模型`：对当前完整模型执行 ShapeFix 和同域面/边合并，完成后会刷新显示并写入操作历史；如果修复失败，会尝试回滚到修复前状态。
+- `修复选中零件/solid`：优先修复当前选中对象所属 solid；如果当前对象没有 solid，则修复所属零件。face 或 edge 被选中时，也会按其所属 solid/零件执行局部修复。
 - 导出按钮会根据当前选中对象自动启用或禁用，避免选中 face 时误点 `导出选中 edge` 这类不匹配的操作。
 - 所有导出按钮都会先做质量检查。发现 B-Rep 无效、没有 solid、零件包含多个 solid、体积接近 0 等风险时，会先弹窗确认是否继续导出。
 
@@ -451,7 +490,7 @@ python main.py --smoke-test
   - 负数表示沿内侧方向切削。
   - 点击 `推拉平面` 后，会先出现半透明预览体；绿色表示向外加料方向，红色表示向内切削方向。
   - 如果距离为 0 会直接阻止；如果方向置信度低或距离相对 face 尺寸偏大，会先弹窗确认。
-  - 如果选中 face 周围有共享边且共面的碎面，程序会自动把这些 face 合成同一片推拉区域，属性表和历史记录会显示 `推拉共面区域 Face 数`。
+  - 如果选中 face 周围有共面且相接/重叠的碎面，程序会自动把这些 face 合成同一片推拉区域，属性表和历史记录会显示 `推拉共面区域 Face 数`。
   - 加料时程序会让拉伸体和原实体产生极小重叠，并在布尔后尝试合并同域面/边，使导出的 STEP 更像一个整体实体。
   - 程序随后在后台执行真实布尔运算，完成后再刷新为真正修改后的模型。
   - 选中平面 face 后，可以在 `属性表` 的方向/轴线分组里查看 `推拉向外方向`、`推拉向内方向` 和 `推拉方向置信度`。
@@ -476,12 +515,18 @@ python main.py --smoke-test
   - 缩小孔径时，操作历史会额外记录补料策略、补料半径和补料高度。
   - 端部类型是通过轴线端部 inside / outside 采样得到的估算，不等于 CAD 原始建模历史里的“孔深”参数。
   - 如果选到的圆柱面不是孔，而是柱或圆角，结果可能不是你想要的，所以它目前仍是实验功能。
+- `槽/半孔宽度` + `调整槽/半孔宽度`：
+  - 先切换到 `Feature` 选择模式并选择一个槽/半孔候选 face，或从圆柱候选表中选择局部圆柱形 `hole/groove candidate`。
+  - 选中符合条件的槽/半孔后，`槽/半孔宽度` 会自动填入一个比当前槽宽估算略大的建议值。
+  - 输入目标槽宽后点击 `调整槽/半孔宽度`。
+  - 程序会用当前圆弧角度把目标槽宽换算成目标圆柱直径，再复用圆柱孔/槽调整流程。
+  - 这一步仍是 B-Rep 几何近似；复杂槽、非圆柱槽或圆弧角度不稳定时可能失败并回滚。
 - `凸台直径` + `调整圆柱凸台直径`：
   - 先选择一个完整圆柱凸台 face，建议从 `第一版可编辑对象` 中点击 `调整圆柱凸台直径` 行进入。
   - 只有接近完整圆柱的 `boss/outer-round candidate` 会放行；局部外圆角、圆角面、孔/槽和未明确圆柱面会被阻止。
-  - 目标直径大于当前直径时，会在选中圆柱面的轴向范围内生成目标直径圆柱并 Fuse。
-  - 目标直径小于当前直径时，会生成环形 cutter，把目标直径外侧到原直径附近的材料 Cut 掉。
-  - 点击后会显示半透明预览：绿色表示扩大补料范围，红色表示缩小切削范围。
+  - 目标直径大于当前直径时，会在同域圆柱侧壁范围内生成目标直径圆柱并 Fuse。
+  - 目标直径小于当前直径时，会先用旧外形包络体移除原凸台范围，再 Fuse 目标直径圆柱重建。
+  - 点击后会显示半透明预览：绿色表示扩大/重建补料范围，红色表示缩小移除范围。
   - 这不是 CAD 历史里的“修改凸台特征参数”，而是基于当前 B-Rep 的受限几何布尔编辑。
 - `封堵圆柱孔`：
   - 先选择一个完整圆柱孔 face，建议从 `第一版可编辑对象` 中点击 `封堵圆柱孔` 行进入。
@@ -527,14 +572,18 @@ python main.py --smoke-test
   - 真实编辑会在后台调用 OCCT 倒角 API，完成后刷新模型。
   - 当前只支持对称距离倒角，不支持两侧不同距离或距离+角度倒角。
   - 由于 STEP 不带建模历史，某些边会被 OCCT 判断为不适合倒角；失败时程序会提示并尝试恢复编辑前状态。
-- `边目标长度` + `调整直线边长度`：
-  - 先切换到 `Edge` 选择模式并选择一条直线 edge，或从 `第一版可编辑对象` 中点击 `调整直线边长度` 行进入。
-  - 选中直线 edge 后，`边目标长度` 会自动填入当前边长。
-  - 把它改成目标长度后点击 `调整直线边长度`。
-  - 程序会先查找该边端点附近是否有可推拉的平面端面，并计算需要移动的端面 face 和推拉距离。
-  - 通过检查后，会显示蓝绿色半透明预览，表示将要移动的端面推拉范围。
-  - 真实编辑复用平面推拉的布尔流程，执行失败时会回滚到编辑前状态。
-  - 如果这条边没有明确端面，或端面方向与边长变化不匹配，会被阻止。这是受限功能，不是任意边参数化改长。
+- `边目标长度` + `直接修改边长`：
+  - 先切换到 `Edge` 选择模式并选择一条 edge，或从 `第一版可编辑对象` 中点击边长相关行进入。
+  - 选中 edge 后，`边目标长度` 会自动填入当前边长。
+  - 右侧边长基准下拉框可以选择 `自动`、`中心`、`固定起点` 或 `固定终点`。
+  - 把它改成目标长度后点击 `直接修改边长`。
+  - 直线 edge 会优先查找端点附近是否有可推拉的平面端面，并计算需要移动的端面 face 和推拉距离。
+  - 圆形/圆弧 edge 会优先尝试复用相邻圆柱面的孔/槽或凸台直径编辑，并在确认窗口显示换算出来的目标直径。
+  - `固定起点` 会尽量让起点不动、移动终点侧；`固定终点` 相反；`中心` 会让缩放 fallback 以 edge 中心为基准。
+  - 如果没有明确端面或可复用圆柱面，程序会按所选基准尝试整体/轴向几何缩放 fallback；这会影响所属 part/solid 的其它尺寸，因此会弹出高风险确认。
+  - 通过检查后，会显示蓝绿色半透明预览，表示将要移动或缩放的范围。
+  - 真实编辑在后台执行，失败时会回滚到编辑前状态。
+  - 这是第一版 B-Rep 结果几何修改，不是任意边参数化改长。
 - `平移 X/Y/Z` + `平移选中零件` / `平移选中 solid`：
   - 输入 X、Y、Z 三个方向的平移量。
   - 选择 `Part` 后点击 `平移选中零件`，会移动整个 part。
@@ -564,20 +613,59 @@ python main.py --smoke-test
   - 历史详情会显示热力图统计，包括最大距离、平均距离和发生明显变化的采样点比例。
   - `清除差异预览` 可以关闭红/绿叠加显示。
   - `导出差异报告` 会把当前选中的历史记录导出为 `.txt`，里面包含操作详情、拓扑变化、几何变化和热力图统计。
+  - `导出编辑历史` 会把当前会话中的本软件编辑记录导出为 `.json`，用于留档和后续复盘。
   - 当前热力图是“编辑后模型顶点到编辑前模型表面”的距离估算，不是完整 CAD 公差报告。
   - 点击某条历史记录时，程序也会尝试重新高亮当时编辑的目标 face，并用青色小点标出当时的拾取位置。
   - 由于布尔编辑后拓扑 ID 可能重新分配，历史里的 face ID 只能作为定位参考，不能视为稳定的 CAD 建模历史 ID。
   - 撤销后对应记录会从列表里退回。
   - 重做后对应记录会重新显示。
 
-## 文件说明
+## 目录结构
+
+当前整理后的项目结构是：
+
+```text
+pythonocc-step-editor/
+  main.py                 # 程序入口，保持 python main.py 启动
+  docs/
+    screenshots/          # 调试截图和问题截图
+  step_editor/
+    __init__.py           # 包导出
+    app.py                # 主窗口初始化、UI 搭建和程序启动
+    constants.py          # OCCT 曲面、曲线和方向类型常量映射
+    export.py             # 导出、导出质量检查和面区域导出逻辑
+    features.py           # 平面、圆柱、孔、槽、凸台、圆角等候选识别和编辑计划
+    geometry_utils.py     # OCC 几何、拓扑、布尔修复、向量和形状工具函数
+    info_panel.py         # 属性面板、信息树和复制信息逻辑
+    model.py              # StepModel 核心状态、拓扑索引、基础属性和 mixin 组合
+    model_types.py        # PartNode、TopologyStats 等模型数据结构
+    operations.py         # 推拉、孔径、孔深、圆角、倒角、边长等实际编辑操作
+    polydata.py           # OCC shape / edge / face 到 VTK polydata 的显示数据生成
+    records.py            # 操作历史记录数据结构
+    step_io.py            # STEP/XCAF 读取、产品名解析和 STEP 写出
+    transforms.py         # part / solid 平移和旋转
+    ui_helpers.py         # UI 常量、格式化函数和 VTK 显示小工具
+    widgets.py            # 自定义 Qt 小组件
+    window_actions.py     # 导出、编辑按钮、扫描、后台编辑调度等窗口动作
+    window_core.py        # 文件加载、结构树、VTK 视图、选择、拾取、高亮和预览
+    window_state.py       # 选择状态、按钮状态、撤销/重做和历史定位
+    workers.py            # 后台编辑和后台扫描 worker
+  environment.yml         # Conda 环境说明，用于安装 pythonocc-core、VTK、PySide6 等依赖
+  geom_extract.step       # 当前默认测试模型
+  README.md               # 项目说明和使用说明
+```
+
+这次整理把根目录收窄到入口、环境配置、默认模型和文档，主要代码放到 `step_editor/` 包里；问题截图和调试截图放到 `docs/screenshots/`。后端和窗口层都按 mixin / 工具模块拆开，尽量不改变功能行为。
+
+`step_editor/model.py` 现在主要保留 StepModel 的核心状态、拓扑缓存、基础属性查询和 mixin 组合；具体能力分散到 `features.py`、`operations.py`、`export.py`、`transforms.py`、`polydata.py`、`step_io.py` 和 `geometry_utils.py`。
+
+`step_editor/app.py` 现在主要保留主窗口初始化、左侧操作面板搭建和程序入口；VTK 视图、选择高亮、编辑动作、扫描、撤销/重做和属性面板逻辑已经拆到 `window_core.py`、`window_actions.py`、`window_state.py`、`info_panel.py` 和 `ui_helpers.py`。
+
+其他文件说明：
 
-- `main.py`：程序入口和桌面界面。
-- `step_model.py`：STEP/OCCT 后端逻辑。
-- `environment.yml`：Conda 环境说明，用于安装 pythonocc-core、VTK、PySide6 等依赖。
 - `.gitignore`：Git 忽略规则，避免提交 Python 缓存、临时文件和导出的 STEP 文件。
-- `geom_extract.step`：当前默认测试模型。
-- `README.md`：项目说明和使用说明。
+- `*_edited.step`、`*_export.step`、`*_diff_*.txt`、`*_operation_history.json`：运行或导出时产生的结果文件，默认不提交。
+- `docs/screenshots/`：调试截图和问题截图，例如第三方软件显示效果、模型结构树截图等。
 
 ## 当前版本边界