R524809
345 lines
16 KiB
Markdown
345 lines
16 KiB
Markdown
# Ozon Seller Kit 总体架构
|
||
|
||
> 状态：架构设计（待确认）
|
||
> 最后更新：2026-08-11
|
||
> 相关：[插件方案](./extension/plan.md) · [部署](./deployment.md) · [文案后端](./ai-copy-backend-plan.md)
|
||
|
||
---
|
||
|
||
## 1. 项目定位
|
||
|
||
围绕 Ozon 跨境上品的一套自用工具链，覆盖**采集 → 编辑 → 发布**全链路，货源来自 Ozon 竞品页（跟卖）与 1688/淘宝/拼多多（补素材）。
|
||
|
||
四个组成部分，各自独立可用、通过明确契约衔接：
|
||
|
||
|
||
| # | 部分 | 形态 | 状态 | 职责 |
|
||
| --- | ---------- | ------------------------- | ------- | ---------------------------- |
|
||
| ① | **工具台 v1** | 静态页（原生 JS + Tailwind CDN） | ✅ 在用 | 计价、上品登记、水印、俄文文案。**冻结维护，不重构** |
|
||
| ② | **采集插件** | Chrome MV3 扩展 | 🔨 待开发 | Ozon/1688 商品页采集 → 落本地文件夹 |
|
||
| ③ | **发布工作台** | Web 应用 | 📋 待设计 | 导入本地文件夹 → 编辑/图片处理 → 提交发布 |
|
||
| ④ | **服务端** | FastAPI | 🔨 部分就绪 | AI 文案、图片处理、Ozon API 代理、凭证保管 |
|
||
|
||
|
||
**关键边界**：① 与 ③ 并存不互相替代。① 是已验证好用的轻量工具，③ 是面向"整商品发布"的新流程；③ 成熟后 ① 的计价器可能被吸收，但那是以后的事。
|
||
|
||
---
|
||
|
||
|
||
|
||
## 2. 目录结构
|
||
|
||
```
|
||
ozon-seller-kit/
|
||
├── server/ # ④ 服务端（FastAPI）
|
||
│ ├── main.py
|
||
│ ├── api/ # ai / image / ozon / collection
|
||
│ ├── services/
|
||
│ ├── schemas/ # Pydantic = 数据契约真源
|
||
│ ├── config/
|
||
│ └── requirements.txt
|
||
│
|
||
├── web/ # ① 工具台 v1 —— 原地冻结，不改目录名
|
||
│ ├── ozonSeller.html
|
||
│ ├── js/ css/ imgs/
|
||
│ └── README.md # 标注「v1，仅修 bug」
|
||
│
|
||
├── extension/ # ② 采集插件（WXT + TS）
|
||
│ ├── entrypoints/
|
||
│ ├── src/{profiles,collector,export,storage}/
|
||
│ └── package.json
|
||
│
|
||
├── studio/ # ③ 发布工作台
|
||
│ └── （技术栈待定，见 §8）
|
||
│
|
||
├── packages/
|
||
│ └── schema/ # 跨端共享契约（TS 类型 + JSON Schema）
|
||
│
|
||
├── reference/
|
||
│ └── 1688-extension/ # 反编译参考资料，非本项目代码
|
||
│
|
||
├── docs/ # 全部文档集中于此
|
||
│ ├── architecture.md # ← 本文
|
||
│ ├── deployment.md
|
||
│ ├── ai-copy-backend-plan.md
|
||
│ ├── contracts/ # 数据契约说明
|
||
│ ├── extension/ # 插件方案
|
||
│ └── studio/ # 发布工作台方案
|
||
│
|
||
├── start.command
|
||
└── .env / .env.example
|
||
```
|
||
|
||
两处与现状不同，需要迁移（§9）：后端从仓库根收进 `server/`；`seller-helper/` 拆解为 `reference/` + `docs/extension/`。
|
||
|
||
### 2.1 为什么后端要收进 `server/`
|
||
|
||
现状后端散在仓库根（`main.py`、`api/`、`services/`、`schemas/`、`config/`）。四个部分并列后，根目录会同时出现 Python 包目录和三个前端项目目录，`api/` 这种名字看不出属于谁。收进 `server/` 后每个顶层目录一一对应一个部分。
|
||
|
||
代价：`start.command` 与 `docs/deployment.md` 里的启动路径要改，`.env` 加载路径 `parents[1]` 要跟着调。Python 内部 import 全是 `from api import ...` 这类顶层相对形式，只要工作目录切到 `server/` 就不受影响。
|
||
|
||
**这是唯一有破坏性的改动，建议在动** `studio/` **之前一次做完，不要拖到中途。** 如果你想零风险，也可以让后端留在根目录——架构其余部分不依赖这个决定。
|
||
|
||
### 2.2 为什么 `web/` 不改名
|
||
|
||
改名会动 `main.py` 的挂载路径、`start.command`、部署文档，收益只是"名字更清楚"。目录名保持 `web/`，在里面放一个 README 标注定位即可。
|
||
|
||
路由上两代共存：`studio/` 上线后占 `/studio`，`web/` 继续在 `/ozonSeller.html`。谁占根路径是路由配置问题，跟目录名无关。
|
||
|
||
---
|
||
|
||
|
||
|
||
## 3. 核心数据契约：商品文件夹
|
||
|
||
**这是整个架构最重要的一个决定。** 四个部分之间不直接调用彼此的代码，只认一个约定：磁盘上的「商品文件夹」。
|
||
|
||
```
|
||
儿童保温杯_316不锈钢/
|
||
├── product.json # 商品数据（唯一真源）
|
||
├── sources.json # 采集溯源：哪个平台、哪个 URL、什么时候
|
||
└── images/
|
||
├── main/ # main-001.jpg …
|
||
├── sku/ # sku-001-blue.jpg（文件名带规格名）
|
||
├── detail/ # detail-001.jpg …
|
||
└── video/
|
||
```
|
||
|
||
数据流因此变成：
|
||
|
||
```
|
||
插件 ──写──> 商品文件夹 ──读──> 发布工作台 ──调用──> 服务端 ──> Ozon API
|
||
↑
|
||
1688 插件二次采集追加
|
||
```
|
||
|
||
三个好处：
|
||
|
||
1. **插件和工作台完全解耦**。插件不需要知道工作台存在，反之亦然。任一端重写不影响另一端。
|
||
2. **中间产物可见可改**。采集结果就是普通文件夹，能用 Finder 看、能手动补图、能备份、能在两台机器间拷。
|
||
3. **跨平台合并天然成立**。Ozon 采完，切到 1688 采同类商品，选同一个文件夹继续写入——就是往同一目录追加文件，不需要任何服务端参与。
|
||
|
||
|
||
|
||
### 3.1 product.json
|
||
|
||
结构对齐 Ozon `ProductAPI_ImportProductsV3`，但**不等于**它的请求体。区别在于采集阶段拿不到的字段留空，由工作台补齐：
|
||
|
||
|
||
| 字段 | 采集阶段 | 工作台补齐 |
|
||
| ------------------------- | ----------- | -------------------------- |
|
||
| `name` / `description` | ✅ 原文（可能是俄文） | 改写/翻译 |
|
||
| `images` | 本地相对路径 | 上传图床后换成公网 URL |
|
||
| `offer_id` | ❌ 空 | **必须填自己的货号**（跟卖场景下不能沿用竞品的） |
|
||
| `description_category_id` | ❌ 空 | 类目选择/推荐 |
|
||
| `attributes[].id` | ❌ 空 | 查类目属性字典映射 |
|
||
| 尺寸重量 | 参数表里有就带上 | 校验补全 |
|
||
| `price` / `old_price` | 采到竞品价，仅供参考 | 计价器算出 |
|
||
|
||
|
||
所以 product.json 有个 `_meta.stage` 字段标明它处在哪个阶段：`collected` → `edited` → `published`。
|
||
|
||
契约细节见 `[docs/contracts/product-json.md](./contracts/product-json.md)`。
|
||
|
||
### 3.2 契约真源与双语言实现
|
||
|
||
Pydantic（`server/schemas/`）是真源，因为服务端最终要用它做校验。由此派生：
|
||
|
||
```
|
||
server/schemas/product.py (Pydantic)
|
||
│
|
||
├── 导出 JSON Schema ──> packages/schema/product.schema.json
|
||
│ │
|
||
│ └── 生成 TS 类型 ──> 插件 / 工作台
|
||
└── 服务端运行时校验
|
||
```
|
||
|
||
不上 codegen 流水线（单人项目不值得）：插件端手写一份对应的 TS interface，配一个 fixture 文件双向跑一遍校验做契约测试。schema 变更时测试会红。
|
||
|
||
---
|
||
|
||
|
||
|
||
## 4. 各部分职责与边界
|
||
|
||
|
||
|
||
### ① 工具台 v1（`web/`）
|
||
|
||
**冻结。** 只修 bug，不加功能、不重构、不迁技术栈。它当前的价值是「已经好用」，任何改动都是风险。
|
||
|
||
新需求一律进 `studio/`。计价逻辑（`web/js/app.js`）后续会被 studio 复用——那时候是**读它、抄它的公式**，不是改它。
|
||
|
||
### ② 采集插件（`extension/`）
|
||
|
||
只做四件事：识别页面、提取素材、分组、写文件夹。
|
||
|
||
不做：LLM 调用、图片处理、Ozon API、持有任何密钥。
|
||
|
||
一期只支持 Ozon（跟卖是第一优先级），1688 二期。详见 `[docs/extension/plan.md](./extension/plan.md)`。
|
||
|
||
### ③ 发布工作台（`studio/`）
|
||
|
||
导入本地文件夹 → 编辑 → 发布。三块能力：
|
||
|
||
- **表单编辑**：product.json 各字段，类目选择，属性映射，计价（复用 v1 公式）
|
||
- **图片处理**：水印、白底、图内翻译、图生图 —— 重活走服务端
|
||
- **发布**：提交 Ozon 草稿，回填 `product_id`
|
||
|
||
|
||
|
||
### ④ 服务端（`server/`）
|
||
|
||
唯一持有密钥的地方。当前有 `/api/ai/*`（文案）；待补 `/api/image/*`、`/api/ozon/*`。
|
||
|
||
**Ozon 发布有个硬约束值得提前知道**：`ProductAPI_ImportProductsV3` 的 `images` 只接受**公网可访问的 URL**，Ozon 服务器会主动来拉。本地文件夹里的图必须先上传到图床/对象存储才能发布。这决定了服务端必须有图床能力，也决定了「本地文件夹」方案无法绕过服务端直接发布。
|
||
|
||
---
|
||
|
||
|
||
|
||
## 5. 端到端数据流
|
||
|
||
```
|
||
① 浏览 Ozon 竞品页
|
||
│ 点插件按钮 → 侧边栏打开 → 人工确认页面加载完 → 点采集
|
||
▼
|
||
② 侧边栏表单化展示采集结果（可二次编辑），图片分组勾选
|
||
│ 选保存目录 → 导出
|
||
▼
|
||
③ 本地商品文件夹（product.json + images/）
|
||
│ （可选）切到 1688 采同类商品，选同一文件夹追加
|
||
▼
|
||
④ 发布工作台：选择文件夹导入
|
||
│ 编辑字段 / 加水印 / 图生图 / 定类目 / 计价
|
||
▼
|
||
⑤ 服务端：图片上传图床 → 属性字典校验 → 提交 Ozon 草稿
|
||
▼
|
||
⑥ 回填 product_id 到 product.json，stage 置 published
|
||
```
|
||
|
||
每一步的产物都落盘，中断了可以从任意一步接着来。
|
||
|
||
---
|
||
|
||
|
||
|
||
## 6. 技术栈
|
||
|
||
|
||
| 部分 | 技术栈 | 说明 |
|
||
| ----------- | ----------------------- | ------------------------------------ |
|
||
| ① web | 原生 JS + Tailwind CDN | 不动 |
|
||
| ② extension | WXT + React + TS strict | WXT 比 Plasmo 活跃 |
|
||
| ③ studio | 待定（见 §8） | |
|
||
| ④ server | FastAPI + Pydantic | 已有 |
|
||
| 共享 | pnpm workspace | 只为 `packages/schema` 共享，不上 turborepo |
|
||
|
||
|
||
pnpm workspace 的唯一目的是让插件和 studio 共用契约类型。`pnpm-workspace.yaml` 三行搞定，不引入构建编排复杂度。
|
||
|
||
---
|
||
|
||
|
||
|
||
## 7. 服务端演进
|
||
|
||
当前是无状态的：只有 AI 文案代理，没有数据库。按需要逐步加，不要一次上齐：
|
||
|
||
|
||
| 阶段 | 触发条件 | 要加什么 |
|
||
| --- | -------------- | -------------------------------------- |
|
||
| 现在 | — | 无状态，`/api/ai/*` |
|
||
| S1 | studio 要处理图片 | `/api/image/*`（水印/白底/翻译），仍无状态：收图返图 |
|
||
| S2 | 要发布到 Ozon | `/api/ozon/*` + 图床 + 类目字典缓存（SQLite 够用） |
|
||
| S3 | 图片处理变慢（图生图、视频） | 任务队列 + `/api/job/:id` 轮询 |
|
||
| S4 | 想要跨设备同步 | 商品库落库，本地文件夹降级为导入导出格式 |
|
||
|
||
|
||
**S1、S2 都不需要数据库**，类目字典用文件缓存即可。S4 是个大改动，只在真的有多设备需求时才做——本地文件夹方案的一个优点就是单机场景下完全不需要它。
|
||
|
||
---
|
||
|
||
|
||
|
||
## 8. 已定决策
|
||
|
||
|
||
|
||
### D1 · 后端迁入 `server/` ✅
|
||
|
||
代价是改 `start.command`、`settings.py` 的 `.env` 路径、`deployment.md`。Python 内部 import 不受影响（工作目录切到 `server/` 即可）。**这是唯一有破坏性的改动，在开工 studio 前一次做完。**
|
||
|
||
### D2 · studio 用 React + Vite + TS ✅
|
||
|
||
studio 的核心是"几十个字段的结构化表单 + 图片批处理"，正是原生 JS 最吃力的场景。与插件同栈，图片处理组件和契约类型可两边复用。v1 的计价公式（`web/js/app.js`）抄过来即可，不改原文件。
|
||
|
||
### D3 · 保存用 File System Access API ✅
|
||
|
||
`chrome.downloads` 的 `filename` 只能是下载目录下的相对路径，不接受绝对路径或 `..`，因此无法满足"用户选择保存目录"，也无法读回 `sources.json` 做去重。
|
||
|
||
File System Access 在 side panel（扩展页面上下文）可用，`showDirectoryPicker()` 拿到的 handle 存进 IndexedDB 后**跨会话免重复授权**，正好支撑"Ozon 采完切 1688 追加到同一文件夹"。`chrome.downloads` 保留为降级路径（用户拒绝授权时）。
|
||
|
||
细节见 `[docs/extension/plan-revision.md](./extension/plan-revision.md)` R1。
|
||
|
||
---
|
||
|
||
|
||
|
||
## 9. 迁移计划
|
||
|
||
一次性做完，中途不要停在半路：
|
||
|
||
```
|
||
① 后端收拢
|
||
main.py api/ services/ schemas/ config/ requirements.txt → server/
|
||
改 server/config/settings.py: parents[1] → parents[1]（指向 server/，.env 仍在仓库根则用 parents[2]）
|
||
改 start.command: cd server 后再 uvicorn
|
||
改 docs/deployment.md 中所有路径
|
||
|
||
② 参考资料归位
|
||
seller-helper/1688-extension/ → reference/1688-extension/
|
||
|
||
③ 文档集中
|
||
seller-helper/docs/方案设计.md → docs/extension/legacy-v1.md
|
||
seller-helper/docs/方案设计-V2.md → docs/extension/legacy-v2.md
|
||
seller-helper/docs/插件开发方案.md → docs/extension/plan.md
|
||
seller-helper/extension-plan/IMPLEMENTATION_PLAN.md → 合并进 docs/extension/plan.md
|
||
|
||
④ 上一轮错放的代码归位
|
||
seller-helper/extension-plan/profiles-ozon.ts → extension/src/profiles/ozon.ts
|
||
seller-helper/extension-plan/download-implementation.ts → extension/src/export/download.ts
|
||
（建插件项目时再放，现在先留在 docs/extension/ 作为草案附件）
|
||
|
||
⑤ 删空目录
|
||
seller-helper/
|
||
|
||
⑥ web/ 加 README 标注 v1 冻结
|
||
```
|
||
|
||
`reference/1688-extension/` 要不要进 git：它是反编译产物，约 40 个 bundle。建议**加进** `.gitignore`，保留在本地即可——设计结论已经写进 `docs/extension/plan.md` §2，原始 bundle 只在需要再次查证时才用。
|
||
|
||
---
|
||
|
||
|
||
|
||
## 10. 里程碑（已调整优先级）
|
||
|
||
**插件先行：1688/淘宝 → Ozon**。理由见 `[docs/extension/1688-taobao-implementation.md](./extension/1688-taobao-implementation.md)`。
|
||
|
||
|
||
| # | 内容 | 依赖 | 产出 | 工作量 |
|
||
| ------ | ---------------------------------- | --- | ------------------------------- | --- |
|
||
| **M0** | 目录迁移 + 文档集中 | — | ✅ 已完成，服务正常起 | — |
|
||
| **M1** | 插件：1688 采集引擎 | M0 | Console 里能跑 `scanCurrentPage()` | 4h |
|
||
| **M2** | 插件：淘宝 profile | M1 | 淘宝页面同样可用 | 1h |
|
||
| **M3** | 插件：Side Panel + File System Access | M2 | 生成完整商品文件夹到本地 | 4h |
|
||
| **M4** | 插件：sources.json 去重 | M3 | 二次采集追加不重复 | 1h |
|
||
| **M5** | 契约真源：product.json Pydantic | M0 | `server/schemas/product.py` | 2h |
|
||
| **M6** | 插件：Ozon profile 实测 | M4 | Ozon 选择器验证（需真实页面链接） | 2h |
|
||
| **M7** | studio：导入文件夹 + 表单编辑 | M5 | 能改能存 | 8h |
|
||
| **M8** | studio + server：图片处理 | M7 | 水印/白底可用 | 6h |
|
||
| **M9** | server：Ozon 发布 | M8 | 草稿进 Ozon 后台 | 4h |
|
||
|
||
|
||
**M4 结束时插件功能完整**，可以采集 1688/淘宝商品到本地文件夹，跨平台追加不重复。M9 结束时全链路跑通。 |