更新史诗006文档：添加故事006.021解决小程序首页多规格商品加入购物车失败bug

- 创建新故事文档006.021.mini-home-page-multi-spec-cart-bug-fix.story.md
- 更新史诗006主文档，添加故事21详情
- 更新史诗进度状态和成功标准

🤖 Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

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

@@ -1,9 +1,9 @@
 # 史诗006：父子商品多规格支持 - 棕地增强
 
 ## 史诗状态
-**进度**: 17/20 故事完成 (85.0%)
+**进度**: 17/21 故事完成 (81.0%)
 **最近更新**: 2025-12-16 (故事13完成：父子商品列表缓存自动刷新优化)
-**当前状态**: 故事1-15、17、20已完成，故事18-19待开始，故事16已拆分
+**当前状态**: 故事1-15、17、20已完成，故事18-19、21待开始，故事16已拆分
 
 ### 完成概览
 - ✅ **故事1**: 管理后台父子商品配置功能 (已完成)
@@ -26,6 +26,7 @@
 - ⏳ **故事18**: 父子商品管理面板剩余测试修复 (待开始)
 - ⏳ **故事19**: 批量创建组件测试修复与API模拟规范化 (待开始)
 - ✅ **故事20**: 商品管理集成测试API模拟规范化 (已完成)
+- ⏳ **故事21**: 小程序首页多规格商品加入购物车失败bug修复 (待开始)
 
 ## 史诗目标
 新增父子商品多规格支持功能，在商品添加购物车或立即购买时，能同时支持单规格和多规格选择，以子商品作为多规格选项，并支持手动指定子商品。
@@ -78,6 +79,7 @@
   16. ⏳ 父子商品管理面板所有测试通过，组件交互逻辑正确（故事18待实现）
   17. ⏳ 批量创建组件测试全部通过，API模拟符合规范（故事19待实现）
   18. ✅ 商品管理集成测试API模拟规范化，跨包集成测试正确工作（故事20已实现）
+  19. ⏳ 小程序首页多规格商品加入购物车功能稳定可靠，无成功提示但实际未添加的bug（故事21待实现）
 
 ## 设计决策
 
@@ -679,7 +681,7 @@
       - `packages/goods-management-ui-mt/tests/unit/BatchSpecCreatorInline.test.tsx` - 修复表单验证测试
       - `packages/goods-management-ui-mt/tests/unit/BatchSpecCreator.test.tsx` - 更新API模拟规范
 
-20. **故事20：商品管理集成测试API模拟规范化** ⏳ **待开始**
+20. **故事20：商品管理集成测试API模拟规范化** ✅ **已完成**
     - **问题背景**：商品管理集成测试需要更新API模拟规范，确保跨包集成测试正确配置API响应
     - **解决方案**：更新goods-management.integration.test.tsx集成测试文件，使用统一的rpcClient模拟
     - **功能需求**：
@@ -693,6 +695,24 @@
     - **文件变更**：
       - `packages/goods-management-ui-mt/tests/integration/goods-management.integration.test.tsx` - 更新API模拟规范
 
+21. **故事21：小程序首页多规格商品加入购物车失败bug修复** ⏳ **待开始**
+    - **问题背景**：用户在小程序首页点击多规格商品的购物车图标时，弹出规格选择组件，选择规格后点击"加入购物车"，系统显示成功提示但实际购物车内容未更新。单规格商品功能正常。
+    - **解决方案**：分析并修复ID类型转换问题，确保商品ID在数据流中保持类型一致性，修复商品卡片、首页处理函数和购物车上下文之间的数据传递问题。
+    - **功能需求**：
+      - 修复商品卡片中的ID类型转换逻辑（`spec.id.toString()`）
+      - 修复首页中的ID解析逻辑（`parseInt(goods.id)`）
+      - 确保购物车上下文接受正确的ID类型
+      - 添加完善的错误处理和调试日志
+    - **验收标准**：
+      - 用户在小程序首页能够成功添加多规格商品到购物车
+      - 购物车数量正确更新，商品实际存在于购物车中
+      - 单规格商品功能不受影响
+      - 相关测试通过，问题不再出现
+    - **文件变更**：
+      - `mini/src/components/goods-card/index.tsx` - 修复`handleSpecConfirm`函数
+      - `mini/src/pages/index/index.tsx` - 修复`handleAddCart`函数
+      - `mini/tests/unit/components/goods-card/goods-card.test.tsx` - 更新测试用例
+
 ## 兼容性要求
 - [x] 现有API保持向后兼容，新增端点不影响现有功能（故事2、4、7已确保）
 - [x] 数据库schema向后兼容，利用现有spuId字段（故事1-4已实现）
