# Story 006.001: 管理后台父子商品配置功能

## Status
Draft

## Story
**As a** 系统管理员，
**I want** 能够在商品管理UI中配置父子商品关系，
**so that** 支持多规格商品管理和展示

## Acceptance Criteria
1. 在商品管理UI中添加spuId/spuName字段表单控件
2. 新增子商品关联选择器，支持选择已有商品作为子商品
3. 新增批量子商品创建功能，支持统一创建多个子商品规格
4. 父子商品关系展示和编辑界面
5. **验收标准**：管理员能成功配置父子商品关系

## Tasks / Subtasks
- [x] **分析现有商品管理UI结构** (AC: 1, 2, 3, 4)
  - [x] **已确认**：商品管理组件文件位置：`packages/goods-management-ui-mt/src/components/GoodsManagement.tsx`
  - [x] **发现**：当前表单中没有spuId/spuName字段，需要添加
  - [x] 分析现有商品表单结构（835行代码），确定spuId/spuName字段添加位置
  - [x] 检查现有商品列表和详情页的父子商品显示需求
  - [x] 分析多租户UI包的组件结构和依赖关系
  - [x] **发现**：API客户端使用单租户版本，需要更新为多租户版本

- [x] **验证商品Schema中的父子商品字段** (AC: 1)
  - [x] 检查现有Schema文件：`packages/goods-module-mt/src/schemas/goods.schema.mt.ts`
  - [x] **已确认**：spuId和spuName字段已存在（第87-94行，第200-207行，第279-286行）
  - [x] **已确认**：Schema字段定义符合父子商品需求：spuId默认0，spuName可选
  - [x] 检查其他Schema文件：`admin-goods.schema.mt.ts`、`user-goods.schema.mt.ts`、`public-goods.schema.mt.ts` 也包含相同字段

- [x] **修复API客户端使用多租户版本** (AC: 1, 2, 3, 4)
  - [x] 检查API客户端文件：`packages/goods-management-ui-mt/src/api/goodsClient.ts`
  - [x] **发现**：当前导入`@d8d/goods-module`的单租户版本`adminGoodsRoutes`
  - [x] 需要更新为导入多租户版本：`@d8d/goods-module-mt`的`adminGoodsRoutesMt`
  - [x] 更新客户端管理器类型定义
  - [x] 验证更新后的API调用正常工作

- [x] **在商品管理表单中添加spuId/spuName字段** (AC: 1)
  - [x] 在商品创建/编辑表单中添加spuId字段输入控件
  - [x] 在商品创建/编辑表单中添加spuName字段输入控件
  - [x] 添加字段说明：spuId=0表示父商品或单规格商品，spuId>0表示子商品
  - [x] 确保字段验证逻辑正确

- [x] **实现子商品关联选择器组件** (AC: 2)
  - [x] 创建子商品选择器组件，支持搜索和选择已有商品
  - [x] 添加租户过滤：只能选择同一租户下的商品
  - [x] 添加父子关系验证：不能选择自己作为父商品，不能循环引用
  - [x] 支持批量选择多个子商品

- [x] **实现批量子商品创建功能** (AC: 3)
  - [x] 创建批量规格创建表单，支持输入多个规格名称、价格、库存
  - [x] 实现批量创建逻辑：基于父商品信息创建多个子商品
  - [x] 添加事务处理确保批量创建的一致性
  - [x] 添加验证：规格名称不能重复，价格和库存必须有效

- [x] **实现父子商品关系展示界面** (AC: 4)
  - [x] 在商品详情页显示父子商品关系树
  - [x] 父商品显示子商品列表，子商品显示父商品信息
  - [x] 支持从父子商品关系树跳转到对应商品详情
  - [x] 添加父子商品关系编辑功能

- [x] **编写单元测试和集成测试** (AC: 1, 2, 3, 4, 5)
  - [x] 测试spuId/spuName字段表单验证
  - [x] 测试子商品关联选择器功能
  - [x] 测试批量子商品创建流程
  - [x] 测试父子商品关系展示和编辑
  - [x] 确保测试覆盖率 ≥ 80%

