Expand seller store functionality

2026-09-07 17:51:11 +08:00
parent 4c0f3a4a79
commit ceb644a3f9
35 changed files with 32883 additions and 364 deletions
@@ -1,12 +1,12 @@
 # Atlas Seller Kit 交接说明

-> 更新：2026-09-06。此文是新 AI 对话、架构讨论与开发工作的首读入口。开始开发前，必须先阅读并遵守 [`development-collaboration-contract.md`](./development-collaboration-contract.md)。
+> 更新：2026-09-07。此文是新 AI 对话、架构讨论与开发工作的首读入口。开始开发前，必须先阅读并遵守 [`development-collaboration-contract.md`](./development-collaboration-contract.md)。

 ## 1. 项目定位

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

-当前已完成 pnpm monorepo 初始化：包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享 API 契约、数据库包、本地基础设施 Compose 与依赖锁文件。API 已实现健康/readiness、集中配置与安全基础、认证、个人工作空间上下文、平台目录/上下文、门店、水印/素材、采集箱与扩展采集入库；Worker 已具备 Ozon 凭据验证、采集记录清理和来源素材转存消费链路，仓库同步尚未接入。Web 已具备完整前端框架（布局、路由、主题）、登录/注册页、页头平台选择器、店铺管理、水印管理、真实采集箱页面和采集数据测试页；浏览器扩展已提供 PKCE 授权、悬浮窗及 Ozon/1688/淘宝/天猫首版页面状态解析。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件。可选择性复用已经验证过的纯计价公式、采集扩展思路和 AI 任务经验，但必须先适配多租户和云端边界。
+当前已完成 pnpm monorepo 初始化：包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享 API 契约、数据库包、本地基础设施 Compose 与依赖锁文件。API 已实现健康/readiness、集中配置与安全基础、认证、个人工作空间上下文、平台目录/上下文、门店、水印/素材、采集箱与扩展采集入库；Worker 已具备 Ozon 凭据验证、采集记录清理和来源素材转存消费链路，仓库同步尚未接入。Web 已具备完整前端框架（布局、路由、主题）、登录/注册页、页头平台选择器、店铺管理、水印管理、真实采集箱页面和采集数据测试页；浏览器扩展已提供毛子 ERP 风格的网页登录态同步、悬浮窗及 Ozon/1688/淘宝/天猫首版页面状态解析。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件。可选择性复用已经验证过的纯计价公式、采集扩展思路和 AI 任务经验，但必须先适配多租户和云端边界。

 当前运行时基线：Node 24.20.0、pnpm 11.25.0、PostgreSQL 18.6、Redis 7.4.11、MinIO `RELEASE.2025-09-07T16-13-09Z`；Web 默认端口为 `8100`，API 默认端口为 `8200`，扩展 dev server 默认端口为 `8110`（仅本地开发用），Worker 无 HTTP 端口。完整目录、依赖边界与版本表见 [`architecture/project-structure.md`](../architecture/project-structure.md) 和 [`architecture/technology-and-deployment.md`](../architecture/technology-and-deployment.md)。

@@ -89,7 +89,7 @@

 ### 1.9 开发进度（2026-09-05）：M2.2 / M2.3 扩展采集首个闭环

- 已实现扩展 PKCE 授权码、扩展专用 access/refresh token 轮换、现有 Atlas Web 会话的静默授权分支，以及扩展会话检查/撤销。扩展不读取 Web token 或 refresh Cookie；回调 URI 必须按已安装扩展 ID 精确登记。
+- 已实现毛子 ERP 风格的 Atlas Web 登录态同步：扩展打开 Atlas Web 标签，轮询读取本站 localStorage 中的短期 Web access token，保存到 extension storage 并用 Bearer token 检查会话/采集。扩展不读取 refresh Cookie、来源站 Cookie 或来源站 localStorage。
 - 已实现 `POST /api/extension/materials`：从扩展身份推导工作空间，创建或复用未绑定目标平台/门店的采集记录、SPU、SKU 草稿和来源素材任务。采集载荷严格限制为来源证据、规范化字段和素材 URL，不能携带店铺、Cookie、API Key 或目标平台。
 - Worker 已消费素材转存 outbox 事件，执行 HTTPS 公网地址校验、大小/图片格式限制、哈希去重与 MinIO/Kodo 转存；单个素材失败不回滚采集箱商品。
 - 浏览器扩展已实现 Ozon 公开商品页的小型 Shadow DOM 悬浮窗及未登录/已登录状态。Ozon 首版解析器以当前公开 SKU 和公开变体状态为证据，不生成笛卡尔积假 SKU。Ozon Seller 四接口本地观察、Ozon 变体详情逐页补全及 1688/淘宝/天猫解析仍未开始。
