开发记录
PhantomTank Factory 开发日志
记录 PhantomTank Factory 从 Python 工具改写到 Tauri + Vue + Rust 桌面应用的重构过程，以及亮度算法重写、双通道彩色合成与实时预览中的关键取舍。
关联作品：PhantomTank Factory
一款 Windows 桌面端的幻影坦克合成工具：选择表图与里图，生成「缩略图看一张、点开看另一张」的 PNG。
技术栈：Tauri 2 + Vue 3 + TypeScript + Rust。
仓库：github.com/YamaArashiHZ/PhantomTankFactory · 开发周期（重构版）：2026-07-23 ~ 07-24
背景与动机
幻影坦克这套做法最早是我用 Python 写的脚本配合 PIL 一顿合成的，后来加了个 customtkinter 的 GUI 方便日常用。但脚本版依赖重、打包体积大，交互也一直停留在「能用」的层面，而且没有安装包、没有自动更新。
干脆用 Tauri 2 重写一版正经的桌面应用：安装包轻量、图像处理放 Rust 侧不卡 UI、支持应用内自动更新。重写沿用同一套校验过的合成流程，把重心放在工程化和交互体验上。
技术选型
| 层 | 技术 | 理由 |
|---|---|---|
| 壳 | Tauri 2 | 体积小，Rust 后端适合做图像处理 |
| 前端 | Vue 3 + Vite | 轻量，适合手写交互 |
| UI | Naive UI + 手写局部样式 | 组件齐全又不至于全盘交给组件库 |
| 图像 | Rust image crate |
原生性能，合成大图不卡 UI |
| 配置 | Tauri Store | 参数持久化，AppConfig 集中管理 |
| 更新 | tauri-plugin-updater | 依赖 GitHub latest.json 签名校验，应用内自动更新 |
| 包管理 | pnpm | 前端依赖与 Tauri 工程统一管理 |
关键设计原则：合成计算全部放在 Rust 侧，前端只做选图、调参数和展示预览；预览走「按最长边缩小」的独立管线，原图合成留给导出。
版本里程碑
| 版本 | 日期 | 主题 |
|---|---|---|
| v0.1.0 | 2026-07-23 | 以 Tauri + Vue 重构的首个可用版本：选图预览、亮度、导出 |
| v0.1.1 | 2026-07-24 | 图片解码缓存、错误细分与 opener 权限修复 |
| v0.2.0 | 2026-07-24 | 彩色双通道合成、对比度/饱和度、拖拽导入、自动更新、自动化测试与 CI |
开发时间线
Day 1 · 07-23：重构骨架与基础功能
把 Python 版的核心流程先搬到 Rust，前端用 Vue 搭出主界面，当天跑通「能用」的主线：
- 以 Tauri + Vue 重构 v0.1：表图/里图选择与预览、亮度调节、导出 PNG
- 修复选图预览被裁剪、无法完整显示的问题，预览区自适应比例并同步双卡布局
- 添加实时效果预览与清晰度档位（低/中/高/原图）
- 导出底部通知、预览开关、自定义滚动条
- 效果查看页（对已生成图片做白/黑底预览）、关于页与侧栏品牌标识
- NSIS 中文安装包配置、README 下载说明；补充 MIT 许可与中文 README
首次踩坑：预览区自适应有点反直觉，表图和里图卡片一改比例，另一张就错位，最后统一成按容器等比缩放才稳。
Day 2 · 07-24：功能冲刺与工程化
这是最密集的一天，从「能用」推到「可发布」：
- 亮度算法重写：从断开的两段式公式改为线性插值（正方向向白色渐变、负方向向黑色渐变、0 值保持原样）。默认值 50 / -50 的合成结果与旧版完全一致，其他值下变化平滑连续
- 拖拽导入图片：从文件管理器直接拖放到预览框，拖入时全屏暗色遮罩并在预览框处挖孔高亮
- 对比度 & 饱和度滑条：在原图阶段调整，0 为不变
- 彩色幻影坦克合成（实验性）：双通道算法——灰度管线始终计算，确保 Alpha 通道的亮度信息准确；彩色管线保留 RGB 细节
- 黑白/彩色参数独立存储：两种模式各自记住亮度/对比度/饱和度，切换自动恢复；滑块以 easeOutCubic 曲线在 280ms 内平滑过渡
- 导出进度条：生成按钮右侧新增进度条，百分比平滑增长
- 自动化测试与 CI：Rust 35 项（覆盖所有图像处理函数 + 彩色合成验证）、前端 21 项（覆盖配置校验全场景）；CI 跑
cargo test+cargo clippy+cargo fmt+vue-tsc+vitest - 发布与工程：Release 工作流（tag/手动触发自动打包发版）+ tauri-action 生成
latest.json与更新产物；pre-commit hooks、Dependabot、PR 模板、CI 徽章；版本信息集中化、图片解码缓存与错误细化
关键决策与踩坑记录
- 为什么重写而非修 Python 版：customtkinter + PIL 那套依赖重、打包大、不易分发。Tauri 2 天然带安装包与自动更新，Rust「image」crate 做像素操作也不吃 UI 线程。
- 亮度算法用线性插值：旧版是两段断开公式，滑到中点附近会有突变。改成向白/黑线性插值后，±50 与旧结果一致，其余值平滑。改这个是为了手感，但必须保住旧结果兼容性。
- 彩色模式是双通道：灰度管线用来生成 Alpha 遮罩（保证亮度信息准确），彩色管线单独跑一遍保留 RGB。两者最后叠在一起，实验性标注是因为它依赖较新的渲染一致行为。
- 实时预览靠缩小 + 缓存：预览按最长边缩小（320/640/1280/原图），配合按「路径 + 文件修改时间」判定的图片解码缓存（上限 4 条，满则整体清空）。拖动滑条时反复碰同一对图片，命中缓存就省掉重复 IO 和解码。
- 自动更新链路：
tauri-plugin-updater+ GitHublatest.json签名验证。发布时由 tauri-action 生成更新产物；NSIS 用中文安装包、installMode: currentUser，多数 Win10/11 已自带 WebView2，无需额外运行时。 - 测试先于发布：把图像处理函数全部拆出来做单元测试，Rust 覆盖 35 项 + 前端覆盖 21 项，CI 全自动。这样彩色合成、亮度边界这类容易翻转的算法改动都有回归兜底。
数据一览
- 开发周期：2 天（2026-07-23 ~ 07-24）
- 重构分支提交数：30
- 版本：v0.1.0 → v0.2.0
- 自动化测试：Rust 35 项 + 前端 21 项
- 自动更新：tauri-plugin-updater + GitHub
latest.json签名校验
本文档由项目会话记录与 git 历史整理生成，用于个人网站开发日志栏目。