## Dev Notes

### 技术栈信息 [Source: architecture/tech-stack.md]
- **运行时**: Node.js 20.18.3
- **框架**: Hono 4.8.5 (Web框架和API路由，RPC类型安全)
- **前端框架**: React 19.1.0 (用户界面构建)
- **数据库**: PostgreSQL 17 (通过TypeORM进行数据持久化存储)
- **ORM**: TypeORM 0.3.25 (数据库操作抽象，实体管理)
- **样式**: Tailwind CSS 4.1.11 (原子化CSS框架)
- **状态管理**: React Query 5.83.0 (服务端状态管理)
- **测试框架**: Vitest 2.x (单元测试框架，更好的TypeORM支持)
- **API测试**: hono/testing (内置，API端点测试，更好的类型安全)

### 项目结构信息 [Source: architecture/source-tree.md]
- **包管理**: 使用pnpm workspace管理多包依赖关系
- **包架构层次**:
  - **基础设施层**: shared-types → shared-utils → shared-crud
  - **测试基础设施**: shared-test-util
  - **业务模块层**: 多租户模块包（-mt后缀），支持租户数据隔离
  - **应用层**: server (重构后)
- **多租户架构**:
  - **包复制策略**: 基于Epic-007方案，通过复制单租户包创建多租户版本
  - **租户隔离**: 通过租户ID实现数据隔离，支持多租户部署
  - **后端包**: 10个多租户模块包，支持租户数据隔离
- **文件命名**: 保持现有kebab-case命名约定
- **模块化架构**: 采用分层包结构，支持按需安装和独立开发

### 编码标准 [Source: architecture/coding-standards.md]
- **代码风格**: TypeScript严格模式，一致的缩进和命名
- **测试位置**: `__tests__` 文件夹与源码并列（但实际使用`tests/`目录）
- **覆盖率目标**: 核心业务逻辑 > 80%
- **测试类型**: 单元测试、集成测试、E2E测试
- **现有API兼容性**: 确保测试不破坏现有API契约
- **数据库集成**: 使用测试数据库，避免污染生产数据

### 测试策略 [Source: architecture/testing-strategy.md]
- **单元测试范围**: 单个函数、类或组件，验证独立单元的正确性
- **单元测试位置**: `packages/*-module/tests/unit/**/*.test.ts`
- **集成测试范围**: 多个组件/服务协作，验证模块间集成和交互
- **集成测试位置**: `packages/*-module/tests/integration/**/*.test.ts`
- **测试框架**: Vitest + Testing Library + hono/testing + shared-test-util
- **单元测试覆盖率目标**: ≥ 80%
- **集成测试覆盖率目标**: ≥ 60%
- **测试执行频率**: 单元测试每次代码变更，集成测试每次API变更

### 数据模型设计 [Source: docs/prd/epic-006-parent-child-goods-multi-spec-support.md#数据库层面]
**现有商品实体结构** (已确认):
- `spuId`字段: 类型`int unsigned`，默认0，注释"主商品ID"
- `spuName`字段: 类型`varchar(255)`，可空，注释"主商品名称"
- **父子商品定义**:
  - `spuId = 0`: 表示父商品或单规格商品
  - `spuId > 0`: 表示子商品，值为父商品的ID
  - `spuName`: 存储父商品名称，便于展示

**文件位置**:
- 商品实体文件: `packages/goods-module-mt/src/entities/goods.entity.mt.ts` (第75-79行)
- 商品Schema文件: `packages/goods-module-mt/src/schemas/goods.schema.mt.ts` (第87-94行，第200-207行，第279-286行)

### API设计 [Source: docs/prd/epic-006-parent-child-goods-multi-spec-support.md#API设计]
**现有商品API路由**:
- 管理员商品路由: `adminGoodsRoutesMt` (`packages/goods-module-mt/src/routes/admin-goods-routes.mt.ts`)
- 公共商品路由: `publicGoodsRoutesMt` (需要确认文件位置)
- 用户商品路由: `userGoodsRoutesMt` (`packages/goods-module-mt/src/routes/user-goods-routes.mt.ts`)