@@ -100,7 +100,32 @@
 - 扩展浮窗现覆盖 1688 商品详情、淘宝商品详情和天猫商品详情。1688 仅遍历 `skuMapOriginal` 中实际存在的组合；淘宝/天猫仅在同时取得 `skuBase.skus[].skuId + propPath` 时创建多 SKU，并以 `skuCore.sku2info` 补充参考价格。规格轴本身从不展开为笛卡尔积。
 - 缺少真实组合证据时，扩展只保存规格轴，服务端创建一个默认 SKU 并标记为待确认；颜色等轴值图片仍作为候选素材，绝不伪造来源 SKU 图片绑定。
 - “编辑上架”暂时不进入未完成的商品编辑模块，改为打开 `/collection-test/{collectionItemId}`。该只读测试页展示实际保存的规范化载荷、原始证据、SKU 草稿和素材转存任务，用于验证每个平台的采集结果。`GET /api/collection-items/{id}` 已提供该工作空间隔离的检查读模型。
- 已通过 API/Worker TypeScript 检查、Web 与扩展生产构建；`apps/api/test/extension.e2e.test.ts` 已覆盖 PKCE 授权、扩展会话、采集幂等复用和测试页所用检查读模型。尚未在真实来源商品页执行样本回归，接手者应按第 6 节先完成该验证。
+- 已通过 API/Worker TypeScript 检查、Web 与扩展生产构建；`apps/api/test/extension.e2e.test.ts` 已覆盖扩展会话、采集幂等复用和测试页所用检查读模型。尚未在真实来源商品页执行样本回归，接手者应按第 6 节先完成该验证。
+
+### 1.11 开发进度（2026-09-07）：扩展网页登录态同步与稳定 ID
+
+- 扩展登录采用毛子 ERP 模式：点击后打开并保留 Atlas Web 标签；Web 登录或恢复会话后写入本站 localStorage，扩展每 2 秒读取并验证该短期 Web Bearer token。没有有效网页会话时，用户在同一标签登录后即可完成插件登录。
+- Atlas Web access token 写入 localStorage 是维护者批准的窄范围例外；扩展不读取 refresh Cookie、来源站 Cookie 或来源站 localStorage。Token 失效后插件清除缓存并重新要求网页登录。
+- 不再需要 `EXTENSION_COLLECTOR_REDIRECT_URI` 或 `identity` 权限；方案 A 的网页确认 + PKCE 配对设计单独记录在 [`extension-login-alternatives.md`](./extension-login-alternatives.md)，当前不作为插件默认路径。
+- `apps/extension/wxt.config.ts` 的 manifest 带有仅公开的 RSA `key`，Chrome 为解压加载和自托管包保持稳定扩展 ID；私钥未写入仓库。`wxt build` 已确认最终 `manifest.json` 含该 key。
+- 已通过 contracts、API（含测试 TS）、Web、扩展的类型/生产构建，以及 `apps/api/test/extension.e2e.test.ts`：Web Bearer 会话检查 → 工作空间解析 → 采集幂等上报。
+- 同一工作空间内的同一来源商品再次采集时，系统保留 `collection_item` / `product` ID，但用最新页面快照覆盖来源标题、价格、证据、SKU 与候选素材。迁移 `013_collection_source_snapshot_refresh.sql` 为记录和素材任务增加快照版本；旧转存任务取消，Worker 仅处理当前版本，不能将旧页面内容回写到新快照。
+- Ozon 公开商品页解析器现从 JSON-LD `BreadcrumbList` 提取来源类目（可见面包屑为回退），保存当前页面语言的类目路径及对应面包屑证据；解析器版本为 `ozon-public-1.1.0`。
+
+### 1.12 开发进度（2026-09-07）：Ozon 公开多 SKU 采集与归并
+
+- 解析器改为优先读取 Ozon 已渲染的 `state-webAspects-*.data-state.aspects[].variants[]`，不再用脚本文本正则猜测 SKU。保存的三 SKU 页面快照 `packages/reference/ozon1.html` 已确认能直接得到 `5387004839`、`5387005639`、`5387005221`。
+- 增加只限 Ozon MAIN world 的页面 JSON bridge：只接受数字 SKU 和固定的 `modal/aspectsNew` / `product/<sku>` 路径，白名单返回 `webAspects`、`webProductHeading`、`webPrice`、`webGallery` 状态；不暴露 Cookie、请求头或任意请求能力。扩展以并发 3、最多 100 SKU 队列补全实际变体详情；个别失败保留已发现变体和证据。
+- Ozon 公开页面没有稳定 SPU/组 ID；当前 URL SKU 仅保存为入口证据。API 对 Ozon 用本次 `source_sku` 集合与已有 `product_variants.source_sku` 的交集复用并覆盖同一采集快照，允许用户从同组任一 SKU 页面重复采集。多个既有记录命中时返回 `SOURCE_VARIANT_GROUP_AMBIGUOUS`，不静默合并。
+
+### 1.13 开发进度（2026-09-07）：Ozon 商品特征、描述与素材预览
+
+- `/collection-test/{collectionItemId}` 的“素材转存任务”现在直接展示转存成功素材的缩略图，并显示关联来源 SKU。页面为每个 `succeeded + asset_id` 的任务按 4 路并发申请素材短时预览 URL；URL 只保存在浏览器内存，不能写回采集记录、产品或对象存储路径。没有 SKU 直接关联的规格轴图片会明确显示为“商品级”。已在现有三 SKU 采集记录 `7172fa38-0e4d-485e-9d53-1bd92aced79a` 实测确认 37 张素材可显示。
+- Ozon 解析器升级为 `ozon-public-2.2.0`。本地页面优先读取 `webShortCharacteristics`、`webDetailedCharacteristics`、`webCharacteristics` 的 `characteristics[]`；当前入口 SKU 的 `/product/<sku>/` 补全响应会再读取完整 `webCharacteristics`，去重后写入 `common.attributes`。这沿用旧插件已验证的数据形状，不通过页面文本或全页 DOM 猜测参数。
+- 固定的 Ozon 详情页段仍只读取 `webDescription` / `webRichContent`。其中 `webDescription.richAnnotationJson` 被转换为纯文本写入 `common.description`，原 JSON 同时保留在 `raw_value` 供检查；富文本中的图片只走既有详情素材白名单，不会混入描述文本。
+- MAIN world bridge 的返回白名单已经增加上述三个 Characteristics widget，仍然只接受固定 Ozon 同源路径和数字 SKU，不暴露 Cookie、请求头或任意请求能力。
+- **兼容性提醒：** 已有采集记录不会自动重新解析历史 `normalized_payload`。例如上面的现有记录仍标记为 `ozon-public-2.1.0`，只能验证新素材预览；需重新在来源商品页执行“编辑上架”，系统会覆盖同一采集快照，届时在规范化载荷查看新版属性与描述。
+- 已通过扩展 `wxt prepare + tsc + build`、Web `vite build`、`tsx --test test/*.test.mts`（5 项，包括 Ozon 页面快照中“类型/原产国/材料”等 5 个特征和富文本描述样本）以及浏览器测试页实测。

 ## 2. 已确认产品决策

