feat: 优化图片资源删除管理，生图任务列表管理

2026-08-30 14:50:33 +08:00
parent 4ee667142b
commit 957289f717
46 changed files with 4180 additions and 524 deletions
@@ -1,8 +1,8 @@
 # 工作交接说明（HANDOFF）

-> 更新：2026-08-29 晚
+> 更新：2026-08-30
 > 读者：下一个接手工作的 AI / 开发者（工具无关）。先读本文再动手，避免重复探索。
-> 配套文档：[`README`](../../README.md)（项目总览）、[`collect.md`](./collect.md)（采集）、[`trial-page.md`](./trial-page.md)（试算页）、[`image-suite.md`](./image-suite.md)（生图）、[`api.md`](./api.md)（契约）、[`backend-structure.md`](./backend-structure.md)（后端结构）
+> 配套文档：[`README`](../../README.md)（项目总览）、[`collect.md`](./collect.md)（采集）、[`trial-page.md`](./trial-page.md)（试算页）、[`image-suite.md`](./image-suite.md)（生图）、[`background-jobs.md`](./background-jobs.md)（**后台任务中心方案、实施状态与路线图**）、[`image-asset-lifecycle.md`](./image-asset-lifecycle.md)（图片与水印存储规则）、[`api.md`](./api.md)（契约）、[`backend-structure.md`](./backend-structure.md)（后端结构）

 ---

