feat(extension): 采集插件功能开发

docs/project/HANDOFF.md

@@ -1,12 +1,12 @@
 # Atlas Seller Kit 交接说明
 
-> 更新：2026-09-04。此文是新 AI 对话、架构讨论与开发工作的首读入口。开始开发前，必须先阅读并遵守 [`development-collaboration-contract.md`](./development-collaboration-contract.md)。
+> 更新：2026-09-06。此文是新 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 已具备完整前端框架（布局、路由、主题）、登录/注册页、页头平台选择器、店铺管理、水印管理与真实采集箱页面；浏览器扩展仍为可运行骨架。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件。可选择性复用已经验证过的纯计价公式、采集扩展思路和 AI 任务经验，但必须先适配多租户和云端边界。
+当前已完成 pnpm monorepo 初始化：包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享 API 契约、数据库包、本地基础设施 Compose 与依赖锁文件。API 已实现健康/readiness、集中配置与安全基础、认证、个人工作空间上下文、平台目录/上下文、门店、水印/素材、采集箱与扩展采集入库；Worker 已具备 Ozon 凭据验证、采集记录清理和来源素材转存消费链路，仓库同步尚未接入。Web 已具备完整前端框架（布局、路由、主题）、登录/注册页、页头平台选择器、店铺管理、水印管理、真实采集箱页面和采集数据测试页；浏览器扩展已提供 PKCE 授权、悬浮窗及 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)。
 
@@ -87,6 +87,21 @@
 - Web 的采集箱已替换占位页，支持容量显示、标题/来源筛选、手动创建、批量删除、清空确认、空/加载/错误状态。商品编辑入口明确保留给下一任务，未伪造可发布能力。
 - `apps/api/test/collection.e2e.test.ts` 覆盖手动创建、幂等重放、列表读取、乐观锁冲突和软删除；该测试、本次受影响的 API/Worker/Web TypeScript 检查及 Web 生产构建均已通过。任务清单见 [`m2.1-collection-box-foundation.md`](./m2.1-collection-box-foundation.md)。
 
+### 1.9 开发进度（2026-09-05）：M2.2 / M2.3 扩展采集首个闭环
+
+- 已实现扩展 PKCE 授权码、扩展专用 access/refresh token 轮换、现有 Atlas Web 会话的静默授权分支，以及扩展会话检查/撤销。扩展不读取 Web token 或 refresh Cookie；回调 URI 必须按已安装扩展 ID 精确登记。
+- 已实现 `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/淘宝/天猫解析仍未开始。
+- 详情、边界和本地配置见 [`m2.2-m2.3-extension-collection.md`](./m2.2-m2.3-extension-collection.md)。
+
+### 1.10 开发进度（2026-09-06）：M2.4 来源解析器与采集测试页
+
+- 扩展浮窗现覆盖 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 节先完成该验证。
+
 ## 2. 已确认产品决策
 
 | 主题 | 决策 |
@@ -139,17 +154,17 @@ User → Workspace → Membership / Role
 - 所有接口遵循统一鉴权、工作空间隔离、页头平台上下文、金额字符串、错误格式、`Idempotency-Key`、`If-Match` 和异步 `operation` 约定。
 - **响应信封是强制契约：** 成功单资源或同步动作返回 `{ "data": T }`，列表返回 `{ "data": T[], "meta": PaginationMeta }`，失败返回 `{ "error": ApiError }`，`204 No Content` 不返回响应体。项目不采用完整 JSON:API；任何调用方不得自行增加嵌套 `data` 或以 `data: null` 表示错误。完整规则见 [`api/conventions.md`](../api/conventions.md)。
 - 关键异步动作必须在同一事务写入业务记录、`operations`（如需用户可见进度）和 `outbox_events`；Dispatcher 至少一次投递 BullMQ，Worker 必须幂等。
-- DDL 已通过本地隔离 PostgreSQL 执行验证；迁移执行器、认证/工作空间基础、幂等与 Outbox 写入闭环、Outbox Dispatcher、Ozon 凭据验证 Worker、上传意图清理 Worker 与采集记录清理 Worker 均已实现。仓库同步、来源素材转存、发布和在线商品同步 Worker 仍待实现。
+- DDL 已通过本地隔离 PostgreSQL 执行验证；迁移执行器、认证/工作空间基础、幂等与 Outbox 写入闭环、Outbox Dispatcher、Ozon 凭据验证 Worker、上传意图清理 Worker、采集记录清理 Worker 与来源素材转存 Worker 均已实现。仓库同步、发布和在线商品同步 Worker 仍待实现。
 
 仍需在对应模块开始编码前完成的 P1/P2 决策和数据模型补丁，集中记录在 [`reviews/implementation-readiness-open-items.md`](../reviews/implementation-readiness-open-items.md)。
 
 ## 6. 下一步建议
 
-下一步建议按采集入口顺序推进：
+下一步建议按以下顺序推进：
 
-1. M2.2：实现扩展 PKCE 授权、`POST /api/extension/materials` 与来源素材转存 Worker；素材只传来源 URL 和净化证据，不传 Cookie、店铺凭据或二进制。
-2. M2.3：实现插件悬浮窗与 Ozon 公开商品页解析器，验证真实 SKU 组合、素材关联和重复采集复用。
-3. M2.4：实现 1688、淘宝、天猫解析器及各自的稳定 SKU 证据规则。
+1. 用允许保存的单 SKU、单规格轴和颜色×尺码页面样本，在 Ozon、1688、淘宝、天猫逐项验证采集结果；页面状态未暴露组合数据时补 MAIN world bridge 或站点适配器，但绝不以规格轴猜测 SKU。
+2. 完成 Ozon 公开变体队列的逐 SKU hydrate；再独立实施 Seller 网页四接口本地观察实验，默认关闭、仅保存净化结果且不影响标准采集。
+3. 将当前 `/collection-test/{collectionItemId}` 只读检查面替换为正式商品编辑入口：按页头平台创建发布配置、预选同平台默认门店，并接入 SKU/媒体/类目编辑。
 4. 进入商品编辑/在线同步前，关闭评审中的 P1：SKU 与平台发布配置同商品归属、未映射属性持久化、统一乐观锁 Repository 规则；平台能力 Schema 已在 M2.1 按固定键落地。在线商品归档策略和 Client ID 编辑边界仍待确认。
 
 账户资料的已确认补充：`users.avatar_asset_id` 只保存素材引用，绝不保存公开 URL；`users.revision` 用于 `PATCH /api/auth/me` 的 `If-Match`。资料更新已实现幂等与版本冲突检测；修改密码已实现旧密码校验、按 IP/用户限流、撤销旧会话并轮换新会话。头像上传必须复用素材模块的预签名直传与校验流程，不引入 base64 直传；素材模块尚未实现时头像只能为 `null`。
@@ -165,4 +180,6 @@ User → Workspace → Membership / Role
 - [数据库角色与 RLS](../architecture/database-security.md)
 - [实现前待决与待落地事项](../reviews/implementation-readiness-open-items.md)
 - [浏览器采集插件需求与技术方案](../requirements/collector-browser-extension.md)
+- [M2.2 / M2.3 扩展采集交接](./m2.2-m2.3-extension-collection.md)
+- [M2.4 来源解析与测试页交接](./m2.4-source-parsers-and-inspection.md)
 - [技术栈、异步任务与部署方案](../architecture/technology-and-deployment.md)