下载客户端 (pf-download)

定位

pf-download 是图模工坊的桌面下载客户端——面向运营/交付人员的 Windows 应用，登录后端、筛选订单、批量下载合成成品，带队列、重试、去重、自动轮询与离线告警。它随”合成状态与下载状态解耦”一起引入（8bedb52），是下载状态流的消费端。

• 形态：Wails 桌面应用（Go 后端 + Vue 3 前端），产物 pf-download.exe
• Go：module pf-download，Go 1.25，Wails v2.13，energye/systray
• 前端：Quasar 2.23 + Vue 3.5 + Pinia + vue-router + vue-i18n
• 窗口：1280×800（最小 1024×700），关闭最小化到系统托盘（暂停/继续/退出）
• 运行数据：%APPDATA%\pf-download（config、download_history.json、download_receipts.json、session.json、logs/）

它做什么

一句话：登录 pf-service → 浏览订单/提交 → 把已合成成品排队下载到本地文件夹，并把下载回执同步回服务端。

1
2
3
4
5
6
7
8

登录（pf-service JWT）
  → GET /api/download/orders/page        订单分页 + 每单提交统计
  → GET /api/download/shops/options      店铺筛选
  → GET /api/download/submissions/page   提交分页（按 composeStatus / hasDownloaded 过滤）
  → GET /api/download/submissions/:id/images   列出可下载成品
  → 下载引擎入队 → GET /api/download/images/:sid/:iid/:idx/file  流式取文件
  → POST /api/download/submissions/:id/receipt  标记首次下载
  → SyncReceipts 回写回执；本地记 history 去重

GetSubmissionsPage(..., status, downloadStatus, ...) 的双状态签名，正是”合成状态 / 下载状态解耦”的直接体现（详见 数据模型）。

应用结构

Go 侧 app.go（绑定到 window.go.main.App.*）聚合 pkg/ 下的服务：

前端页面：index、history、queue、settings、login；src/bridge/index.ts 是 Wails 桥接，boot/auth.ts、boot/i18n.ts。

能力要点

• 队列 + 重试：批量下载排队，失败可重试，磁盘状态跟踪
• 去重：download_history.json 记录已下载，避免重复
• 自动轮询：无人值守模式定时拉取新完成的成品
• 离线告警：后端不可达时告警
• 系统集成：托盘常驻、Windows 开机自启

发布分发

apps/pf-download/upload.js（”新增 MinIO 客户端上传工具”提交）是发布辅助脚本，不是应用核心：bun run upload.js 把构建好的 build/bin/pf-download.exe 用 Bun S3Client 传到 MinIO pf-bucket/downloads/pf-download.exe，终端用户即可从 https://pf.wangijun.com/storage/downloads/pf-download.exe 下载客户端。

开发

1
2

bun dev:download    # bun run --filter @wangijun/pf-download dev（Wails dev, serverUrl :9000）
# 构建 .exe 由 wails build 产出 → upload.js 发布到 MinIO

pf-download 不进 根 dev/部署脚本主流程（只有 dev:download）——它以 .exe 形式分发，不部署到 Nginx。

下一步

• 想看它消费的下载 API → pf-service 后端
• 想看合成/下载状态如何解耦 → 数据模型
• 想看运营在后台的审核视图 → 管理后台