# 史诗006：父子商品多规格支持 - 棕地增强

## 史诗目标
新增父子商品多规格支持功能，在商品添加购物车或立即购买时，能同时支持单规格和多规格选择，以子商品作为多规格选项，并支持手动指定子商品。

## 史诗描述

### 现有系统上下文
- **数据库支持**：商品表已有父子商品关系字段（spuId/spuName）
- **Schema支持**：所有商品Schema（Admin/User/Public）都包含spuId/spuName字段
- **UI缺失**：商品管理UI表单缺少spu相关字段和父子商品配置功能
- **前端组件**：已有`GoodsSpecSelector`组件但被注释，购物车支持spec字段但无规格选择逻辑
- **技术栈**：TypeORM + Hono + React + Taro小程序 + 多租户架构
- **API路由**：
  - 小程序：使用`publicGoodsRoutesMt`（公共商品路由）
  - 管理后台：使用`adminGoodsRoutes`（管理员路由）
- **多租户特性**：商品实体有tenantId字段，API路由支持租户隔离和数据权限

### 增强详情
- **管理后台**：新增父子商品配置界面，支持手动关联已有商品和批量创建子商品
- **前端**：父子商品的多规格选择界面和逻辑，支持多租户环境
- **API调整**：优化商品列表和详情API对父子商品的支持
- **集成点**：多租户商品模块、商品管理UI、商品详情页、购物车系统、订单提交流程
- **成功标准**：
  1. 管理员能配置父子商品关系
  2. 用户能在商品详情页选择子商品作为规格
  3. 购物车和订单正确记录规格信息
  4. 商品列表页保持整洁（只显示父商品）
  5. 多租户隔离机制保持完整

## 设计决策

### 1. 规格概念澄清
- **规格 = 子商品的名称**：子商品的`name`字段作为规格名称
- **规格选择 = 选择子商品**：选择规格时实际选择对应的子商品
- **购物车逻辑简化**：
  - 如果选择规格：使用子商品的`id`、`name`、`price`、`stock`
  - 如果不选择规格：使用父商品的`id`、`name`、`price`、`stock`
  - **关键洞察**：`name`字段已经包含完整的规格信息，`spec`字段可能暂时不需要
- **核心优势**：购物车和订单系统几乎不需要修改

### 2. 商品列表展示策略
- **商品列表页**（首页、分类页、搜索页）：只显示父商品（spuId=0）
- **商品详情页**：显示父商品详情 + 规格选择器（子商品作为选项）
- **单规格商品**：保持现有行为不变（spuId=0且无子商品）

### 3. API设计
- **公共商品列表API**（`/api/v1/goods`）：默认只返回父商品（spuId=0）
- **商品详情API**（`/api/v1/goods/:id`）：
  - 父商品：返回商品详情 + 子商品列表（作为规格选项）
  - 子商品：返回子商品详情 + 父商品基本信息
- **新增API**：`GET /api/v1/goods/:id/children` 获取指定父商品的子商品列表
- **管理员商品API**：显示完整的父子商品关系树

### 4. 父子商品配置方式
1. **手动关联**：在创建/编辑父商品时，选择已有商品作为子商品
2. **批量创建**：创建父商品时，同时创建多个子商品规格（如不同颜色、尺寸等）

## 故事

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

2. **故事2：商品API父子商品支持优化**
   - 公共商品列表API：默认只返回父商品（spuId=0）
   - 新增API端点：`GET /api/v1/goods/:id/children` 获取子商品列表
   - 商品详情API：根据商品类型返回相应数据（父商品+子商品列表或子商品+父商品信息）
   - 管理员商品API：增强父子商品关系展示
   - **验收标准**：API变更保持向后兼容，新增端点正常工作

3. **故事3：父子商品多规格选择组件开发**
   - 激活并增强现有的`GoodsSpecSelector`组件
   - 支持父子商品关系，以子商品名称作为规格选项显示
   - 规格选择实际选择对应的子商品ID
   - 适配多租户商品数据查询
   - **验收标准**：规格选择器能正确显示子商品名称作为规格，并能选择对应的子商品

4. **故事4：商品详情页规格选择集成**
   - 在商品详情页集成规格选择组件
   - "立即购买"和"加入购物车"支持规格选择
   - 规格选择后使用子商品的价格和库存信息
   - 多租户环境下的商品规格数据获取
   - **验收标准**：用户能在商品详情页成功选择规格，系统使用正确的子商品价格和库存

5. **故事5：购物车和订单规格支持**
   - **购物车最小化修改**：适配`addToCart`逻辑，支持添加子商品（使用子商品信息填充CartItem）
   - **规格信息显示**：购物车和订单中通过`name`字段显示完整规格信息
   - **订单系统兼容**：订单创建使用商品ID（可能是子商品ID），保持现有逻辑
   - **多租户兼容性**：确保父子商品在同一租户下
   - **验收标准**：购物车能正确添加子商品，订单显示完整商品名称，现有单规格商品不受影响

## 兼容性要求
- [ ] 现有API保持向后兼容，新增端点不影响现有功能
- [ ] 数据库schema向后兼容，利用现有spuId字段
- [ ] UI变更遵循现有设计模式
- [ ] 性能影响最小化，特别是商品列表查询
- [ ] 多租户隔离机制保持完整

## 风险缓解
- **主要风险**：API变更影响现有客户端，规格选择逻辑影响购物车功能
- **缓解措施**：逐步集成，保持向后兼容，现有无规格商品继续正常工作
- **回滚计划**：移除新增API端点，恢复原有逻辑，保持多租户完整性

## 完成定义
- [ ] 所有故事完成，验收标准满足
- [ ] 现有功能通过测试验证
- [ ] API变更经过兼容性测试
- [ ] 多租户隔离机制保持完整
- [ ] 性能测试通过，无明显性能下降
- [ ] 文档适当更新
- [ ] 现有功能无回归

## 技术要点

### 数据库层面
- 利用现有`spuId`字段：0表示父商品或单规格商品，>0表示子商品
- `spuName`字段存储父商品名称，便于展示

### 多租户支持
- 所有操作必须包含tenantId过滤
- 父子商品必须在同一租户下
- 数据权限机制保持完整

### 性能考虑
- 商品列表查询添加`spuId=0`条件
- 子商品列表查询使用分页
- 规格选择器数据懒加载

### 前端适配
- **规格选择器**：显示子商品名称作为规格选项，选择时使用子商品信息
- **购物车逻辑极致简化**：
  - 如果选择规格：`CartItem`使用子商品的`id`、`name`、`price`、`stock`
  - 如果不选择规格：`CartItem`使用父商品的`id`、`name`、`price`、`stock`
  - **关键**：`name`字段已经包含完整规格信息，`spec`字段可暂时忽略或设置为相同值
- **商品详情页**：父商品信息展示，规格选择后使用选中商品的信息
- **最大优势**：购物车和订单逻辑几乎不需要修改，只需正确选择商品

---
**史诗创建时间**：2025-12-06
**创建人**：John (Product Manager)
**技术栈**：TypeORM + Hono + React + Taro小程序 + 多租户架构
**优先级**：高（支持电商核心功能）