fix(product-families): 不打印链接移出族（纯数据修复）——矩阵不再计算不打印工艺，BRTF004 恢复烫画×单面
- 生产数据操作（未改源代码）：11 条光板/不打印链接 family_id 置空（族 1/2/63/135/148）， 名下 3 商品脱族，族 148 主链接 964→965、族 135 主链接置空 - 容器内直调已部署 FamilyRecomputeService 重算 5 族：全库矩阵不再含「不打印」， 族 148 = 烫画×单面印花×不包邮（min 19），public 端口验证通过 - 回滚存档：deploy/backups/20260903-noprint-removal/（全库 dump + 受影响行 CSV + RESTORE.md） - 文档：product-center/structs 记录数据约定与回流风险（organize/autoGroup/人工改标签会回挂散链接）； AGENTS.md 沉淀 占位借词表值/物化JSON需显式重算/数据修复三件套 三条经验
This commit is contained in:
yeuimu
@@ -113,3 +113,6 @@ Prisma Postgres 最佳实践: prisma-postgres 技能
|
||||
- **改"镜像字段"的数据前先查覆盖路径**：分类名每小时被 `syncCategories` 用 SDS 原名无条件覆盖——直接改库/界面改名都会被下一轮同步冲回。此类字段的清洗必须写进同步入库路径（如 `cleanCategoryDisplayName`），存量靠回填脚本；数据先改而镜像未重部署的窗口期内会被冲回一次，重部署后自动恢复。
|
||||
- **合并分叉血统时警惕"文本无冲突、行为有冲突"**：git 自动合并可能把两侧对同一机制的不同设计（如 热转印=烫画别名 vs 一等公民词表）拼进一个文件，编译通过但行为矛盾——合并后必须跑两侧血统各自的测试才能暴露；行级冲突反而不是最危险的。另：`git status | head` 截断会漏看冲突文件，连续 cherry-pick 后要全仓 `grep '<<<<<<<'` 扫一遍。
|
||||
- **生产栈收敛三件套**：动栈结构前先 `pg_dump -Fc` 双库 + 数据卷归档 + 配置快照落 `deploy/backups/<时间戳>/` 并写 RESTORE.md；切换用"外部卷 external 引用 + down 不带 -v + 切换前后行数 diff"保证数据零丢失；先 `docker compose build` 预构建再 down/up，把停机窗口压到秒级。
|
||||
- **矩阵维度占位不得借用业务词表既有值**：曾让「不打印」链接的印花数量占位为「单面印花」，导致顾客端出现「不打印+单面印花」的自相矛盾组合（不打印根本无印花面）。2026-09-03 数据收口：光板/不打印链接不入族（`family_id=NULL`），矩阵不计算不打印工艺。**回流风险**：`organize`/`autoGroup` 会把散链接按分类重新归族、人工改链接标签会触发 `attachToMatchingFamily` 回挂——跑这两类操作前必须先排查光板链接（清单与回滚见 `deploy/backups/20260903-noprint-removal/`）。
|
||||
- **重部署不会自愈物化 JSON**：`price_matrix` 是物化列，代码修好/词表修正后已物化的矩阵**不会自动重算**（重算只在归族/成员变化/详情同步/标签调整等事件时触发）——族 148 曾因旧容器物化的坏矩阵跨镜像存活，"代码明明对了线上却没变"。此类修复收尾必须显式触发受影响族重算（可容器内 `node -e` 直调 `FamilyRecomputeService.recomputeFamily`，用已部署代码、免重建免鉴权）。
|
||||
- **批量数据修复前"全量 dump + 受影响行快照 + RESTORE.md"三件是底线**：全量 `pg_dump -Fc` 兜灾难恢复，受影响行 CSV（含改前外键值）支持精准回滚，RESTORE.md 写清逐表恢复命令与重算步骤；事务内逐步核对影响行数与预期一致再 COMMIT。
|
||||
|
||||
@@ -57,7 +57,8 @@
|
||||
|
||||
**模型**：SDS 叶子分类即产品模型（如分类 `DG001 180G纯棉T恤（JSA002）` 下 16 条链接），
|
||||
族 = 同分类链接的合并体；链接名解析列（`国家（物流）品名-SKU-工艺[-仓库]`）提供
|
||||
物流/工艺归因。例：DG001 族 = 16 链接 × 3 工艺 × 3 物流 × 9 尺码（S~XXXXXL 并集）× 20 颜色 ≈ 470 格价格矩阵，起价取光板（不打印）最低价。
|
||||
物流/工艺归因。例：DG001 族 = 16 链接 × 3 工艺 × 3 物流 × 9 尺码（S~XXXXXL 并集）× 20 颜色 ≈ 470 格价格矩阵，起价取矩阵内最低价。
|
||||
（2026-09-03 起：**光板/不打印链接不配置进族**，矩阵不再计算「不打印」工艺，起价只来自印花工艺链接。）
|
||||
|
||||
**价格**：`价格 = f(尺码, 颜色, 物流, 工艺[含印花数量])`，全部从成员链接变体推导透传
|
||||
（同格子多仓库取最低价，来源全保留）；`family_price_overrides` 表支持按格人工改价，
|
||||
@@ -112,7 +113,12 @@ curl -X POST /product-families/organize -H "$AUTH" # 后台「整理
|
||||
未整理（无标签）的 SDS 成员不进矩阵，整理后齐全。
|
||||
|
||||
派生默认（脚本层假设，显式可审查）：工艺无关键字 → 烫画；印花数量无单/双面且工艺非不打印 →
|
||||
单面印花；不打印/光板 无印花面不补（矩阵中印花数量以单面占位，纯结构化规则）。
|
||||
单面印花；不打印/光板 无印花面不补。
|
||||
**数据约定（2026-09-03 起）**：不打印/光板链接不进族（`family_id=NULL`），SKU 矩阵不计算
|
||||
「不打印」工艺——不存在「不打印×单面印花」这类矛盾组合。⚠️ 回流风险：运行 `organize` /
|
||||
`POST /product-families/autoGroup` 会把这些散链接按分类重新归族；人工编辑其标签也会触发
|
||||
`attachToMatchingFamily` 回挂。重新归族前须先排查光板链接（备份与清单见
|
||||
`deploy/backups/20260903-noprint-removal/`）。
|
||||
「恢复自动」（链接标签重置）本身是显式人工动作，同样走整理服务的单链接派生。
|
||||
|
||||
**人工标签缺啥补啥 + 旧词别名**（2026-09-02 起）：
|
||||
@@ -121,8 +127,9 @@ curl -X POST /product-families/organize -H "$AUTH" # 后台「整理
|
||||
就按链接名称自动补哪组（并入人工集合一起存为 manual 行，人工勾选值永不被动），响应带
|
||||
`filledDimensionTags`；未归族链接随后自动并入匹配族（同 SDS 分类优先，回退族语义名称键），
|
||||
响应带 `attachedFamilyId`。
|
||||
- 工艺旧词「热转印」按别名归一为「烫画」进价格矩阵（`CRAFT_TAG_ALIASES`），标签字典本身不动。
|
||||
历史背景：曾有 16 条人工链接因勾了旧词「热转印」被封闭词表静默踢出合并矩阵。
|
||||
- 工艺「热转印」是矩阵词表一等公民（`DIM_VALUES.craft` 含 烫画/直喷/不打印/热转印），
|
||||
打了该标签的链接按「热转印」工艺进价格矩阵；标签字典本身不动。
|
||||
历史背景：曾有 16 条人工链接因勾了「热转印」被封闭词表静默踢出合并矩阵。
|
||||
- 名称回退分组键为**族语义键** `familyNameKey`（第 1 段剥离物流备注、保留 国家+品名+SKU）：
|
||||
包邮/不包邮、单面/双面印花是矩阵维度，不再拆族；不同国家/不同款号仍不同族。
|
||||
|
||||
@@ -146,7 +153,7 @@ curl -X POST /product-families/organize -H "$AUTH" # 后台「整理
|
||||
"family": {
|
||||
"familyId": "12", "familyCode": "DG015", "familyName": "DG015 180G纯棉T恤",
|
||||
"sizes": [...], "colors": [...],
|
||||
"printCounts": ["单面印花", "双面印花"], "crafts": ["烫画", "直喷", "不打印"], "logistics": ["包邮", "不包邮"],
|
||||
"printCounts": ["单面印花", "双面印花"], "crafts": ["烫画", "直喷"], "logistics": ["包邮", "不包邮"],
|
||||
"sizeChart": { /* 并集 */ }, "packageSpecs": { /* 并集 */ },
|
||||
"priceMatrix": { /* rows 为 {sizeId, colorId, printCount, craft, logistics, price, manual, sources} */ },
|
||||
"minPrice": "29.5"
|
||||
@@ -156,8 +163,8 @@ curl -X POST /product-families/organize -H "$AUTH" # 后台「整理
|
||||
|
||||
矩阵维度来源是**链接级标签**（印花数量/印刷工艺/物流渠道三组；人工接管后按人工标签），
|
||||
不再用原始链接名的第 3 段（`craftLabel` 含「直喷单面/光板不打印」等噪声）。名称派生规则已
|
||||
覆盖裸「单面/双面」写法（如「直喷双面」→ 双面印花 + 直喷）。光板/不打印链接无印花面概念，
|
||||
矩阵中印花数量维回退「单面印花」占位。前端本地按五维联动 `priceMatrix` 即可实时算价
|
||||
覆盖裸「单面/双面」写法（如「直喷双面」→ 双面印花 + 直喷）。光板/不打印链接不进族、
|
||||
无印花面概念，不参与矩阵维度。前端本地按五维联动 `priceMatrix` 即可实时算价
|
||||
（设计 D4）。
|
||||
|
||||
**边界声明**：价格区间筛选（minPrice/maxPrice）仍作用于链接 `goodPrice`（族内任一链接命中即
|
||||
|
||||
@@ -73,7 +73,7 @@ apps/api/
|
||||
│ ├── tag-groups/ # 标签分组 CRUD（受 JWT 保护，含批量排序）
|
||||
│ ├── positions/ # 坑位 CRUD（受 JWT 保护）
|
||||
│ ├── origin-goods/ # SDS 原始商品快照（只读分页 + 配置状态树 + 链接级标签人工接管）
|
||||
│ ├── product-families/ # 产品族（SPU 层）：CRUD / auto-group（并入已有族优先，familyNameKey 族语义键）/ attachToMatchingFamily（单链接自动归族）/ consolidateFragments（碎片族合并）/ 成员管理 / 自定义成员 / 价格覆盖 / 重算 / 按链接名称派生标签（auto-tag-rules，含 热转印→烫画 别名）
|
||||
│ ├── product-families/ # 产品族（SPU 层）：CRUD / auto-group（并入已有族优先，familyNameKey 族语义键）/ attachToMatchingFamily（单链接自动归族）/ consolidateFragments（碎片族合并）/ 成员管理 / 自定义成员 / 价格覆盖 / 重算 / 按链接名称派生标签（auto-tag-rules，含 热转印→烫画 别名）。数据约定（2026-09-03 起）：光板/不打印链接不入族、矩阵不计算不打印工艺；auto-group/organize/人工改标签会把散链接回挂，运行前须排查（备份见 deploy/backups/20260903-noprint-removal/）
|
||||
│ ├── goods/ # 商品 CRUD + 批量优先级 + 批量创建 + 展示名规范化（品名 SKU，剥 ASCII 型号限定词，纯款号按 SDS 分类名补描述）
|
||||
│ ├── sync/ # SDS 同步：分类 / 商品 / 同步日志
|
||||
│ ├── public/ # 公开 API：分类树 / 国家 / 商品分页 / 商品详情
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
# No-Print Links Removal Fix Implementation Plan（纯数据修复，不改源代码）
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 「不打印/光板」链接移出商品族，SKU 矩阵不再出现「不打印」工艺（含其「单面印花」占位组合）；BRTF004（族 148）恢复烫画×单面印花矩阵。**用户明确：本修复不修改源代码，纯数据操作。**
|
||||
|
||||
**Background / Root cause（2026-09-03 诊断）:**
|
||||
|
||||
1. 「不打印×单面印花」来自 `family-recompute.service.ts` 的结构化占位规则（不打印链接无印花数量标签 → 占位单面印花）。占位逻辑在代码里，**但不需要改代码**：把不打印链接移出族后，占位分支对无成员的族不再生效，矩阵自然无该组合。
|
||||
2. 族 148 烫画消失根因：**陈旧物化矩阵**。族 148 两成员（964 光板不打印、965 烫画单面）均在族内、未下架、标签齐全；矩阵物化于 09-02 16:00（旧容器时期），09-03 02:05 新镜像部署后无任何事件触发重算。用**当前已部署的正确代码**重算即恢复烫画。
|
||||
3. 全库审计（141 个有活跃烫画成员的族）：除族 148 外全部健康（crafts 含烫画、printCounts 为单面或单面+双面）。无 craft=不打印 覆盖价，无 autoManaged=false 冻结族，无未归族烫画链接。
|
||||
|
||||
**最终数据修复面：**
|
||||
|
||||
| 族 | 移出的不打印成员链接 | 主链接修正 | 名下商品脱族 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 (DG001) | 166, 731, 859, 961 | 无需（primary=163 不变） | good 361 |
|
||||
| 2 (DG004) | 171, 749, 763, 852 | 无需（primary=167 不变） | — |
|
||||
| 63 (METP001) | 759 | 无需（primary=339 不变） | — |
|
||||
| 135 (PLJM030) | 760 | primary→NULL（移除后无剩余成员，族变空矩阵，公列表自然消失） | good 554 |
|
||||
| 148 (BRTF004) | 964 | primary→965（烫画链接承接） | good 359（good 360 承接公开代表行） |
|
||||
|
||||
**回流风险（不改代码的代价，需文档化 + 运行纪律）：**
|
||||
- `organize` / `POST /product-families/autoGroup`：会把 family_id=null 的链接按分类重新归族 → **不打印链接会回流**。运行前须先排查，或将来补代码守卫。
|
||||
- 人工编辑链接标签（`origin-goods.service.ts:184`）会触发 `attachToMatchingFamily` 把散链接挂回匹配族。
|
||||
- 同步钩子无回流风险（`sync.service.ts:690` 只对 familyId 非空的链接重算）。
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 备份（用户要求的风险回滚存档）
|
||||
|
||||
- [ ] `deploy/backups/20260903-noprint-removal/`：`pg_dump -Fc` 全库 + 受影响行 CSV（origin_goods 11 行改前 family_id、goods 3 行、product_families 5 行含 price_matrix 全量）+ `RESTORE.md` 逐表恢复命令；`pg_restore --list` 验证备份完整
|
||||
|
||||
### Task 2: 数据修复（单事务）
|
||||
|
||||
- [ ] `UPDATE origin_goods SET family_id=NULL` 11 条链接
|
||||
- [ ] `UPDATE goods SET family_id=NULL`（origin_good_id ∈ 859/760/964 且 family_id 非空）
|
||||
- [ ] 族 148 `primary_origin_good_id=965`；族 135 `primary_origin_good_id=NULL`
|
||||
- [ ] 提交前逐条核对影响行数 = 预期（11 / 3 / 1 / 1）
|
||||
|
||||
### Task 3: 容器内直调重算（用已部署代码，不重建镜像）
|
||||
|
||||
- [ ] `docker exec deploy-v2-api-1 node -e` 实例化 `FamilyRecomputeService(new PrismaClient())`，对族 1/2/63/135/148 依次 `recomputeFamily`
|
||||
|
||||
### Task 4: 验证
|
||||
|
||||
- [ ] SQL 终检：全库无 price_matrix 含「不打印」；族 148 矩阵 crafts=['烫画']、printCounts=['单面印花']、minPrice=烫画链接价（19）
|
||||
- [ ] `GET /public/goods?keyword=BRTF004`：一条代表行（good 360），价格 19
|
||||
- [ ] `GET /public/goods/148`：family 块 crafts 含烫画、printCounts=['单面印花']、无不打印
|
||||
- [ ] `GET /public/goods?keyword=PLJM030`：无结果（仅光板的族已隐去）
|
||||
|
||||
### Task 5: 文档与沉淀
|
||||
|
||||
- [ ] `docs/references/product-center.md`：不打印链接不参与族矩阵的数据约定 + 回流风险
|
||||
- [ ] `docs/references/structs.md` 同步
|
||||
- [ ] AGENTS.md 沉淀：①矩阵维度占位借用词表既有值导致语义硬伤（本次以数据收口：不打印链接不入族）②代码修复/重部署后物化 JSON 不会自愈——须显式触发全量重算（族 148 教训）③批量数据修复前 pg_dump+受影响行导出+RESTORE.md 三件套
|
||||
|
||||
### Task 6: 提交合并
|
||||
|
||||
- [ ] 本文档 + 文档更新提交 `bugfix/no-print-links-removal-yeuimu`，合并回 develop
|
||||
Reference in New Issue
Block a user