@@ -162,10 +187,11 @@ User → Workspace → Membership / Role

 下一步建议按以下顺序推进：

-1. 用允许保存的单 SKU、单规格轴和颜色×尺码页面样本，在 Ozon、1688、淘宝、天猫逐项验证采集结果；页面状态未暴露组合数据时补 MAIN world bridge 或站点适配器，但绝不以规格轴猜测 SKU。
-2. 完成 Ozon 公开变体队列的逐 SKU hydrate；再独立实施 Seller 网页四接口本地观察实验，默认关闭、仅保存净化结果且不影响标准采集。
+1. 在真实 Ozon 多 SKU 页面加载已构建扩展，确认 MAIN world bridge 未被页面策略阻断、三 SKU 都写入采集测试页、SKU 级画廊关系正确，并在新版规范化载荷确认完整特征与描述；再以任一兄弟 SKU 页面重采集，确认服务端覆盖同一记录。
+2. 用允许保存的单 SKU、单规格轴和颜色×尺码页面样本，在 1688、淘宝、天猫逐项验证采集结果；页面状态未暴露组合数据时补站点适配器，但绝不以规格轴猜测 SKU。之后独立实施 Seller 网页四接口本地观察实验，默认关闭、仅保存净化结果且不影响标准采集。
 3. 将当前 `/collection-test/{collectionItemId}` 只读检查面替换为正式商品编辑入口：按页头平台创建发布配置、预选同平台默认门店，并接入 SKU/媒体/类目编辑。
 4. 进入商品编辑/在线同步前，关闭评审中的 P1：SKU 与平台发布配置同商品归属、未映射属性持久化、统一乐观锁 Repository 规则；平台能力 Schema 已在 M2.1 按固定键落地。在线商品归档策略和 Client ID 编辑边界仍待确认。
