Atlas Seller Kit 交接说明

更新：2026-09-01。此文是新 AI 对话、架构讨论与开发工作的首读入口。

1. 项目定位

这是一个全新的云端产品，不是 ozon-seller-kit 的本地版重构。目标用户将拥有多个门店；每个门店可属于不同平台和国家，因此语言、币种、类目和发布规则不能写死为 Ozon 或中文/俄文。

当前项目还没有业务代码、数据库、部署或依赖。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 /trial/:id 或商品编辑页组件。可选择性复用已经验证过的纯计价公式、采集扩展思路和 AI 任务经验，但必须先适配多租户和云端边界。

2. 已确认产品决策

主题	决策
商品模型	每个商品是一个 SPU，且始终至少有一条 SKU；单规格商品使用默认 SKU，多规格商品使用多条 SKU。
平台可售单元	一个 SKU 对应一个独立平台 offer；Ozon 首个平台中对应 `/v3/product/import.items[]` 的一项和独立 `offer_id`。
通用属性	类目、标题、品牌、型号、主题标签、简介、JSON 富内容、条形码、采买地址、货源备注及未来商品级属性。
SKU 属性	SKU 名称、图片、视频封面、视频、货号、采购价、售价、划线价、包装重量和尺寸、商品重量和尺寸、商品颜色、颜色名称等。
型号/货号	型号是父商品通用字段；SKU 共用型号。货号属于 SKU，可由 AI 生成并允许人工编辑。
规格	实物规格与包装物流规格严格分离；尺寸图只读取实物规格，计价/物流/发布只读取包装规格。
继承	可继承字段的 `null` 表示该字段没有覆盖父商品默认值，不表示 SKU 不存在、名称为空或商品为单规格。
尺寸图	必须逐 SKU 生成，任务保存 SKU ID 和实物规格快照。
定价	SKU 上点“定价”打开弹窗，以有效包装数据计算；用户确认后回填 SKU 销售价和划线价。
编辑体验	新商品 AI 编辑页取代旧商品编辑页；旧试算页不再追加多 SKU 功能。
采集插件	采集 Ozon、1688、淘宝、天猫详情页；未登录只显示登录入口，已登录显示“编辑上架 / 采集商品 / 进入 ERP”。采集记录始终写入当前工作空间的默认店铺。详情见 `requirements/collector-browser-extension.md`。
采集 SKU	只有来源给出稳定 SKU/组合证据时创建多个 SKU；不能把规格轴做笛卡尔积。没有专属 SKU 图时，真实 SKU 继承父商品默认图而不复制资产。
媒体	采集主图/详情图是商品候选池；来源明确给出 SKU、或可靠的规格轴值（如颜色）与图片关系时才自动绑定。其余素材由编辑页人工选择。
发布	商品采集、编辑、定价、AI 媒体和发布至 Ozon 后台并上线是核心闭环。正式发布使用官方 Seller API，按一 SKU 一 import item/offer 执行、轮询结果并设置库存。

3. Ozon 已核对结论

仓内旧项目的 docs/ozon-seller-api/04-product-import.md 记录：Ozon /v3/product/import 每个 item 都有独立 offer_id、价格、包装尺寸/重量和图片，尺寸/重量不能为零；单次最多 100 项。03-category-attributes.md 记录类目属性的 is_aspect=true 表示变体属性。

因此 Ozon 适配器应以“一 SKU 一 import item/offer”为最小稳定单位。现有资料没有可强制把多个 item 合并为一个 Ozon 前台变体组的 API 契约，不能依赖自动归并；这是未来 Ozon 联调阶段要在真实店铺或沙盒验证的能力。

4. 云端架构底线

使用 PostgreSQL；所有业务行必须受 workspace_id 或可安全追溯至工作空间的外键约束。
首期注册后静默创建一个个人工作空间，并只建立一个 owner 成员；不展示工作空间、成员、角色或店铺级权限管理。后续有团队协作需求时再扩展。
平台连接属于门店：平台、国家/站点、默认语言、默认币种、加密后的凭据和能力配置均不得写进商品核心表。
本地素材使用 MinIO；共享测试和生产素材使用七牛 Kodo，不使用应用服务器本地目录作为持久存储。
AI、生图、导出、采集转存和发布使用 Redis + BullMQ 队列/Worker，任务可重试、可恢复且携带工作空间与 SKU 上下文。
用户界面语言、采集源语言、商品编辑语言和发布目标语言相互独立；文案及属性值需要支持多语言版本。
Ozon Seller 网页内部接口可以在插件中作为显式开启的观察性实验采集；不得保存 Cookie、不得阻塞标准采集、不得替代官方 Seller API 发布或把未验证经营数据视为本店事实。

建议的核心层级：

User → Workspace → Membership / Role
                  → Store → Platform connection / market / locale / currency
                           → Product (SPU) → ProductVariant (SKU)
                                             → attributes / media / pricing snapshots / tasks

5. 下一步建议

在开始实施前，以下内容需要继续细化并获得确认：

云端多租户、认证、权限与门店模型；
PostgreSQL schema、迁移策略和租户隔离策略；
平台适配器接口（先 Ozon，后续可接其他平台）；
多语言/市场/币种的数据模型；
对象存储、任务队列、密钥加密和部署方案。
浏览器采集载荷、采集箱页面、真实多 SKU 解析测试集，以及 Ozon Seller 网页观察实验的字段口径，见 requirements/collector-browser-extension.md。

之后再按 docs/product/ 的商品编辑页、数据库和 API 契约实现产品功能。

6.2 KiB Raw Blame History