ozon-seller-kit/docs/v2/architecture.md

# V2 总体架构

> 状态：方案设计（待确认）
> 上游：[V2 总览](./README.md) · V1 [`architecture.md`](../architecture.md)
> 前置阅读：建议先读 [`capability-inventory.md`](./capability-inventory.md) 了解现状资产。

---

## 1. 组件与职责

```
┌───────────────┐   Bearer Token    ┌──────────────────────────────────────────────┐
│ Chrome 插件     │ ────────────────▶ │ 服务端 server/（FastAPI）                     │
│ extension-v2    │  POST /api/materials│                                              │
│ （Ozon/1688 采集）│                   │  ├─ api/    采集/商品/类目/店铺/发布/图片/汇率 │
└───────────────┘                     │  ├─ services/  Ozon / DeepSeek / 套图 / 七牛    │
        ▲                              │  ├─ models/   SQLAlchemy ORM + Alembic        │
        │  远程配置 / 埋点               │  └─ jobs/    异步：图下载转存 / 发布轮询        │
┌───────┴───────┐                     │                                              │
│ 采集配置文件     │                     └──────┬───────────────┬───────────────┬────────┘
│（可热更）        │                            │               │               │
└───────────────┘                 ┌──────────▼──┐    ┌───────▼────────┐  ┌─────▼─────────┐
                                  │ PostgreSQL  │    │ 七牛对象存储     │  │ Ozon Seller API│
                                  │ 商品/店铺/任务│    │ 源图/生成图/水印 │  │ Client-Id+Api-Key│
                                  └─────────────┘    └────────────────┘  └───────────────┘
                                                ▲
                                                │ REST /api/*
                                  ┌─────────────┴──────────────┐
                                  │ studio/（React + Vite + antd）│
                                  │ 采集箱 / 商品编辑 / 发布 / 店铺 / 导出 │
                                  └────────────────────────────┘
```

四个部分与 V1 一致（插件 / studio / server / 采集配置），但 **studio 的职责显著扩大**（从单页图生图 → 完整工作台），**server 从无状态代理 → 有状态业务中枢**。

---

## 2. 核心边界（延续 V1，补充 V2）

1. **密钥只放服务端**：DeepSeek / DASHSCOPE / 七牛 / Ozon 店铺 Client-Id+Api-Key 全部只在 server 侧；插件和 studio 只持有一个长期 Bearer Token。
2. **插件仍做纯采集**：不调 LLM、不做图片处理、不碰 Ozon API；只是把「写本地文件夹」换成「上传落库」。
3. **服务端是唯一出网口（对 Ozon/云厂商）**：插件 background 与服务端通信，studio 与服务端通信；谁都不直连 Ozon。
4. **商品数据单点真源 = `products` 表**：`_` 前缀的本地扩展字段（`_raw`/`_pricing`/`_images`）仍保留在 JSONB 里，提交 Ozon 前按 V1 契约剥离。
5. **图片一律七牛公网 URL**：数据库里存七牛 URL，不存本地路径、不存源站 URL（源站 URL 仅存 `product_assets.source_url` 做溯源）。

---

## 3. 技术栈

| 部分 | 技术栈 | 说明 |
|---|---|---|
| server | FastAPI + SQLAlchemy 2.0（async）+ Alembic + httpx | 沿用现状 FastAPI；ORM 用 SQLAlchemy 2.0 async |
| DB | PostgreSQL 16（腾讯云 CDB） | JSONB 存 attributes/raw/pricing |
| 任务 | 轻量：先 DB 轮询 + asyncio 后台任务；量大再上 Redis/Celery | 图下载转存、发布轮询都是 IO 密集 |
| 对象存储 | 七牛云 Kodo | 源图转存 + 生成图 + 水印结果 |
| 缓存 | 类目/属性字典 → PostgreSQL 表 + 内存 LRU；可选 Redis | 见 `ozon-publish.md` §3 |
| studio | React 19 + Vite 7 + antd 6 + react-router 7 | 沿用现状；加 react-query 或 zustand 管状态 |
| extension | WXT + React + TS | 沿用；改造 export → upload |
| 鉴权 | JWT（短期）+ Bearer Token；MVP 单用户，预留 `users` 表 | 见 §6 |

**与 V1 的差异**：唯一新增重依赖是 **SQLAlchemy + Alembic** 和 **七牛 SDK（qiniu）**。任务队列一期不引入 Redis/Celery，用「DB 状态机 + 后台协程」即可（单人自用规模）。

---

## 4. 目录结构（目标）