**需要新增的API端点** (在故事2中实现):
- `GET /api/v1/goods/:id/children` - 获取指定父商品的子商品列表
- 商品详情API需要增强：父商品返回详情+子商品列表，子商品返回详情+父商品信息

### 组件架构 [Source: architecture/source-tree.md#多租户包架构]
**多租户前端组件架构**:
- **多租户商品管理UI包**: `packages/goods-management-ui-mt/` (`@d8d/goods-management-ui-mt`)
- **主要组件**: `src/components/GoodsManagement.tsx`
- **共享UI组件**: `@d8d/shared-ui-components` (shadcn/ui组件库，46+基础组件)
- **技术栈**: React 19.1.0 + TypeScript + @tanstack/react-query + shadcn/ui + Tailwind CSS
- **API客户端**: 使用Hono Client RPC风格API调用
- **依赖管理**: 通过pnpm workspace管理包依赖关系

**多租户管理界面包架构** (基于Epic-007):
- **包复制策略**: 通过复制单租户包创建多租户版本
- **租户上下文管理**: 支持租户切换和数据隔离
- **前端包**: 10个多租户管理界面包，每个包对应一个业务模块
- **共享组件**: 使用`@d8d/shared-ui-components`提供统一UI体验

### 文件位置和命名约定
- **商品管理组件**: `packages/goods-management-ui-mt/src/components/GoodsManagement.tsx` (多租户商品管理UI包)
- **商品表单**: 在`GoodsManagement.tsx`组件内实现，没有单独的表单组件
- **子商品选择器组件**: 建议创建`packages/goods-management-ui-mt/src/components/GoodsChildSelector.tsx`
- **批量规格创建组件**: 建议创建`packages/goods-management-ui-mt/src/components/BatchSpecCreator.tsx`
- **父子关系展示组件**: 建议创建`packages/goods-management-ui-mt/src/components/GoodsRelationshipTree.tsx`
- **API客户端**: `packages/goods-management-ui-mt/src/api/goodsClient.ts` (需要确认实际文件位置)

### 多租户实体命名模式
基于现有多租户模块观察：
- **实体类名**: 以`Mt`结尾（如`GoodsMt`）
- **表名**: 以`_mt`结尾（如`goods_mt`）
- **文件命名**: `*.mt.ts` 或 `*.entity.ts`
- **必须包含**: `tenant_id`字段用于租户隔离

### 技术约束
- **数据库**: 使用PostgreSQL 17，支持父子商品关系查询
- **租户隔离**: 所有操作必须包含tenantId过滤，父子商品必须在同一租户下
- **数据权限**: 管理员路由使用完整CRUD功能，不使用数据权限控制
- **事务处理**: 批量创建子商品必须使用数据库事务确保数据一致性
- **验证逻辑**: 父子商品关系需要验证，防止循环引用和无效关联

### 集成点
1. **商品模块集成**: 使用现有的`goods-module-mt`包，包含实体、Schema和服务
2. **文件模块集成**: 商品图片使用`file-module-mt`包的文件实体
3. **租户模块集成**: 所有操作需要租户ID过滤
4. **UI组件集成**: 使用现有的shadcn/ui组件库构建界面

### 测试要求
- **单元测试**: 测试表单验证、选择器逻辑、批量创建逻辑
- **集成测试**: 测试完整的父子商品配置流程
- **边界条件测试**: 测试无效spuId、循环引用、跨租户选择等场景
- **覆盖率**: 核心业务逻辑必须达到80%以上单元测试覆盖率

### 项目结构注意事项
- 需要遵循现有的多租户包架构模式
- 前端组件应该创建在多租户商品管理UI包的components目录下
- 需要正确配置React Query用于数据获取和状态管理
- 使用现有的shadcn/ui组件库保持UI一致性
- **注意**: 父子商品关系展示需要查询商品列表，可能需要增强现有商品服务
- **多租户UI包集成**: 组件需要支持租户上下文管理

