docs: update references for product families; fix controller import and test isolation

2026-08-28 12:50:42 +08:00
parent c8531bfe08
commit 502b7eba6e
5 changed files with 81 additions and 12 deletions
@@ -50,6 +50,58 @@
  - 配置弹窗（右栏拖拽/配置按钮）：自动勾选同分类下同名兄弟原产品作为副源提交（`mergedOriginGoodIds`）；
  - 编辑弹窗「关联原产品」区：可搜索添加副源、移除副源、切换主源（切换后旧主源自动转为副源）。

+> 该 Good 级合并能力保留可用；新一级的「产品族（SPU）合并」见下节，公开读路径接入族数据属于三期范围。
+
+## 产品族（SPU 层，一期后端已上线）
+
+设计文档：`docs/superpowers/specs/2026-08-28-product-family-merge-design.md`。
+
+**模型**：SDS 叶子分类即产品模型（如分类 `DG001 180G纯棉T恤（JSA002）` 下 16 条链接），
+族 = 同分类链接的合并体；链接名解析列（`国家（物流）品名-SKU-工艺[-仓库]`）提供
+物流/工艺归因。例：DG001 族 = 16 链接 × 3 工艺 × 3 物流 × 9 尺码（S~XXXXXL 并集）× 20 颜色 ≈ 470 格价格矩阵，起价取光板（不打印）最低价。
+
+**价格**：`价格 = f(尺码, 颜色, 物流, 工艺[含印花数量])`，全部从成员链接变体推导透传
+（同格子多仓库取最低价，来源全保留）；`family_price_overrides` 表支持按格人工改价，
+删覆盖即恢复推导价。
+
+**关键端点用法示例**（JWT）：
+
+```bash
+# 1. 自动成族：先预览
+curl -X POST /product-families/auto-group -H "Authorization: Bearer $T" \
+  -d '{"apply": false}'
+# → { applied: 0, groups: [{ groupKey: "cat:8240", familyName: "DG001 180G纯棉T恤（JSA002）", memberCount: 16, ... }] }
+
+# 2. 应用（幂等，可重复执行）
+curl -X POST /product-families/auto-group -H "Authorization: Bearer $T" -d '{"apply": true}'
+
+# 3. 族详情：成员 + 并集尺码表/包装 + 五维价格矩阵
+curl /product-families/12 -H "Authorization: Bearer $T"
+
+# 4. 人工改价（维度必须存在于族矩阵选项，否则 400 并列出非法键）
+curl -X PUT /product-families/12/price-overrides -H "Authorization: Bearer $T" \
+  -d '{"items": [{"sizeId":"size_S","colorId":"color_blk","craft":"单面印花","logistics":"包邮","price": 23, "note": "促销"}]}'
+
+# 5. 删覆盖恢复推导价
+curl -X DELETE /product-families/12/price-overrides -H "Authorization: Bearer $T" \
+  -d '{"cells": [{"sizeId":"size_S","colorId":"color_blk","craft":"单面印花","logistics":"包邮"}]}'
+
+# 6. 族内创建自定义商品（人工补链接，物流/工艺归因必填）
+curl -X POST /product-families/12/members/custom -H "Authorization: Bearer $T" \
+  -d '{"goodName":"美国（海运）180g纯棉T恤-DG001-烫画","logisticsLabel":"海运","craftLabel":"烫画",
+       "variants":[{"sku":"C-M","sizeId":"size_M","sizeName":"M","colorId":"color_red","colorName":"红色","price": 33}]}'
+```
+
+**同步联动**：商品同步落库时刷新解析列；新链接与已有族**同分类唯一命中**时自动挂族
+（多族/零族留给管理员；锁定族只置 `stale`）；详情同步提交后异步重算受影响族
+（进程内去重、幂等）。回填/修复脚本：
+
+```bash
+pnpm --filter @inkreach/api backfill:product-families
+# → [1/2] 解析全部链接名 [2/2] 自动建族 [3/3] 全量族重算（幂等，可随时重跑）
+```
+
+
 ## 验证

 ```bash