Página inicial Explorar Ajuda
Registrar Entrar
186-template-175
/
mini-starter
fork de 155-template-138/mini-starter
2
0
Fork 0
Arquivos
Tree: 3eeaefc94a
Branches Tags
mini-starter
/
docs
/
stories
/
006.017.mini-goods-card-multi-spec-support.story.md

006.017.mini-goods-card-multi-spec-support.story.md 15 KB
Histórico Raw

Story 006.017: 小程序商品卡片多规格支持

Status

Completed

Story

As a 小程序用户， I want 在商品列表页面（首页、商品列表页、搜索结果页）点击商品卡片的"添加到购物车"图标时，如果商品有多规格选项，能够弹出规格选择器选择规格后再添加到购物车， so that 无需进入商品详情页就能快速完成多规格商品的购物车添加操作，提升购物体验

Acceptance Criteria

  1. 用户点击商品卡片的购物车图标时，如果商品有多规格选项（有子商品），弹出规格选择器（GoodsSpecSelector组件）
  2. 用户在规格选择器中选择规格和数量后，点击确定成功添加到购物车
  3. 如果商品没有规格选项（单规格商品），直接添加到购物车，现有功能不受影响
  4. 购物车正确记录父子商品关系，parentGoodsId字段正确设置
  5. 所有使用商品卡片的页面（首页、商品列表页、搜索结果页）都支持多规格商品
  6. 现有单规格商品功能不受影响，无回归问题
  7. 添加完整的单元测试，覆盖多规格和单规格场景

Tasks / Subtasks

  • [x] 分析现有商品卡片组件和规格选择器组件 (AC: 1, 2, 3, 4)

    • 分析mini/src/components/goods-card/index.tsx组件的当前实现，特别是handleAddCart函数
    • 分析mini/src/components/goods-spec-selector/index.tsx组件的API和props接口
    • 分析商品详情页（mini/src/pages/goods-detail/index.tsx）中的规格选择逻辑，作为参考实现
    • 确认商品卡片需要传递哪些数据给规格选择器（goodsId, parentGoodsId, hasSpecOptions等）

  • [x] 设计商品卡片组件扩展方案 (AC: 1, 2, 3, 4, 5)

    • 设计商品卡片props扩展，添加多规格支持所需字段
    • 设计状态管理方案：showSpecModal控制弹窗显示，selectedSpec记录选择的规格
    • 设计规格选择器的集成方式，参考商品详情页的handleAddToCart逻辑
    • 设计购物车添加逻辑，确保parentGoodsId正确传递

  • [x] 实现商品卡片多规格支持 (AC: 1, 2, 3, 4)

    • 修改mini/src/components/goods-card/index.tsx组件，添加规格选择判断逻辑
    • 集成GoodsSpecSelector组件，支持add-to-cart操作类型
    • 实现handleAddCart函数的多规格处理逻辑
    • 添加状态管理：showSpecModal、selectedSpec、pendingAction等状态
    • 确保规格选择器正确获取子商品列表数据

  • [x] 更新商品卡片使用页面 (AC: 5)

    • 更新mini/src/pages/index/index.tsx首页，确保传递正确的商品数据给商品卡片
    • 更新mini/src/pages/goods-list/index.tsx商品列表页，确保传递正确的商品数据
    • 更新mini/src/pages/search-result/index.tsx搜索结果页，确保传递正确的商品数据
    • 更新mini/src/components/goods-list/index.tsx商品列表组件，确保数据传递正确

  • [x] 编写单元测试 (AC: 7)

    • 创建mini/tests/unit/components/goods-card/goods-card.test.tsx测试文件
    • 测试单规格商品直接添加到购物车场景
    • 测试多规格商品弹出规格选择器场景
    • 测试规格选择后成功添加到购物车场景
    • 测试父子商品关系正确记录场景
    • 测试商品卡片在不同页面的数据传递正确性

  • [x] 集成测试和验证 (AC: 1, 2, 3, 4, 5, 6)

    • 运行现有测试套件，确保无回归问题
    • 手动测试首页商品卡片的多规格支持
    • 手动测试商品列表页的多规格支持
    • 手动测试搜索结果页的多规格支持
    • 验证购物车中父子商品关系正确性

  • [x] 修复多规格商品加入购物车成功但实际未添加的问题 (AC: 2, 4)

    • 分析商品卡片和购物车上下文之间的ID类型不匹配问题
    • 修复商品卡片ID类型转换问题，确保子商品ID正确传递
    • 测试修复后的功能，验证多规格商品能正确添加到购物车

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 (服务端状态管理)
  • 测试框架: Jest 29.x (mini小程序专用测试框架)
  • API测试: hono/testing (内置，API端点测试，更好的类型安全)