+5. **账户认证待开发：忘记密码。** 登录页提供入口；请求接口始终返回同一结果以防邮箱枚举，使用短时有效的一次性不透明邮件令牌（数据库仅存哈希），确认重置后撤销该用户全部 session。实施前先补充认证 API 契约、邮件投递配置和迁移；交付 API、Web、邮件链接与限流/令牌失效回归测试。详情见 [`requirements/account-store-watermark.md`](../requirements/account-store-watermark.md) §2.3。

 账户资料的已确认补充：`users.avatar_asset_id` 只保存素材引用，绝不保存公开 URL；`users.revision` 用于 `PATCH /api/auth/me` 的 `If-Match`。资料更新已实现幂等与版本冲突检测；修改密码已实现旧密码校验、按 IP/用户限流、撤销旧会话并轮换新会话。头像上传必须复用素材模块的预签名直传与校验流程，不引入 base64 直传；素材模块尚未实现时头像只能为 `null`。

@@ -42,7 +42,7 @@
 1. PostgreSQL 是业务事实来源。所有业务数据必须有 `workspace_id`，或能经强制外键安全追溯到工作空间；查询必须在事务中设置 `SET LOCAL app.workspace_id`。
 2. 数据库约束、RLS 与迁移是安全边界；不得只依赖 API 服务层校验。迁移必须可重复执行、可在全新本地环境验证。
 3. 关键可重试写入必须实现幂等；触发异步工作的事务必须同时写入 Transactional Outbox。Redis/BullMQ 不得成为业务事实的唯一来源，Worker 必须幂等。
-4. access token 不得写入浏览器持久化存储；Cookie、API Key、预签名 URL 等秘密不得写进日志、Outbox 载荷、fixture 或提交进仓库。
+4. access token 不得写入浏览器持久化存储；Cookie、API Key、预签名 URL 等秘密不得写进日志、Outbox 载荷、fixture 或提交进仓库。**维护者已于 2026-09-07 批准唯一例外：**为自托管采集插件的网页登录态同步，Atlas Web 可在本站 `localStorage["atlas.extension.web-access"]` 写入当前短期 access token，扩展仅可从 Atlas Web 标签读取并保存到 extension storage；不得读取/写入 refresh Cookie，生产 host permission 必须限制为 Atlas Web 域。完整取舍见 [`extension-login-alternatives.md`](./extension-login-alternatives.md)。
 5. 不得从旧 `ozon-seller-kit` 复制 SQLite、多店铺无隔离、无鉴权 API 或旧商品编辑实现。复用逻辑前必须适配多租户与云端边界。

 ## 5. 工作方式与集成规则
