From 6418aa7302d2143412a8d19b6afb0a7b6c013ae7 Mon Sep 17 00:00:00 2001 From: yeuimu <2197651308@qq.com> Date: Fri, 28 Aug 2026 13:40:19 +0800 Subject: [PATCH] feat(api): public good detail family block behind gray-release flag --- apps/api/.env.example | 4 + apps/api/src/goods/goods.service.ts | 8 + .../product-families.service.ts | 14 +- .../src/public/dto/public-good-detail.dto.ts | 21 ++ .../src/public/public-family-block.spec.ts | 205 ++++++++++++++++++ apps/api/src/public/public.service.ts | 46 ++++ apps/api/src/sync/sync.service.ts | 5 + docs/references/product-center.md | 23 ++ docs/references/structs.md | 4 +- 9 files changed, 324 insertions(+), 6 deletions(-) create mode 100644 apps/api/src/public/public-family-block.spec.ts diff --git a/apps/api/.env.example b/apps/api/.env.example index 493372c..c9de2c5 100644 --- a/apps/api/.env.example +++ b/apps/api/.env.example @@ -18,3 +18,7 @@ CORS_ORIGINS=http://localhost:5173 THROTTLE_LIMIT=120 PORT=3001 + +# Gray release: expose product-family block (union size chart + 5-dim price matrix) +# in GET /public/goods/:goodId responses. Off = response shape identical to before. +PUBLIC_DETAIL_FROM_FAMILY=false diff --git a/apps/api/src/goods/goods.service.ts b/apps/api/src/goods/goods.service.ts index 0c9e850..c86c245 100644 --- a/apps/api/src/goods/goods.service.ts +++ b/apps/api/src/goods/goods.service.ts @@ -122,11 +122,17 @@ export class GoodsService { ); await this.ensureMergedOriginGoods(mergedIds); const result = await this.prisma.$transaction(async (tx) => { + // Good 的族是派生数据：主链接所属族 + const primary = await tx.originGood.findUnique({ + where: { id: BigInt(dto.originGoodId) }, + select: { familyId: true }, + }); const created = await tx.good.create({ data: { goodName: dto.goodName, goodImage: dto.goodImage, originGoodId: BigInt(dto.originGoodId), + familyId: primary?.familyId ?? null, countryId: BigInt(dto.countryId), categoryId: BigInt(dto.categoryId), positionId: dto.positionId === undefined ? null : BigInt(dto.positionId), @@ -217,6 +223,7 @@ export class GoodsService { const good = await tx.good.create({ data: { originGoodId: originGood.id, + familyId: family?.id ?? null, countryId: BigInt(dto.countryId), categoryId: BigInt(dto.categoryId), positionId: @@ -445,6 +452,7 @@ export class GoodsService { goodName: og.goodName ?? `Origin Good ${og.sdsGoodId}`, goodImage: og.goodImage, originGoodId: og.id, + familyId: og.familyId, countryId: BigInt(dto.countryId), categoryId: BigInt(dto.categoryId), positionId: dto.positionId === undefined ? null : BigInt(dto.positionId), diff --git a/apps/api/src/product-families/product-families.service.ts b/apps/api/src/product-families/product-families.service.ts index 7408f05..f624e06 100644 --- a/apps/api/src/product-families/product-families.service.ts +++ b/apps/api/src/product-families/product-families.service.ts @@ -221,6 +221,10 @@ export class ProductFamiliesService { where: { id: { in: removeIds }, familyId: id }, data: { familyId: null }, }); + await this.prisma.good.updateMany({ + where: { originGoodId: { in: removeIds }, familyId: id }, + data: { familyId: null }, + }); // 移除的是主链接（或主链接已不在族内）→ 落到剩余第一个成员 if (remaining > 0) { const stillPrimary = await this.prisma.originGood.count({ @@ -248,10 +252,12 @@ export class ProductFamiliesService { } if (dto.addOriginGoodIds?.length) { - await this.attachMembers( - id, - dto.addOriginGoodIds.map((v) => BigInt(v)), - ); + const addIds = dto.addOriginGoodIds.map((v) => BigInt(v)); + await this.attachMembers(id, addIds); + await this.prisma.good.updateMany({ + where: { originGoodId: { in: addIds } }, + data: { familyId: id }, + }); } await this.recompute.recomputeFamily(id); diff --git a/apps/api/src/public/dto/public-good-detail.dto.ts b/apps/api/src/public/dto/public-good-detail.dto.ts index 56df449..b9c764e 100644 --- a/apps/api/src/public/dto/public-good-detail.dto.ts +++ b/apps/api/src/public/dto/public-good-detail.dto.ts @@ -59,6 +59,27 @@ export class PublicGoodDetailDto extends PublicGoodDto { @ApiProperty({ nullable: true }) detailSyncedAt!: string | null; + + /** 灰度字段：PUBLIC_DETAIL_FROM_FAMILY=true 且主链接有所属族时输出，否则完全不含该键 */ + @ApiProperty({ + required: false, + nullable: true, + type: Object, + description: '产品族块：并集尺码表/包装规则 + 五维价格矩阵（尺码×颜色×工艺×物流）', + }) + family?: { + familyId: string; + familyCode: string | null; + familyName: string; + sizes: Array<{ key: string; name: string | null }>; + colors: Array<{ key: string; name: string | null; hex: string | null; imageUrl: string | null }>; + crafts: string[]; + logistics: string[]; + sizeChart: Record | null; + packageSpecs: Record | null; + priceMatrix: Record; + minPrice: string | null; + } | null; } export class PublicTagGroupFilterDto { diff --git a/apps/api/src/public/public-family-block.spec.ts b/apps/api/src/public/public-family-block.spec.ts new file mode 100644 index 0000000..78db062 --- /dev/null +++ b/apps/api/src/public/public-family-block.spec.ts @@ -0,0 +1,205 @@ +import { Test } from '@nestjs/testing'; +import { Prisma } from '@prisma/client'; +import { PublicService } from './public.service'; +import { PrismaService } from '../prisma/prisma.service'; +import { FamilyRecomputeService } from '../product-families/family-recompute.service'; + +/** + * 三期灰度族块集成测试：PUBLIC_DETAIL_FROM_FAMILY 开关两态行为、 + * 族块字段内容、Good.familyId 派生与成员移动联动。 + */ +describe('PublicService family block (PUBLIC_DETAIL_FROM_FAMILY)', () => { + let service: PublicService; + let prisma: PrismaService; + const stamp = Date.now(); + const createdOriginGoodIds: bigint[] = []; + const createdFamilyIds: bigint[] = []; + const createdGoodIds: bigint[] = []; + const createdCountryIds: bigint[] = []; + const createdCategoryIds: bigint[] = []; + const prevFlag = process.env.PUBLIC_DETAIL_FROM_FAMILY; + let sdsGoodId = ''; + let familyId = 0n; + + beforeAll(async () => { + const moduleRef = await Test.createTestingModule({ + providers: [PublicService, PrismaService], + }).compile(); + service = moduleRef.get(PublicService); + prisma = moduleRef.get(PrismaService); + await prisma.onModuleInit(); + + const country = await prisma.country.create({ + data: { countryName: `公开族国家-${stamp}` }, + }); + createdCountryIds.push(country.id); + const category = await prisma.category.create({ + data: { categoryName: `公开族分类-${stamp}` }, + }); + createdCategoryIds.push(category.id); + + // 族 + 主链接（带变体）+ Good + const og = await prisma.originGood.create({ + data: { + sdsGoodId: `pubfam-${stamp}`, + goodName: `美国（包邮）测试T恤-PF${stamp}-单面印花`, + goodPrice: new Prisma.Decimal(25), + craftLabel: '单面印花', + logisticsLabel: '包邮', + }, + }); + sdsGoodId = og.sdsGoodId; + createdOriginGoodIds.push(og.id); + await prisma.originGoodVariant.create({ + data: { + originGoodId: og.id, + sdsVariantId: 'pf-v1', + sku: `PF-${stamp}-S`, + sizeId: 'size_S', + sizeName: 'S', + colorId: 'color_blk', + colorName: '黑色', + price: new Prisma.Decimal(25), + }, + }); + const family = await prisma.productFamily.create({ + data: { familyName: `公开族-${stamp}`, familyCode: `PF${stamp}`, primaryOriginGoodId: og.id }, + }); + familyId = family.id; + createdFamilyIds.push(family.id); + await prisma.originGood.update({ where: { id: og.id }, data: { familyId: family.id } }); + await new FamilyRecomputeService(prisma).recomputeFamily(family.id); + + const good = await prisma.good.create({ + data: { + originGoodId: og.id, + familyId: family.id, + countryId: country.id, + categoryId: category.id, + goodName: `公开族商品-${stamp}`, + }, + }); + createdGoodIds.push(good.id); + }); + + afterAll(async () => { + process.env.PUBLIC_DETAIL_FROM_FAMILY = prevFlag; + await prisma.good.deleteMany({ where: { id: { in: createdGoodIds } } }); + await prisma.originGood.deleteMany({ where: { id: { in: createdOriginGoodIds } } }); + await prisma.productFamily.deleteMany({ where: { id: { in: createdFamilyIds } } }); + await prisma.country.deleteMany({ where: { id: { in: createdCountryIds } } }); + await prisma.category.deleteMany({ where: { id: { in: createdCategoryIds } } }); + await prisma.$disconnect(); + }); + + it('开关关闭：响应完全不含 family 键（与现状形状一致）', async () => { + process.env.PUBLIC_DETAIL_FROM_FAMILY = 'false'; + const detail = await service.getGood(sdsGoodId); + expect(detail.goodId).toBe(sdsGoodId); + expect('family' in detail).toBe(false); + }); + + it('开关开启：输出族块（物化矩阵 + 并集 + 起价）', async () => { + process.env.PUBLIC_DETAIL_FROM_FAMILY = 'true'; + const detail = await service.getGood(sdsGoodId); + expect(detail.family).not.toBeNull(); + expect(detail.family!.familyCode).toBe(`PF${stamp}`); + expect(detail.family!.familyId).toBe(familyId.toString()); + expect(detail.family!.crafts).toEqual(['单面印花']); + expect(detail.family!.logistics).toEqual(['包邮']); + expect(detail.family!.priceMatrix).toBeTruthy(); + expect(detail.family!.minPrice).toBe('25'); + // 旧字段保留（向后兼容） + expect(detail.variants.length).toBe(1); + expect(detail.sizeChart).toBeDefined(); + }); + + it('无族商品：开关开启也不含 family 键', async () => { + process.env.PUBLIC_DETAIL_FROM_FAMILY = 'true'; + const og2 = await prisma.originGood.create({ + data: { + sdsGoodId: `pubfam-2-${stamp}`, + goodName: `无族链接-${stamp}`, + goodPrice: new Prisma.Decimal(10), + }, + }); + createdOriginGoodIds.push(og2.id); + const good2 = await prisma.good.create({ + data: { + originGoodId: og2.id, + countryId: createdCountryIds[0], + categoryId: createdCategoryIds[0], + goodName: `无族商品-${stamp}`, + }, + }); + createdGoodIds.push(good2.id); + const detail = await service.getGood(`pubfam-2-${stamp}`); + expect('family' in detail).toBe(false); + }); +}); + +describe('Good familyId derivation', () => { + let prisma: PrismaService; + let familiesService: import('../product-families/product-families.service').ProductFamiliesService; + const stamp = Date.now(); + const ids = { originGood: [] as bigint[], family: [] as bigint[], good: [] as bigint[], country: [] as bigint[], category: [] as bigint[] }; + + beforeAll(async () => { + const moduleRef = await Test.createTestingModule({ + providers: [PrismaService], + }).compile(); + prisma = moduleRef.get(PrismaService); + await prisma.onModuleInit(); + familiesService = new (require('../product-families/product-families.service').ProductFamiliesService)( + prisma, + new FamilyRecomputeService(prisma), + ); + }); + + afterAll(async () => { + await prisma.good.deleteMany({ where: { id: { in: ids.good } } }); + await prisma.originGood.deleteMany({ where: { id: { in: ids.originGood } } }); + await prisma.productFamily.deleteMany({ where: { id: { in: ids.family } } }); + await prisma.country.deleteMany({ where: { id: { in: ids.country } } }); + await prisma.category.deleteMany({ where: { id: { in: ids.category } } }); + await prisma.$disconnect(); + }); + + it('updateMembers 移除/添加成员时，Good.familyId 联动', async () => { + const country = await prisma.country.create({ data: { countryName: `联动国家-${stamp}` } }); + ids.country.push(country.id); + const category = await prisma.category.create({ data: { categoryName: `联动分类-${stamp}` } }); + ids.category.push(category.id); + const og = await prisma.originGood.create({ + data: { sdsGoodId: `derive-${stamp}`, goodName: `联动链接-${stamp}` }, + }); + ids.originGood.push(og.id); + const family = await prisma.productFamily.create({ + data: { familyName: `联动族-${stamp}`, primaryOriginGoodId: og.id }, + }); + ids.family.push(family.id); + await prisma.originGood.update({ where: { id: og.id }, data: { familyId: family.id } }); + const good = await prisma.good.create({ + data: { + originGoodId: og.id, + familyId: family.id, + countryId: country.id, + categoryId: category.id, + goodName: `联动商品-${stamp}`, + }, + }); + ids.good.push(good.id); + + // 移出族 → Good.familyId 置空 + await familiesService.updateMembers(family.id, { removeOriginGoodIds: [og.id.toString()] }); + expect( + (await prisma.good.findUniqueOrThrow({ where: { id: good.id } })).familyId, + ).toBeNull(); + + // 重新挂回 → Good.familyId 回填 + await familiesService.updateMembers(family.id, { addOriginGoodIds: [og.id.toString()] }); + expect( + (await prisma.good.findUniqueOrThrow({ where: { id: good.id } })).familyId, + ).toBe(family.id); + }); +}); diff --git a/apps/api/src/public/public.service.ts b/apps/api/src/public/public.service.ts index 37e74ba..70397b5 100644 --- a/apps/api/src/public/public.service.ts +++ b/apps/api/src/public/public.service.ts @@ -32,6 +32,16 @@ const PUBLIC_GOOD_INCLUDE = { include: { detail: true, variants: { orderBy: [{ sortOrder: 'asc' as const }, { id: 'asc' as const }] }, + family: { + select: { + id: true, + familyCode: true, + familyName: true, + sizeChart: true, + packageSpecs: true, + priceMatrix: true, + }, + }, }, }, mergedOriginGoods: { @@ -402,6 +412,42 @@ export class PublicService { sortOrder: variant.sortOrder, })), detailSyncedAt: detail?.syncedAt.toISOString() ?? null, + ...this.familyBlock(good), + }; + } + + /** + * 灰度族块（设计 D4：零新增公开端点）：仅当 PUBLIC_DETAIL_FROM_FAMILY=true + * 且主链接有所属族时输出；数据全部来自 ProductFamily 的物化 JSON，无额外查询。 + */ + private familyBlock( + good: PublicGoodRow, + ): Pick | Record { + if (process.env.PUBLIC_DETAIL_FROM_FAMILY !== 'true') return {}; + const family = good.originGood.family; + if (!family || !family.priceMatrix) return {}; + const matrix = family.priceMatrix as { + 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: Array<{ price: string }>; + }; + const prices = matrix.rows.map((r) => Number(r.price)).filter((n) => Number.isFinite(n)); + return { + family: { + familyId: family.id.toString(), + familyCode: family.familyCode, + familyName: family.familyName, + sizes: matrix.sizes, + colors: matrix.colors, + crafts: matrix.crafts, + logistics: matrix.logistics, + sizeChart: (family.sizeChart as Record | null) ?? null, + packageSpecs: (family.packageSpecs as Record | null) ?? null, + priceMatrix: matrix as unknown as Record, + minPrice: prices.length ? String(Math.min(...prices)) : null, + }, }; } diff --git a/apps/api/src/sync/sync.service.ts b/apps/api/src/sync/sync.service.ts index c923f80..1bd4ee6 100644 --- a/apps/api/src/sync/sync.service.ts +++ b/apps/api/src/sync/sync.service.ts @@ -715,6 +715,11 @@ export class SyncService { where: { id: originGoodId }, data: { familyId }, }); + // Good 的族随主链接联动 + await this.prisma.good.updateMany({ + where: { originGoodId }, + data: { familyId }, + }); this.familyRecompute.enqueue(familyId); } else { await this.prisma.productFamily.update({ diff --git a/docs/references/product-center.md b/docs/references/product-center.md index c4d9b1d..458c56d 100644 --- a/docs/references/product-center.md +++ b/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` 开关、手动重算、 diff --git a/docs/references/structs.md b/docs/references/structs.md index 4d476c5..946b796 100644 --- a/docs/references/structs.md +++ b/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 |