feat(collection): 采集箱开发

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：商品编辑、平台发布配置、定价与首次上架。