### 实际代码探索发现
**基于实际代码分析发现**:
1. **商品管理组件**: `packages/goods-management-ui-mt/src/components/GoodsManagement.tsx` (835行)
   - 表单使用React Hook Form + Zod验证
   - 当前表单**没有**spuId/spuName字段，需要添加
   - 表单包含：商品名称、价格、分类、供应商、商户、库存等字段
   - 使用`GoodsCategoryCascadeSelector`、`SupplierSelector`、`MerchantSelector`等选择器组件

2. **API客户端问题**: `packages/goods-management-ui-mt/src/api/goodsClient.ts`
   - 当前导入单租户版本：`import { adminGoodsRoutes } from '@d8d/goods-module'`
   - 需要改为多租户版本：`import { adminGoodsRoutesMt } from '@d8d/goods-module-mt'`
   - 使用单例模式的客户端管理器

3. **Schema验证**: 所有商品Schema文件都已包含spuId/spuName字段
   - `goods.schema.mt.ts`: 第87-94行，第200-207行，第279-286行
   - `admin-goods.schema.mt.ts`: 第88-90行，第202-204行
   - `user-goods.schema.mt.ts`: 第89-91行，第203-205行
   - `public-goods.schema.mt.ts`: 第90-92行

4. **商品服务**: `packages/goods-module-mt/src/services/goods.service.mt.ts`
   - 继承`GenericCrudService`，提供基础CRUD功能
   - 需要增强以支持父子商品查询

### 需要开发代理特别注意的事项
1. **API客户端修复**: 必须先修复API客户端使用多租户版本，否则父子商品功能无法正常工作
2. **表单字段添加**: spuId/spuName字段需要添加到创建和编辑表单中
3. **父子关系验证**: 需要添加业务逻辑验证（不能循环引用、必须在同一租户下等）
4. **批量创建事务**: 批量子商品创建需要事务处理确保数据一致性

## Testing
### 测试标准 [Source: architecture/testing-strategy.md]
- **测试文件位置**: `packages/goods-management-ui-mt/tests/` 目录下
- **单元测试位置**: `tests/unit/**/*.test.{ts,tsx}`
- **集成测试位置**: `tests/integration/**/*.test.{ts,tsx}`
- **测试框架**: Vitest + Testing Library + hono/testing + shared-test-util
- **覆盖率要求**: 单元测试 ≥ 80%，集成测试 ≥ 60%
- **测试模式**: 使用测试数据工厂模式，避免硬编码测试数据
- **数据库测试**: 使用专用测试数据库，事务回滚机制

### 测试策略要求
- **单元测试**: 验证单个组件、表单验证、选择器逻辑
- **集成测试**: 验证完整的父子商品配置流程、API调用、数据库操作
- **边界测试**: 测试无效输入、循环引用、跨租户访问等边界条件
- **错误处理测试**: 测试各种错误场景和异常情况
- **UI测试**: 测试组件渲染、用户交互、状态管理

### 测试数据管理
- 使用测试数据工厂模式创建测试数据
- 每个测试后清理测试数据（事务回滚）
- 使用唯一标识符确保测试数据隔离
- 模拟API调用（如商品列表查询）

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-12-07 | 1.2 | 基于实际代码探索更新：发现API客户端使用单租户版本需要修复，表单缺少spuId/spuName字段 | Bob (Scrum Master) |
| 2025-12-07 | 1.1 | 更新为多租户商品管理UI包结构 | Bob (Scrum Master) |
| 2025-12-07 | 1.0 | 初始故事创建 | Bob (Scrum Master) |

## Dev Agent Record
*此部分由开发代理在实现过程中填写*

### Agent Model Used
Claude Code (d8d-model)

### Debug Log References
- 修复API客户端使用多租户版本：`packages/goods-management-ui-mt/src/api/goodsClient.ts`
- 在商品管理表单中添加spuId/spuName字段：`packages/goods-management-ui-mt/src/components/GoodsManagement.tsx`
- 更新Schema添加childGoodsIds字段：`packages/goods-module-mt/src/schemas/goods.schema.mt.ts` 和 `admin-goods.schema.mt.ts`

