9.9 KiB
采集箱与在线商品需求
状态：已确认核心规则，待补充具体 PostgreSQL 表和 API 契约。采集插件入口和来源多 SKU 规则见
collector-browser-extension.md。
1. 领域边界
采集箱是工作空间共用的商品工作池：插件的“采集商品”“编辑上架”以及手动创建商品，都先创建或复用一条采集箱记录。采集时没有目标平台和门店。用户进入 ERP 编辑时使用页头当前平台；系统为该商品取得或创建这个平台的发布配置，并预选该平台默认门店。门店可以为这次及后续未上架 SKU 修改，但采集箱商品本身不属于任何门店。
上架成功不会把商品移出采集箱。 采集箱保留该商品，以便继续查看和编辑 Atlas 草稿；某个已成功提交到平台的 SKU 不能再次提交上架，但同一 SPU 下仍未上架的 SKU 可以首次上架。采集箱状态随当前页头平台变化：商品在 A 平台上架后，切换到 B 平台仍是未上架。在线商品是另一份“目标店铺在平台上实际存在什么商品”的同步视图，不能只由 Atlas 的发布记录推断。
来源采集 / 手动创建
→ 采集箱（持续保留、可编辑；已成功上架 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 编辑入口：
- 读取页头当前平台（首期默认 Ozon），取得或创建该商品的当前平台发布配置；
- 服务端预选该工作空间在此平台的默认店铺，用户可在编辑页改为该平台的另一已授权门店；无门店则提示前往店铺管理；
- 用户可编辑 SKU、媒体、定价、动态类目属性；已成功上架的 SKU 仅能保存 Atlas 侧编辑，未上架 SKU 可被选择并提交首次上架；
- 发布成功或失败后均返回/保留采集箱记录，状态和原因随任务、同步更新。
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 资料已确认以下同步链路：
POST /v3/product/list：按last_id游标分页拉取店铺商品，支持ALL、VISIBLE、INVISIBLE、EMPTY_STOCK筛选；每项返回product_id与offer_id，单页最多 1000 条。POST /v3/product/info/list：按product_id、offer_id或sku批量读取详情，每批最多 100 条；返回名称、价格、图片、属性、库存、visible、审核状态、失败/拒绝原因和可见性详情。
因此可以使用 Client-Id + Api-Key 完成同步，不需要浏览器 Cookie。依据见 商品列表 API 与 商品信息 API。
5.2 同步任务
在线商品页提供“同步 Ozon 商品”入口；后台也可按后续确定的频率自动执行。同步必须是 BullMQ 异步任务：
创建 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. 待补充
- 采集箱草稿已绑定目标后，是否允许换平台/换店铺及其迁移规则；
- 在线商品首期列表字段、筛选与只读详情已按
../api/online-listings.md实现；编辑入口和“认领外部商品”流程仍待设计； - 自动同步频率、手动同步冷却时间、单店并发和限流参数；
- 采集箱容量 1000 的最终套餐口径及超限提示；
- 采集箱“首次导入成功”的用户文案，以及在线商品“实际可见/库存”的用户文案；二者必须区分，不能把
visible=true当作采集箱上架状态。