546 lines
27 KiB
Markdown
546 lines
27 KiB
Markdown
# 产品族（SPU）合并 — 一期后端实施计划
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 在原产品库与 Good 之间落地 ProductFamily（产品族）层：链接名结构化解析、族 CRUD、自动建族、成员管理（含自定义商品）、价格推导矩阵 + 人工覆盖、同步钩子与回填脚本。
|
||
|
||
**Architecture:** `OriginGood` 保持纯 SDS 镜像不动；新增 `product-families` NestJS 模块（controller/service/DTO）+ 独立的 `FamilyRecomputeService`（并集与矩阵物化，可被同步钩子异步调用）。价格 = 成员变体按 (物流, 工艺) 归因的并集矩阵，`FamilyPriceOverride` 覆盖表按格改价。设计依据：`docs/superpowers/specs/2026-08-28-product-family-merge-design.md`。
|
||
|
||
**Tech Stack:** NestJS 10 + Prisma 5 + PostgreSQL + Jest（测试与现有 `*.spec.ts` 同构，mock PrismaService）。
|
||
|
||
**分期:** 本计划为一期后端。二期（admin 前端）、三期（公开读路径灰度 + Good.familyId）在一期合并后另出计划。
|
||
|
||
**环境基线（已就绪）:** `apps/api/.env` 已配置；依赖已安装；远程库漂移已修复（3 个迁移已对齐）；现有 15 套件 107 测试全绿。
|
||
|
||
---
|
||
|
||
## 文件结构总览
|
||
|
||
```
|
||
apps/api/
|
||
prisma/
|
||
schema.prisma # 修改：+ProductFamily/+FamilyPriceOverride/+OriginGood 解析列
|
||
migrations/<ts>_add_product_families/migration.sql
|
||
backfill-product-families.ts # 新建：解析回填+自动建族+全量重算脚本
|
||
src/
|
||
product-families/ # 新建模块
|
||
origin-name.parser.ts # 纯函数解析器（零依赖）
|
||
origin-name.parser.spec.ts
|
||
family-recompute.service.ts # 并集/矩阵物化核心
|
||
family-recompute.service.spec.ts
|
||
product-families.service.ts # CRUD/auto-group/members/overrides
|
||
product-families.service.spec.ts
|
||
product-families.controller.ts
|
||
product-families.module.ts
|
||
dto/ (create/patch/auto-group/members/overrides)
|
||
src/sync/sync.service.ts # 修改：upsertOriginGood 解析列；persistProductDetail 后钩子
|
||
src/origin-goods/origin-goods.service.ts # 修改：树叶子节点 + 族信息
|
||
src/goods/goods.service.ts # 修改：createCustom 扩展解析列与 familyId
|
||
src/app.module.ts # 修改：注册 ProductFamiliesModule
|
||
```
|
||
|
||
**约定（全程适用）:**
|
||
- 价格矩阵 JSON 的格子维度键：`sizeId = variant.sizeId ?? variant.sizeName`、`colorId = variant.colorId ?? variant.colorName`（无 id 用名称，两者皆空则该变体不可归格，跳过）。
|
||
- Decimal 一律 `toString()` 后入 JSON。
|
||
- Prisma JSON 写入用 `value ?? Prisma.DbNull` 惯例（与 `persistProductDetail` 一致）。
|
||
- 每个 Task 完成 = 测试绿 + conventional commit。
|
||
|
||
---
|
||
|
||
### Task 1: 链接名解析器（纯函数，TDD）
|
||
|
||
**Files:**
|
||
- Create: `apps/api/src/product-families/origin-name.parser.ts`
|
||
- Test: `apps/api/src/product-families/origin-name.parser.spec.ts`
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
```ts
|
||
// origin-name.parser.spec.ts
|
||
import { parseOriginName, originGroupKey } from './origin-name.parser';
|
||
|
||
describe('parseOriginName', () => {
|
||
it('解析完整四段名（含仓库）', () => {
|
||
expect(parseOriginName('美国（不包邮）240g涤纶休闲短裤-DG206-单面印花-美西洛杉矶一仓')).toEqual({
|
||
country: '美国', logisticsLabel: '不包邮', productName: '240g涤纶休闲短裤',
|
||
skuCode: 'DG206', craftLabel: '单面印花', warehouseLabel: '美西洛杉矶一仓',
|
||
});
|
||
});
|
||
it('解析三段名（无仓库）', () => {
|
||
expect(parseOriginName('墨西哥（不包邮）180g纯棉女装修身T恤-METP001-单面印花')).toEqual({
|
||
country: '墨西哥', logisticsLabel: '不包邮', productName: '180g纯棉女装修身T恤',
|
||
skuCode: 'METP001', craftLabel: '单面印花', warehouseLabel: null,
|
||
});
|
||
});
|
||
it('物流备注含星号等符号原样保留', () => {
|
||
const r = parseOriginName('波兰（包邮*运费订单结算时支付）250g男女同款抓毛圆领卫衣-PLHM002-双面印花');
|
||
expect(r.logisticsLabel).toBe('包邮*运费订单结算时支付');
|
||
expect(r.skuCode).toBe('PLHM002');
|
||
});
|
||
it('半角括号也能解析', () => {
|
||
const r = parseOriginName('美国(包邮)T恤-DG001-单面印花');
|
||
expect(r.country).toBe('美国'); expect(r.logisticsLabel).toBe('包邮'); expect(r.productName).toBe('T恤');
|
||
});
|
||
it('段1无括号时 country=整段、物流为空', () => {
|
||
const r = parseOriginName('美国T恤-DG001-单面印花');
|
||
expect(r.country).toBe('美国T恤'); expect(r.logisticsLabel).toBeNull(); expect(r.productName).toBeNull();
|
||
});
|
||
it('两段名：只解析国家/物流/品名/SKU', () => {
|
||
const r = parseOriginName('美国（包邮）T恤-DG001');
|
||
expect(r.skuCode).toBe('DG001'); expect(r.craftLabel).toBeNull(); expect(r.warehouseLabel).toBeNull();
|
||
});
|
||
it('一段名/空值/_null 安全', () => {
|
||
expect(parseOriginName('随便一个名字').skuCode).toBeNull();
|
||
expect(parseOriginName(null).country).toBeNull();
|
||
expect(parseOriginName('').country).toBeNull();
|
||
});
|
||
it('段前后空格被 trim', () => {
|
||
const r = parseOriginName('美国（包邮） T恤 - DG001 - 单面印花');
|
||
expect(r.skuCode).toBe('DG001'); expect(r.craftLabel).toBe('单面印花'); expect(r.productName).toBe('T恤');
|
||
});
|
||
});
|
||
|
||
describe('originGroupKey', () => {
|
||
it('与 admin truncateToProcess 语义一致：前3段、物流差异导致不同组', () => {
|
||
expect(originGroupKey('美国（包邮）T恤-DG001-单面印花-美西一仓')).toBe('美国（包邮）T恤-DG001-单面印花');
|
||
expect(originGroupKey('美国（不包邮）T恤-DG001-单面印花')).not.toBe(originGroupKey('美国（包邮）T恤-DG001-单面印花'));
|
||
});
|
||
it('空名返回空串', () => expect(originGroupKey(null)).toBe(''));
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 运行确认失败**
|
||
|
||
Run: `cd apps/api && npx jest origin-name.parser --silent`
|
||
Expected: FAIL（模块不存在）
|
||
|
||
- [ ] **Step 3: 最小实现**
|
||
|
||
```ts
|
||
// origin-name.parser.ts
|
||
export interface ParsedOriginName {
|
||
country: string | null;
|
||
logisticsLabel: string | null;
|
||
productName: string | null;
|
||
skuCode: string | null;
|
||
craftLabel: string | null;
|
||
warehouseLabel: string | null;
|
||
}
|
||
|
||
const FULLWIDTH = { open: '（', close: '）' };
|
||
|
||
function splitSegment1(seg: string): Pick<ParsedOriginName, 'country' | 'logisticsLabel' | 'productName'> {
|
||
const full = seg.indexOf(FULLWIDTH.open);
|
||
if (full >= 0) {
|
||
const close = seg.indexOf(FULLWIDTH.close, full);
|
||
if (close > full) {
|
||
return {
|
||
country: seg.slice(0, full).trim() || null,
|
||
logisticsLabel: seg.slice(full + 1, close).trim() || null,
|
||
productName: seg.slice(close + 1).trim() || null,
|
||
};
|
||
}
|
||
}
|
||
const halfOpen = seg.indexOf('(');
|
||
if (halfOpen >= 0) {
|
||
const close = seg.indexOf(')', halfOpen);
|
||
if (close > halfOpen) {
|
||
return {
|
||
country: seg.slice(0, halfOpen).trim() || null,
|
||
logisticsLabel: seg.slice(halfOpen + 1, close).trim() || null,
|
||
productName: seg.slice(close + 1).trim() || null,
|
||
};
|
||
}
|
||
}
|
||
return { country: seg.trim() || null, logisticsLabel: null, productName: null };
|
||
}
|
||
|
||
export function parseOriginName(name: string | null | undefined): ParsedOriginName {
|
||
const empty: ParsedOriginName = { country: null, logisticsLabel: null, productName: null, skuCode: null, craftLabel: null, warehouseLabel: null };
|
||
if (!name) return empty;
|
||
const segs = name.split('-').map((s) => s.trim());
|
||
if (segs.length === 0 || segs[0] === '') return empty;
|
||
const head = splitSegment1(segs[0]);
|
||
return {
|
||
...head,
|
||
skuCode: segs[1] || null,
|
||
craftLabel: segs[2] || null,
|
||
warehouseLabel: segs.length > 3 ? segs.slice(3).join('-') : null,
|
||
};
|
||
}
|
||
|
||
/** 与 admin 端 truncateToProcess（KEEP_SEGMENTS=3）语义一致的分组键 */
|
||
export function originGroupKey(name: string | null | undefined): string {
|
||
if (!name) return '';
|
||
return name.split('-').slice(0, 3).join('-');
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 测试通过**
|
||
|
||
Run: `cd apps/api && npx jest origin-name.parser --silent`
|
||
Expected: PASS
|
||
|
||
- [ ] **Step 5: Commit** `feat(api): add origin good name parser`
|
||
|
||
---
|
||
|
||
### Task 2: Prisma Schema 与迁移
|
||
|
||
**Files:**
|
||
- Modify: `apps/api/prisma/schema.prisma`
|
||
|
||
- [ ] **Step 1: schema 增量**
|
||
|
||
在 `OriginGood` model（L23-44）中 `source` 字段后追加：
|
||
|
||
```prisma
|
||
familyId BigInt? @map("family_id")
|
||
skuCode String? @map("sku_code")
|
||
logisticsLabel String? @map("logistics_label")
|
||
craftLabel String? @map("craft_label")
|
||
warehouseLabel String? @map("warehouse_label")
|
||
```
|
||
|
||
relations 区追加 `family ProductFamily? @relation(fields: [familyId], references: [id], onDelete: SetNull, onUpdate: NoAction)`；`@@index` 区追加 `@@index([familyId])`、`@@index([skuCode])`、`@@index([logisticsLabel])`、`@@index([craftLabel])`。
|
||
|
||
在 `GoodOriginGood`（L248）之后新增两个 model：
|
||
|
||
```prisma
|
||
// ---------- Product Families (SPU layer over origin goods) ----------
|
||
model ProductFamily {
|
||
id BigInt @id @default(autoincrement()) @map("family_id")
|
||
familyCode String? @unique @map("family_code")
|
||
familyName String @map("family_name")
|
||
familyImage String? @map("family_image")
|
||
countryId BigInt? @map("country_id")
|
||
categoryId BigInt? @map("category_id")
|
||
primaryOriginGoodId BigInt? @map("primary_origin_good_id")
|
||
detail Json?
|
||
sizeChart Json? @map("size_chart")
|
||
packageSpecs Json? @map("package_specs")
|
||
priceMatrix Json? @map("price_matrix")
|
||
autoManaged Boolean @default(true) @map("auto_managed")
|
||
stale Boolean @default(false)
|
||
createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(6)
|
||
updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz(6)
|
||
|
||
originGoods OriginGood[]
|
||
priceOverrides FamilyPriceOverride[]
|
||
country Country? @relation(fields: [countryId], references: [id], onDelete: SetNull, onUpdate: NoAction)
|
||
category Category? @relation(fields: [categoryId], references: [id], onDelete: SetNull, onUpdate: NoAction)
|
||
|
||
@@index([countryId])
|
||
@@index([categoryId])
|
||
@@map("product_families")
|
||
}
|
||
|
||
model FamilyPriceOverride {
|
||
id BigInt @id @default(autoincrement()) @map("family_price_override_id")
|
||
familyId BigInt @map("family_id")
|
||
sizeId String @map("size_id")
|
||
colorId String @map("color_id")
|
||
craft String
|
||
logistics String
|
||
price Decimal @db.Decimal(12, 2)
|
||
note String?
|
||
createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(6)
|
||
updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz(6)
|
||
|
||
family ProductFamily @relation(fields: [familyId], references: [id], onDelete: Cascade, onUpdate: NoAction)
|
||
|
||
@@unique([familyId, sizeId, colorId, craft, logistics])
|
||
@@map("family_price_overrides")
|
||
}
|
||
```
|
||
|
||
`Country`/`Category` model 的 relations 区各加 `families ProductFamily[]`。注意 `primaryOriginGoodId` 刻意**不建 FK**（避免与 origin_goods 成环依赖，删除主链接时由服务层清理）。
|
||
|
||
- [ ] **Step 2: 生成并应用迁移**
|
||
|
||
Run: `cd apps/api && npx prisma migrate dev --name add_product_families && npx prisma generate`
|
||
Expected: 生成新 migration 目录，数据库应用成功，`npx jest --silent` 保持全绿。
|
||
|
||
- [ ] **Step 3: Commit** `feat(api): add product_families schema and migration`
|
||
|
||
---
|
||
|
||
### Task 3: FamilyRecomputeService（并集 + 矩阵物化，TDD 核心）
|
||
|
||
**Files:**
|
||
- Create: `apps/api/src/product-families/family-recompute.service.ts`
|
||
- Test: `apps/api/src/product-families/family-recompute.service.spec.ts`
|
||
|
||
**核心类型（导出，供 service/脚本复用）:**
|
||
|
||
```ts
|
||
export interface PriceMatrixSource { sdsGoodId: string; sdsVariantId: string; price: string }
|
||
export interface PriceMatrixRow {
|
||
sizeId: string; sizeName: string | null;
|
||
colorId: string; colorName: string | null;
|
||
craft: string; logistics: string;
|
||
price: string; manual: boolean;
|
||
sources: PriceMatrixSource[];
|
||
}
|
||
export interface PriceMatrix {
|
||
sizes: Array<{ key: string; name: string | null }>;
|
||
colors: Array<{ key: string; name: string | null; hex: string | null; imageUrl: string | null }>;
|
||
crafts: string[];
|
||
logistics: string[];
|
||
rows: PriceMatrixRow[];
|
||
}
|
||
export interface ChartSizeRow { sizeId?: string | null; sizeName?: string | null; measurements?: unknown; [k: string]: unknown }
|
||
export interface ChartLike { columns?: unknown; rows?: ChartSizeRow[] }
|
||
```
|
||
|
||
**行为规格（测试逐条覆盖）:**
|
||
|
||
1. `unionCharts(charts: Array<{ rows: ChartSizeRow[] }>): ChartSizeRow[]` — 按 `sizeName ?? sizeId` 对齐取并集；冲突时按“提供尺码数最多的成员优先，其次主链接”裁决（成员排序：rows 数 desc → isPrimary desc → id asc）。
|
||
2. `derivePriceMatrix(members, overrides)` — 规则：
|
||
- 仅统计 `craftLabel && logisticsLabel` 均非空成员的 `enabled=true、price!=null` 变体；
|
||
- 同格子多来源：`price` 取最低，`sources` 全保留；
|
||
- 覆盖命中（sizeId/colorId/craft/logistics 四键相等）→ `price=覆盖价, manual=true`；命中推导不存在的格子 → 新增行（`sources=[]`）；
|
||
- `sizes/colors` 选项 = 全体参与变体的键去重（含覆盖新增键）；`crafts/logistics` = 成员标签去重 ∪ 覆盖用到的值。
|
||
3. `recomputeFamily(familyId)`：加载族+成员（`delisted=false`，含 detail/variants/overrides）；`autoManaged=true` → 物化写回 `sizeChart/packageSpecs/priceMatrix` 且 `stale=false`；`autoManaged=false` → 仅 `stale=true` 不改物化字段；族不存在 → no-op。canonical `detail` 仅在为空时从主链接（`primaryOriginGoodId` ?? 第一个成员）初始化一次。
|
||
4. `enqueue(familyId)`：进程内 Map 去重，串行执行，异常记 logger.error 不抛出。
|
||
|
||
**测试样例（mock prisma，参照 `goods.service.spec.ts` 的 `mockPrisma` 模式）:**
|
||
|
||
```ts
|
||
const mkMember = (over: Partial<OriginGood> = {}): any => ({
|
||
id: 1n, sdsGoodId: 'a', craftLabel: '单面印花', logisticsLabel: '包邮', delisted: false,
|
||
detail: null, variants: [], ...over,
|
||
});
|
||
```
|
||
|
||
用例清单：
|
||
- 并集：`[{S,XL},{XL,XXL}]` → `[S,XL,XXL]` 顺序稳定（按首次出现序）；
|
||
- 冲突：成员A(rows=2)与B(rows=3)同尺码不同测量值 → 取B的行；
|
||
- 主链接优先于同 rows 数的非主链接；
|
||
- 矩阵：两个成员（同物流工艺不同仓库）同格子 25.00/24.50 → price=24.50、sources 两条；
|
||
- craft 或 logistics 为空的成员不参与矩阵；
|
||
- 覆盖：命中改价 manual=true；未命中格新增行；crafts/logistics 选项并入覆盖值；
|
||
- delisted 成员被 where 过滤（验证 findUnique include 的 where 参数）；
|
||
- autoManaged=false 只置 stale；
|
||
- detail 为空时从主链接初始化、非空不动。
|
||
|
||
Run: `cd apps/api && npx jest family-recompute --silent`
|
||
|
||
- [ ]Commit: `feat(api): add family recompute service with union and price matrix`
|
||
|
||
---
|
||
|
||
### Task 4: ProductFamilies 模块骨架（CRUD + 注册）
|
||
|
||
**Files:**
|
||
- Create: `src/product-families/product-families.module.ts`、`product-families.service.ts`、`product-families.controller.ts`、`dto/product-family.dto.ts`
|
||
- Modify: `src/app.module.ts`（imports 加 `ProductFamiliesModule`）
|
||
|
||
**DTO（class-validator，与现有 goods DTO 风格一致）:**
|
||
|
||
```ts
|
||
export class CreateProductFamilyDto {
|
||
@IsString() @IsNotEmpty() @MaxLength(200) familyName: string;
|
||
@IsOptional() @IsString() @MaxLength(100) familyCode?: string;
|
||
@IsOptional() @IsString() familyImage?: string;
|
||
@IsOptional() @IsBigInt() countryId?: bigint;
|
||
@IsOptional() @IsBigInt() categoryId?: bigint;
|
||
@IsOptional() @IsBigInt() primaryOriginGoodId?: bigint;
|
||
@IsOptional() @IsArray() originGoodIds?: bigint[]; // 建族时直接挂成员
|
||
}
|
||
export class PatchProductFamilyDto extends PartialType(CreateProductFamilyDto) {
|
||
@IsOptional() @IsBoolean() autoManaged?: boolean;
|
||
}
|
||
```
|
||
|
||
**Service 方法与语义:**
|
||
- `list({ keyword?, page, pageSize })` → `{ items, total, page, pageSize }`，items 含 `_count.originGoods`、`stale`、`autoManaged`、`familyCode`；keyword 匹配 familyName/familyCode contains。
|
||
- `create(dto)`：`familyCode` 冲突时自动追加 `-2`/`-3` 后缀（`ensureUniqueCode` 私有方法）；挂成员后 `recompute`。
|
||
- `detail(id)`：含成员（含解析列）、覆盖列表、物化矩阵摘要。
|
||
- `patch(id, dto)`：仅 canonical 字段 + autoManaged + primaryOriginGoodId；改 primary 后 recompute。
|
||
- BigInt 序列化沿用现有模式（查询结果直接返回，序列化时 `JSON.stringify` 需 `(BigInt.prototype as any).toJSON` 已有全局处理则复用；无则在返回前 `JSON.parse(JSON.stringify(x, (_, v) => typeof v === 'bigint' ? v.toString() : v))`）。
|
||
|
||
**Controller 路由（JWT 默认保护，无需额外装饰）:**
|
||
|
||
```ts
|
||
@Controller('product-families')
|
||
export class ProductFamiliesController {
|
||
@Get() list(@Query() q)
|
||
@Post() create(@Body() dto)
|
||
@Get(':id') detail(@Param('id', ParseBigIntPipe) id: bigint)
|
||
@Patch(':id') patch(@Param('id', ParseBigIntPipe) id: bigint, @Body() dto)
|
||
}
|
||
```
|
||
|
||
测试：create 的 familyCode 去重后缀、list keyword 过滤、patch 不触碰物化字段。
|
||
Run: `cd apps/api && npx jest product-families.service --silent`
|
||
|
||
- [ ]Commit: `feat(api): product families module skeleton with CRUD`
|
||
|
||
---
|
||
|
||
### Task 5: 自动建族 auto-group（预览 + 应用）
|
||
|
||
**Files:**
|
||
- Modify: `src/product-families/product-families.service.ts`、`product-families.controller.ts`、`dto/product-family.dto.ts`
|
||
|
||
**语义:**
|
||
- `POST /product-families/auto-group` body `{ apply?: boolean }`。
|
||
- 候选 = `source=SDS, delisted=false, familyId=null` 的 OriginGood，按 `originGroupKey(goodName)` 分组（空键丢弃）；组内 ≥1 条即可成族。
|
||
- 预览返回 `{ groups: [{ groupKey, familyName, familyCode, memberCount, sampleNames: string[] }] }`，`familyName=parse.productName ?? seg1`、`familyCode=parse.skuCode`。
|
||
- `apply=true`：每组 create（Code 冲突走 `ensureUniqueCode`）+ 挂成员 + 逐族 recompute；跳过组内成员已全部有族的组（防止重复建族）。
|
||
- 幂等：重复调用 apply 不产生重复族（候选 familyId=null 过滤保证）。
|
||
|
||
测试：分组正确性（物流不同不同组）、空键丢弃、apply 幂等、preview 不写库。
|
||
|
||
- [ ]Commit: `feat(api): family auto-group preview and apply`
|
||
|
||
---
|
||
|
||
### Task 6: 成员管理 + 自定义成员
|
||
|
||
**Files:**
|
||
- Modify: `product-families.service.ts`、`product-families.controller.ts`、`dto/product-family.dto.ts`
|
||
|
||
**语义:**
|
||
- `POST /:id/members` body `{ addOriginGoodIds?: bigint[], removeOriginGoodIds?: bigint[] }`：
|
||
- add：校验 OriginGood 存在；成员变更后 recompute；
|
||
- remove：从族摘除（`familyId=null`）；若移除的是 `primaryOriginGoodId` → 自动落到剩余第一个成员并置告警字段（实现：primary 置 null，recompute 用第一个成员兜底）。
|
||
- `POST /:id/members/custom` body：
|
||
|
||
```ts
|
||
export class CreateCustomMemberDto {
|
||
@IsString() @IsNotEmpty() goodName: string;
|
||
@IsOptional() @IsString() goodImage?: string;
|
||
@IsString() @IsNotEmpty() logisticsLabel: string; // 必填：矩阵归因
|
||
@IsString() @IsNotEmpty() craftLabel: string; // 必填：矩阵归因
|
||
@IsOptional() @IsString() skuCode?: string;
|
||
@IsOptional() @IsString() warehouseLabel?: string;
|
||
@IsArray() @ValidateNested({ each: true }) @Type(() => CustomVariantDto)
|
||
variants: CustomVariantDto[]; // 至少1条
|
||
@IsOptional() @IsObject() detail?: { sizeChart?: object; packageSpecs?: object; [k: string]: unknown };
|
||
}
|
||
export class CustomVariantDto {
|
||
@IsString() sku: string;
|
||
@IsOptional() @IsString() sizeId?: string; @IsOptional() @IsString() sizeName?: string;
|
||
@IsOptional() @IsString() colorId?: string; @IsOptional() @IsString() colorName?: string;
|
||
@IsOptional() @IsString() colorHex?: string; @IsOptional() @IsString() imageUrl?: string;
|
||
@IsNumber() @Min(0.01) price: number;
|
||
}
|
||
```
|
||
|
||
- 创建 `OriginGood { source: CUSTOM, sdsGoodId: 'custom-'+randomUUID(), familyId:族id, 解析列=dto }` + variants + 可选 `OriginGoodDetail{sizeChart, packageSpecs}`；成功后 recompute。
|
||
- CUSTOM 成员在 recompute 中与 SDS 同权（读其变体价格），重算永不写其变体/详情。
|
||
|
||
测试：成员增删触发 recompute、移除主链接的 primary 兜底、custom 成员创建字段落库（sdsGoodId 前缀 custom-、解析列来自 dto）、recompute 计入 custom 变体。
|
||
|
||
- [ ]Commit: `feat(api): family member management and custom members`
|
||
|
||
---
|
||
|
||
### Task 7: 价格覆盖表
|
||
|
||
**Files:**
|
||
- Modify: `product-families.service.ts`、`product-families.controller.ts`、`dto/product-family.dto.ts`
|
||
|
||
**语义:**
|
||
- `GET /:id/price-overrides` → `{ items: [...override, derivedPrice: string|null, diff: string|null] }`（对照推导价与差额，便于 admin 展示）。
|
||
- `PUT /:id/price-overrides` body `{ items: [{ sizeId, colorId, craft, logistics, price, note? }] }`：批量 upsert（`@@unique` 五键）；写后 recompute。
|
||
- `DELETE /:id/price-overrides` body `{ cells: [{ sizeId, colorId, craft, logistics }] }`：删覆盖恢复推导价，recompute。
|
||
- 校验：`price > 0`；四维度键必须 ∈ 族当前矩阵选项（`priceMatrix.sizes/colors/crafts/logistics`），否则 400（错误信息列出非法键）。
|
||
- **边界**：族尚未物化（priceMatrix 为 null，如刚建族未 recompute）→ 先 recompute 再校验。
|
||
|
||
测试：upsert 幂等、非法维度键 400、删除后恢复推导价、覆盖后矩阵行 manual=true、derivedPrice/diff 计算。
|
||
|
||
- [ ]Commit: `feat(api): family price overrides endpoints`
|
||
|
||
---
|
||
|
||
### Task 8: 手动重算端点 + 同步钩子 + 新链接自动挂族
|
||
|
||
**Files:**
|
||
- Modify: `product-families.controller.ts`（`POST /:id/recompute`）
|
||
- Modify: `src/sync/sync.service.ts`:
|
||
- `upsertOriginGood`（L686-742）：`goodName` 解析后把 `skuCode/logisticsLabel/craftLabel/warehouseLabel` 并入 create/update data（字段级：解析结果全量覆盖，空值也写 null，保持镜像纯度）；
|
||
- `upsertOriginGood` 新插入（`!existing`）时尝试**自动挂族**：按 `originGroupKey(goodName)` 找同键已有族的成员 → 唯一族：`autoManaged=true` 直接挂+enqueue，`false` 只置 `stale=true`；多族/零族：跳过（留给管理员）；
|
||
- `persistProductDetail`（L606-659）事务成功返回后：查 `originGood.familyId`，非空则 `familyRecompute.enqueue(familyId)`。
|
||
- `SyncModule` imports `ProductFamiliesModule`（导出 `FamilyRecomputeService`）；`SyncService` 构造注入。
|
||
- 循环依赖防护：`ProductFamiliesModule` **不** import `SyncModule`。
|
||
|
||
测试：upsert data 含解析列、新链接唯一族命中挂载、多族不挂、persist 后 enqueue 被调用（spy）。
|
||
|
||
- [ ]Commit: `feat(api): sync hooks for parsing, auto-attach and family recompute`
|
||
|
||
---
|
||
|
||
### Task 9: 回填脚本（解析 → 自动建族 → 全量重算）
|
||
|
||
**Files:**
|
||
- Create: `apps/api/prisma/backfill-product-families.ts`（package.json 加 script `"backfill:product-families": "ts-node prisma/backfill-product-families.ts"`）
|
||
|
||
**语义（与 auto-group 复用 service，脚本只做编排）:**
|
||
1. 全量 SDS+CUSTOM OriginGood 回填四解析列（`prisma.$transaction` 分批 100 条 update）；
|
||
2. 调 `autoGroup({ apply: true })`（此时 familyId 全 null，等价全量建族；CUSTOM 单条成族、code 取 skuCode ?? `CUSTOM-<id>`）；
|
||
3. 遍历所有族逐个 `recomputeFamily`，输出统计 `{ parsed, unparsable, familiesCreated, recomputed }` 与不可解析清单；
|
||
4. 幂等：重复执行时步骤1无变化、步骤2候选为空、步骤3重算结果相同。
|
||
|
||
Run（真实库执行一次）: `cd apps/api && pnpm backfill:product-families`
|
||
Expected: 约 544 条解析、>90% 成族、0 报错。
|
||
|
||
- [ ]Commit: `feat(api): product families backfill script`
|
||
|
||
---
|
||
|
||
### Task 10: origin-goods 树接入族信息
|
||
|
||
**Files:**
|
||
- Modify: `src/origin-goods/origin-goods.service.ts`（`getTree` L116 起）
|
||
|
||
**语义（最小增量，不破坏现有响应形状）:**
|
||
- `findMany originGoods` 的 include 增加 `family: { select: { id: true, familyName: true, familyCode: true, stale: true, autoManaged: true } }`；
|
||
- 树叶子节点 payload 增加 `familyId: string | null`、`familyName: string | null`、`familyCode: string | null` 字段（沿用该文件现有的叶子映射处，逐字段展开；BigInt → string 与现有一致）；
|
||
- 类型 `OriginGoodsTreeResponse` 相应扩展（该文件内或 dto 文件内的 interface）。
|
||
|
||
测试：叶子包含族字段、无族时为 null。
|
||
|
||
- [ ]Commit: `feat(api): expose family info in origin goods tree`
|
||
|
||
---
|
||
|
||
### Task 11: goods.service createCustom 扩展
|
||
|
||
**Files:**
|
||
- Modify: `src/goods/goods.service.ts`（`createCustom` L174-221）、`src/goods/dto/`（对应 create-custom DTO）
|
||
|
||
**语义:**
|
||
- `POST /goods/custom` 请求体可选新增：`logisticsLabel/craftLabel/skuCode/warehouseLabel/familyId`；
|
||
- 有 `familyId` → 创建的 CUSTOM OriginGood 直接入族（校验族存在，404 否则）并 enqueue recompute；
|
||
- 无 `familyId` → 维持现状（独立 CUSTOM 商品，familyId=null，后续可被挂族或运行回填脚本时单条成族）；
|
||
- 现有调用方不传新字段 → 行为完全不变（回归红线）。
|
||
|
||
测试：带 familyId 创建入族、不带时与旧路径一致（现有 spec 全绿即证）。
|
||
|
||
- [ ]Commit: `feat(api): custom goods support family attribution`
|
||
|
||
---
|
||
|
||
### Task 12: 文档更新 + 全量验证
|
||
|
||
**Files:**
|
||
- Modify: `docs/references/structs.md`（新模块/新表/新端点）、`docs/references/product-center.md`（族概念与端点用法示例）、`README.md`（backfill 命令）
|
||
- Modify: `docs/references/authority-matrix-ui.md`（product-families 读写权限行）
|
||
|
||
- [ ] **Step 1:** `cd apps/api && npx jest --silent` 全绿（现有 107 + 新增全部）。
|
||
- [ ] **Step 2:** `pnpm -r build` 通过（api/admin/website 均编译）。
|
||
- [ ] **Step 3:** 启动 `pnpm --filter @inkreach/api dev`，Swagger `/api/docs` 冒烟：auto-group 预览 → 应用 → 族详情含矩阵 → 覆盖改价 → 重算。
|
||
- [ ] **Step 4:** 遵循 verification-before-completion 技能自查。
|
||
- [ ]Commit: `docs: update references for product families`
|
||
|
||
---
|
||
|
||
## Self-Review 记录
|
||
|
||
- **Spec 覆盖:** §5.1/5.2/5.5/5.6 数据模型→Task 2；§6 解析→Task 1/8/9；§7 并集→Task 3；§8 价格→Task 3/7；§9 同步联动→Task 8；§10.1 端点→Task 4-8、10、11；§12 迁移→Task 2/9。三期范围（公开读路径/Good.familyId/good_origin_goods 废弃）不在本计划，已声明。
|
||
- **占位符:** 无 TBD/TODO；核心算法任务（1/3/5/6/7）含完整测试规格与代码。
|
||
- **类型一致:** `PriceMatrix/PriceMatrixRow` 在 Task 3 定义、Task 7 校验引用同一类型；`ensureUniqueCode` 在 Task 4 定义、Task 5 复用；`enqueue/recomputeFamily` 在 Task 3 定义、Task 6/8/9/11 复用。
|