```
ozon-seller-kit/
├── server/
│   ├── main.py                    # 应用入口，挂载路由 + studio 静态
│   ├── api/                       # 按域拆：collection / products / categories /
│   │   │                          #   shops / publish / export / image / ai / fx / auth
│   ├── services/                  # ozon_client / deepseek / image_suite / qiniu / pricing
│   ├── models/                    # SQLAlchemy 模型（见 database.md）
│   ├── schemas/                   # Pydantic（接口契约真源）
│   ├── jobs/                      # 后台协程：下载转存 / 发布轮询
│   ├── migrations/                # Alembic
│   └── config/                    # settings.py + models.yaml（沿用）
├── studio/                        # 工作台（多页）
│   └── src/
│       ├── pages/
│       │   ├── collection/        # 采集箱列表
│       │   ├── product/           # 商品编辑（核心）
│       │   │   └── components/    #   PricingPanel / CopyPanel / ImagePanel /
│       │   │                      #   CategoryPicker / AttributeMapper / PublishPanel
│       │   ├── publish/           # 发布任务 / 状态
│       │   ├── shops/             # 店铺管理（Client-Id / Api-Key）
│       │   ├── export/            # CSV 导出
│       │   └── ai-image/          # 保留：智能修图（wanx2.1-imageedit，改名）
│       ├── services/              # 与 /api/* 对齐的客户端
│       ├── stores/                # zustand：商品编辑态 / 采集箱筛选
│       └── pricing/               # 从 v1 抄来的计价纯函数（不改原文件）
├── extension-v2/                  # 采集插件（改造：上传落库）
│   └── src/
│       ├── messaging/             # 消息层（plan.md §9）
│       ├── api/                   # 后端客户端（仅 background）
│       └── collector/ profiles/   # 沿用采集引擎
├── web/                           # v1 工具台，冻结
├── docs/
│   ├── v2/                        # ★ 本文档集
│   └── ...（V1 文档）
└── .env / .env.example
```

---

## 5. 状态机：商品生命周期

V1 是 `collected → edited → published`。V2 因为「落库 + 异步发布」，扩展为：

```
collected ──(进入编辑)──> editing ──(填写完整)──> ready ──(点发布)──> publishing
                                                                      │
                              ┌───────────────────────────────────────┤
                              ▼                                        ▼
                          imported（成功）                          failed（失败，可改后重发）
                              │                                        ▲
                              └────── published ──(可归档)──> archived ─┘

collected  插件刚上传，只有素材与原文
editing    用户正在编辑（计价/文案/图片/类目）
ready      必填项齐全，可发布
publishing 已提交 ImportProductsV3，拿到 task_id，等待轮询
published  轮询 imported 成功，回填 product_id
failed     轮询返回 errors / 校验失败；可回到 editing 修复后重发
archived   手动归档（软删）
```

- 每步都落库，刷新/换设备不丢。
- `publishing` 由发布任务表（`publish_tasks`）驱动，服务端轮询 `/v1/product/import/info` 更新状态。
- 状态定义详见 [`database.md`](./database.md) §2.2。

---

## 6. 鉴权与多租户

**MVP（单人自用）**：`.env` 里配一个 `APP_TOKEN`，插件 options 页和 studio 登录页填同一个值，请求头 `Authorization: Bearer <APP_TOKEN>`。服务端校验后签发短期 JWT，后续请求用 JWT。

**预留升级路径（不影响 MVP）**：`users` 表 + `shops.user_id` 已留好外键，未来要做多用户 SaaS 只需补注册/登录 + 按 `user_id` 过滤查询，schema 不用改。

| 层 | MVP | 升级 |
|---|---|---|
| 身份 | 单个 `APP_TOKEN` | `users` 表 + 密码哈希 |
| 会话 | 短期 JWT（`Authorization: Bearer`） | 同左，加刷新令牌 |
| 店铺归属 | 全部归当前用户 | 按 `user_id` 隔离 |
| 密钥保护 | 店铺 Api-Key 服务端 AES-GCM 加密落库 | 同左 |

---

## 7. 部署拓扑（腾讯云）

```
                    ┌────────────── nginx (443) ──────────────┐
                    │  /api/*     → uvicorn (127.0.0.1:8800)  │
  浏览器/插件 ─────▶ │  /          → studio 静态资源（构建产物）│
                    │  /ozonSeller.html → web/（v1，可选保留） │
                    └─────────────────────────────────────────┘
                                    │
              ┌─────────────────────┼─────────────────────┐
              ▼                     ▼                     ▼
     PostgreSQL（CDB）      七牛 Kodo（对象存储）    外部 API（Ozon/DeepSeek/DashScope）
```

- **单进程部署**：FastAPI 同源托管 studio 构建产物（与 V1 托管 web/ 同思路），`/api` 走 nginx 反代到 uvicorn。
- **环境变量**：`.env` 在服务器上维护（不入 git），新增 `APP_TOKEN` / `DATABASE_URL` / `QINIU_*` / `APP_BASE_URL`。
- **CORS**：同源托管时 `CORS_ORIGINS` 留空；开发期 studio 跑 8900 时用 Vite 代理 `/api`，无需 CORS。
- 详见 [`migration.md`](./migration.md) §5。

---

## 8. 与 V1 的差异小结

| 维度 | V1 | V2 |
|---|---|---|
| 契约真源 | 磁盘「商品文件夹」 | `products` 表 + 七牛 |
| 插件出口 | File System Access 写盘 | `POST /api/materials` 落库 |
| studio | 单页图生图 | 多页工作台 |
| server | 无状态代理（ai/image） | 有状态业务中枢（DB/七牛/Ozon/任务） |
| 发布 | 预留 `/api/ozon/*` 占位 | 完整发布链路 + 任务轮询 |
| 图片 | 图生图（wanx2.1）+ 前端水印 | 智能修图 + 电商套图 + 七牛托管 |
| 数据导出 | v1 登记表 CSV（前端） | 服务端统一 CSV 导出 |
| 部署 | 本机 127.0.0.1 | 腾讯云公网 |