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