R524809
a77ec26a02
- 删除 shops/publish/categories/ozon 相关路由、模型、schema 与客户端服务（V2.1 决策放弃 API 直传，改人工上传）
- materials 新增 DELETE /assets/{id}：删除素材记录与本地文件，并同步修正 asset_counts
- 试算页支持单张素材删除，生图弹窗交互微调
- 新增 docs/v2.1/HANDOFF.md 工作交接说明，README 补充索引
102 lines
7.8 KiB
Markdown
102 lines
7.8 KiB
Markdown
# 工作交接说明（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 改动：浏览器实测 + 必要时截图确认
|