@@ -706,7 +726,7 @@
 - **回滚计划**：移除新增API端点，恢复原有逻辑，保持多租户完整性
 
 ## 完成定义
-- [x] 所有故事完成，验收标准满足（14/20完成，故事13、17-20待实现，故事16已拆分）
+- [x] 所有故事完成，验收标准满足（17/21完成，故事18-19、21待实现，故事16已拆分）
 - [x] 现有功能通过测试验证（故事1-15测试通过）
 - [x] API变更经过兼容性测试（故事2-15 API测试通过）
 - [x] 多租户隔离机制保持完整（故事1-15已实现）

docs/stories/006.021.mini-home-page-multi-spec-cart-bug-fix.story.md

@@ -0,0 +1,131 @@
+# Story 006.021: 小程序首页多规格商品加入购物车失败bug修复
+
+## Status
+Pending
+
+## Story
+**As a** 小程序用户，
+**I want** 在小程序首页点击多规格商品的购物车图标时，能够正确选择规格并成功添加到购物车，
+**so that** 多规格商品能够像单规格商品一样顺利添加到购物车，获得一致的购物体验
+
+## 问题背景
+当前在小程序首页中，用户点击商品卡片上的购物车图标添加商品到购物车时，如果商品是多规格商品（有子商品），会弹出规格选择组件。用户选择规格后点击"加入购物车"，系统显示"已添加到购物车"成功提示，但实际购物车内容并未更新，商品没有真正添加到购物车。而单规格商品（无子商品）的加入购物车功能正常。
+
+这个问题导致用户在多规格商品的购物体验上出现严重问题：用户看到成功提示但实际购物车为空，需要重复操作或放弃购买。
+
+## 与故事17的关系
+故事17（小程序商品卡片多规格支持）已经实现了小程序商品卡片的多规格支持，并修复了"多规格商品加入购物车成功但实际未添加的问题"。然而，根据用户反馈，这个问题仍然存在或出现了新的表现形式。
+
+## Acceptance Criteria
+1. 用户在小程序首页点击多规格商品的购物车图标时，能够正常弹出规格选择器（GoodsSpecSelector组件）
+2. 用户在规格选择器中选择规格和数量后，点击"确定"按钮，商品能够正确添加到购物车
+3. 购物车数量能够正确更新，商品实际存在于购物车中
+4. 用户收到"已添加到购物车"提示后，能够在购物车页面看到添加的商品
+5. 单规格商品（无子商品）的加入购物车功能不受影响，保持正常
+6. 修复后需要通过相关测试验证，确保问题不再出现
+7. 需要添加或更新测试用例，覆盖此bug的修复场景
+
+## Tasks / Subtasks
+- [ ] **分析问题根本原因** (AC: 1, 2, 3, 4)
+  - [ ] 分析当前bug的具体表现和重现步骤
+  - [ ] 检查`mini/src/components/goods-card/index.tsx`中的`handleSpecConfirm`函数，特别是ID类型转换逻辑
+  - [ ] 检查`mini/src/pages/index/index.tsx`中的`handleAddCart`函数，特别是`parseInt(goods.id)`逻辑
+  - [ ] 检查购物车上下文`CartContext`中的`addToCart`函数，验证ID类型匹配性
+  - [ ] 检查规格选择器`GoodsSpecSelector`组件的`onConfirm`回调参数传递
+  - [ ] 分析可能的数据流问题：商品卡片 → 规格选择器 → 首页处理函数 → 购物车上下文
+
+- [ ] **设计修复方案** (AC: 1, 2, 3, 4, 5)
+  - [ ] 设计ID类型一致性解决方案：确保商品ID在数据流中保持一致的字符串或数字类型
+  - [ ] 设计数据传递验证方案：确保规格选择后的数据正确传递到购物车添加逻辑
+  - [ ] 设计错误处理方案：添加更完善的错误处理，避免静默失败
+  - [ ] 设计测试验证方案：如何验证修复后的功能正确性
+
+- [ ] **实现修复** (AC: 1, 2, 3, 4, 5)
+  - [ ] 修复商品卡片中的ID类型转换问题（`spec.id.toString()`）
+  - [ ] 修复首页中的ID解析问题（`parseInt(goods.id)`）
+  - [ ] 确保购物车上下文接受正确的ID类型
+  - [ ] 添加调试日志，便于问题追踪
+  - [ ] 修复相关类型定义，确保类型安全
+
+- [ ] **编写和更新测试** (AC: 6, 7)
+  - [ ] 更新现有商品卡片测试，添加多规格商品加入购物车场景
+  - [ ] 添加集成测试，验证完整的商品卡片 → 规格选择 → 购物车添加流程
+  - [ ] 测试ID类型转换边界情况
+  - [ ] 确保所有相关测试通过
+
+- [ ] **验证修复效果** (AC: 1, 2, 3, 4, 5, 6)
+  - [ ] 手动测试小程序首页多规格商品加入购物车功能
+  - [ ] 验证购物车数量正确更新
+  - [ ] 验证购物车页面正确显示添加的商品
+  - [ ] 验证单规格商品功能不受影响
+  - [ ] 运行相关测试套件，确保无回归问题
+
+## 技术分析要点
+
+### 潜在问题点分析
+根据代码审查，发现以下潜在问题：
+
+1. **ID类型不一致问题**：
+   - `goods-card/index.tsx:79`: `id: spec.id.toString()` - 将数字ID转换为字符串
+   - `pages/index/index.tsx:200`: `const id = parseInt(goods.id)` - 将字符串ID解析为数字
+   - 如果`spec.id`已经是字符串，`toString()`可能产生错误结果
+   - `parseInt`可能因格式问题失败
+
+2. **数据流验证**：
+   - 需要验证规格选择器返回的数据结构是否与`handleSpecConfirm`期望的一致
+   - 需要验证`handleAddCart`接收的数据是否包含完整的规格信息
+
+3. **错误处理缺失**：
+   - 当前实现中缺少关键错误处理，可能导致静默失败
+   - 需要添加更完善的错误提示和日志记录
+
+### 参考实现
+参考商品详情页（`mini/src/pages/goods-detail/index.tsx`）的规格选择逻辑，确保一致性：
+- 商品详情页的规格选择流程经过充分测试，功能正常
+- 需要确保商品卡片的多规格支持与商品详情页保持相同的数据处理和错误处理逻辑
+
+## 文件变更计划
+
+### 主要修改文件
+1. `mini/src/components/goods-card/index.tsx` - 修复`handleSpecConfirm`函数中的ID类型处理
+2. `mini/src/pages/index/index.tsx` - 修复`handleAddCart`函数中的ID解析逻辑
+3. 可能修改`mini/src/contexts/CartContext.tsx` - 确保ID类型兼容性
+
+### 测试文件
+1. `mini/tests/unit/components/goods-card/goods-card.test.tsx` - 更新测试用例，添加多规格商品加入购物车失败场景
+2. 可能添加集成测试文件，验证完整流程
+
+## 技术约束
+- **多租户兼容性**：保持多租户数据过滤逻辑不变
+- **API兼容性**：保持与现有商品API的兼容性
+- **性能考虑**：避免不必要的类型转换和数据复制
+- **向后兼容性**：确保修复不影响现有单规格商品功能
+
+## 测试策略
+- **单元测试**：测试修复后的ID类型处理逻辑
+- **集成测试**：测试完整的商品卡片 → 规格选择 → 购物车添加流程
+- **手动测试**：在实际小程序环境中验证修复效果
+- **回归测试**：确保现有功能不受影响
+
+## Change Log
+| Date | Version | Description | Author |
+|------|---------|-------------|--------|
+| 2025-12-16 | 1.0 | 初始故事创建，修复小程序首页多规格商品加入购物车失败bug | John (Product Manager) |
+
+## Dev Agent Record
+*此部分由开发代理在实现过程中填写*
+
+### Agent Model Used
+TBD
+
+### Debug Log References
+TBD
+
+### Completion Notes List
+TBD
+
+### File List
+TBD
+
+## QA Results
+*此部分由QA代理在审查完成后填写*