148 lines
9.6 KiB
Markdown
148 lines
9.6 KiB
Markdown
# 产品族二期（admin 前端）实施计划
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** admin 后台落地产品族管理界面：新增「产品族」标签页（列表/详情/成员管理/自定义成员/人工改价/自动成族），GoodsView 原产品树接入族信息。
|
||
|
||
**Architecture:** 新建 `views/product-family/` 目录按职责拆组件（不复制 GoodsView 巨型单文件模式）；API 走新增 `src/api/product-families.ts`；GoodsView 仅做两处增量（兄弟勾选按族匹配、树节点族徽标）。依赖一期后端 `/product-families/*` 端点（已上线 develop）。
|
||
|
||
**Tech Stack:** Vue 3 `<script setup>` + Element Plus（auto-import）+ vitest（纯逻辑 TDD；仓库无 @vue/test-utils，组件以 vue-tsc + vite build 验证）。
|
||
|
||
**范围约定:** Good 配置表单的 familyId 字段属三期（后端 `Good.familyId` 未上线），本期不做；现有 Good 级合并（mergedOriginGoodIds）保持原样。
|
||
|
||
---
|
||
|
||
### Task 1: 类型与 API client
|
||
|
||
**Files:**
|
||
- Modify: `apps/admin/src/types/index.ts`（OriginGoodsTreeNode + 族字段；新增 ProductFamily 系列）
|
||
- Create: `apps/admin/src/api/product-families.ts`
|
||
|
||
- [ ] types：`OriginGoodsTreeNode` 增加 `familyId: string | null; familyName: string | null; familyCode: string | null; familyStale: boolean | null`；新增：
|
||
|
||
```ts
|
||
export interface ProductFamilyMember {
|
||
id: string; sdsGoodId: string; goodName: string; goodImage: string | null
|
||
source: 'SDS' | 'CUSTOM'; delisted: boolean
|
||
skuCode: string | null; logisticsLabel: string | null; craftLabel: string | null; warehouseLabel: string | null
|
||
}
|
||
export interface FamilyPriceOverrideRow {
|
||
id: string; sizeId: string; colorId: string; craft: string; logistics: string
|
||
price: string; note: string | null; derivedPrice: string | null; diff: string | null
|
||
}
|
||
export interface ProductFamily {
|
||
id: string; familyCode: string | null; familyName: string; familyImage: string | null
|
||
countryId: string | null; categoryId: string | null; primaryOriginGoodId: string | null
|
||
autoManaged: boolean; stale: boolean
|
||
detail: Record<string, unknown> | null
|
||
sizeChart: { rows?: Array<Record<string, unknown>> } | null
|
||
packageSpecs: { rows?: Array<Record<string, unknown>> } | null
|
||
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: Array<{ sizeId: string; sizeName: string | null; colorId: string; colorName: string | null
|
||
craft: string; logistics: string; price: string; manual: boolean
|
||
sources: Array<{ sdsGoodId: string; sdsVariantId: string; price: string }> }>
|
||
} | null
|
||
originGoods: ProductFamilyMember[]
|
||
priceOverrides: FamilyPriceOverrideRow[]
|
||
_count: { originGoods: number; priceOverrides: number }
|
||
}
|
||
export interface AutoGroupPreviewGroup {
|
||
groupKey: string; familyName: string; familyCode: string | null
|
||
memberCount: number; sampleNames: string[]
|
||
}
|
||
export interface CustomMemberVariantInput { sku: string; sizeId?: string | null; sizeName?: string | null
|
||
colorId?: string | null; colorName?: string | null; colorHex?: string | null; imageUrl?: string | null; price: number }
|
||
```
|
||
|
||
- [ ] `src/api/product-families.ts`：
|
||
|
||
```ts
|
||
import request from './request'
|
||
import type { PaginatedResult, ProductFamily, AutoGroupPreviewGroup } from '@/types'
|
||
|
||
export const productFamiliesApi = {
|
||
list: (params: { keyword?: string; page?: number; pageSize?: number }) =>
|
||
request.get<any, PaginatedResult<ProductFamily>>('/product-families', { params }),
|
||
detail: (id: string) => request.get<any, ProductFamily>(`/product-families/${id}`),
|
||
create: (data: { familyName: string; familyCode?: string; familyImage?: string; originGoodIds?: string[]; primaryOriginGoodId?: string }) =>
|
||
request.post<any, ProductFamily>('/product-families', data),
|
||
patch: (id: string, data: Record<string, unknown>) =>
|
||
request.patch<any, ProductFamily>(`/product-families/${id}`, data),
|
||
autoGroup: (apply: boolean) =>
|
||
request.post<any, { applied: number; groups: AutoGroupPreviewGroup[] }>('/product-families/auto-group', { apply }),
|
||
updateMembers: (id: string, data: { addOriginGoodIds?: string[]; removeOriginGoodIds?: string[] }) =>
|
||
request.post<any, ProductFamily>(`/product-families/${id}/members`, data),
|
||
createCustomMember: (id: string, data: Record<string, unknown>) =>
|
||
request.post<any, unknown>(`/product-families/${id}/members/custom`, data),
|
||
recompute: (id: string) => request.post<any, ProductFamily>(`/product-families/${id}/recompute`),
|
||
listOverrides: (id: string) =>
|
||
request.get<any, { items: FamilyPriceOverrideRow[] }>(`/product-families/${id}/price-overrides`),
|
||
putOverrides: (id: string, items: Array<Record<string, unknown>>) =>
|
||
request.put<any, { items: FamilyPriceOverrideRow[] }>(`/product-families/${id}/price-overrides`, { items }),
|
||
deleteOverrides: (id: string, cells: Array<Record<string, unknown>>) =>
|
||
request.delete<any, { items: FamilyPriceOverrideRow[] }>(`/product-families/${id}/price-overrides`, { data: { cells } }),
|
||
}
|
||
```
|
||
|
||
（`request` 封装与 goods.ts 一致；delete 带 body 用 `{ data }`。）
|
||
|
||
- [ ] `pnpm --filter @inkreach/admin test` 通过（现有 spec 不受影响）→ Commit `feat(admin): product families api client and types`
|
||
|
||
### Task 2: 族匹配工具（TDD）
|
||
|
||
**Files:**
|
||
- Create: `apps/admin/src/utils/family-match.ts` + `family-match.spec.ts`
|
||
|
||
- [ ] 先写失败测试：`sameFamily(a, b)` —— 两节点 `familyId` 相等且非空 → true；任一 familyId 为空 → 回退 `sameOriginGroup(goodName)`；均空 false。
|
||
- [ ] 实现（3 行逻辑，复用 `sameOriginGroup`）。
|
||
- [ ] 测试通过 → Commit `feat(admin): family match util`
|
||
|
||
### Task 3: 产品族标签页组件
|
||
|
||
**Files:**
|
||
- Create: `apps/admin/src/views/product-family/FamilyView.vue`
|
||
- Create: `apps/admin/src/views/product-family/FamilyDetailDrawer.vue`
|
||
- Create: `apps/admin/src/views/product-family/AutoGroupDialog.vue`
|
||
- Create: `apps/admin/src/views/product-family/PriceOverridePanel.vue`
|
||
- Create: `apps/admin/src/views/product-family/CustomMemberDialog.vue`
|
||
- Modify: `apps/admin/src/views/product-management/ProductManagementView.vue`（tabs 增加 `{ name: 'families', label: '产品族', comp: FamilyView }`，icon 用 `Files`）
|
||
|
||
- [ ] **FamilyView**：顶部工具栏（关键词搜索、`自动成族`按钮开 AutoGroupDialog、`新建族`简易弹窗）+ el-table（familyCode/familyName/成员数/覆盖数/autoManaged 标签/stale 红点/更新时间/操作列 `详情`）+ el-pagination；行点击开 FamilyDetailDrawer（`@reload` 重新拉列表）。
|
||
- [ ] **FamilyDetailDrawer**（el-drawer size 70%）：
|
||
- 头部：familyName/familyCode/stale 标记/autoManaged 开关（`patch`）/`重算`按钮（`recompute`）；
|
||
- canonical 编辑：名称/编码/主图（复用 ImageUpload）/主链接（成员下拉选择）→ `patch`；
|
||
- 成员表：goodName/物流/工艺/仓库/来源/操作`移除`（`updateMembers remove`）；
|
||
- 添加成员：输入 origin_good_id 列表（el-select remote 搜索用 `originGoodsApi.getOriginGoodsList` keyword）→ `updateMembers add`；
|
||
- `新建自定义成员`按钮开 CustomMemberDialog；`价格管理`折叠区嵌入 PriceOverridePanel；
|
||
- 矩阵摘要：sizes/crafts/logistics 数量 + 起价（rows 最低 price）。
|
||
- [ ] **AutoGroupDialog**：打开先 `autoGroup(false)` 预览（表格：族名/编码/成员数/示例名）；`确认建族`按钮调 `autoGroup(true)` 后 `@done` 刷新。
|
||
- [ ] **PriceOverridePanel**：按 (craft × logistics) el-tabs；表格行=尺码、列=颜色（或平铺行），单元格显示矩阵价 + manual 高亮 + 行内编辑（el-input-number）→ 失焦 `putOverrides` 单格；顶部已设覆盖列表（推导价/差额/删除恢复）。
|
||
- [ ] **CustomMemberDialog**：表单 goodName/goodImage/物流*/工艺*/skuCode/仓库 + 变体动态行（sku/sizeId/sizeName/colorId/colorName/price）→ `createCustomMember`。
|
||
- [ ] `pnpm --filter @inkreach/admin build`（vue-tsc + vite）通过。
|
||
- [ ] Commit `feat(admin): product family management tab`
|
||
|
||
### Task 4: GoodsView 接入族信息
|
||
|
||
**Files:**
|
||
- Modify: `apps/admin/src/views/goods/GoodsView.vue`
|
||
|
||
- [ ] L411 兄弟自动勾选：`sameOriginGroup(...)` 换成 `sameFamily(ogNode, s)`（familyId 优先、名称回退）——`collectSiblings` 收集的节点已带 familyId 字段（tree 接口已返回）。
|
||
- [ ] 右侧树节点 label：`familyCode` 存在时以 el-tag 小徽标展示在名称后；`familyStale` 时加橙点提示。
|
||
- [ ] 构建通过 + `pnpm --filter @inkreach/admin test` 全绿。
|
||
- [ ] Commit `feat(admin): goods view family badges and sibling matching`
|
||
|
||
### Task 5: 验证与文档
|
||
|
||
- [ ] `pnpm --filter @inkreach/admin test`、`pnpm --filter @inkreach/admin build`、`pnpm --filter @inkreach/api test` 全绿。
|
||
- [ ] 起后端 + admin dev，浏览器冒烟（登录 → 产品族 tab → 列表 → 详情 → 自动成族预览 → 改价）——如环境不可用则以 curl 走 vite 代理替代。
|
||
- [ ] 更新 `docs/references/structs.md`（admin 章节目录树 + 新页面）与 `docs/references/product-center.md`（后台操作路径）。
|
||
- [ ] Commit `docs: admin product family references`
|
||
|
||
## Self-Review
|
||
|
||
- 设计 §11.2 四组件全覆盖（FamilyList 并入 FamilyView 表格，粒度合并不改语义）；§11.3 两处增量落地（Good 表单 familyId 明确延后三期并在范围约定声明）；§11.4 client ✓。
|
||
- 组件无测试设施属仓库现状，以 vue-tsc/build 兜底并在计划头部声明；纯逻辑（family-match）走 TDD。
|