Expand seller store functionality

docs/api/collection-and-extension.md

@@ -4,42 +4,19 @@
 
 ## 1. 浏览器扩展授权
 
-扩展不读取 ERP 网页 localStorage，也不用 Web 端 refresh cookie。每个发布扩展在服务端登记 `client_id` 和允许的 `chrome-extension://{extension-id}/…` 回调地址，扩展使用 PKCE 授权码流程。
+首期按毛子 ERP 风格复用 Atlas Web 登录态。用户从插件点击登录后，扩展打开固定 Atlas Web 页面；用户在该页完成登录或会话恢复后，Web 将当前短期 access token 镜像到本站 `localStorage["atlas.extension.web-access"]`。扩展每 2 秒仅从该 Atlas 标签读取这个值，保存到 Chrome extension storage，并以 Bearer token 调用下述接口。
 
-1. 扩展打开：`GET /api/extension/authorize?client_id={id}&redirect_uri={uri}&state={random}&code_challenge={S256}&code_challenge_method=S256`。
-2. 用户在 Atlas Web 完成登录；首期不额外展示工作空间选择/授权确认页。
-3. 服务端只向已登记的 `redirect_uri` 回跳 `?code={one-time}&state={original}`。授权码 60 秒有效、只能交换一次，且绑定 client、回调地址和 PKCE challenge。
-4. 扩展调用 `POST /api/extension/auth/exchange`：
-
-```json
-{
-  "client_id": "atlas-collector",
-  "code": "one-time-code",
-  "redirect_uri": "chrome-extension://extension-id/callback",
-  "code_verifier": "original-pkce-verifier"
-}
-```
-
-成功返回扩展专用短期 access token 与可轮换 refresh token；令牌只存 Chrome 扩展专属存储：
-
-```json
-{ "data": {
-  "access_token": "eyJ…", "expires_in": 900, "refresh_token": "opaque", "refresh_token_expires_in": 2592000,
-  "token_type": "Bearer"
-} }
-```
-
-`POST /api/extension/auth/refresh` 接收 `{ "refresh_token": "opaque" }`，轮换并返回同形状令牌；`POST /api/extension/auth/revoke` 撤销当前扩展 refresh token，返回 `204`。令牌续期、撤销和错误响应不得泄露 Web 会话或其他工作空间信息。
+这是维护者批准的自托管插件例外：扩展不读取 refresh cookie、Cookie、来源站 localStorage 或来源站授权信息；Web token 不得进入日志、数据库、Outbox 或采集载荷。Token 失效返回 `401` 后，插件清除自己的缓存并要求用户再次从 Atlas Web 登录同步。完整取舍见 [`../project/extension-login-alternatives.md`](../project/extension-login-alternatives.md)。
 
 `GET /api/extension/session`
 
-使用扩展 access token，返回最小化状态：
+使用从 Atlas Web 同步的 Bearer token，返回最小化状态：
 
 ```json
 { "data": { "authenticated": true, "workspace": { "id": "uuid", "available": true }, "can_collect": true } }
 ```
 
-不返回平台、默认店铺、Cookie、Ozon 凭据或 Web refresh token。令牌失效返回 `401`，插件只展示“登录 Atlas ERP”。
+不返回平台、默认店铺、Cookie、Ozon 凭据或 Web refresh token。令牌失效返回 `401`，插件清除缓存并只展示“登录 Atlas ERP”。
 
 ## 2. 插件上报采集结果
 
@@ -49,14 +26,14 @@ Headers：扩展 Bearer token 与 `Idempotency-Key` 必填。请求体为已定
 
 请求体不得包含或传入 `workspace_id`、`target_platform_id`、`platform_id`、`store_id`、`api_key`、Cookie、授权头或来源站会话字段。服务端从扩展令牌解析工作空间，并将来源 `platform` 映射为系统已启用的来源平台。
 
-服务端在一个事务中：检查工作空间采集箱上限 → 按 `workspace + source_platform + source_item_key` 查找活动记录 → 创建或复用 `collection_item`、`product`、来源确认的 `product_variants` 和持久化 `collection_asset_transfers` → 再经 outbox 投递素材 Worker。重复上报不会增加采集箱配额，也不覆盖用户已编辑草稿。
+服务端在一个事务中：检查工作空间采集箱上限 → 按 `workspace + source_platform + source_item_key` 查找活动记录 → 创建记录，或以本次页面快照覆盖已有记录的来源 URL、标题、价格、原始证据、规范化载荷、SKU 草稿与候选素材 → 再经 outbox 投递素材 Worker。重复上报不会增加采集箱配额，且会保留原有 `collection_item` 与 `product` ID；旧素材任务被取消，新素材任务使用新的来源快照版本，旧 Worker 不得回写新快照。
 
 成功返回 `201`（新建）或 `200`（复用）：
 
 ```json
 { "data": {
   "collection_item": { "id": "uuid", "status": "materializing", "source_title": "商品标题", "variant_count": 3 },
-  "product_id": "uuid", "reused": false,
+  "product_id": "uuid", "reused": false, "refreshed": false,
   "editor_entry_path": "/products/uuid",
   "materialization": { "total": 12, "queued": 12, "succeeded": 0, "failed": 0 }
 } }