docs: add desktop gui design spec

docs/superpowers/specs/2026-04-14-desktop-gui-design.md

@@ -0,0 +1,343 @@
+# STP2GLB 本地桌面界面设计
+
+## 1. 背景与目标
+
+当前 `STP2GLB.exe` 已经具备完整的 STEP 转 GLB 能力，也支持单文件和目录批量转换。但它主要通过命令行使用，这对客户或合作方有较高门槛：
+
+- 需要记忆参数和命令格式
+- 需要理解输入输出路径规则
+- 出错时难以判断问题出在参数、文件还是程序本身
+
+本次工作的目标不是重写转换引擎，而是在现有 `STP2GLB.exe` 外增加一个正式、易交付、易上手的本地桌面界面，让客户无需接触命令行就能完成转换。
+
+本设计以以下原则为约束：
+
+- 从现有可执行程序复用能力，不改动核心转换链路
+- 面向对外客户交付，界面风格应专业稳重
+- 发布形态以绿色版为主，换机器后应尽可能简单运行
+- 第一版只覆盖核心业务闭环，不引入与转模无关的复杂系统能力
+
+## 2. 成功标准
+
+第一版完成后，应满足以下业务标准：
+
+1. 用户可以在桌面界面中完成单文件转换，无需手写命令。
+2. 用户可以在桌面界面中完成目录批量转换，无需手写命令。
+3. 用户可以通过界面填写常用参数，并在需要时展开高级参数。
+4. 用户可以清楚看到执行过程、成功结果和失败原因。
+5. 绿色版程序在新机器上以“解压即用”为主要交付方式，不依赖客户额外安装 Python、Node 等开发环境。
+
+## 3. 用户与产品定位
+
+### 3.1 目标用户
+
+目标用户是外部客户或合作方，而不是内部开发人员。因此产品设计重点不是暴露全部底层技术细节，而是降低理解成本和操作风险。
+
+### 3.2 产品气质
+
+界面风格采用“专业稳重”方向：
+
+- 强调清晰、可信、正式
+- 不做偏开发者风格的工具面板
+- 不做过度科技感或展示感设计
+- 视觉和交互优先传达“可靠、明确、可控”
+
+## 4. 方案选择与结论
+
+本次目标是为现有转换引擎增加本地桌面界面。可选路径包括：
+
+### 方案 A：桌面壳直接调用 `STP2GLB.exe`
+
+优点：
+
+- 最短路径复用现有能力
+- 不需要改造转换核心为服务架构
+- 更适合绿色版分发
+
+缺点：
+
+- 需要在桌面程序中处理子进程调用、日志回传和错误展示
+
+### 方案 B：先启动本地 HTTP 服务，再由界面通过接口调用
+
+优点：
+
+- 前后职责边界清晰
+- 后续扩展 Web 版更顺手
+
+缺点：
+
+- 第一版链路更长
+- 需要管理本地服务生命周期、端口占用和异常回收
+- 对“换机器低成本运行”的目标不够友好
+
+### 方案 C：传统 Windows 原生 GUI 直接调用 exe
+
+优点：
+
+- 形态上更传统
+
+缺点：
+
+- 界面开发和迭代成本更高
+- 对第一版快速产品化没有明显收益
+
+### 最终结论
+
+第一版采用“本地网页壳桌面程序 + 直接调用 `STP2GLB.exe`”的方式实现。技术上推荐使用 `Tauri` 作为桌面壳。
+
+这样做的本质原因是：
+
+- 核心价值在现有 exe 的转换能力，不在重新搭一套服务系统
+- 绿色版交付更轻，换机器部署成本更低
+- 界面开发效率更高，后续做参数页、日志区和批量列表更直接
+
+## 5. 发布形态
+
+### 5.1 交付方式
+
+第一版以绿色版发布为主，不以安装包作为前置要求。
+
+交付目录应包含：
+
+- 桌面界面主程序
+- `STP2GLB.exe`
+- `gltfpack.exe`（当压缩功能启用时）
+- 程序运行所需的静态资源
+
+目标体验是：客户在新机器上拿到压缩包后，解压并打开主程序即可使用。
+
+### 5.2 部署原则
+
+为满足“换机器后简单方便运行”的目标，发布目录应遵循以下原则：
+
+- 所有核心依赖随绿色版目录一起分发
+- 运行路径尽量采用相对路径发现同目录中的 `STP2GLB.exe`
+- 不要求客户手工配置环境变量
+- 不要求客户手工启动独立服务
+
+## 6. 第一版功能范围
+
+### 6.1 必做功能
+
+- 单文件转换
+- 目录批量转换
+- 输入路径选择
+- 输出路径选择
+- 基础参数设置
+- 高级参数折叠设置
+- 启用压缩输出
+- 实时日志显示
+- 成功/失败结果反馈
+- 打开输出目录
+
+### 6.2 第一版不做
+
+- 历史任务管理
+- 并发任务和任务队列
+- 3D 预览
+- 云端上传下载
+- 账号体系
+- 自动更新
+- 复杂批处理编排
+
+这些能力不是没有价值，而是不影响第一版是否真正解决“客户能不能直接完成转换”这个核心问题。
+
+## 7. 界面结构设计
+
+第一版采用单窗口主界面，不拆成多页面。
+
+原因：
+
+- 核心业务流程短
+- 用户关心的是“选输入、设参数、开始执行、拿结果”
+- 多页面会增加理解成本，不利于首次使用
+
+主窗口分为四个区域。
+
+### 7.1 输入区
+
+职责是让用户先明确“我要转什么”。
+
+支持两种模式：
+
+- 单文件模式：选择一个 `.stp` 或 `.step` 文件
+- 批量模式：选择一个目录，扫描其中的 STEP 文件
+
+设计要求：
+
+- 界面上明确展示当前模式
+- 根据模式切换输入控件文案
+- 批量模式下显示扫描到的文件数量
+
+### 7.2 输出区
+
+职责是让用户明确“结果要放到哪里”。
+
+规则如下：
+
+- 单文件模式下，输出目标是 `.glb` 文件路径
+- 批量模式下，输出目标是输出目录
+- 启用压缩后，额外展示压缩输出策略
+
+设计要求：
+
+- 不让用户自己猜“这里该填文件还是文件夹”
+- 输出控件跟随输入模式自动变化
+- 在压缩开启时，界面应明确压缩结果是覆盖原输出还是写到独立位置
+
+### 7.3 参数区
+
+参数区分为基础参数和高级参数，避免第一屏暴露全部底层开关。
+
+基础参数建议包含：
+
+- 转换精度预设：低 / 标准 / 高
+- 是否仅转换实体
+- 是否启用压缩输出
+
+高级参数建议包含：
+
+- 线性偏差
+- 角度偏差
+- 相对偏差
+- 最大几何体数量
+- 网格超时
+- 调试模式
+- `gltfpack` 路径与参数（默认隐藏）
+
+设计原则：
+
+- 常用用户优先使用基础参数完成工作
+- 懂行用户可以展开高级参数进行精细控制
+- 高级参数文案要尽量解释业务含义，不只展示参数名
+
+### 7.4 执行与结果区
+
+这是客户建立信任感的关键区域。
+
+应包含：
+
+- 开始转换按钮
+- 执行中状态提示
+- 实时日志输出
+- 成功/失败结果提示
+- 批量模式下的总数、成功数、失败数
+- 成功后打开输出目录入口
+
+设计原则：
+
+- 让用户始终知道程序正在做什么
+- 失败时能直接看到可反馈的问题信息
+- 成功时能立刻找到输出结果
+
+## 8. 业务流程设计
+
+### 8.1 单文件转换流程
+
+1. 用户选择“单文件转换”
+2. 选择输入 STEP 文件
+3. 选择输出 GLB 文件路径
+4. 调整基础参数，必要时展开高级参数
+5. 点击“开始转换”
+6. 界面展示实时日志和状态
+7. 转换成功后提示并支持打开输出位置
+
+### 8.2 批量目录转换流程
+
+1. 用户选择“批量目录转换”
+2. 选择输入目录
+3. 程序扫描目录中的 `.stp/.step` 文件
+4. 用户选择输出目录
+5. 调整参数
+6. 点击“开始转换”
+7. 界面展示当前整体进度、日志以及成功/失败统计
+8. 完成后支持打开输出目录并查看失败项
+
+## 9. 技术架构设计
+
+### 9.1 分层原则
+
+架构分为三层：
+
+- 界面层：负责输入收集、状态展示和交互反馈
+- 桌面壳层：负责调用本地子进程、读取日志、管理文件路径
+- 转换引擎层：由现有 `STP2GLB.exe` 完成实际转换
+
+### 9.2 技术选型
+
+- 桌面壳：`Tauri`
+- 界面：本地 Web 前端
+- 转换执行：由桌面壳调用 `STP2GLB.exe`
+- 可选压缩：复用 `gltfpack.exe`
+
+### 9.3 调用策略
+
+执行链路如下：
+
+1. 界面收集用户输入和参数
+2. 桌面壳根据模式拼装命令行参数
+3. 以子进程方式调用 `STP2GLB.exe`
+4. 实时读取标准输出和错误输出
+5. 将日志持续回传到界面
+6. 执行结束后，根据退出码和输出结果判断成功与否
+
+### 9.4 成功判定
+
+不能只依赖退出码，还应结合结果文件是否实际生成来判断。
+
+原因：
+
+- 从业务视角看，用户关心的是“结果文件有没有拿到”
+- 仅看进程退出可能无法覆盖所有落地失败场景
+
+因此第一版成功判定建议采用双条件：
+
+- 进程退出码为成功
+- 目标输出文件或输出目录中的预期结果实际存在
+
+## 10. 错误处理与用户反馈
+
+第一版错误处理重点不是做复杂恢复机制，而是让错误足够可理解、可定位。
+
+应覆盖的典型错误包括：
+
+- 输入文件不存在
+- 输入目录中没有 STEP 文件
+- 输出路径不合法
+- `STP2GLB.exe` 未找到
+- `gltfpack.exe` 未找到
+- 转换过程异常退出
+- 某些批量文件转换失败
+
+反馈原则：
+
+- 错误提示用业务语言解释问题，而不是只显示技术栈异常
+- 日志区保留原始输出，便于技术支持排查
+- 批量模式下区分“部分失败”和“全部失败”
+
+## 11. 验收标准
+
+第一版验收以以下标准为准：
+
+1. 在单文件模式下，用户可成功将 STEP 文件转换为 GLB。
+2. 在批量模式下，用户可成功选择目录并完成批量转换。
+3. 用户可通过基础参数完成常规转换。
+4. 用户可通过高级参数执行更细粒度控制。
+5. 转换过程可在界面中看到实时状态和日志。
+6. 成功后用户可直接找到输出结果。
+7. 失败时用户能看到明确错误信息，并可将日志反馈给技术支持。
+8. 绿色版程序在新机器上以最少额外配置运行。
+
+## 12. 后续扩展方向
+
+第一版完成后，如业务有需要，可在不改变现有核心架构的前提下继续扩展：
+
+- 参数预设
+- 最近使用记录
+- 日志导出
+- 多语言
+- 结果校验
+- 更完整的批量任务视图
+
+这些能力应在第一版稳定后再评估，而不是提前纳入当前范围。