feat: 方案设计、数据库和接口设计基本完成
This commit is contained in:
R524809
@@ -11,17 +11,18 @@
|
||||
浏览器插件让用户在来源商品详情页一键把商品导入 Atlas。它必须：
|
||||
|
||||
1. 采集商品原始文本、参数、媒体、规格轴和真实 SKU 组合；
|
||||
2. 把记录写入登录用户当前工作空间的**当前默认店铺**；
|
||||
2. 把记录写入登录用户当前工作空间共用的采集箱；采集时不关联目标平台或门店；
|
||||
3. 让用户选择“只进入采集箱”或“导入后直接编辑上架”；
|
||||
4. 保存来源证据和素材转存任务，确保后续可以修正、重试、审计；
|
||||
5. 尽可能保留真实多 SKU，不凭名称、图片或笛卡尔积猜测不存在的组合。
|
||||
5. 尽可能保留真实多 SKU，不凭名称、图片或笛卡尔积猜测不存在的组合；
|
||||
6. 一期提供 Ozon Seller 网页增强采集：在用户浏览器的现有登录会话中调用第 7.3 节列出的四个接口，保存经过净化的观察结果。
|
||||
|
||||
首期来源站点与旧采集插件相同：Ozon（`ozon.ru`、`ozon.kz`、`ozon.by`）、1688、淘宝、天猫。
|
||||
|
||||
### 1.2 非目标
|
||||
|
||||
- 插件内不展示采集详情、商品字段编辑、AI 智能规划、AI 文案、AI 生图、套图生成、图片导出或定价；这些工作均在 Atlas ERP 页面完成。
|
||||
- 插件不直接调用 Atlas 的正式发布接口，不直接创建 Ozon offer，也不保存 Ozon Seller Cookie。
|
||||
- 插件不直接调用 Atlas 的正式发布接口，不直接创建 Ozon offer，也不提取完整、上传或持久化 Ozon Seller Cookie。
|
||||
- 插件不以网页上的规格名称、SKU 图片或“所有颜色 × 所有尺码”的笛卡尔积推测真实 SKU。
|
||||
- Ozon Seller 网页内部接口仅用于可观察的实验性采集，不能成为生产发布、库存或定价的唯一数据源。
|
||||
|
||||
@@ -38,10 +39,9 @@
|
||||
| 状态 | 悬浮窗内容 | 行为 |
|
||||
|---|---|---|
|
||||
| 未登录或令牌失效 | `登录 Atlas ERP` | 新标签打开 Atlas 登录页。完成授权后，插件自动刷新为已登录状态。 |
|
||||
| 已登录但没有默认店铺 | `前往 ERP 设置默认店铺` | 打开店铺管理页；不允许导入，避免采集记录落到不确定的店铺。 |
|
||||
| 已登录且存在当前默认店铺 | `编辑上架`、`采集商品`、`进入 ERP` | 按下面的操作规则执行。 |
|
||||
| 已登录 | `编辑上架`、`采集商品`、`进入 ERP` | 允许采集；采集箱记录只归属工作空间，不要求已有目标店铺。 |
|
||||
|
||||
首期不在悬浮窗中选择店铺。服务端从插件授权身份解析工作空间，并使用该工作空间的当前默认店铺；默认店铺切换在 ERP 中完成。
|
||||
首期不在悬浮窗中选择平台或店铺。服务端从插件授权身份只解析工作空间，创建未绑定目标平台/门店的采集记录和商品基础草稿。用户进入 Atlas ERP 编辑页时，页面使用页头当前选中的平台；首期页头默认选择 Ozon，服务端取得该平台发布配置并预选默认店铺。若当前平台没有可用门店，允许保留采集箱记录，但不能进入该平台的商品编辑/发布流程，应引导用户在店铺管理中添加门店。
|
||||
|
||||
推荐采用扩展专用的短期授权码流程：插件打开 Atlas 登录/授权页，登录页完成后向 `chrome-extension://{extension-id}/...` 回传一次性 code，插件交换短期 access token 与可轮换 refresh token。令牌只放 Chrome 扩展专属存储，后台请求统一携带 `Authorization: Bearer`。不得像参考插件一样直接读取 ERP 网页 localStorage 中的长期 Token。
|
||||
|
||||
@@ -49,26 +49,27 @@
|
||||
|
||||
| 操作 | 流程 | 成功结果 |
|
||||
|---|---|---|
|
||||
| 编辑上架 | 扫描当前页 → 上报采集记录 → 创建/复用商品草稿 → 打开编辑页 | 新标签打开 `/products/{productId}/editor`；素材继续后台转存，编辑页显示状态。 |
|
||||
| 编辑上架 | 扫描当前页 → 上报采集记录 → 创建/复用未绑定目标的商品基础草稿 → 打开 ERP 编辑入口 | 新标签打开 `/collection-items/{collectionItemId}/edit`；ERP 按页头当前平台取得发布配置并预选门店后进入 `/products/{productId}/editor`，素材继续后台转存。 |
|
||||
| 采集商品 | 扫描当前页 → 上报采集记录 | 停留来源页，提示“已进入采集箱”；用户以后从采集箱编辑。 |
|
||||
| 进入 ERP | 不扫描、不上报 | 新标签打开 Atlas ERP 首页。 |
|
||||
|
||||
“上报成功”定义为：数据库事务已创建或复用采集记录、商品草稿、SKU 草稿和素材转存任务。它不等待所有图片下载完成；各素材的 `pending/downloading/ready/failed` 状态在采集箱和编辑页可见，失败可单独重试。
|
||||
“上报成功”定义为：数据库事务已创建或复用工作空间级采集记录、未绑定目标的商品草稿、SKU 草稿和素材转存任务。它不等待所有图片下载完成；各素材的 `pending/downloading/ready/failed` 状态在采集箱和编辑页可见，失败可单独重试。
|
||||
|
||||
## 3. 端到端流程与状态
|
||||
|
||||
```text
|
||||
来源商品详情页
|
||||
→ 插件认证、确认当前默认店铺
|
||||
→ 插件认证、确认当前工作空间
|
||||
→ 平台采集器（原始证据 + 规范化结果）
|
||||
→ 扩展后台统一上报
|
||||
→ Atlas API：幂等创建采集记录、SPU 草稿、真实 SKU 草稿、素材任务
|
||||
→ Atlas API：幂等创建工作空间级采集记录、未绑定平台/门店的 SPU 基础草稿、真实 SKU 草稿、素材任务
|
||||
→ Redis/BullMQ Worker：下载、校验、去重、转存到 MinIO/Kodo
|
||||
→ 采集箱
|
||||
├─ 继续编辑：商品编辑页
|
||||
→ 工作空间共用采集箱（无目标平台/门店；上架后仍保留）
|
||||
├─ 当前平台下未上架 SKU：编辑并首次上架；已上架 SKU：仅编辑 Atlas 草稿，不能再次上架
|
||||
└─ 删除/归档/重试
|
||||
→ 文案、SKU 媒体、定价、AI 生图、发布校验
|
||||
→ 发布快照 → 官方 Ozon Seller API 导入、轮询、库存设置、上线状态
|
||||
→ 发布快照 → 官方 Ozon Seller API 导入、轮询；库存由用户在 Ozon 后台设置
|
||||
→ 在线商品：异步同步店铺全部 Ozon 商品（含非 Atlas 发布商品）
|
||||
```
|
||||
|
||||
建议的采集状态：
|
||||
@@ -83,7 +84,13 @@
|
||||
| `failed` | 采集请求或关键记录创建失败；保留可诊断错误。 |
|
||||
| `archived` | 用户不再处理的采集记录。 |
|
||||
|
||||
同一默认店铺内，以 `source_platform + source_item_key` 进行幂等。重复“采集商品”应返回已有采集记录；重复“编辑上架”打开同一商品草稿。只有用户在 ERP 中明确选择“重新采集并合并/创建副本”时，才允许覆盖或复制。
|
||||
同一工作空间内，以 `source_platform + source_item_key` 进行幂等。重复“采集商品”应返回已有采集记录；重复“编辑上架”打开同一未绑定目标的商品草稿或其已绑定的编辑入口。只有用户在 ERP 中明确选择“重新采集并合并/创建副本”时，才允许覆盖或复制。
|
||||
|
||||
### 3.1 采集箱与目标店铺的绑定时点
|
||||
|
||||
采集来源平台与目标发布平台是不同概念：例如从 1688 采集的商品可以在后续发布到 Ozon，也可能未来发布到其他平台。因此采集箱和刚创建的商品草稿只携带 `workspace_id`、来源平台及来源证据，`target_platform_id`、`target_store_id` 均为未设置状态。
|
||||
|
||||
用户从采集箱点击“编辑”时，ERP 读取页头当前平台。服务端验证该平台存在于当前系统配置中，并取得/创建该商品在这个平台的发布配置，预选该工作空间在该平台的默认店铺；用户可在编辑页改选门店。A 平台与 B 平台的发布配置和 SKU 上架状态相互独立。扩展不能传入、指定或覆盖这个选择。
|
||||
|
||||
## 4. 统一采集数据模型
|
||||
|
||||
@@ -243,12 +250,12 @@ interface CollectedVariant {
|
||||
|
||||
### 7.1 目的与边界
|
||||
|
||||
毛子 ERP 在公开 Ozon 商品页采集外，还要求浏览器打开已登录的 `seller.ozon.ru`，并通过跨标签消息调用 Seller 网页的内部接口。Atlas 可以在 Ozon 采集插件中实现一个**可选、显式开启、只用于观察结果**的实验模式。
|
||||
毛子 ERP 在公开 Ozon 商品页采集外，还要求浏览器打开已登录的 `seller.ozon.ru`，并通过跨标签消息调用 Seller 网页的内部接口。Atlas **一期即实现**第 7.3 节四个接口的浏览器本地观察模式；用户须在插件设置中显式开启。
|
||||
|
||||
实验模式目标是把公开页面发现的来源 SKU 与 Seller 网页返回的补充数据并排保存，帮助评估是否值得采用；它不得：
|
||||
|
||||
- 自动修改 Atlas 商品、价格、包装规格、库存或发布数据；
|
||||
- 读取、保存、上传或记录 Seller Cookie、`company_id` 以外的会话凭据；
|
||||
- 提取完整 Cookie、保存/上传 Cookie，或将 Cookie 写入日志、数据库、队列和扩展持久化存储；
|
||||
- 替代官方 `Client-Id + Api-Key` Seller API 的正式发布、库存和状态同步；
|
||||
- 将返回的销量/浏览等数据表述为“当前店铺数据”，除非 Ozon 未来提供可验证的官方契约。
|
||||
|
||||
@@ -270,7 +277,9 @@ interface CollectedVariant {
|
||||
→ 毛子 ERP 加密后上传自己的后端
|
||||
```
|
||||
|
||||
Atlas 只可借鉴“请求必须在已登录 Ozon 同源标签执行”的技术结构。实验结果进入 `source_evidence` 或独立 `seller_enrichment_observations`，保存原始响应的净化副本、字段清单、接口名、时间、当前来源 SKU、解析版本和错误信息。
|
||||
Atlas 只可借鉴“请求必须在已登录 Ozon 同源标签执行”的技术结构。四个请求由浏览器扩展在 Seller 同源标签的页面上下文执行，`credentials: include` 仅让浏览器自动附带现有会话 Cookie；Atlas 不取得 Cookie 正文。请求所需的 `company_id` 仅在本次浏览器会话内从已登录 Seller 页面状态或 `sc_company_id` Cookie 取得，不上传为会话凭据、不写入扩展持久化存储。
|
||||
|
||||
实验结果进入 `source_evidence` 或独立 `seller_enrichment_observations`，保存**净化后的**响应副本、字段清单、接口名、采集时间、当前来源 SKU、解析版本和错误信息。`company_id` 如确有诊断必要，只能保存不可逆摘要或单独受控的店铺匹配标记，不能保存完整 Cookie。
|
||||
|
||||
### 7.3 四个接口与已观察到的用途
|
||||
|
||||
@@ -291,40 +300,54 @@ Atlas 只可借鉴“请求必须在已登录 Ozon 同源标签执行”的技
|
||||
|
||||
验证方法：使用两个不同店铺账户，对同一个不属于任一店铺的公开 SKU 对比响应；再和当前店铺已上架 SKU 的官方 Seller API 数据对比。只有在口径、权限和稳定性得到确认后，才能决定是否建设独立“选品洞察”功能。
|
||||
|
||||
### 7.5 Atlas 实验流程与安全控制
|
||||
### 7.5 一期 Atlas 本地观察流程与安全控制
|
||||
|
||||
1. 用户在插件设置中显式打开“采集 Ozon Seller 网页观察数据（实验）”。默认关闭。
|
||||
2. 用户自行在浏览器登录 `seller.ozon.ru`；插件只检测标签页和请求可用性，不显示、不导出、不持久化 Cookie。
|
||||
3. 标准公开页面采集先完成。对每一个发现的 `sourceVariantKey`，后台按低并发、有限数量发起四个观察请求。
|
||||
1. 用户在插件设置中显式打开“采集 Ozon Seller 网页观察数据（实验）”；默认关闭。该开关和第 7.3 节四接口能力均在一期交付。
|
||||
2. 用户自行在浏览器登录 `seller.ozon.ru` 并保留一个有效 Seller 标签页；插件只检测标签页和请求可用性，不显示、不导出、不持久化 Cookie。
|
||||
3. 标准公开页面采集先完成。对每一个发现的 `sourceVariantKey`，扩展后台按低并发、有限数量，通过 Seller 标签页依次发起四个观察请求。
|
||||
4. 回传前清除请求/响应中可能存在的会话字段、用户信息、店铺名称、授权头等无关信息；服务器再次执行结构化白名单与脱敏。
|
||||
5. 结果写入工作空间隔离的观察记录。采集箱展示“公开页数据 / Seller 网页观察数据”的字段差异，但不会自动覆盖草稿。
|
||||
6. 请求失败、账号无权、没有 Seller 标签页或内部接口变更时，只记录 `unavailable` 原因；“编辑上架”和“采集商品”仍正常完成。
|
||||
|
||||
### 7.6 Cookie 能力分级与毛子 ERP 调研结论
|
||||
|
||||
“不持久化 Cookie”不等于“不使用用户浏览器的现有登录态”。浏览器在 Seller 同源 `fetch(..., { credentials: 'include' })` 时会自动附带该站 Cookie；Cookie 不需要、也不应离开浏览器才能完成一期四接口观察。
|
||||
|
||||
已核对的毛子 ERP 插件行为：它具有 Chrome `cookies` 权限；其本地跨标签请求会读取 `sc_company_id` 并使用 `credentials: 'include'` 调用四个接口；此外，用户点击“绑定 Cookie”后，它会读取完整 Seller Cookie 列表并提交给毛子后端的 `/api.shop/set_cookies`。该后端后续具体调用范围无法仅凭插件产物证明。
|
||||
|
||||
| 级别 | Cookie 位置与用途 | 能力边界 | Atlas 决策 |
|
||||
|---|---|---|---|
|
||||
| **一级：浏览器本地观察** | 用户浏览器管理 Cookie；扩展仅在已登录 Seller 标签页同源发请求，不读取完整 Cookie 值。 | 一期调用第 7.3 节四接口，保存净化结果；用户需保持浏览器 Seller 登录态。 | **一期实现。** |
|
||||
| 二级：加密保存 Cookie（实验） | 用户显式授权后，浏览器将会话 Cookie 加密上传；云端 Worker 在白名单内调用网页接口。 | 可在用户未打开浏览器时执行已验证的补充查询或定时刷新；不自动获得任何未经验证的新业务能力。 | **预留，不实现。** |
|
||||
| 三级：Cookie 驱动业务自动化 | 云端以会话身份调用具有写入副作用的网页接口。 | 可能涉及发布、改价、库存、广告等高风险操作；接口稳定性、账号权限、平台规则均未确认。 | **不纳入当前规划。** |
|
||||
|
||||
二级若未来立项，必须逐接口白名单、独立风险评审和用户再次授权；按门店验证 `company_id` 匹配；Cookie 只做信封加密保存，队列仅传 `secret_id`；不得记录明文、不得返回前端，支持立即撤销、过期检测和完整审计。无论任何级别，正式商品发布、库存和状态同步仍以官方 `Client-Id + Api-Key` Seller API 为准。
|
||||
|
||||
## 8. Atlas API、任务与存储
|
||||
|
||||
### 8.1 插件接口建议
|
||||
|
||||
| 接口 | 用途 |
|
||||
|---|---|
|
||||
| `GET /api/extension/session` | 返回登录状态、工作空间、当前默认店铺是否可用；不返回敏感门店凭据。 |
|
||||
| `GET /api/extension/session` | 返回登录状态和工作空间是否可用；不返回平台、目标店铺或敏感门店凭据。 |
|
||||
| `POST /api/extension/auth/exchange` | 用一次性授权码交换扩展短期令牌。 |
|
||||
| `POST /api/extension/materials` | 接收 `CollectedProductPayload`；服务端解析当前身份与默认店铺，实施幂等创建。 |
|
||||
| `POST /api/extension/materials` | 接收 `CollectedProductPayload`；服务端仅解析当前工作空间，实施幂等创建未绑定目标平台/门店的采集记录和草稿。 |
|
||||
| `GET /api/collection-items/{id}` | 查询采集记录、SKU 发现数、素材转存状态和警告。 |
|
||||
| `POST /api/collection-items/{id}/retry-assets` | 重新投递失败素材。 |
|
||||
| `POST /api/collection-items/{id}/seller-enrichment-observations` | 仅实验开关启用时接收已净化的 Ozon Seller 网页观察数据。 |
|
||||
| `POST /api/collection-items/{id}/seller-enrichment-observations` | 一期的本地观察开关启用时，接收已净化的四接口结果；不接收 Cookie。 |
|
||||
|
||||
不得让插件在请求体中随意指定 `workspace_id` 或 `store_id`。服务端从令牌确定工作空间，读取该工作空间的当前默认店铺，并在事务中应用 PostgreSQL RLS。
|
||||
不得让插件在请求体中随意指定 `workspace_id`、`platform_id` 或 `store_id`。服务端从令牌确定工作空间并在事务中应用 PostgreSQL RLS；目标平台和店铺仅在 ERP 编辑入口按第 3.1 节规则绑定。
|
||||
|
||||
### 8.2 素材转存
|
||||
|
||||
- 插件上报来源 URL、Referer origin、MIME/类型、组别、排序和媒体关系；不把二进制图片塞进常规 JSON。
|
||||
- Worker 用受控请求下载来源素材，进行 MIME、大小、尺寸、哈希校验，再写入私有 MinIO/Kodo 对象存储。
|
||||
- Worker 用受控请求下载来源素材，进行 MIME、大小、尺寸、哈希校验，再写入私有 MinIO/Kodo 对象存储；资产记录保存 `storage_provider + bucket + object_key`，不保存转存后文件的长期访问 URL。
|
||||
- 下载受来源防盗链、过期 URL 或风控影响而失败时，保留来源 URL 和错误；用户可重新采集或在编辑页手动上传。
|
||||
- 同一工作空间内用内容哈希和来源规范化 URL 去重，但同一资产可在多个商品/SKU 媒体关系中复用。
|
||||
|
||||
### 8.3 可恢复性
|
||||
|
||||
采集记录、素材任务、Ozon Seller 网页实验请求和未来发布任务都应先写 PostgreSQL，再经 outbox 投递 BullMQ。重试必须有幂等键、次数上限、指数退避和可见错误。浏览器关闭、Worker 重启或 Redis 重建都不能造成已创建商品草稿重复或素材关系丢失。
|
||||
采集记录、素材任务和未来发布任务都应先写 PostgreSQL，再经 outbox 投递 BullMQ。第 7.3 节四接口请求必须在用户浏览器的 Seller 同源标签完成，不能投递给云端 Worker；扩展将结果或 `unavailable` 原因提交服务端后再落库。浏览器关闭、Worker 重启或 Redis 重建都不能造成已创建商品草稿重复或素材关系丢失。
|
||||
|
||||
## 9. 旧实现与参考实现的取舍
|
||||
|
||||
@@ -348,10 +371,10 @@ Atlas 只可借鉴“请求必须在已登录 Ozon 同源标签执行”的技
|
||||
|
||||
### 10.1 分期
|
||||
|
||||
1. **采集基础**：扩展认证、小浮窗、默认店铺检查、统一载荷、采集箱入库、素材转存、幂等和“编辑上架/采集商品”。
|
||||
1. **采集基础与 Seller 本地观察**：扩展认证、小浮窗、工作空间检查、统一载荷、无目标平台/门店的采集箱入库、素材转存、幂等和“编辑上架/采集商品”；同时实现第 7.3 节四接口的跨标签同源调用、净化存储、`unavailable` 回退和字段差异展示。
|
||||
2. **真实多 SKU**：1688 `skuMapOriginal`、淘宝/天猫 `skuId + propPath`、Ozon 公开 `sku` 变体遍历；完善 SKU 媒体继承与采集箱警告。
|
||||
3. **Ozon Seller 网页观察实验**：四个接口的同源调用、净化存储、字段差异观察页与双店铺验证；不接入正式发布链路。
|
||||
4. **编辑与发布闭环**：动态属性、AI 文案/媒体、定价快照、发布校验、官方 Ozon Seller API 导入、轮询和库存设置。
|
||||
3. **观察数据验证**：用双店铺账户完成字段字典、口径、权限范围和稳定性对照；不接入正式发布链路，也不升级为 Cookie 云端保存。
|
||||
4. **编辑与发布闭环**：动态属性、AI 文案/媒体/类目、定价快照、发布校验、官方 Ozon Seller API 导入和轮询；库存由用户在 Ozon 后台设置。
|
||||
|
||||
### 10.2 验收样本矩阵
|
||||
|
||||
@@ -366,17 +389,17 @@ Atlas 只可借鉴“请求必须在已登录 Ozon 同源标签执行”的技
|
||||
| 无 SKU 图 | 真实 SKU 均存在并继承父商品默认图。 |
|
||||
| 个别变体详情/素材失败 | 保留发现的 SKU 和错误；可单独重试。 |
|
||||
| 重复点击采集 | 复用同一采集记录和商品草稿。 |
|
||||
| 无默认店铺/令牌过期 | 只显示正确的登录或设置引导，不写入数据。 |
|
||||
| Ozon Seller 实验无权限 | 标准公开采集成功，观察实验单独失败且不阻塞。 |
|
||||
| 无目标店铺/令牌过期 | 没有 Ozon 默认店铺时仍可采集；进入 Ozon 编辑时提示设置默认店铺。令牌过期时只显示登录引导，不写入数据。 |
|
||||
| Ozon Seller 本地观察无权限、未登录或无 Seller 标签页 | 标准公开采集成功，四接口观察分别记录 `unavailable` 且不阻塞。 |
|
||||
|
||||
## 11. 待确认与后续文档
|
||||
|
||||
本文件已确认插件入口、默认店铺、多 SKU 基本原则和 Ozon Seller 网页观察实验的边界。实施前仍需补充：
|
||||
本文件已确认插件入口、工作空间共用采集箱、目标平台/门店绑定时点、多 SKU 基本原则和 Ozon Seller 网页观察实验的边界。实施前仍需补充：
|
||||
|
||||
1. `CollectedProductPayload` 的 OpenAPI/JSON Schema 与 PostgreSQL 表、迁移和 RLS 细节；
|
||||
2. 当前默认店铺的服务端选择、切换和删除规则；
|
||||
2. ERP 页头当前平台、该平台默认店铺的选择、切换和删除规则，以及采集草稿已绑定目标后的换平台策略；
|
||||
3. 各来源真实页面快照测试集与解析器版本策略；
|
||||
4. Ozon Seller 网页四接口实验的字段字典、双店铺对照结果、数据保留期和是否继续投入；
|
||||
4. Ozon Seller 网页四接口的字段字典、双店铺对照结果、数据保留期和是否具备建设独立选品洞察的价值；
|
||||
5. 采集箱列表、详情、重新采集、合并与归档的页面需求；
|
||||
6. 正式 Ozon 发布任务的状态机、请求/响应审计与库存策略。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user