9.7 KiB
STP2GLB 本地桌面界面设计
1. 背景与目标
当前 STP2GLB.exe 已经具备完整的 STEP 转 GLB 能力，也支持单文件和目录批量转换。但它主要通过命令行使用，这对客户或合作方有较高门槛：
- 需要记忆参数和命令格式
- 需要理解输入输出路径规则
- 出错时难以判断问题出在参数、文件还是程序本身
本次工作的目标不是重写转换引擎，而是在现有 STP2GLB.exe 外增加一个正式、易交付、易上手的本地桌面界面，让客户无需接触命令行就能完成转换。
本设计以以下原则为约束：
- 从现有可执行程序复用能力，不改动核心转换链路
- 面向对外客户交付，界面风格应专业稳重
- 发布形态以绿色版为主，换机器后应尽可能简单运行
- 第一版只覆盖核心业务闭环，不引入与转模无关的复杂系统能力
2. 成功标准
第一版完成后，应满足以下业务标准：
- 用户可以在桌面界面中完成单文件转换，无需手写命令。
- 用户可以在桌面界面中完成目录批量转换，无需手写命令。
- 用户可以通过界面填写常用参数，并在需要时展开高级参数。
- 用户可以清楚看到执行过程、成功结果和失败原因。
- 绿色版程序在新机器上以“解压即用”为主要交付方式，不依赖客户额外安装 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.exegltfpack.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 单文件转换流程
- 用户选择“单文件转换”
- 选择输入 STEP 文件
- 选择输出 GLB 文件路径
- 调整基础参数，必要时展开高级参数
- 点击“开始转换”
- 界面展示实时日志和状态
- 转换成功后提示并支持打开输出位置
8.2 批量目录转换流程
- 用户选择“批量目录转换”
- 选择输入目录
- 程序扫描目录中的
.stp/.step文件 - 用户选择输出目录
- 调整参数
- 点击“开始转换”
- 界面展示当前整体进度、日志以及成功/失败统计
- 完成后支持打开输出目录并查看失败项
9. 技术架构设计
9.1 分层原则
架构分为三层：
- 界面层：负责输入收集、状态展示和交互反馈
- 桌面壳层：负责调用本地子进程、读取日志、管理文件路径
- 转换引擎层：由现有
STP2GLB.exe完成实际转换
9.2 技术选型
- 桌面壳：
Tauri - 界面：本地 Web 前端
- 转换执行：由桌面壳调用
STP2GLB.exe - 可选压缩：复用
gltfpack.exe
9.3 调用策略
执行链路如下：
- 界面收集用户输入和参数
- 桌面壳根据模式拼装命令行参数
- 以子进程方式调用
STP2GLB.exe - 实时读取标准输出和错误输出
- 将日志持续回传到界面
- 执行结束后，根据退出码和输出结果判断成功与否
9.4 成功判定
不能只依赖退出码，还应结合结果文件是否实际生成来判断。
原因：
- 从业务视角看，用户关心的是“结果文件有没有拿到”
- 仅看进程退出可能无法覆盖所有落地失败场景
因此第一版成功判定建议采用双条件：
- 进程退出码为成功
- 目标输出文件或输出目录中的预期结果实际存在
10. 错误处理与用户反馈
第一版错误处理重点不是做复杂恢复机制，而是让错误足够可理解、可定位。
应覆盖的典型错误包括：
- 输入文件不存在
- 输入目录中没有 STEP 文件
- 输出路径不合法
STP2GLB.exe未找到gltfpack.exe未找到- 转换过程异常退出
- 某些批量文件转换失败
反馈原则：
- 错误提示用业务语言解释问题，而不是只显示技术栈异常
- 日志区保留原始输出，便于技术支持排查
- 批量模式下区分“部分失败”和“全部失败”
11. 验收标准
第一版验收以以下标准为准：
- 在单文件模式下，用户可成功将 STEP 文件转换为 GLB。
- 在批量模式下，用户可成功选择目录并完成批量转换。
- 用户可通过基础参数完成常规转换。
- 用户可通过高级参数执行更细粒度控制。
- 转换过程可在界面中看到实时状态和日志。
- 成功后用户可直接找到输出结果。
- 失败时用户能看到明确错误信息，并可将日志反馈给技术支持。
- 绿色版程序在新机器上以最少额外配置运行。
12. 后续扩展方向
第一版完成后，如业务有需要，可在不改变现有核心架构的前提下继续扩展：
- 参数预设
- 最近使用记录
- 日志导出
- 多语言
- 结果校验
- 更完整的批量任务视图
这些能力应在第一版稳定后再评估，而不是提前纳入当前范围。