feat(product-edit)：商品编辑页初版

2026-09-09 15:11:58 +08:00
parent 319887726e
commit 130a005231
19 changed files with 1541 additions and 21 deletions
@@ -16,7 +16,7 @@ API 启动后会在 `/api-docs` 提供 Swagger UI，并在其 OpenAPI 文档中
 | [`watermarks-and-assets.md`](./watermarks-and-assets.md) | 部分已实现 | 水印模板、字体、店铺推荐水印，以及水印图片直传、校验和短时预览；图片渲染派生待实现。 |
 | [`pricing.md`](./pricing.md) | 已设计 | 汇率、物流价卡、即时试算、定价方案、报价快照衔接。 |
 | [`collection-and-extension.md`](./collection-and-extension.md) | 已设计 | 插件授权、采集写入、采集箱查询、素材转存与状态。 |
-| [`product-editor-and-publishing.md`](./product-editor-and-publishing.md) | 已设计 | 商品编辑、SKU、类目、属性、AI、媒体选择、定价确认与部分 SKU 首次上架。 |
+| [`product-editor-and-publishing.md`](./product-editor-and-publishing.md) | M3.1 部分已实现 | 编辑上下文、只读快照和产品/平台文案/SKU 的原子草稿保存；类目/属性、媒体、定价、AI 与首次上架仍待实现。 |
 | [`online-listings.md`](./online-listings.md) | 初版已设计 | 店铺独有的在线商品镜像、读取与异步同步；编辑/认领仍待讨论。 |

 旧的 [`../product/api.md`](../product/api.md) 是商品域的早期草案：已确认的产品规则可作为背景，但不能当作最终 HTTP 契约。后续商品模块会迁入本目录并替换其中的路径和细节。
@@ -1,5 +1,7 @@
 # 商品编辑与首次上架 API

+> M3.0 已实现第 1 节的 `POST /editor-contexts` 和 `GET /editor` 基础读模型，以及对应数据库归属约束。M3.1 已实现第 2 节的产品基础字段、当前平台文案、SKU 与 `offer_id` 的原子草稿保存及双版本并发控制；规格、类目/属性切换、媒体选择、定价、AI 与发布仍是冻结契约，尚未实现。
+
 > 此处的商品始终是采集箱内的 Atlas 草稿。所有平台范围接口要求 `X-Atlas-Platform-Id`。商品通用资料可以跨平台复用；`product_platform_profile`、SKU 首次导入状态和在线商品不能跨平台/门店复用。

 ## 1. 进入编辑与读取编辑器
@@ -161,6 +161,21 @@
 - 1688、淘宝、天猫已加入受限 MAIN-world 商品状态桥：1688 仅投影公开商品的画廊、SKU、价格、参数等固定字段；淘宝/天猫仅投影 `__ICE_APP_CONTEXT__` 中的公开商品结果。桥不提供任意 window 读取、Cookie、请求头或通用 fetch。新采集器将这些结构化数据、JSON-LD、受限详情 DOM 与既有图片 profile 映射为 Atlas 新 `CollectedProductPayload`。
 - `/collection-test/{collectionItemId}` 现单独展示商品描述、类目路径、全部特征表、规格轴、SKU 草稿、素材候选，并保留规范化载荷和原始证据，供解析核对。扩展解析器测试覆盖 JSON-LD 描述兜底、完整特征合并和图片白名单。

+### 1.19 开发进度（2026-09-09）：M3.0 商品编辑领域基础
+
+- 新增迁移 `018_product_editor_foundation.sql`：采集期最小 `products` / `product_variants` 扩展为可编辑的产品聚合，并建立平台发布配置、SKU 平台 listing、平台属性及未映射属性草稿表。所有表启用并强制工作空间 RLS。
+- `product_variant_platform_listings` 同时保存 `product_id`，以 profile→product 和 variant→product 两条复合外键强制同商品归属；数据库会拒绝同一工作空间中“商品 A profile + 商品 B SKU”的错误组合。属性和未映射属性也受 profile/variant 与 product 的复合外键约束。
+- 已实现 `POST /api/collection-items/{id}/editor-contexts`：只有当前页头目标平台存在已验证默认门店时，才原子取得或创建产品的该平台 profile，并为现有 SKU 建立初始 `not_listed` listing。`GET /api/products/{id}/editor` 返回产品、profile、SKU listing、属性和待处理未映射属性的只读快照。
+- `products.version` 已迁移为统一命名的 `revision`；新增共享版本冲突辅助。M3.1 的完整草稿写入仍必须以 `product.revision + profile.revision` 条件更新为边界，并覆盖并发保存。
+- API 集成测试覆盖默认店铺前置、上下文幂等复用、读模型、跨商品外键拒绝和未映射属性读回。正式编辑 Web、草稿保存、类目切换、素材选择、定价与发布尚未开始。
+
+### 1.20 开发进度（2026-09-09）：M3.1 商品草稿保存与正式编辑入口
+
+- 已实现 `PUT /api/products/{id}/editor-draft`：产品基础资料、当前平台标题/描述/标签/履约方式，以及完整 SKU 集合和未上架 listing 的 `offer_id` 在同一事务保存。新 SKU 以 `client_key` 回传稳定 ID；省略现有 SKU 会软删除 Atlas 草稿，绝不触发平台下架。
+- 请求必须携带 `If-Match: "{product_revision}:{profile_revision}"` 与 `Idempotency-Key`。服务端先后执行两个带 revision 条件的更新；任一步冲突或 SKU/货号校验失败都会回滚整笔保存。店铺内货号重复会返回可展示的 `422`，重复请求键安全重放原响应。
+- Web 的采集箱“编辑上架”和手动创建现会创建编辑上下文后进入 `/products/{id}/editor`。正式页可编辑产品基础资料、当前平台文案及 SKU/货号，遇到版本冲突会重新加载最新快照。
+- 此批刻意不展示未具备平台 schema 或发布校验的数据：类目/属性切换与未映射属性恢复、规格继承、候选媒体物化/选图、定价确认、AI 和首次 Ozon 导入仍待后续纵向任务。
+
 ## 2. 已确认产品决策

 | 主题 | 决策 |
@@ -37,7 +37,7 @@

 ### 1. SKU 与平台发布配置的同商品归属

-**状态：已决策，待数据库约束设计。**
+**状态：M3.0 已落地数据库约束（2026-09-09）；发布任务、在线镜像等后续表必须复用该归属链。**

 `product_variant_platform_listings` 同时引用平台发布配置（profile）和通用 SKU（variant），但必须强制：`variant.product_id = profile.product_id`。同一条归属链也适用于属性、报价、发布任务项和在线镜像映射。

@@ -45,7 +45,7 @@

 ### 2. 类目切换后未映射属性的持久化

-**状态：已决策，待数据模型补齐。**
+**状态：M3.0 已落地持久化表（2026-09-09）；类目切换写入与恢复操作随编辑草稿保存实现。**

 切换目标平台类目后，旧类目中无法映射的属性值必须作为 Atlas 草稿保留，供用户查看、复用或手动处理，不能只出现在一次 API response 的 warning 中。

@@ -58,7 +58,7 @@

 ### 3. 乐观锁的统一实施

-**状态：已决策，待 Repository 规则和测试落地。**
+**状态：M3.1 已使用产品/profile 双 `revision` 条件更新、事务回滚和集成测试落地；后续编辑资源不得绕过该规则。**

 `revision` 不依赖数据库触发器自动递增。所有可编辑资源的更新必须由统一 Repository/数据访问层执行：