feat(collection): 采集箱开发

docs/project/HANDOFF.md

@@ -6,7 +6,7 @@
 
 这是一个全新的云端产品，不是 `ozon-seller-kit` 的本地版重构。目标用户可拥有多个门店，每个门店只能绑定一个平台；平台自身可支持多个市场、国家、语言和币种。因此语言、币种、类目和发布规则不能写死为 Ozon 或中文/俄文。
 
-当前已完成 pnpm monorepo 初始化：包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享 API 契约、数据库包、本地基础设施 Compose 与依赖锁文件。API 已实现健康/readiness、集中配置与安全基础、认证、个人工作空间上下文、平台目录/上下文、门店基础管理和操作查询；Worker 已具备首个 Ozon 凭据验证消费链路，仓库同步尚未接入。Web 已具备完整前端框架（布局、路由、主题）、登录/注册页、页头平台选择器与店铺管理页（已接入真实 API），其余业务页面为占位；扩展为可运行骨架。不要从旧项目复制 SQLite 模型、无鉴权 API、旧 `/trial/:id` 或商品编辑页组件。可选择性复用已经验证过的纯计价公式、采集扩展思路和 AI 任务经验，但必须先适配多租户和云端边界。
+当前已完成 pnpm monorepo 初始化：包含 Web、NestJS API、BullMQ Worker、WXT 浏览器扩展、共享 API 契约、数据库包、本地基础设施 Compose 与依赖锁文件。API 已实现健康/readiness、集中配置与安全基础、认证、个人工作空间上下文、平台目录/上下文、门店、水印/素材与采集箱基础管理；Worker 已具备 Ozon 凭据验证及采集记录清理消费链路，仓库同步与来源素材转存尚未接入。Web 已具备完整前端框架（布局、路由、主题）、登录/注册页、页头平台选择器、店铺管理、水印管理与真实采集箱页面；浏览器扩展仍为可运行骨架。不要从旧项目复制 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)。
 
@@ -78,6 +78,15 @@
 - 对 `failed` / `expired` 意图，Worker 删除其 MinIO/S3 临时对象；对象不存在也视为已清理。仅对象存储删除成功才写入 `object_cleaned_at`，删除暂时失败会保留记录并在下次扫描重试。
 - 新增迁移 `007_media_upload_cleanup.sql`，该字段与清理索引必须在部署 Worker 前执行。
 
+### 1.8 开发进度（2026-09-04）：M2.1 采集箱基础闭环
+
+- 已新增 `008_collection_box_foundation.sql` 与 `009_fix_collection_limit_function.sql`，并在本地 PostgreSQL 实际执行。迁移建立工作空间隔离的采集记录、商品草稿、默认 SKU 与来源素材转存任务；采集箱默认上限为 1000 条，数据库触发器在并发创建/恢复时锁定工作空间并强制限制。
+- 平台能力现有固定键：`can_be_source`、`can_be_target`、`can_be_header_context`。Ozon 是首期目标和页头平台；1688、淘宝、天猫仅作为采集来源，API 平台目录不会把它们暴露给 ERP 页头选择器。
+- API 已实现手动创建采集草稿、按页头平台列出采集箱、备注的 `If-Match` 更新、批量删除、清空和失败素材重试入口。采集记录始终不绑定目标平台或店铺；本阶段列表的上架摘要固定为“等待首次上架”，不冒充 Ozon 前台可见性。
+- 批量删除和清空会软删除 Atlas 采集草稿、创建 `operation` 与 Outbox 事件；Worker 取消尚未执行的素材任务并完成清理操作。它们绝不删除或下架平台商品。
+- 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)。
+
 ## 2. 已确认产品决策
 
 | 主题 | 决策 |
@@ -130,19 +139,18 @@ 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 写入闭环以及上述门店 HTTP 模块已实现。Outbox Dispatcher 与平台 Worker 仍未实现。
+- DDL 已通过本地隔离 PostgreSQL 执行验证；迁移执行器、认证/工作空间基础、幂等与 Outbox 写入闭环、Outbox Dispatcher、Ozon 凭据验证 Worker、上传意图清理 Worker 与采集记录清理 Worker 均已实现。仓库同步、来源素材转存、发布和在线商品同步 Worker 仍待实现。
 
 仍需在对应模块开始编码前完成的 P1/P2 决策和数据模型补丁，集中记录在 [`reviews/implementation-readiness-open-items.md`](../reviews/implementation-readiness-open-items.md)。
 
 ## 6. 下一步建议
 
-当前优先完成门店纵向闭环，而不是继续扩展商品接口：
+下一步建议按采集入口顺序推进：
 
