refactor(server): 移除已放弃的 Ozon API 直传模块，新增素材删除接口

- 删除 shops/publish/categories/ozon 相关路由、模型、schema 与客户端服务（V2.1 决策放弃 API 直传，改人工上传） - materials 新增 DELETE /assets/{id}：删除素材记录与本地文件，并同步修正 asset_counts - 试算页支持单张素材删除，生图弹窗交互微调 - 新增 docs/v2.1/HANDOFF.md 工作交接说明，README 补充索引
2026-08-28 17:47:57 +08:00
parent dc6d38c128
commit a77ec26a02
20 changed files with 248 additions and 1010 deletions
@@ -0,0 +1,101 @@
+# 工作交接说明（HANDOFF）
+
+> 更新：2026-08-28 晚
+> 读者：下一个接手工作的 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)（后端结构）
+
+---
+
+## 1. 项目一句话
+
+Ozon 跨境上品工具链。当前主链路（V2.1，已放弃 Ozon API 直传）：
+
+```
+extensions/collector 扩展采集（Ozon/1688/淘宝/天猫）
+  → 「上报商品」POST /api/materials 入库 + 自动打开试算页
+  → studio /trial/{id} 试算页：计价 → 俄文文案 → AI 生图（套图+单张）→ 登记
+  → 导出 CSV / 组合码 → 人工上 Ozon 卖家后台
+```
+
+技术栈：FastAPI（server，8800）+ React19/Vite/antd6（studio，8900）+ WXT Chrome 扩展（extensions/collector）。SQLite（`data/app.db`），无鉴权（V2.1 决策：先功能后鉴权）。
+
+## 2. 启动与构建
+
+```bash
+# server（我最后用的方式；日志在 /tmp/osk-server.log）
+cd ozon-seller-kit
+.venv/bin/uvicorn main:app --app-dir server --reload --reload-include "*.yaml" --host 127.0.0.1 --port 8800
+
+# studio
+pnpm -C studio dev          # http://localhost:8900，/api 代理到 8800
+
+# 扩展（改了扩展代码后必跑，然后 chrome://extensions 刷新）
+pnpm -C extensions/collector install   # 首次
+pnpm -C extensions/collector build     # 产物 .output/chrome-mv3
+```
+
+密钥在根目录 `.env`（已配好）：`DEEPSEEK_API_KEY`（规划+文案）、`RIGHTAPI_API_KEY`（生图主力：gpt-image-2-vip / nano-banana 系列）、`DASHSCOPE_API_KEY`（通义，可选）、`ARK_API_KEY` 未配（豆包未用）。
+
+## 3. 当前进度
+
+### ✅ 已完成（已提交，git log 有记录）
+| 阶段 | 内容 |
+|---|---|
+| Phase A | 试算页前端 `/trial/:id` 五区块：1 商品信息 / 2 价格试算（公式对齐 v1 web）/ 3 俄文文案 / 4 采集图片+出图方案+生成结果 / 5 入库与导出 |
+| Phase C | ISS 扩展并入 `extensions/collector/`；「上报商品」按钮（01 区块下方）→ 入库 + 新标签打开试算页；设置弹窗含上报开关/后台地址/试算页地址 |
+| Phase B | 生图服务端（`server/api/suite.py` + `services/{planner,generator,prompts/,tasks,watermark}`，平移自 image-suite-studio） |
+| 后端整理 | 鉴权全删（server+studio）；冻结链路隔离 `server/legacy/`（接口仍挂载）；`collection.py`→`materials.py`；suite 业务下沉 `services/suite_service.py` |
+
+### ✅ 已联调验证（真实调用生图 API）
+plan / generate（串行队列+轮询+回写 generated）/ image-edit（单张，含 `after_asset_id` 插入原图后）/ 水印（文字 Panda Store 右下角）/ export/images（ZIP 分组结构）/ proxy-image / DELETE /api/assets/{id}（删素材+文件）/ materials 上报（product_id 返回）。
+
+### 🔨 最近一轮 UI 迭代（**部分未提交**，见 git status）
+- 出图方案卡：左右 12:12；左列灰卡内含「规划并生成 + AI 智能规划」；数量改 Stepper（− 输入 ＋，0-5）；AI 智能规划按钮高度与一键生图一致；说明文字支持换行
+- 水印设置移到「6 生成结果」标题栏最右；默认文本改 `Panda Store`
+- 生成结果卡：新增「单张 AI 生图」小节（含套图回写与单张图）；底部「AI 编辑」可点击 → 同款生图弹窗，新图经 `after_asset_id` 插在原图后；每张图右上角 ✕ 删除（Popconfirm 二次确认 → `DELETE /api/assets/{id}`）
+- 采集图片卡不再显示 generated 素材（归生成结果卡）
+- 型号/货号：后缀独立存储（货号框 `addonBefore` 展示 `型号-`，只输后缀；型号/货号框后有复制按钮）；型号含 `-` 不再增殖
+- 侧边栏：展开 200 / 折叠 60，折叠图标居中（`SidebarMenu.css` 尾部规则）
+- 采买地址：「打开地址」按钮 + 复制图标；仅 1688/淘宝/天猫/拼多多来源自动填充
+- 试算页水印弹窗默认文本 Panda Store（注意 localStorage `trialWatermark` 有旧值需手改一次）
+
+## 4. 下一步（按优先级）
+
+1. **提交当前改动**：`git status` 有一批未提交（后端整理 + 最近 UI 迭代 + extensions settings 改动），建议按模块分 2-3 个 commit
+2. **手动全流程回归**（浏览器 + Chrome 真机扩展）：采集 → 上报 → 试算页五区块 → 生成/编辑/删除 → 登记表录入/导出 CSV/组合码 → 清空
+3. **Phase D 待办**：批量 CSV 服务端化（`GET /api/export/trial-csv`，替代前端逐个拉详情拼装）；登记表数据当前存 localStorage（换设备不可见，如需跨设备要落库）
+4. **远期**：鉴权/账户体系重做（从 `server/deps.py` 层重新引入）；ISS-only 产品模式构建配置；`extension-v1/v2`、`web/`、`server/legacy/` 的清理时机
+
+## 5. 已知坑（新会话必读）
+
+| # | 坑 | 对策 |
+|---|---|---|
+| 1 | `uvicorn --reload` 不监控 `.env` | 改 `.env` 后手动重启 server |
+| 2 | 套图任务在内存（`services/tasks.py`） | server 重启丢任务状态（前端已提示重新生成）；已落盘图片不丢 |
+| 3 | 生图全局串行（`generator.py` 的 `asyncio.Lock`） | 一次只跑一个生成队列，测试时别并发提交 |
+| 4 | 单张 image-edit 是同步接口 | gpt 系列单张 1-5 分钟，前端 axios 超时 120s 可能先断（后端仍在跑，图会出现在生成结果） |
+| 5 | **ZCode IAB 浏览器调试 quirks**：`press`/Backspace 键注入在该页时灵时不灵（`fill` 可靠）；`fullPage` 截图偶发失败；文件上传不可用；改代码后页面 React 事件偶发失灵 → **reload 页面**即恢复 | 优先用 `fill`/`domSnapshot`/`getBoundingClientRect` 的 evaluate（注意 evaluate 可能被拒 side-effect，读值即可） |
+| 6 | 试算页水印文本存 localStorage（`trialWatermark`） | 改默认值不影响已保存设置；登记表同理存 localStorage `trialRegisterRecords` |
+| 7 | `studio/tsconfig.app.tsbuildinfo` 是构建产物 | 提交前 `git checkout -- studio/tsconfig.app.tsbuildinfo` |
+| 8 | 冻结代码不要投入 | `server/legacy/`、`extension-v1/`、`extension-v2/`、`web/`、studio 商品编辑页的属性映射/发布区块 |
+| 9 | AI 规划/生图花钱 | rightapi 按张计费；联调时 plan 张数设 1-2、优先 `nano-banana-2-lite`（快/便宜） |
+
+## 6. 关键文件速查
+
+| 功能 | 前端（studio/src/） | 后端（server/） |
+|---|---|---|
+| 试算页骨架 | `pages/trial/TrialPage.tsx` | — |
+| 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 图片与生图 | `pages/trial/TrialSuitePanel.tsx` + `AiImageGenModal.tsx` | `api/suite.py` + `services/{suite_service,generator,planner,prompts/,tasks,watermark}.py` |
+| 05 登记与导出 | `pages/trial/TrialExportPanel.tsx`（localStorage `trialRegisterRecords`） | — |
+| 前端服务层 | `services/{suite,product,ai,fx,api}.ts` | `schemas/suite.py`（契约对齐） |
+| 扩展上报 | `extensions/collector/src/api/report.ts` + `entrypoints/{background,sidepanel/App}.tsx` + `storage/settings.ts` | `api/materials.py` |
+
+## 7. 验收标准（改完怎么算完成）
+
+1. `pnpm -C studio exec tsc -b` 零错误、`pnpm -C studio build` 通过（提交前还原 `tsconfig.app.tsbuildinfo`）
+2. 改扩展：`pnpm -C extensions/collector build` 通过
+3. 改 server：`/api/health` 200、涉及接口 curl/页面冒烟通过
+4. UI 改动：浏览器实测 + 必要时截图确认