# 采集箱与在线商品需求

> 状态：已确认核心规则，待补充具体 PostgreSQL 表和 API 契约。采集插件入口和来源多 SKU 规则见 [`collector-browser-extension.md`](./collector-browser-extension.md)。

## 1. 领域边界

采集箱是工作空间共用的商品工作池：插件的“采集商品”“编辑上架”以及手动创建商品，都先创建或复用一条采集箱记录。采集时没有目标平台和门店。用户进入 ERP 编辑时使用页头当前平台；系统为该商品取得或创建这个平台的发布配置，并预选该平台默认门店。门店可以为这次及后续未上架 SKU 修改，但采集箱商品本身不属于任何门店。

**上架成功不会把商品移出采集箱。** 采集箱保留该商品，以便继续查看和编辑 Atlas 草稿；某个已成功提交到平台的 SKU 不能再次提交上架，但同一 SPU 下仍未上架的 SKU 可以首次上架。采集箱状态随**当前页头平台**变化：商品在 A 平台上架后，切换到 B 平台仍是未上架。在线商品是另一份“目标店铺在平台上实际存在什么商品”的同步视图，不能只由 Atlas 的发布记录推断。

```text
来源采集 / 手动创建
  → 采集箱（持续保留、可编辑；已成功上架 SKU 不可再次上架）
  → 发布任务 / Ozon 当前状态
  → 在线商品（店铺级平台同步视图，含非 Atlas 创建商品）
```

## 2. 采集箱列表

默认按更新时间倒序显示当前工作空间内所有未删除的采集箱商品；已上架商品仍显示。

| 列 | 展示与规则 |
|---|---|
| 复选框 | 用于批量删除。 |
| 图片 | 首张已就绪主图；素材转存中显示占位进度，失败显示占位和提示。 |
| 产品名称 | 来源标题或手动填写标题；尚未填写时显示“未命名商品”。 |
| 采集价格 | 单 SKU 显示来源价格；多 SKU 显示最小值–最大值，始终保留来源币种。它不是目标店铺售价。 |
| SKU 数量 | 来源确认的真实 SKU 数；无可靠组合时是默认 SKU `1`，并带“待确认”提示。 |
| 采集来源 | Ozon、1688、淘宝、天猫或手动创建；这是**来源平台**，不是目标发布平台。 |
| 备注 | 工作空间内管理备注，不发送给平台。 |
| 上架状态 | 按页头当前平台显示 `未上架`、`已部分上架` 或 `已上架`，口径见第 3 节。 |
| 创建时间 | 采集箱记录首次创建时间。 |
| 更新时间 | 采集补全、素材转存、编辑保存、发布任务或同步结果更新的时间。 |
| 操作 | 未上架：`编辑上架`、`删除`；已上架：`编辑`、`删除`。 |

顶部功能：

- 按产品标题模糊查询；
- 按采集来源平台筛选；
- 按上架状态筛选；
- `手动创建商品`；
- 容量进度条：`当前有效采集箱商品数 / 1000`；
- `批量删除`、`清空采集箱`。

容量按采集箱商品数计算，不按 SKU 数计算。一条采集箱记录即使含多个 SKU，也只计 1 个。由于已上架商品仍保留在采集箱，它同样占用当前 1000 条临时上限；已删除记录不计入。重复采集命中工作空间内同一 `source_platform + source_item_key` 时复用原记录，不增加额度。

## 3. 当前平台的上架状态和失败原因

列表按当前平台汇总该 SPU 下未删除 SKU 的**首次导入结果**；它不是 Ozon 前台可见性。Ozon 库存由卖家后续在 Ozon 后台设置，`visible`、库存、审核等实际状态在在线商品中查看。主状态有三种：

| 主状态 | 判定 |
|---|---|
| `未上架` | 当前平台没有任何 SKU 导入成功；包括未选择门店、尚未提交、提交处理中或所有已提交 SKU 均失败。 |
| `已部分上架` | 至少一个 SKU 已导入成功，且仍有未删除 SKU 未导入成功或正在处理。 |
| `已上架` | 当前平台下全部未删除 SKU 均已导入成功。若删除所有未上架 SKU、只留下已上架 SKU，状态随即变为此值。 |

“未上架”不能只给笼统结果。状态列的第二行或悬浮详情应展示状态说明：

- `未选择目标平台`；
- `等待发布`；
- `导入处理中` / `审核中`；
- `已导入，库存由 Ozon 后台维护`；
- `审核拒绝：{最近原因}`；
- `上架失败：{最近失败原因}`；
- `已归档或已下架`。

失败原因优先取最近 Atlas 发布任务保存的结构化错误；同步后若 Ozon 返回更准确的 `errors`、`status.decline_reasons` 或 `status.state_description`，以 Ozon 同步结果更新展示。处理/审核中不应误标为失败。

已成功上架的 SKU 没有“重新上架”或“更新平台商品”路径：编辑仅保存 Atlas 草稿，不向 Ozon 提交接口请求。未上架 SKU 可以在同一 SPU 中继续首次上架。若未来需要修改 Ozon 已有商品，应从在线商品的 SKU 行进入专门的“编辑在线商品”流程，并单独设计可修改字段、审核及发布规则；不能复用采集箱的上架按钮。首次发布仍为每个 SKU 保存独立不可变快照和任务记录。