@@ -0,0 +1,31 @@
+# 浏览器采集插件登录方案备忘
+
+> 状态：2026-09-07 记录。本文保留备选方案，不代表当前默认实现。
+
+## 方案 A：网页确认 + PKCE 配对（备选，暂不启用）
+
+1. 插件创建 3 分钟有效的连接请求，生成本地 PKCE verifier/challenge。
+2. 插件打开固定的 Atlas `/extension-connect` 网页。
+3. 网页复用 HttpOnly Web 会话确认连接；未登录时登录后继续。
+4. 插件轮询请求状态，凭 verifier 换取独立 access/refresh token。
+
+优点：Web refresh cookie 和 Web access token 永不交给扩展；扩展令牌可独立撤销。缺点：需要配对表、轮询端点、确认页、状态机和失败回收，当前阶段对“登录后采集”的简单需求而言复杂度过高。
+
+## 方案 B：毛子 ERP 风格的网页登录态同步（当前采用）
+
+1. 用户在插件点击登录。
+2. 插件打开固定 Atlas ERP 网页；未登录时用户在该网页完成登录。
+3. Web 登录或刷新会话后，把当前 access token 写到本站 `localStorage["atlas.extension.web-access"]`。
+4. 插件每 2 秒从该 Atlas 网页标签读取该值；读取到后写入自己的 `chrome.storage.local`。
+5. 插件用该 Bearer token 调用扩展会话校验接口；校验成功即显示采集操作。
+6. 后续扩展 API 请求经后台统一附加 `Authorization: Bearer <token>`。
+
+该流程不依赖 `chrome.identity`、`chromiumapp.org` 回调 URL 或用户配置的扩展 ID；扩展清单的公开 `key` 仅用于稳定扩展 ID。
+
+## 安全取舍与边界
+
+- 这是对项目“Web access token 不落持久化存储”规则的**维护者批准的、窄范围例外**，仅为自托管采集插件互操作。
+- Token 仅写入 Atlas Web 自己的 origin，扩展只通过 `scripting.executeScript` 从其被打开的 Atlas 标签读取；不会读取 Cookie、refresh token、来源站点账号或来源站点 localStorage。
+- 插件仍只取得短期 Web access token；收到 401 时清除插件缓存，用户需再次从 Atlas 网页同步新 Token。
+- 当前阶段不应把该 Token 写入日志、数据库、Outbox、采集载荷或页面 DOM；生产部署必须将扩展 host permission 限定为正式 Atlas Web 域。
+- 方案 A 保留为未来需要独立可撤销插件会话时的升级路径。
@@ -4,24 +4,29 @@

 ## 已交付