-1. 验证并补齐 Outbox Dispatcher 与凭据验证 Worker 的集成测试：覆盖成功、401/403、限流/超时重试、旧密钥任务取消和无密钥日志。
-2. 在凭据验证通过后实现仓库同步 Worker、幂等 upsert 和状态回写，并补充失败重试、死信与集成测试。
-3. ~~Web 接入真实认证和门店管理 API~~ 已基本完成：登录/注册、会话刷新、平台上下文、门店列表/创建/编辑/默认切换/删除均已上线（见 1.2）；剩余水印绑定入口待素材/水印模块交付后接入。前端不得保存 API Key 或 refresh token。
-4. ~~接着实现素材直传和水印管理~~ 已完成后端上传、校验、预览与临时对象清理；接着实现水印实际渲染、采集箱与商品编辑。浏览器扩展仅在采集 API 稳定后实现实际解析器。
-5. 在开始商品编辑/在线同步模块前，关闭评审文档中的 P1 事项：同商品归属约束、未映射属性持久化、乐观锁 Repository 规则、平台能力 Schema；并确认在线商品归档策略和 Client ID 编辑边界。
+1. M2.2：实现扩展 PKCE 授权、`POST /api/extension/materials` 与来源素材转存 Worker；素材只传来源 URL 和净化证据，不传 Cookie、店铺凭据或二进制。
+2. M2.3：实现插件悬浮窗与 Ozon 公开商品页解析器，验证真实 SKU 组合、素材关联和重复采集复用。
+3. M2.4：实现 1688、淘宝、天猫解析器及各自的稳定 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`。
 

docs/project/m2.1-collection-box-foundation.md

@@ -0,0 +1,56 @@
+# M2.1：采集箱基础闭环（手动创建）
+
+> 状态：进行中。负责人：当前全栈开发。开始日期：2026-09-04。
+
+## 目标
+
+交付一个工作空间级采集箱，使用户能够在 ERP 手动创建商品草稿、查看和管理采集记录；为后续浏览器插件上报、素材转存和商品编辑建立真实、隔离且可恢复的数据边界。
+
+采集箱记录不绑定目标平台、门店、店铺凭据或平台 Cookie。来源平台与未来发布目标平台是两个独立概念；列表中的上架摘要仅按页头当前目标平台计算，不能代表采集状态或 Ozon 前台可见性。
+
+## 本任务范围
+
+### 数据与平台能力
+
+- 新增采集记录、商品草稿、默认 SKU 与素材转存任务的最小迁移；所有业务行经 `workspace_id` 受 RLS 保护。
+- 工作空间采集箱默认上限为 1000 条；数据库锁与约束必须防止并发创建或恢复绕过限制。
+- 同一工作空间中，后续来源采集将以 `source_platform + source_item_key` 复用活动记录；手动创建使用独立身份，不伪造来源。
+- 平台能力固定为 `can_be_source`、`can_be_target`、`can_be_header_context`。Ozon 是首期目标/页头平台；1688、淘宝、天猫仅为来源平台，不能出现在页头选择器。
+- 采集记录的备注更新遵守 `If-Match` 乐观锁；创建、删除、清空遵守幂等与 Transactional Outbox。
+
+### API 与 Worker
+
+- `GET /api/collection-items`：必须带 `X-Atlas-Platform-Id`，按标题、来源和当前平台上架摘要筛选，返回容量、缩略图处理状态和采集状态。
+- `POST /api/collection-items`：创建 `manual` 采集记录、商品草稿和默认 SKU；不设置目标平台或门店。
+- `PATCH /api/collection-items/{id}`：本阶段仅允许修改备注。
+- `POST /api/collection-items/bulk-delete`、`POST /api/collection-items/clear`：软删除 Atlas 草稿，返回延迟清理操作；不得删除、下架或隐藏任何平台商品。
+- `POST /api/collection-items/{id}/asset-retries`：先实现受限校验和操作创建；实际来源素材下载在 M2.2 接入。
+- Worker 消费采集清理事件，取消未执行的素材任务并完成操作；不得物理删除仍被引用的素材。
+
+### Web
+
+- 用真实采集箱页面替换占位页：容量进度、标题搜索、来源/上架状态筛选、分页、加载/空/错误状态。
+- 实现手动创建、备注编辑、单条与批量删除、清空的确认流程，并明确删除不影响平台商品。
+- 同时展示 `collection_status` 与 `listing_summary`，不混用两种状态。
+- “编辑上架”保留为下一项商品编辑任务的正式入口；本任务不会伪造已可发布的编辑能力。
+
+## 非范围
+
+- 扩展 PKCE 授权、`POST /api/extension/materials`、来源页面解析器与 Ozon Seller 本地观察。
+- 来源图片下载、校验、去重和对象存储转存的实际 Worker。
+- 商品编辑、平台发布配置、定价、首次发布与在线商品同步。
+
+## 验收
+
+1. 新建手动商品后可在刷新后的列表中读取，并始终至少存在一个默认 SKU。
+2. 跨工作空间不能读取、修改或删除采集记录；并发创建无法超出配置容量。
+3. 相同幂等键重放得到历史响应，不同请求复用同一键返回 `409`；过期 revision 返回 `409 VERSION_CONFLICT`。
+4. 删除、批量删除和清空仅软删除 Atlas 采集草稿，确认文案和 API 均不暗示平台商品会被删除或下架。
+5. API 集成测试、受影响工作区 TypeScript 检查与 Web 生产构建通过。
+
+## 后续顺序
+
+1. M2.2：扩展 PKCE 授权、插件上报接口与来源素材转存 Worker。
+2. M2.3：插件悬浮窗与 Ozon 公开商品页解析器。
+3. M2.4：1688、淘宝、天猫解析器与真实 SKU 证据规则。
+4. M3：商品编辑、平台发布配置、定价与首次上架。