# 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 功能。 |
| 媒体 | 采集主图/详情图是商品候选池；只有来源有稳定关联时才把图片绑定 SKU。1688、淘宝、天猫暂不假设能可靠采集 SKU 图片。 |
| 发布 | 本期只设计“上架至平台”按钮与数据边界，不实现真正发布。 |

## 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. 云端架构底线

1. 使用 PostgreSQL；所有业务行必须受 `workspace_id` 或可安全追溯至工作空间的外键约束。
2. 首期注册后静默创建一个个人工作空间，并只建立一个 `owner` 成员；不展示工作空间、成员、角色或店铺级权限管理。后续有团队协作需求时再扩展。
3. 平台连接属于门店：平台、国家/站点、默认语言、默认币种、加密后的凭据和能力配置均不得写进商品核心表。
4. 本地素材使用 MinIO；共享测试和生产素材使用七牛 Kodo，不使用应用服务器本地目录作为持久存储。
5. AI、生图、导出、采集转存和发布使用 Redis + BullMQ 队列/Worker，任务可重试、可恢复且携带工作空间与 SKU 上下文。
6. 用户界面语言、采集源语言、商品编辑语言和发布目标语言相互独立；文案及属性值需要支持多语言版本。

建议的核心层级：

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

## 5. 下一步建议

在开始前端或商品模块前，先形成以下文档并获得确认：

1. 云端多租户、认证、权限与门店模型；
2. PostgreSQL schema、迁移策略和租户隔离策略；
3. 平台适配器接口（先 Ozon，后续可接其他平台）；
4. 多语言/市场/币种的数据模型；
5. 对象存储、任务队列、密钥加密和部署方案。

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

## 6. 文档导航

- [商品 AI 编辑页总览](../product/README.md)
- [编辑页交互设计](../product/product-ai-editor.md)
- [商品/SKU 数据模型](../product/data-model.md)
- [商品编辑 API 契约](../product/api.md)
- [技术栈、异步任务与部署方案](../architecture/technology-and-deployment.md)