# V2 后端 API 设计

> 状态：方案设计（待确认）
> 上游：[V2 总览](./README.md) · [V2 架构](./architecture.md) · [数据库](./database.md)

统一约定：
- 前缀 `/api`；鉴权 `Authorization: Bearer <JWT>`（除 `/auth/login`、`/health` 外）。
- 错误：FastAPI 语义状态码；`detail` 为可读中文；校验错误 `422`。
- 列表分页：`?page=&page_size=` 或 `?limit=&last_id=`（Ozon 风格，仅对代理 Ozon 的接口）。
- 时间一律 ISO 8601 UTC。

---

## 1. 鉴权 `/api/auth`

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/auth/login` | `{token}` → `{access_token, expires_at}`。MVP：token 等于 `.env` 的 `APP_TOKEN`；升级后：用户名密码 |

---

## 2. 采集入库 `/api/materials`（插件 → 服务端）

沿用 `docs/extension/plan.md` §14 的契约，**把「文件夹」换成「商品」**。

### `POST /api/materials` ★ 主接口

```jsonc
{
  "product": {                        // 对应「文件夹」；首次上传可空=新建
    "id": "uuid-or-null"              // 传了=追加到已有商品（跨平台补素材）
  },
  "source": {
    "platform": "ozon",               // ozon | 1688 | taobao
    "itemId": "123456789",
    "url": "https://www.ozon.ru/product/…",
    "collectedAt": 1710000000000
  },
  "texts": [
    { "kind": "title", "content": "…" },
    { "kind": "params", "content": "…", "pairs": [{ "key": "…", "value": "…" }] }
  ],
  "images": [
    { "groupKey": "main", "groupName": "主图", "variantName": null,
      "url": "https://…原图…", "index": 0, "type": "img", "dedupeKey": "…" }
  ],
  "refererOrigin": "https://www.ozon.ru"    // 该站图片下载需带的 Referer
}
```

响应：

```jsonc
{ "product": { "id": "…", "stage": "collected" }, "assetsQueued": 12 }
```

**语义**：服务端立即落库（product + texts 进 raw + assets 置 `pending`），**响应不等图片下载完成**；后台协程按 `refererOrigin` 下载源图 → 转存七牛 → 更新 asset 状态。插件无需等待。

### 其余

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/materials/bytes` | 字节兜底：`multipart/form-data`（`product_id` + `meta`(JSON) + `file`），供源图带登录态、插件在页面上下文抓字节上传 |
| GET | `/products/:id/fingerprints` | 跨页去重：返回已采集 `dedupeKey` 列表 |
| GET | `/collected?platform=&itemId=` | 状态回显：`{collected, count}`（页面徽标用） |

---

## 3. 商品 `/api/products`

### 列表（采集箱 / 发布列表）

`GET /api/products?stage=&q=&page=&page_size=`

```jsonc
{
  "total": 128,
  "items": [
    {
      "id": "…", "stage": "collected",
      "name": "…", "offer_id": "", "price": null,
      "source_platform": "ozon", "source_url": "…",
      "asset_count": { "main": 6, "sku": 4, "detail": 9 },
      "ozon_product_id": null,
      "created_at": "…", "updated_at": "…"
    }
  ]
}
```

### 详情 / 编辑 / 删除

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/products/:id` | 完整商品（含 raw / pricing / copy / attributes / assets） |
| PATCH | `/products/:id` | 部分更新（编辑页 autosave）。可改字段见 database.md §2.3 |
| POST | `/products` | 手动新建商品（不经过插件） |
| DELETE | `/products/:id` | 软删（stage→archived）或硬删（采集箱未发布项） |
| POST | `/products/:id/stage` | `{stage}` 流转（editing→ready 前校验必填项） |

> 编辑页的计价、文案、图片、类目/属性都是「编辑 `products` 的某几列」，统一走 `PATCH /products/:id` 或细分子资源（见 §6–§8），不新增独立存储。

---

## 4. 汇率 `/api/fx`

`GET /api/fx` → `{ "rate": 11.84, "source": "cbr", "updated_at": "…" }`

服务端抓取（FloatRates → 俄央行 → er-api 三级降级，沿用 v1 数据源但**移到服务端**），缓存 + 脏数据过滤（5~25 区间）。前端计价用它，也可在计价时快照进 `products.fx_rate`。

---

## 5. AI 文案 `/api/ai`（沿用现有，零改动）

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/ai/models` | 模型列表（models.yaml） |
| POST | `/ai/copy` | 中文采买信息 → 俄文标题/描述/标签 + 中文对照 |

V2 编辑页的「文案」面板直接消费这两个接口，生成结果写入 `products.copy` + `products.name/description`（用户确认后）。

---