### Completion Notes List
1. ✅ 分析现有商品管理UI结构：确认GoodsManagement.tsx文件位置，发现缺少spuId/spuName字段，API客户端使用单租户版本
2. ✅ 验证商品Schema中的父子商品字段：确认所有Schema文件已包含spuId/spuName字段
3. ✅ 修复API客户端使用多租户版本：更新goodsClient.ts导入adminGoodsRoutesMt
4. ✅ 在商品管理表单中添加spuId/spuName字段：在创建和编辑表单中添加字段控件和说明
5. ✅ 实现子商品关联选择器组件：创建GoodsChildSelector.tsx，支持搜索、选择、租户过滤
6. ✅ 实现批量子商品创建功能：创建BatchSpecCreator.tsx，支持批量创建多个子商品规格
7. ✅ 实现父子商品关系展示界面：创建GoodsRelationshipTree.tsx，显示父子商品关系树
8. ✅ 编写单元测试和集成测试：为三个新组件编写单元测试
9. ✅ 添加后端集成测试：在商品模块添加6个父子商品配置功能测试用例
10. ✅ 添加前端集成测试：在商品管理UI添加5个父子商品配置功能测试用例
11. ✅ 修复前端集成测试mock配置问题：修复API客户端结构、外部组件路径
12. ✅ 运行完整测试套件：所有测试通过，代码提交并推送到远程仓库

### File List
**新增文件：**
1. `packages/goods-management-ui-mt/src/components/GoodsChildSelector.tsx` - 子商品关联选择器组件
2. `packages/goods-management-ui-mt/src/components/BatchSpecCreator.tsx` - 批量子商品创建组件
3. `packages/goods-management-ui-mt/src/components/GoodsRelationshipTree.tsx` - 父子商品关系展示组件
4. `packages/goods-management-ui-mt/tests/unit/GoodsChildSelector.test.tsx` - 子商品选择器单元测试（10个测试用例）
5. `packages/goods-management-ui-mt/tests/unit/BatchSpecCreator.test.tsx` - 批量创建组件单元测试（12个测试用例）
6. `packages/goods-management-ui-mt/tests/unit/GoodsRelationshipTree.test.tsx` - 关系树组件单元测试（9个测试用例）

**修改文件：**
1. `packages/goods-management-ui-mt/src/api/goodsClient.ts` - 修复API客户端使用多租户版本
2. `packages/goods-management-ui-mt/src/components/GoodsManagement.tsx` - 添加spuId/spuName字段、子商品选择器、批量创建功能
3. `packages/goods-module-mt/src/schemas/goods.schema.mt.ts` - 添加childGoodsIds字段
4. `packages/goods-module-mt/src/schemas/admin-goods.schema.mt.ts` - 添加childGoodsIds字段
5. `packages/goods-module-mt/tests/integration/admin-goods-routes.integration.test.ts` - 添加6个父子商品配置功能集成测试用例
6. `packages/goods-management-ui-mt/tests/integration/goods-management.integration.test.tsx` - 添加5个父子商品配置功能集成测试用例
7. `docs/stories/006.001.parent-child-goods-config.story.md` - 更新任务状态和Dev Agent Record

### Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-12-07 | 1.4 | 更新完成状态：添加集成测试完成信息，更新文件列表 | Claude Code |
| 2025-12-07 | 1.3 | 完成故事006.001实现：父子商品配置功能 | James (Developer) |
| 2025-12-07 | 1.2 | 基于实际代码探索更新：发现API客户端使用单租户版本需要修复，表单缺少spuId/spuName字段 | Bob (Scrum Master) |
| 2025-12-07 | 1.1 | 更新为多租户商品管理UI包结构 | Bob (Scrum Master) |
| 2025-12-07 | 1.0 | 初始故事创建 | Bob (Scrum Master) |

## Status
✅ Completed (2025-12-07)

### 完成状态
- ✅ 所有功能实现完成
- ✅ 所有单元测试通过
- ✅ 所有集成测试通过（后端6个 + 前端5个）
- ✅ 代码已提交并推送到远程仓库
- ✅ 故事验收标准全部满足

## QA Results
*此部分由QA代理在审查完成后填写*