## 4. 编辑、手动创建与删除

### 4.1 编辑上架

点击后进入 ERP 编辑入口：

1. 读取页头当前平台（首期默认 Ozon），取得或创建该商品的当前平台发布配置；
2. 服务端预选该工作空间在此平台的默认店铺，用户可在编辑页改为该平台的另一已授权门店；无门店则提示前往店铺管理；
3. 用户可编辑 SKU、媒体、定价、动态类目属性；已成功上架的 SKU 仅能保存 Atlas 侧编辑，未上架 SKU 可被选择并提交首次上架；
4. 发布成功或失败后均返回/保留采集箱记录，状态和原因随任务、同步更新。

### 4.2 手动创建

“手动创建商品”创建来源为 `manual` 的工作空间级采集箱草稿，并立即打开同一编辑入口。它不因为是手动创建而绕过采集箱、目标平台绑定、发布校验或任务快照。

### 4.3 删除与清空

- 删除只删除 Atlas 中的采集箱记录及其未被其他记录引用的素材关系；不删除来源站商品。
- 已上架采集箱记录也允许删除，但二次确认必须说明：**不会删除或下架 Ozon 商品，也不会从在线商品同步列表移除。**
- 删除时取消未执行的素材任务；已转存文件在确认没有任何引用后延迟物理清理。
- “清空采集箱”清理当前工作空间所有未删除的采集箱记录（包括已上架记录），必须展示数量并二次确认；不影响任何平台商品和在线商品记录。

## 5. 在线商品

在线商品是店铺级的 Ozon 实际商品镜像：既包含通过 Atlas 发布的商品，也包含卖家此前直接在 Ozon 后台或其他工具创建的商品。它是**平台 + 门店独有**的数据，不能跨平台或跨门店复用；即使某行关联到采集箱 SKU，它仍是 Ozon 店铺中的独立事实记录。**列表粒度为 Ozon `product_id` / `offer_id` 对应的一条商品 SKU 行，不按 Atlas 采集箱 SPU 聚合展示。** 一个采集箱 SPU 有多个 SKU 时，在线商品中应显示为多行；外部同步商品同样按这个粒度展示。

### 5.1 Ozon API 能力确认

现有 Ozon Seller API 资料已确认以下同步链路：

1. `POST /v3/product/list`：按 `last_id` 游标分页拉取店铺商品，支持 `ALL`、`VISIBLE`、`INVISIBLE`、`EMPTY_STOCK` 筛选；每项返回 `product_id` 与 `offer_id`，单页最多 1000 条。
2. `POST /v3/product/info/list`：按 `product_id`、`offer_id` 或 `sku` 批量读取详情，每批最多 100 条；返回名称、价格、图片、属性、库存、`visible`、审核状态、失败/拒绝原因和可见性详情。

因此可以使用 `Client-Id + Api-Key` 完成同步，不需要浏览器 Cookie。依据见 [商品列表 API](../integrations/ozon-seller-api/06-product-list.md) 与 [商品信息 API](../integrations/ozon-seller-api/05-product-info.md)。

### 5.2 同步任务

在线商品页提供“同步 Ozon 商品”入口；后台也可按后续确定的频率自动执行。同步必须是 BullMQ 异步任务：

```text
创建 store_online_product_sync 任务
  → /v3/product/list 分页获得全部 product_id + offer_id
  → /v3/product/info/list 每批最多 100 条补全详情
  → 以 store_id + ozon_product_id（或同店 offer_id）upsert 在线商品 SKU 镜像
  → 将 Atlas SKU 映射到匹配的 Ozon 商品；非 Atlas 商品保持“外部同步”来源
  → 成功完成全量分页后，处理本轮未见项目为疑似已删除/已归档，不直接物理删除
  → 保存同步时间、游标、统计、失败原因和原始响应摘要
```

同步中的并发、分页、重试、限流和异常应由 Worker 控制。同步失败保留上一轮成功镜像，并在在线商品页显示“最近同步失败”；不把失败当作平台商品已下架。

### 5.3 与采集箱的关联

通过 Atlas 发布的 SKU，使用 `store_id + offer_id` 和发布回填的 Ozon `product_id` 建立稳定映射。在线商品的每一 SKU 行可显示其 Atlas 来源链接；采集箱 SPU 的当前平台上架状态由首次导入映射汇总，**不**由在线商品的当前可见性派生。外部同步得到的 Ozon 商品也可出现在在线商品，但初始没有采集箱记录或 Atlas 商品关联；后续如需纳入编辑，另行设计“认领/导入在线商品”流程。

## 6. 待补充

1. 采集箱草稿已绑定目标后，是否允许换平台/换店铺及其迁移规则；
2. 在线商品列表的字段、筛选、详情、编辑入口和“认领外部商品”流程；
3. 自动同步频率、手动同步冷却时间、单店并发和限流参数；
4. 采集箱容量 1000 的最终套餐口径及超限提示；
5. 采集箱“首次导入成功”的用户文案，以及在线商品“实际可见/库存”的用户文案；二者必须区分，不能把 `visible=true` 当作采集箱上架状态。