feat(api): public good detail family block behind gray-release flag

docs/references/product-center.md

@@ -101,8 +101,31 @@ pnpm --filter @inkreach/api backfill:product-families
 # → [1/2] 解析全部链接名 [2/2] 自动建族 [3/3] 全量族重算（幂等，可随时重跑）
 ```
 
+**公开读路径灰度（三期已上线，默认关闭）**：环境变量 `PUBLIC_DETAIL_FROM_FAMILY=true` 时，
+`GET /public/goods/:goodId` 在既有响应上**增量**输出 `family` 块：
+
+```jsonc
+{
+  "family": {
+    "familyId": "12", "familyCode": "DG015", "familyName": "DG015 180G纯棉T恤",
+    "sizes": [...], "colors": [...], "crafts": ["单面印花", ...], "logistics": ["包邮", ...],
+    "sizeChart": { /* 并集 */ }, "packageSpecs": { /* 并集 */ },
+    "priceMatrix": { /* 五维矩阵：rows 为 {sizeId, colorId, craft, logistics, price, manual, sources} */ },
+    "minPrice": "29.5"
+  }
+}
+```
+
+实测（DG015 族）：4 工艺 × 2 物流 × 8 尺码 × 12 颜色 = 653 格矩阵，族起价 ¥29.5
+（主源单链接价为 ¥68.74——族视角展示了光板/单面的更低档价格）。前端本地按五维联动
+`priceMatrix` 即可实时算价，无需新增查价端点（设计 D4）。
+
+**边界声明**：商品列表/筛选/排序仍基于主源 `goodPrice`（SQL 层无法廉价解析族矩阵 JSON，
+且避免展示价与筛选价不一致）；`good_origin_goods` 转只读保留，观察期后另行删除。
+
 **后台操作入口（二期已上线）**：商品中心新增「产品族」标签页（`/goods?tab=families`）：
 
+
 - 列表：关键词/分页、成员数、人工改价数、自动托管/锁定状态、`stale` 待处理标记；
 - 「自动成族」：先预览候选分组（SDS 分类聚合），确认后应用并逐族重算；
 - 详情抽屉：canonical 字段编辑（名称/编码/主图/主链接）、`autoManaged` 开关、手动重算、

docs/references/structs.md

@@ -89,7 +89,7 @@ apps/api/
 | `Tag` | 标签，含 `tagColor`、`tagFontColor`、`tagGroupId`、`sortOrder`、`timing` |
 | `TagGroup` | 标签分组（含 `groupName`、`groupColor`、`groupIcon`、`sortOrder`），删除分组时组内 tag 的 `tagGroupId` 通过 `onDelete: SetNull` 自动置空 |
 | `Position` | 坑位：`(country, category)` 维度，关联多个 goods |
-| `Good` | 商品：`originGood × country × category × tag? × position?`，含 `goodPriority` |
+| `Good` | 商品：`originGood × country × category × tag? × position?`，含 `goodPriority`；`familyId` 为派生数据（主链接所属族，创建时自动填充，族成员变更时联动） |
 | `GoodOriginGood` | 副源关联中间表（多对一）：一个 Good 可关联多个副源 OriginGood；主源走 `goods.origin_good_id` 不入表。用于把名称相同但工厂/仓库不同的多个原产品合并为一个商品展示 |
 | `User` | 后台用户（bcrypt 哈希） |
 | `SyncLog` | 同步任务日志，含 `SyncType`（CATEGORIES / PRODUCTS）和 `SyncStatus` |
@@ -114,7 +114,7 @@ apps/api/
 | `/public/tags` `GET` | 公开标签列表（带 `group` 字段，按 group 排序） | 公开 |
 | `/public/tag-groups` `GET` | 公开标签分组列表 | 公开 |
 | `/public/goods` `GET` | 分页商品（支持 `countryId/categoryId/tagIds(逗号分隔)/keyword/page/pageSize`，`tagIds` 为 AND 关系） | 公开 |
-| `/public/goods/:id` `GET` | 商品详情 | 公开 |
+| `/public/goods/:id` `GET` | 商品详情；`PUBLIC_DETAIL_FROM_FAMILY=true` 且主链接有族时额外输出 `family` 块（并集尺码表/包装 + 五维价格矩阵 + 族起价），开关关闭时响应形状与现状一致 | 公开 |
 | `/categories` `/tags` `/tag-groups` `/countries` `/positions` | 后台 CRUD | JWT |
 | `/tags/sort` `PATCH` | 批量更新 tag 排序和分组归属 | JWT |
 | `/tag-groups/sort` `PATCH` | 批量更新分组排序 | JWT |