mini-starter/docs/prd/epic-006-parent-child-goods-multi-spec-support.md

史诗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小程序 + 多租户架构 优先级：高（支持电商核心功能）