@@ -32,7 +32,8 @@ extensions/collector 扩展采集（Ozon/1688/淘宝/天猫）
 pnpm -C extensions/collector build     # 产物 .output/chrome-mv3
 ```

- **start.command 新增**：启动时自动构建采集插件，并起后台监听（3s 轮询 `src/**` + `wxt.config.ts`，改动自动重建；BSD find 语法，无新依赖）。Ctrl+C 会连同监听进程一起清理。
+- **start.command 新增**：启动时会先执行 `alembic upgrade head`，再自动构建采集插件并起后台监听（3s 轮询 `src/**` + `wxt.config.ts`，改动自动重建；BSD find 语法，无新依赖）。Ctrl+C 会连同监听进程一起清理。
+- **后台任务 Worker**：`start.command` 会额外启动 `python server/worker.py`。单独启动 server 时也要另开终端运行该命令，否则生图任务只会停在“排队中”。
 - **运行态提醒**：交接时 server 是上个会话用 nohup 起的后台进程（日志 `/tmp/osk-server.log`），原 start.command 终端已被停掉。新会话建议：`kill $(lsof -ti :8800)` 后用 `./start.command` 正常接管。
 - **`uvicorn --reload` 不监控 `.env`**：改 `.env` 后必须手动重启 server（Kill 8800 端口进程再起）。
 - 密钥在根目录 `.env`：`DEEPSEEK_API_KEY`（规划+文案）、`DASHSCOPE_API_KEY`（通义，可用 ✅）、`RIGHTAPI_API_KEY`（RightCode 中转，**通道当前故障** ❌）、`PCORE_API_KEY`（pcore.ai，**可用 ✅**）、`ARK_API_KEY` 未配（豆包未用）。`.env.example` 有全部键位说明。
@@ -48,7 +49,7 @@ pnpm -C extensions/collector build     # 产物 .output/chrome-mv3
 - **默认生图模型 = `gpt-image-2@pcore`**（`studio/src/services/suite.ts` 的 `DEFAULT_IMAGE_MODEL`）。
 - **同名模型多中转的路由约定**：前端模型 value 用「api模型@provider」后缀区分（目前仅 pcore 用到），服务端 `schemas/suite.py` 的 `MODEL_PROVIDERS` + `api_model()`（剥后缀）处理；白名单 `PCORE_MODELS`。
 - **pcore 协议要点**（`generator.py` 的 `_pcore_request`/`_pcore_poll_task`）：无参考图走 `POST /v1/images/generations`，带参考图走 `/v1/images/edits` 且 images 必须是 **`[{image_url: dataURI}]` 对象数组**（纯字符串报错）；均为异步：提交拿 `id` → 轮询 `GET /v1/images/{kind}/{task_id}` → `completed` 后 `data[0].url` 取图。`size` 是枚举（1024x1536/1024x1024），不接受自定义尺寸。new_api 系中转常见「HTTP 200/503 + 错误体」，错误解析已兼容嵌套 `error.{code,message}`；「No available channel」类错误不重试直接失败。
- **速率**：image2 分组 RPM 70 / RPD 1.2K（日限）；生图全局串行（`generator.py` 的 `asyncio.Lock`），远碰不到 RPM。pcore 账户余额 $5，按张扣费。
+- **速率**：image2 分组 RPM 70 / RPD 1.2K（日限）；当前独立 Worker 单进程逐图领取任务，远碰不到 RPM。pcore 账户余额 $5，按张扣费。

 ## 4. AI 规划张数策略（`planner.py`）

@@ -64,12 +65,16 @@ pnpm -C extensions/collector build     # 产物 .output/chrome-mv3
 |---|---|
 | 试算页 | 五区块页面、计价、俄文文案、采集图片/出图方案/生成结果、登记导出 |
 | 采集对接 | ISS 扩展并入 `extensions/collector/`，「上报商品」入库 + 自动打开试算页 |
-| 生图服务端 | planner/generator/prompts/watermark/tasks，套图 + 单张 AI 生图 + 水印 + ZIP 导出 |
+| 生图服务端 | planner/generator/prompts/watermark/jobs + 独立 Worker，套图 + 单张 AI 生图 + 水印 + ZIP 导出 |
 | **本轮：Pcore 接入** | 新 provider 全链路（生成/编辑/轮询/重试/错误处理），`@pcore` 路由约定，下拉带供应商名，默认模型切 Pcore |
 | **本轮：规划器修复** | thinking 禁用 + 重试 + 张数策略（AI 自主，建议 8 张左右，生图要求可指定） |
 | **本轮：采集箱** | 勾选列 + 全选/取消全选 + 批量删除（硬删、Popconfirm 二次确认、删空页自动回退） |
 | **本轮：采集图片区改版** | 8 列网格；AI 生图按钮半透明悬浮图片右下角；图名显示在图片下方（取 URL 末段）；SKU 名并入图名行（不再悬浮遮挡勾选钮）；勾选钮在右上角；默认全部不勾选 |
 | **本轮：生成结果区** | 「导出图片」按钮（水印按钮右侧，复用 POST /api/export/images，ZIP 内分「套图结果/单张生图」文件夹）；「单张 AI 生图」小节改名「生图记录」（落库历史，刷新后保留） |
+| **本轮：图片生命周期** | 采集、上传与 AI 图片统一保存为 `original + current`；只保留当前水印版；重加/移除水印自动回收旧对象；删除单图/硬删商品会清理本地或七牛对象；具体规则见 [`image-asset-lifecycle.md`](./image-asset-lifecycle.md) |
+| **本轮：图片资源上限** | 单张上传/下载默认 20 MB；采集最多 100 张；导出最多 50 张、总量 200 MB；ZIP 超过 2 MB 自动落临时磁盘并分块返回，配置见 `.env.example` |
+| **本轮：生图任务与轮询** | 单张 AI 编辑改为提交统一异步任务并立即返回 `suite_id`；套图与单张弹窗均采用无重叠递归轮询、取消在途请求与失败退避；套图任务 ID 可在刷新页面后从浏览器会话恢复 |
+| **本轮：持久化图片任务** | 套图、单张编辑与批量添加水印已迁入数据库任务表和独立 Worker；Pcore/RightAPI/通义万相保存第三方任务 ID 并可在重启后恢复轮询；水印逐图进度可刷新恢复、取消并按失败项重试，详见 [`background-jobs.md`](./background-jobs.md) |
 | **本轮：关键 bug 修复** | ① axios 全局 Content-Type 导致 FormData 被 JSON 化 → 上传 422（`api.ts` 移除全局头，**今后勿设**）；② TrialPage `load()` 置 loading 导致整页闪 Spin、卸载面板（杀生图轮询/丢勾选）→ 改静默刷新；③ web v1 页面因 cdn.tailwindcss.com 被墙整页无样式 → tailwind 运行时固化到 `web/vendor/tailwind.js` |
 | **本轮：杂项** | 采买地址「打开地址」改图标按钮（与复制图标同款）；start.command 自动构建+监听插件 |

@@ -80,7 +85,7 @@ pnpm -C extensions/collector build     # 产物 .output/chrome-mv3

 ## 6. ⚠️ 未提交改动清单（当前最大事项）

-分支 `feat-2.1.0`，工作区有 19 个文件改动 + 1 个新目录，**建议按模块分 3-4 个 commit**：
+分支 `feat-2.1.0`，工作区仍有多项未提交改动，**建议按模块分 4-5 个 commit**：

 1. **Pcore 生图接入 + 规划器修复 + 张数策略**
   `server/services/{generator,planner,suite_service,prompts/__init__}.py`、`server/{api/suite.py,schemas/suite.py,config/settings.py}`、`studio/src/services/suite.ts`、`.env.example`、`docs/v2.1/{image-suite,api}.md`
@@ -88,7 +93,8 @@ pnpm -C extensions/collector build     # 产物 .output/chrome-mv3
   `studio/src/pages/trial/{TrialSuitePanel,TrialInfoPanel,TrialPage}.tsx`、`studio/src/pages/collection/CollectionPage.tsx`、`studio/src/services/api.ts`
 3. **web v1 样式修复（CDN 固化）+ start.command 插件自动构建**
   `web/ozonSeller.html`、`web/vendor/tailwind.js`（新目录）、`start.command`
-4. **交接文档**：`docs/v2.1/HANDOFF.md`
+4. **图片生命周期与水印回收**：`server/services/image_assets.py`、`server/services/storage.py`、`server/{api/materials,api/products,models/asset}.py`、迁移 `a41e8c7f4b20_add_asset_image_lifecycle.py`、试算页水印入口
+5. **交接文档**：`docs/v2.1/{HANDOFF,image-asset-lifecycle,optimization-audit}.md`

 提交前：`git checkout -- studio/tsconfig.app.tsbuildinfo`（构建产物，勿提交）。

@@ -105,9 +111,9 @@ pnpm -C extensions/collector build     # 产物 .output/chrome-mv3
 | # | 坑 | 对策 |
 |---|---|---|
 | 1 | `uvicorn --reload` 不监控 `.env` | 改 `.env` 后手动重启 server |
-| 2 | 套图任务在内存（`services/tasks.py`） | server 重启丢任务状态（前端已提示重新生成）；已落盘图片不丢（在「生图记录」区） |
-| 3 | 生图全局串行（`generator.py` 的 `asyncio.Lock`） | 一次只跑一个生成队列，测试时别并发提交 |
-| 4 | 单张 image-edit 是同步接口 | 慢模型单张 1-5 分钟，前端 axios 超时 120s 可能先断（后端仍在跑，图会出现在生图记录） |
+| 2 | 生图任务依赖独立 Worker | `start.command` 会启动；若手动运行 uvicorn，必须另开 `python server/worker.py`，否则任务会一直排队 |
+| 3 | SQLite 仅适合单机 Worker | 当前通过租约恢复异常退出的任务；未来多实例前先迁移 PostgreSQL，再做多 Worker 竞争领取 |
+| 4 | 外部模型任务可恢复范围不同 | Pcore/RightAPI/通义万相保存 provider task id 后可继续轮询；豆包/同步千问没有外部任务 id，进程恰在请求中断时只能重试 |
 | 5 | **axios 实例勿设全局 Content-Type** | axios 1.x 遇「默认 JSON 头 + FormData」会把表单转 JSON 发送（`formDataToJSON`），multipart 接口全 422。已从 `api.ts` 移除；对象请求体 axios 会自动补 JSON 头 |
 | 6 | `web/` 样式依赖公网 CDN | tailwind 已固化 `web/vendor/tailwind.js`；font-awesome/jsdelivr 若也断，同样方式下载到 `web/vendor/` 改引用 |
 | 7 | 试算页水印文本存 localStorage（`trialWatermark`） | 改默认值不影响已保存设置；登记表同理存 localStorage `trialRegisterRecords` |
@@ -116,6 +122,7 @@ pnpm -C extensions/collector build     # 产物 .output/chrome-mv3
 | 10 | AI 规划/生图花钱 | pcore 按 $ 扣费、RightCode 按张计费；联调时 plan 张数设 1-2、优先低成本模型 |
 | 11 | TrialPage `load()` 勿再置 loading | 置 loading = 整页 Spin + 卸载面板 = 杀生图轮询/丢状态（已修，保持静默刷新） |
 | 12 | 浏览器自动化调试怪癖（如 ZCode IAB） | 截图偶发超时（重试一次多半仍失败，改用几何测量/计算样式验证）；文件上传需用 DataTransfer+input change 事件模拟；改代码后 React 事件偶发失灵 → reload 页面即恢复 |
+| 13 | 图片上传/导出存在大小限制 | 默认单张 20 MB、采集 100 张、导出 50 张、ZIP 200 MB；超限接口返回 413。需要调整时改 `.env` 的 `IMAGE_*` / `EXPORT_*` 配置并重启服务 |

 ## 9. 关键文件速查

@@ -125,7 +132,8 @@ pnpm -C extensions/collector build     # 产物 .output/chrome-mv3
 | 01 商品信息（采买地址图标、型号/货号联动） | `pages/trial/TrialInfoPanel.tsx` | `api/materials.py` |
 | 02 价格试算 | `pages/trial/TrialPricingPanel.tsx` + `pricing/pricing.ts` | — |
 | 03 俄文文案 | `pages/product/CopyPanel.tsx`（共用） | `api/ai.py` + `services/deepseek.py` + `prompts/copy_ru.py` |
-| 04 图片与生图（8 列网格/悬浮按钮/图名） | `pages/trial/TrialSuitePanel.tsx` + `AiImageGenModal.tsx` | `api/suite.py` + `services/{suite_service,generator,planner,prompts/,tasks,watermark}.py` |
+| 04 图片与生图（7 列网格/悬浮按钮/图名） | `pages/trial/TrialSuitePanel.tsx` + `AiImageGenModal.tsx` | `api/suite.py` + `services/{jobs,job_worker,suite_service,generator,planner,prompts/,watermark,image_assets}.py` |
+| 图片原图/水印/删除回收 | `TrialSuitePanel.tsx`（水印设置） | `api/materials.py`、`api/products.py`、`services/{image_assets,storage}.py` |
 | 生图供应商路由 | `services/suite.ts`（IMAGE_MODEL_OPTIONS 带供应商名；DEFAULT_IMAGE_MODEL） | `schemas/suite.py`（MODEL_PROVIDERS/`@pcore` 约定）+ `services/generator.py`（generate_pcore 等） |
 | 05 登记与导出 | `pages/trial/TrialExportPanel.tsx`（localStorage `trialRegisterRecords`） | — |
 | 生成结果导出 | `TrialSuitePanel.tsx` handleExportResult（套图+单张分组 ZIP） | `api/export.py` |