-1. 扩展使用 PKCE 授权码登录，而不是读取 Atlas Web 的 localStorage 或 refresh Cookie。`GET /api/extension/authorize` 会优先复用用户浏览器已有的 Atlas Web 会话：会话有效则无感签发一次性 code；没有会话才跳转登录页，成功登录后回到原授权请求。
-2. 服务端保存 code 与扩展 refresh token 的哈希，code 60 秒且一次性使用，扩展 access token 15 分钟、refresh token 30 天并轮换。令牌含扩展专用 audience，不能被普通 Web/API 身份守卫接受。
-3. 扩展上报仅携带来源、规范化 SKU/规格轴、候选素材 URL 和证据；`POST /api/extension/materials` 从扩展令牌解析工作空间，不接受目标平台、门店、Cookie 或 API Key。相同工作空间、来源平台和来源 item key 复用同一采集记录。
-4. 上报事务创建来源采集记录、SPU、来源确认 SKU 和素材转存任务；素材异步事件经 Transactional Outbox 进入 Worker。Worker 仅下载 HTTPS 公网地址，限制重定向、私网地址、20MB 和 PNG/JPEG/WebP，按 SHA-256 去重后写入对象存储。单张失败不会使商品草稿丢失。
-5. Ozon (`ru/kz/by`) 商品详情页显示 Shadow DOM 小浮窗。未登录只显示“登录 Atlas ERP”；已登录显示“编辑上架 / 采集商品 / 进入 ERP”。编辑上架成功后打开现有 `/products/{productId}` ERP 编辑入口；采集商品只提示进入采集箱。
-6. Ozon 解析器保留当前公开 SKU，并只从带 `webProducts`、`webAspects` 或 `aspects` 标识的页面状态发现关联 SKU；不会扫描整页 SKU 或把规格轴做笛卡尔积。来源未给可确认组合时，仍保留当前 SKU。主图作为商品候选素材上报，不伪造 SKU 图片关系。
+1. 扩展按毛子 ERP 风格复用 Atlas Web 登录态：点击登录会打开 Atlas Web；Web 登录/恢复后把当前短期 access token 写入本站 localStorage，扩展每 2 秒从该 Atlas 标签读取并保存到 extension storage。未登录时用户在该页完成登录，标签不会被扩展自动关闭。
+2. 扩展以同步到的 Web Bearer token 调用会话检查和采集接口；服务端同时验证 JWT 与未撤销的 Web session，并从当前用户成员关系解析工作空间。Token 失效时插件清除缓存并重新要求从 Atlas Web 登录同步。
+3. 扩展上报仅携带来源、规范化 SKU/规格轴、候选素材 URL 和证据；`POST /api/extension/materials` 从 Web Bearer 身份解析工作空间，不接受目标平台、门店、Cookie 或 API Key。非 Ozon 来源按 item key 复用；Ozon 额外按已确认 `source_sku` 集合相交复用同一采集记录。
+4. 上报事务创建来源采集记录、SPU、来源确认 SKU 和素材转存任务；同一来源商品再次采集时保留记录与商品 ID，并用本次来源快照替换来源字段、SKU 与候选素材。素材异步事件经 Transactional Outbox 进入 Worker，任务带快照版本；Worker 仅处理当前版本，旧任务不得回写。Worker 仅下载 HTTPS 公网地址，限制重定向、私网地址、20MB 和 PNG/JPEG/WebP，按 SHA-256 去重后写入对象存储。单张失败不会使商品草稿丢失。
+5. Ozon (`ru/kz/by`) 商品详情页显示 Shadow DOM 小浮窗。未登录只显示“登录 Atlas ERP”；已登录显示“编辑上架 / 采集商品 / 进入 ERP”。商品编辑模块尚未完成时，“编辑上架”成功后打开 `/collection-test/{collectionItemId}` 供审查采集结果；采集商品只提示进入采集箱。
+6. Ozon 解析器保留当前公开 SKU 作为入口证据，优先解析 `state-webAspects-*.data-state.aspects[].variants[]` 的真实变体；不会扫描整页 SKU 或把规格轴做笛卡尔积。来源未给可确认组合时，仍保留当前 SKU。
+7. Ozon 多 SKU 补全通过受限 MAIN world bridge 调用同源公开页面 JSON：先读取 `modal/aspectsNew` 的 `webAspectsModal`，再以并发 3、上限 100 的队列补全 `/product/<sku>/` 中的标题、价格、画廊和关联 SKU。每个已补全 SKU 的画廊图片使用 `variant_direct` 关联；单个请求失败保留已发现 SKU 与失败证据。
+8. Ozon 公开响应没有可依赖 SPU/组 ID。服务端在同一来源平台下按新旧 `source_sku` 集合相交覆盖快照；若命中多条历史记录返回 `SOURCE_VARIANT_GROUP_AMBIGUOUS`，不静默合并。
+9. 图片采集沿用旧采集插件已验证的分组 profile：1688、淘宝、天猫只从主图画廊、规格选择器和商品详情容器读取图片，绝不扫描全页 `document.images`。淘宝/天猫详情图排除评论和推荐卡片；URL 会在入库前还原 CDN 原图并按归一化 URL 去重。
+10. Ozon 只从 `webGallery` 读取商品画廊，`coverImage` 与 `images[].src` 归为该真实 SKU 的 `source_main + variant_direct`，不会将第二张及以后的画廊图误标为 SKU 图；`webAspects.data.coverImage` 作为 `source_sku + axis_value`。受限 bridge 额外读取固定的富文本页段来获取 `webDescription` / `webRichContent` / `webFeatures` 内的详情图，仍不接触评价或推荐组件。
+11. 采集数据测试页会为转存成功且已生成 `asset_id` 的素材按 4 路并发申请短时预览 URL，直接显示缩略图，并展示其关联来源 SKU；预览 URL 不保存到业务数据。Ozon 解析器 `ozon-public-2.2.0` 现额外读取短/完整 `web*Characteristics.characteristics[]` 为公共属性，并将 `webDescription.richAnnotationJson` 转为公共描述文本、原 JSON 放入 `raw_value`。该桥接仍只允许固定 Ozon 页面段和 widget 白名单；已有旧版载荷必须重采集才会拥有这些字段。

 ## 配置与安全前提