项目结构信息 [Source: architecture/source-tree.md]

  • 包管理: 使用pnpm workspace管理多包依赖关系
  • 多租户架构: 所有操作必须包含tenantId过滤，父子商品必须在同一租户下
  • 小程序包: mini/目录包含Taro小程序前端代码
  • 主要组件位置:
    • 商品卡片: mini/src/components/goods-card/index.tsx
    • 规格选择器: mini/src/components/goods-spec-selector/index.tsx
    • 商品列表: mini/src/components/goods-list/index.tsx
  • 页面位置:
    • 首页: mini/src/pages/index/index.tsx
    • 商品列表页: mini/src/pages/goods-list/index.tsx
    • 搜索结果页: mini/src/pages/search-result/index.tsx
    • 商品详情页: mini/src/pages/goods-detail/index.tsx (参考实现)
  • API客户端: 使用Hono RPC客户端调用商品API
  • 购物车上下文: mini/src/contexts/CartContext.tsx，包含addToCart和switchSpec函数

编码标准 [Source: architecture/coding-standards.md]

  • 代码风格: TypeScript严格模式，一致的缩进和命名
  • 测试位置: tests/unit/目录与源码对应结构
  • 覆盖率目标: 核心业务逻辑 > 80%
  • 测试类型: 单元测试、集成测试
  • 现有API兼容性: 确保测试不破坏现有API契约

参考实现分析

商品详情页规格选择逻辑 (mini/src/pages/goods-detail/index.tsx):

  • handleAddToCart函数（第355-417行）包含完整的规格选择逻辑
  • 检查是否有规格选项（hasSpecOptions）
  • 如果有规格选项，弹出规格选择器（setShowSpecModal(true)）
  • 规格选择器的onConfirm回调执行添加购物车操作
  • 使用pendingAction状态记录用户意图（加入购物车或立即购买）

商品卡片当前实现 (mini/src/components/goods-card/index.tsx):

  • handleAddCart函数（第41-44行）直接调用onAddCart(data)
  • 没有规格选择判断逻辑
  • 需要添加类似商品详情页的规格选择逻辑

规格选择器组件 (mini/src/components/goods-spec-selector/index.tsx):

  • 支持actionType prop（add-to-cart或buy-now）
  • 从API获取子商品列表作为规格选项
  • onConfirm回调返回选择的规格信息和数量
  • 支持parentGoodsId参数获取子商品列表

技术实现要点

  1. 商品卡片props扩展:

    interface GoodsCardProps {
 // 现有props...
 hasSpecOptions?: boolean;      // 是否有规格选项
 parentGoodsId?: number;       // 父商品ID（用于获取子商品列表）
 goodsId?: number;             // 当前商品ID（父商品或子商品ID）
 // ...其他props
}

  2. 状态管理:

    const [showSpecModal, setShowSpecModal] = useState(false);
const [selectedSpec, setSelectedSpec] = useState<GoodsSpecSelection | null>(null);
const [pendingAction, setPendingAction] = useState<'add-to-cart' | null>(null);

  3. 修改handleAddCart函数:

    const handleAddCart = () => {
 if (hasSpecOptions && parentGoodsId) {
   // 有多规格选项，弹出规格选择器
   setPendingAction('add-to-cart');
   setShowSpecModal(true);
 } else {
   // 单规格商品，直接添加到购物车
   onAddCart(data);
 }
};

  4. 规格选择器集成:

    <GoodsSpecSelector
 open={showSpecModal}
 onOpenChange={setShowSpecModal}
 parentGoodsId={parentGoodsId}
 actionType="add-to-cart"
 onConfirm={(selection) => {
   // 执行添加购物车操作
   onAddCart({
     ...data,
     id: selection.goodsId,      // 子商品ID
     parentGoodsId: parentGoodsId,
     name: selection.goodsName,  // 子商品名称（规格名称）
     price: selection.price,
     count: selection.quantity
   });
   setSelectedSpec(selection);
 }}
/>

  5. 数据传递更新:

    • 首页、商品列表页、搜索结果页需要传递hasSpecOptions和parentGoodsId给商品卡片
    • 需要通过商品API判断商品是否有子商品（规格选项）

文件变更计划

主要修改文件:

  1. mini/src/components/goods-card/index.tsx - 添加规格选择逻辑，集成GoodsSpecSelector组件
  2. mini/src/components/goods-list/index.tsx - 确保传递正确的商品数据

相关页面更新:

  1. mini/src/pages/index/index.tsx - 首页商品卡片数据传递
  2. mini/src/pages/goods-list/index.tsx - 商品列表页数据传递
  3. mini/src/pages/search-result/index.tsx - 搜索结果页数据传递

测试文件:

  1. mini/tests/unit/components/goods-card/goods-card.test.tsx - 商品卡片多规格支持单元测试（新建）
  2. 更新现有页面测试，验证多规格商品添加购物车功能

技术约束

  • 多租户兼容性: 父子商品必须在同一租户下，API调用包含租户过滤
  • API调用: 规格选择器需要调用/api/v1/goods/:id/children获取子商品列表
  • 购物车兼容性: 确保CartContext.addToCart支持父子商品参数
  • 性能考虑: 商品列表页可能显示大量商品，避免不必要的API调用

