joey5628/ozon-seller-kit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a77ec26a0234cf67ceb5f91e6aeb2790b4f75a8d
ozon-seller-kit/docs/v2.1/HANDOFF.md
T
R524809 a77ec26a02 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

7.8 KiB
Raw Blame History

工作交接说明（HANDOFF）

更新：2026-08-28 晚 读者：下一个接手工作的 AI / 开发者。先读本文再动手，避免重复探索。 配套文档：README（项目总览）、collect.md（采集）、trial-page.md（试算页）、image-suite.md（生图）、api.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. 启动与构建

# 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 改动：浏览器实测 + 必要时截图确认
Reference in New Issue View Git Blame Copy Permalink