template-10550/docs/multi-spec-integration-summary.md

商品多规格功能集成总结

完成的工作

1. 前端功能集成 ✅

商品详情页改造

• 文件: src/shop/goodsDetail/index.tsx
• 新增功能:
  • 加载商品规格数据 (listShopGoodsSpec)
  • 加载商品SKU数据 (listShopGoodsSku)
  • 集成规格选择器组件
  • 支持多规格加入购物车
  • 支持多规格立即购买

购物车系统升级

• 文件: src/hooks/useCart.ts
• 改进内容:
  • CartItem 接口新增 skuId 和 specInfo 字段
  • addToCart 函数支持SKU信息
  • 购物车商品唯一性判断支持SKU区分

规格选择器组件优化

• 文件: src/components/SpecSelector/index.tsx
• 改进内容:
  • 支持 action 参数区分加入购物车和立即购买
  • 优化回调函数参数传递
  • 改进组件接口设计

2. 数据流设计 ✅

API调用流程

商品详情页加载
├── getShopGoods(goodsId) - 获取商品基本信息
├── listShopGoodsSpec(goodsId) - 获取商品规格
└── listShopGoodsSku(goodsId) - 获取商品SKU

用户操作流程

用户点击加入购物车/立即购买
├── 检查是否有规格 (specs.length > 0)
├── 有规格: 显示规格选择器
│   ├── 用户选择规格组合
│   ├── 系统匹配对应SKU
│   ├── 更新价格和库存显示
│   └── 确认后执行对应操作
└── 无规格: 直接执行操作

数据结构设计

// 购物车商品项
interface CartItem {
  goodsId: number;
  name: string;
  price: string;
  image: string;
  quantity: number;
  addTime: number;
  skuId?: number;        // 新增: SKU ID
  specInfo?: string;     // 新增: 规格信息
}

// 订单商品项
interface OrderGoodsItem {
  goodsId: number;
  quantity: number;
  skuId?: number;        // 新增: SKU ID
  specInfo?: string;     // 新增: 规格信息
}

技术实现要点

1. 规格数据组织

• 规格按 specName 分组
• 规格值按 specValue 组织
• SKU通过规格值字符串匹配 (sku 字段)

2. SKU匹配算法

// 构建规格值字符串，按规格名称排序确保一致性
const sortedSpecNames = specGroups.map(g => g.specName).sort();
const specValues = sortedSpecNames.map(name => selectedSpecs[name]).join('|');
const sku = skus.find(s => s.sku === specValues);

3. 购物车唯一性判断

// 根据goodsId和skuId判断是否为同一商品
const existingItemIndex = newItems.findIndex(item => 
  item.goodsId === goods.goodsId && 
  (goods.skuId ? item.skuId === goods.skuId : !item.skuId)
);

需要后端配合的工作

1. API参数模型修改 🔄

• ShopGoodsSpecParam 需要添加 goodsId 字段
• ShopGoodsSkuParam 需要添加 goodsId 字段

2. 查询逻辑适配 🔄

• 规格查询接口支持按商品ID过滤
• SKU查询接口支持按商品ID过滤

3. 业务逻辑升级 🔄

• 购物车接口支持SKU信息存储
• 订单创建接口支持SKU信息处理
• 库存扣减逻辑适配多规格
• 价格计算逻辑适配多规格

测试验证

前端测试 ✅

• 商品详情页规格数据加载
• 规格选择器显示和交互
• SKU匹配和价格更新
• 购物车多规格商品支持
• 立即购买多规格商品支持

后端测试 🔄

• API参数传递验证
• 规格数据查询验证
• SKU数据查询验证
• 购物车SKU信息存储
• 订单SKU信息处理

文档输出

1. 后端适配指南: docs/backend-multi-spec-integration.md

   • API接口修改要求
   • 数据库表结构检查
   • 业务逻辑适配建议
   • 测试场景和检查清单

2. 前端测试指南: docs/frontend-multi-spec-test.md

   • 功能测试步骤
   • 数据流验证方法
   • 常见问题排查
   • 调试技巧和优化建议

兼容性保证

向后兼容

• 单规格商品功能完全保持不变
• 现有购物车数据结构兼容
• 现有订单流程不受影响

渐进增强

• 多规格功能作为增强特性
• 规格数据不存在时自动降级为单规格模式
• 错误处理确保用户体验不受影响

下一步工作

短期 (1-2周)

1. 后端API适配完成
2. 端到端测试验证
3. 生产环境部署测试

中期 (1个月)

1. 性能优化和监控
2. 用户反馈收集和改进
3. 边界情况处理完善

长期 (3个月)

1. 规格图片支持
2. 批量操作功能
3. 高级规格管理功能

风险评估

低风险 ✅

• 前端功能实现完整
• 数据结构设计合理
• 向后兼容性良好

中风险 ⚠️

• 后端API适配工作量
• 数据迁移和兼容性
• 性能影响评估

缓解措施

• 详细的后端适配文档
• 完整的测试用例覆盖
• 分阶段部署和验证