测试策略

  • 单元测试: 测试商品卡片的规格选择逻辑，覆盖单规格和多规格场景
  • 集成测试: 测试商品卡片在不同页面的集成，验证数据传递和API调用
  • 手动测试: 在实际页面测试多规格商品的购物车添加流程

Testing

测试标准 [Source: architecture/testing-strategy.md]

  • 测试文件位置: mini/tests/目录下
  • 单元测试位置: tests/unit/**/*.test.{ts,tsx}
  • 测试框架: Jest + Testing Library + Taro模拟
  • 覆盖率要求: 单元测试 ≥ 80%
  • 测试模式: 使用测试数据工厂模式，避免硬编码测试数据

测试策略要求

  • 单元测试: 验证商品卡片组件的规格选择逻辑，包括状态管理、事件处理、条件渲染
  • 集成测试: 验证商品卡片在不同页面的数据传递和交互
  • API模拟: 模拟商品API返回子商品列表数据
  • 用户交互测试: 测试点击购物车图标、规格选择、添加购物车等用户交互

测试场景设计

  1. 单规格商品场景:

    • 点击购物车图标直接添加到购物车
    • 验证onAddCart回调被调用，传递正确的商品数据

  2. 多规格商品场景:

    • 点击购物车图标弹出规格选择器
    • 规格选择器显示子商品列表
    • 选择规格和数量后点击确定
    • 验证onAddCart回调被调用，传递子商品数据和parentGoodsId

  3. 规格选择取消场景:

    • 点击购物车图标弹出规格选择器
    • 点击取消或关闭弹窗
    • 验证购物车添加没有被执行

  4. 数据传递验证:

    • 验证首页、商品列表页、搜索结果页传递正确的hasSpecOptions和parentGoodsId
    • 验证商品卡片正确使用传递的数据

测试数据管理

  • 使用测试数据工厂创建商品数据
  • 模拟单规格商品数据（spuId: 0, 无子商品）
  • 模拟多规格商品数据（spuId: 0, 有子商品列表）
  • 模拟子商品数据（spuId: <父商品ID>）

Change Log

Date Version Description Author
2025-12-15 1.0 初始故事创建，添加小程序商品卡片多规格支持 John (Product Manager)

Dev Agent Record

此部分由开发代理在实现过程中填写

Agent Model Used

Claude Sonnet

Debug Log References

无

Completion Notes List

  • 成功扩展商品卡片组件，支持多规格商品选择
  • 集成GoodsSpecSelector组件，支持add-to-cart操作类型
  • 更新首页数据转换函数，传递hasSpecOptions和parentGoodsId字段
  • 修改handleAddCart函数，支持多规格判断逻辑
  • 添加状态管理：showSpecModal、selectedSpec、pendingAction
  • 确保规格选择器正确获取子商品列表数据
  • 更新商品列表页数据转换和购物车处理，传递hasSpecOptions和parentGoodsId字段
  • 更新搜索结果页数据转换和购物车处理，传递hasSpecOptions和parentGoodsId字段
  • 所有使用商品卡片的页面（首页、商品列表页、搜索结果页）都已支持多规格商品
  • 修复用户指出的逻辑问题：使用childGoodsIds字段准确判断是否有子商品，替代简单的spuId === 0判断
  • 修复pendingAction类型错误：actionType={pendingAction || undefined}
  • 修复API缺少childGoodsIds字段问题，更新public-goods.schema.mt.ts Schema定义
  • API现在正确返回childGoodsIds字段（已验证测试父商品返回childGoodsIds: [9,6,7,10]）
  • 创建商品卡片单元测试文件，覆盖单规格和多规格场景
  • 更新search-result页面测试的useRouter模拟问题
  • 状态更新为Ready for Review，等待测试修复完成
  • 修复多规格商品加入购物车成功但实际未添加的问题：分析并修复商品卡片和购物车上下文之间的ID类型不匹配问题，确保子商品ID正确传递
  • 对照商品详情页加入购物车逻辑，确保一致性：规格选择后的数据传递、parentGoodsId计算逻辑与商品详情页保持一致
  • 修复goods-spec-selector测试失败问题：测试期望2个参数但组件调用3个参数，添加undefined作为第三个参数，所有测试通过

File List

  1. mini/src/components/goods-card/index.tsx - 商品卡片组件，添加多规格支持
  2. mini/src/pages/index/index.tsx - 首页，更新数据转换和购物车处理
  3. mini/src/pages/goods-list/index.tsx - 商品列表页，更新数据转换和购物车处理
  4. mini/src/pages/search-result/index.tsx - 搜索结果页，更新数据转换和购物车处理
  5. packages/goods-module-mt/src/schemas/public-goods.schema.mt.ts - 添加childGoodsIds字段到API Schema定义
  6. mini/tests/unit/pages/search-result/basic.test.tsx - 修复useRouter模拟问题
  7. mini/tests/unit/components/goods-card/goods-card.test.tsx - 商品卡片单元测试文件，覆盖多规格场景
  8. docs/stories/006.017.mini-goods-card-multi-spec-support.story.md - 故事文件，更新任务状态和开发记录

QA Results

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