## 6. 图片 `/api/image`

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/image/edit` | **智能修图**（wanx2.1-imageedit，改名，沿用现有）——单图换背景/去水印/局部重绘/加文字 |
| POST | `/image/suite` | **电商套图**（集成 ecommerce-image-suite，新增）——原图 + 卖点 → 套图 |
| POST | `/image/upload-token` | 获取七牛直传 token（若走前端直传；一期可省，走服务端中转） |

`/image/edit` 与 `/image/suite` 的结果图由服务端**下载 → 转存七牛 → 返回七牛 URL**（改造现状 image_edit.py 已预留的扩展点）。

详见 [`image-strategy.md`](./image-strategy.md)。

---

## 7. 店铺 `/api/shops`

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/shops` | 列表（脱敏：不返回 key） |
| POST | `/shops` | `{name, client_id, api_key, currency_code}` 绑定（加密落库） |
| PATCH | `/shops/:id` | 更新（可只更新 name/currency，或换 key） |
| DELETE | `/shops/:id` | 删除（级联校验是否有进行中发布） |
| POST | `/shops/:id/test` | **连通性校验**：用该店铺凭证调 Ozon `/v1/roles`，成功→`{ok:true, roles:[…]}`，失败→`status=invalid` 并返回原因 |

> `test` 用 `/v1/roles`（返回该 key 的角色与方法权限），既验凭证又验权限范围，成本为零。

---

## 8. 类目与属性 `/api/categories`（服务端代理 Ozon）

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/categories/tree?lang=RU` | 类目树（代理 `/v1/description-category/tree`，服务端缓存） |
| GET | `/categories/:category_id/attributes?type_id=` | 属性列表（代理 `/v1/description-category/attribute`） |
| GET | `/categories/attribute/:attribute_id/values?category_id=&type_id=&q=` | 属性值字典（代理 `/values` 或 `/values/search` 按需） |

> 这些接口需要店铺凭证（Client-Id/Api-Key）。请求体里带 `shop_id`，服务端用对应店铺凭证调 Ozon。类目树可全局缓存（与店铺无关）；属性/值按类目缓存。详见 `ozon-publish.md` §3。

---

## 9. 发布 `/api/publish`

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/products/:id/publish` | `{shop_id}` 发布：组装 items[0] → `/v3/product/import` → 建 `publish_tasks` → 返回 `{task_id}` |
| GET | `/publish/:taskId` | 查询发布任务状态（服务端已轮询回写，直接读库） |
| GET | `/products/:id/publish-history` | 该商品历史发布记录 |

**发布请求体组装**（服务端职责，见 `ozon-publish.md` §5）：
1. 取 `products` 平铺字段 + `attributes`/`complex_attributes`；
2. 剥离 `_` 前缀扩展字段（DB 里已天然分层，无需剥离）；
3. 校验必填（name/description/category/尺寸重量/offer_id/images）；
4. `POST /v3/product/import`（头 `Client-Id`/`Api-Key`）→ 得 `task_id`；
5. 后台轮询 `POST /v1/product/import/info` → 回写 `products.stage` + `ozon_product_id`。

---

## 10. CSV 导出 `/api/export`

`GET /api/export/products.csv?stage=&ids=` → 流式返回带 BOM 的 UTF-8 CSV。

字段（默认全量，`fields=` 可指定子集）：

```
offer_id, product_id, name, description_category_id, price, old_price,
currency_code, vat, weight, weight_unit, depth, width, height, dimension_unit,
barcode, primary_image, images(join "|"), source_platform, source_item_id, source_url,
stage, published_at, created_at
```

已发布商品含 `product_id`；未发布留空。支持按 `stage`（collected/published/全部）与 `ids`（勾选导出）筛选。CSV 字段明细与公式见 [`ozon-publish.md`](./ozon-publish.md) §6。

---

## 11. 插件运维接口（沿用 plan.md §14）

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/ext/profiles` | 远程采集配置下发（选择器热更） |
| POST | `/ext/logs` | 埋点批量上报（抗改版看板） |

---

## 12. 接口 → 现有代码映射（改造量）

| V2 接口 | 现状 | 改造 |
|---|---|---|
| `/auth/*` | 无 | 新建 |
| `/materials` 系列 | 无（plan 里有设计） | 新建 |
| `/products` 系列 | 无 | 新建 |
| `/fx` | 无（v1 前端直连第三方） | 新建（搬 v1 数据源到服务端） |
| `/ai/*` | ✅ 有 | 复用 |
| `/image/edit` | ✅ 有 | 复用 + 加七牛转存 |
| `/image/suite` | 无 | 新建（集成 ecommerce-image-suite） |
| `/shops`、`/categories`、`/publish`、`/export` | 无（`api/ozon.py` 占位） | 新建 |
| `/ext/*` | 无 | 新建 |