- `EXTENSION_COLLECTOR_REDIRECT_URI` 必须精确等于已安装扩展的 `chrome.identity.getRedirectURL('callback')`；不可用通配符代替。
- 本地默认 API 为 `http://localhost:8200`。生产构建应为 Atlas API 域配置扩展 host permission 与 `ATLAS_API_ORIGIN`，并登记对应扩展 ID 的回调 URI。
- 扩展 refresh token 仅存 Chrome extension storage；Web refresh Cookie 从不返回给扩展。Worker 不接触浏览器 Cookie。
+- 扩展清单带有仅公开的 RSA `key`，Chrome 因此为自托管和解压加载生成稳定 ID；该 ID 不参与登录授权，严禁提交私钥。
+- 本地默认 API 为 `http://localhost:8200`。生产构建应为 Atlas API 域配置扩展 host permission 与 `ATLAS_API_ORIGIN`；不需要按用户登记回调 URI。
+- Web access token 镜像到 Atlas Web 自己的 localStorage 是维护者批准的自托管插件例外；扩展不读取 refresh Cookie、来源站 Cookie 或来源站 localStorage。Worker 不接触浏览器 Cookie。安全取舍见 [`extension-login-alternatives.md`](./extension-login-alternatives.md)。

 ## 尚未实现

- Ozon 变体队列逐页 hydrate、SKU 级公开详情补全；当前只消费已加载公开页面状态。
- 1688、淘宝、天猫解析器，以及 Ozon Seller 网页四接口本地观察实验。
- 采集箱详情页的素材关联可视化、重试 UI 和商品编辑/发布闭环。
+- Ozon 多 SKU 的真实来源页人工回归（`packages/reference/ozon1.html` 已作为三 SKU 快照）；Ozon Seller 网页四接口观察实验仍独立于此标准公开采集链路。
+- Ozon Seller 网页四接口本地观察实验；1688、淘宝、天猫基础页面状态解析已在 M2.4 完成，但仍需要真实来源页面回归。
+- 正式采集箱详情页的素材关联可视化、重试 UI 和商品编辑/发布闭环（当前仅 `/collection-test/{id}` 提供只读素材预览与关联 SKU）。

 ## 验收命令

@@ -30,5 +35,6 @@
 ./apps/api/node_modules/.bin/tsc -p apps/api/tsconfig.json --noEmit
 ./apps/worker/node_modules/.bin/tsc -p apps/worker/tsconfig.json --noEmit
 (cd apps/extension && ./node_modules/.bin/wxt prepare && ./node_modules/.bin/tsc -p tsconfig.json --noEmit && ./node_modules/.bin/wxt build)
+(cd apps/extension && ./node_modules/.bin/tsx --test test/*.test.mts)
 (cd apps/web && ./node_modules/.bin/vite build)
 ```