feat: 初始化项目，项目需求、方案文档

docs/product/api.md

@@ -0,0 +1,42 @@
+# 商品编辑 API 契约
+
+> 接口前缀与鉴权细节待基础架构确认。所有请求由当前用户、工作空间、门店上下文授权；客户端不能跨租户指定 ID。
+
+## 1. 采集与读取
+
+| 接口 | 用途 |
+|---|---|
+| `POST /api/stores/{store_id}/materials` | 上报采集商品与可选 SKU 数组；无 SKU 数组时创建默认 SKU。 |
+| `GET /api/products/{product_id}/editor` | 返回编辑页所需商品、SKU、属性 schema、媒体和草稿版本。 |
+| `GET /api/products/{product_id}/validation` | 返回父商品和逐 SKU 的本地发布校验。 |
+
+采集变体按 `platform + source_item_key + source_variant_key` 幂等。只有来源明确给出 SKU—图片关联时才能绑定 SKU；其他图片进入商品候选池。未知口径的规格保留原文并标为 `ambiguous`。
+
+## 2. 草稿、SKU 与属性
+
+| 接口 | 用途 |
+|---|---|
+| `PUT /api/products/{product_id}/editor-draft` | 原子保存商品、SKU、属性、排序和媒体选择；使用 ETag/版本号冲突控制。 |
+| `POST /api/products/{product_id}/variants` | 创建或复制 SKU。 |
+| `PATCH /api/products/{product_id}/variants/{variant_id}` | 修改 SKU；可继承字段传 `null` 恢复默认值。 |
+| `DELETE /api/products/{product_id}/variants/{variant_id}` | 软删除未发布 SKU；已发布 SKU 改停用并留给发布流程处理。 |
+| `GET /api/products/{product_id}/attribute-schema` | 按门店平台和当前类目返回动态属性 schema/字典。 |
+
+schema 适配器对 Ozon 调用 `/v1/description-category/attribute` 和字典值接口，读取 `type`、`is_required`、`is_collection`、`max_value_count`、`dictionary_id`、`is_aspect`。对其他平台提供同一内部 schema 形状。
+
+## 3. 定价、媒体和 AI
+
+| 接口 | 用途 |
+|---|---|
+| `POST /api/products/{product_id}/variants/{variant_id}/pricing/quote` | 用服务端有效包装规格计算预览，不落价。 |
+| `POST /api/products/{product_id}/variants/{variant_id}/pricing/confirm` | 重新计算、校验、保存快照并回填售价/划线价。 |
+| `GET/PUT /api/products/{product_id}/variants/{variant_id}/media` | 读取候选媒体/保存 SKU 已选媒体及顺序。 |
+| `POST /api/products/{product_id}/ai/copy` | 生成父商品的多语言标题、标签、简介等候选草稿。 |
+| `POST /api/products/{product_id}/ai/suite-plans` | 创建显式绑定目标 SKU 的套图规划。 |
+| `POST /api/products/{product_id}/variants/{variant_id}/ai/dimension-image` | 创建单 SKU 尺寸图任务，并固化实物规格快照。 |
+
+确认定价失败（缺失/待确认/无效包装规格或物流校验失败）返回 `422`，不改写现有价格。AI 返回候选结果，不能未经用户确认覆盖手工内容。
+
+## 4. 后续发布
+
+未来平台适配器接受“父商品 + 单 SKU”规范化对象。Ozon 实现将每个启用 SKU 转换为一个 `/v3/product/import.items[]`：复制通用标题、简介、类目和通用属性；填入 SKU offer、价格、包装规格、图片和变体属性。批量按平台限制分组，结果按 SKU 独立保存。