Почетна Преглед Помоћ
Регистрација Пријавите се
186-template-175
/
mini-starter
изданак од 155-template-138/mini-starter
2
0
Креирај огранак 0
Датотеке
Дрво: 02aa8e1b96
Гране Ознаке
mini-starter
/
docs
/
stories
/
005.010.goods-module.story.md

005.010.goods-module.story.md 18 KB
Историја Датотека

Story 005.010: Goods Module

Status

Draft

Story

As a 小程序开发者， I want 将商品管理模块从 packages/server/src 拆分到主项目的 packages 目录下作为独立 package， so that 项目可以按需引入商品分类和商品管理功能，保持模块独立性和向后兼容性

Acceptance Criteria

  1. 创建 @d8d/goods-module package，包含完整的商品分类和商品管理功能
  2. 从 packages/server/src/modules/goods 迁移商品服务代码
  3. 实现商品和商品分类的完整CRUD功能
  4. 提供完整的 TypeScript 类型定义和 API 文档
  5. 集成到现有的文件管理系统（商品图片关联）
  6. 保持与现有认证系统的兼容性
  7. 提供单元测试和集成测试，覆盖率满足要求
  8. 更新 server package 依赖关系，支持按需引入

Tasks / Subtasks

  • [x] Task 1: 创建 goods-module package 基础结构 (AC: 1, 2)

    • 创建 packages/goods-module 目录结构
    • 配置 package.json 和依赖关系，包含供应商和商户模块依赖 [Source: packages/supplier-module/package.json#L48-L58]
    • 配置 TypeScript 编译配置
    • 配置 vitest.config.ts 测试配置
    • 创建基础导出文件

  • [x] Task 2: 迁移商品实体和类型定义 (AC: 2, 4)

    • 迁移 Goods 实体到 packages/goods-module/src/entities/
    • 迁移 GoodsCategory 实体到 packages/goods-module/src/entities/
    • 迁移 GoodsSchema、CreateGoodsDto、UpdateGoodsDto 到 packages/goods-module/src/schemas/
    • 迁移 GoodsCategorySchema、CreateGoodsCategoryDto、UpdateGoodsCategoryDto 到 packages/goods-module/src/schemas/
    • 迁移 RandomGoodsQuerySchema、RandomGoodsResponseSchema 到 packages/goods-module/src/schemas/
    • 创建类型定义文件 packages/goods-module/src/types/goods.types.ts
    • 更新实体导入路径，使用 workspace:* 依赖

  • [x] Task 3: 迁移商品服务 (AC: 2, 3)

    • 迁移 GoodsService 到 packages/goods-module/src/services/
    • 迁移 GoodsCategoryService 到 packages/goods-module/src/services/
    • 重构服务使用 shared-crud 基础设施
    • 更新服务依赖注入配置

  • [x] Task 4: 创建商品路由 (AC: 3, 4)

    • 创建商品分类管理路由 packages/goods-module/src/routes/admin-goods-categories.ts
    • 集成认证中间件
    • 配置用户追踪字段
    • 配置关联关系（分类、供应商、商户、文件） [Source: packages/server/src/modules/goods/goods.entity.ts#L104-L114]

  • [x] Task 4.1: 创建随机商品功能 (AC: 3, 4)

    • 迁移随机商品查询Schema packages/goods-module/src/schemas/random.schema.ts
    • 创建随机商品路由 packages/goods-module/src/routes/public-goods-random.ts
    • 实现随机商品查询逻辑（支持分类过滤和图片包含选项）
    • 配置随机排序和状态过滤
    • 验证关联数据加载（图片、分类、供应商、商户等） [Source: packages/server/src/modules/goods/goods.entity.ts#L104-L114]

  • [x] Task 5: 创建用户权限API路由文件 (AC: 3, 4)

    • 创建用户专用schema packages/goods-module/src/schemas/user-goods.schema.ts
    • 创建管理员专用schema packages/goods-module/src/schemas/admin-goods.schema.ts
    • 创建用户路由 packages/goods-module/src/routes/user-goods-routes.ts
    • 创建管理员路由 packages/goods-module/src/routes/admin-goods-routes.ts
    • 配置数据权限控制，使用 shared-crud 的 dataPermission 配置
    • 验证用户路由只能访问和操作授权的数据
    • 验证管理员路由可以访问所有数据

  • [x] Task 6: 创建公开商品路由 (AC: 3, 4)

    • 创建公开商品schema packages/goods-module/src/schemas/public-goods.schema.ts
    • 创建公开商品路由 packages/goods-module/src/routes/public-goods-routes.ts
    • 配置只读权限，仅支持查询操作
    • 配置状态过滤，只返回可用状态的商品
    • 配置关联关系加载（分类、图片等）
    • 验证公开路由无需认证即可访问

  • [x] Task 7: 创建测试套件 (AC: 7)

    • 创建商品分类路由集成测试 packages/goods-module/tests/integration/admin-goods-categories.integration.test.ts [参考: packages/supplier-module/tests/integration/admin-routes.integration.test.ts]
    • 创建随机商品路由集成测试 packages/goods-module/tests/integration/public-goods-random.integration.test.ts
    • 创建用户路由集成测试 packages/goods-module/tests/integration/user-goods-routes.integration.test.ts [参考: packages/supplier-module/tests/integration/user-routes.integration.test.ts]
    • 创建管理员路由集成测试 packages/goods-module/tests/integration/admin-goods-routes.integration.test.ts [参考: packages/supplier-module/tests/integration/admin-routes.integration.test.ts]
    • 创建公开商品路由集成测试 packages/goods-module/tests/integration/public-goods-routes.integration.test.ts
    • 配置测试数据库连接，使用 shared-test-util
    • 添加关联关系测试场景（分类、供应商、商户、文件） [Source: packages/server/src/modules/goods/goods.entity.ts#L104-L114]
    • 测试商品状态管理逻辑
    • 测试随机商品查询功能
    • 确保测试覆盖率满足要求

  • [ ] Task 8: 集成到现有系统 (AC: 5, 6, 8)

    • 更新 server package 依赖，添加 @d8d/goods-module
    • 在 server 中注册商品路由
    • 验证与文件模块的集成
    • 验证与认证系统的集成
    • 确保商品图片关联正常工作
    • 验证商品分类树形结构

  • [ ] Task 9: 验证和文档 (AC: 4, 6)

    • 运行所有测试验证功能
    • 更新 docs/architecture/source-tree.md 文档
    • 验证向后兼容性

Dev Notes

技术栈信息

  • 后端框架: Hono 4.8.5 [Source: architecture/tech-stack.md#现有技术栈维护]
  • 数据库: PostgreSQL 17 + TypeORM 0.3.25 [Source: architecture/tech-stack.md#现有技术栈维护]
  • 认证: JWT Bearer Token [Source: architecture/api-design-integration.md#API集成策略]
  • 文件存储: MinIO + file-module [Source: architecture/source-tree.md#实际项目结构]

项目结构

  • 包位置: packages/goods-module/ [Source: architecture/source-tree.md#实际项目结构]
  • 代码结构: 遵循现有模块化包模式 [Source: architecture/source-tree.md#包架构层次]
  • 依赖层次: goods-module → supplier-module → merchant-module → file-module → auth-module → user-module → shared-crud → shared-utils → shared-types [Source: docs/architecture/source-tree.md#包架构层次]

商品功能详情

  • 商品实体: Goods 实体包含名称、价格、成本价、销售数量、点击次数、三级分类ID、商品类型、供应商ID、商户ID、图片文件ID、轮播图、详情、简介、排序、状态、库存、SPU信息、最小起购量等字段 [Source: packages/server/src/modules/goods/goods.entity.ts:1-115]
  • 商品分类实体: GoodsCategory 实体包含名称、上级ID、图片文件ID、层级、状态等字段 [Source: packages/server/src/modules/goods/goods-category.entity.ts:1-39]
  • 服务层: 使用 GenericCrudService 提供标准CRUD操作 [Source: packages/server/src/modules/goods/goods.service.ts:1-9]
  • 随机商品功能: 提供随机商品列表查询，支持分类过滤和图片包含选项 [Source: packages/server/src/api/goods/random.ts:49-111]

实体设计

Goods 实体关键字段:

  • name: 商品名称 (varchar(255))
  • price: 售卖价 (decimal(10,2))
  • costPrice: 成本价 (decimal(10,2))
  • categoryId1, categoryId2, categoryId3: 三级分类ID
  • goodsType: 商品类型 (1实物产品, 2虚拟产品)
  • supplierId: 供应商ID
  • merchantId: 商户ID
  • imageFileId: 商品主图文件ID
  • slideImages: 商品轮播图文件列表 (多对多关联)
  • state: 状态 (1可用, 2不可用)
  • stock: 库存
  • lowestBuy: 最小起购量

GoodsCategory 实体关键字段:

  • name: 类别名称 (varchar(255))
  • parentId: 上级分类ID
  • imageFileId: 分类图片文件ID
  • level: 分类层级
  • state: 状态 (1可用, 2不可用)

集成点

  • 认证集成: 使用 auth-module 的认证中间件 [Source: packages/auth-module/src/middleware/auth.middleware.ts:1]
  • 文件集成: 依赖 file-module 获取图片文件信息 [Source: packages/server/src/modules/goods/goods.entity.ts:4]
  • 数据库: 使用现有 TypeORM 数据源 [Source: architecture/source-tree.md:74]
  • API 设计: 遵循现有 RESTful API 模式 [Source: architecture/api-design-integration.md#API集成策略]

环境配置要求

  • 数据库表: 需要 goods 和 goods_category 表 [Source: packages/server/src/modules/goods/goods.entity.ts:7]
  • 文件存储: 需要配置 MinIO 存储桶 [Source: architecture/source-tree.md:248]

依赖关系

  • 基础设施依赖:
    • @d8d/shared-types - 基础类型定义 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L269-L276]
    • @d8d/shared-utils - 工具函数 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L280-L291]
    • @d8d/shared-crud - CRUD基础设施 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L266-L278]
  • 业务模块依赖:
    • @d8d/user-module - 用户管理 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L321-L334]
    • @d8d/auth-module - 认证管理 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L337-L350]
    • @d8d/file-module - 文件管理 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L353-L366]
    • @d8d/supplier-module - 供应商管理 [Source: packages/server/src/modules/goods/goods.entity.ts#L104-L106]
    • @d8d/merchant-module - 商户管理 [Source: packages/server/src/modules/goods/goods.entity.ts#L112-L114]
  • 测试依赖: @d8d/shared-test-util [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L294-L306]

配置参考

  • package.json: 参考供应商模块配置，统一依赖版本 [Source: packages/supplier-module/package.json#L47-L66]
  • tsconfig.json: 参考供应商模块配置 [Source: packages/supplier-module/tsconfig.json#L1-L16]
  • vitest.config.ts: 参考供应商模块配置 [Source: packages/supplier-module/vitest.config.ts#L1-L21]
  • shared-test-util: 测试基础设施包，提供统一的测试工具 [Source: packages/shared-test-util/package.json#L1-L16]

当前用户权限API路由设计

  • 用户路由: packages/goods-module/src/routes/user-goods-routes.ts - 仅限当前用户使用 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L21-L50]
  • 管理员路由: packages/goods-module/src/routes/admin-goods-routes.ts - 管理员使用的完整权限路由 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L21-L50]
  • 公开商品路由: packages/goods-module/src/routes/public-goods-routes.ts - 公开只读商品查询路由
  • 商品分类路由: packages/goods-module/src/routes/admin-goods-categories.ts - 商品分类管理路由
  • 随机商品路由: packages/goods-module/src/routes/public-goods-random.ts - 公开随机商品查询路由
  • 用户专用Schema: packages/goods-module/src/schemas/user-goods.schema.ts - 移除请求schema中的用户权限相关字段，自动使用当前登录用户权限（响应schema保持完整字段）
  • 管理员专用Schema: packages/goods-module/src/schemas/admin-goods.schema.ts - 保留完整权限字段，允许管理员指定权限
  • 公开商品Schema: packages/goods-module/src/schemas/public-goods.schema.ts - 公开只读商品查询schema
  • 数据权限配置: 使用 shared-crud 的 dataPermission 配置 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L22-L25]
  • 权限验证: 查询、创建、更新、删除操作都会验证用户权限 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L26-L41]

向后兼容性

  • API 兼容: 现有商品API保持不变 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L101]
  • 数据库兼容: 数据库schema保持不变 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L102]
  • 认证兼容: 认证流程保持不变 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L103]

Testing

测试标准

  • 测试文件位置: packages/goods-module/tests/ [Source: architecture/testing-strategy.md#L39-L42]
  • 单元测试: tests/unit/**/*.test.ts [Source: architecture/testing-strategy.md#L39-L42]
  • 集成测试: tests/integration/**/*.test.ts [Source: architecture/testing-strategy.md#L47-L56]
  • 测试框架: Vitest 3.2.4 [Source: architecture/testing-strategy.md#L43]

测试要求

  • 覆盖率目标: 单元测试 ≥ 80%，集成测试 ≥ 60% [Source: architecture/testing-strategy.md#L166-L171]
  • 测试数据库: 使用专用测试数据库，事务回滚 [Source: architecture/testing-strategy.md#L200-L202]
  • 测试模式: 遵循测试金字塔策略 [Source: architecture/testing-strategy.md#L33-L64]
  • 测试参考: 参考供应商模块的集成测试模式 [Source: packages/supplier-module/tests/integration/admin-routes.integration.test.ts]

关键测试场景

  • 商品CRUD操作 [参考: packages/supplier-module/tests/integration/admin-routes.integration.test.ts#L53-L283]
  • 商品分类CRUD操作
  • 随机商品列表查询
  • 商品状态管理 [参考: packages/supplier-module/tests/integration/admin-routes.integration.test.ts#L498-L539]
  • 商品库存管理
  • 商品分类树形结构
  • 认证和权限验证 [参考: packages/supplier-module/tests/integration/admin-routes.integration.test.ts#L73-L78]
  • 图片文件关联验证
  • 公开商品路由测试:
    • 验证公开路由无需认证即可访问
    • 验证只返回可用状态的商品
    • 验证只支持查询操作，不支持创建、更新、删除
    • 验证关联关系正确加载（分类、图片等）
  • 用户路由权限测试: [参考: packages/supplier-module/tests/integration/user-routes.integration.test.ts#L455-L543]
    • 验证用户只能访问和操作授权的数据
    • 验证用户创建商品时自动使用当前用户权限 [参考: packages/supplier-module/tests/integration/user-routes.integration.test.ts#L148-L179]
    • 验证用户无法访问其他权限的数据 [参考: packages/supplier-module/tests/integration/user-routes.integration.test.ts#L246-L277]
  • 管理员路由权限测试: [参考: packages/supplier-module/tests/integration/admin-routes.integration.test.ts#L285-L496]
    • 验证管理员可以访问所有数据 [参考: packages/supplier-module/tests/integration/admin-routes.integration.test.ts#L315-L367]
    • 验证管理员可以为其他权限创建商品 [参考: packages/supplier-module/tests/integration/admin-routes.integration.test.ts#L286-L313]
    • 验证管理员可以更新任何商品 [参考: packages/supplier-module/tests/integration/admin-routes.integration.test.ts#L369-L413]
    • 验证管理员可以删除任何商品 [参考: packages/supplier-module/tests/integration/admin-routes.integration.test.ts#L415-L451]
  • 数据权限配置测试: 验证 dataPermission 配置正确工作

Change Log

Date Version Description Author
2025-11-11 1.0 初始故事创建 Bob (Scrum Master)

Dev Agent Record

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

Agent Model Used

  • James (Developer Agent)

Debug Log References

Completion Notes List

  • 2025-11-12: 商品模块基础结构已完成，包括实体、服务、路由和schema迁移
  • 2025-11-12: 随机商品功能已实现，支持分类过滤和图片包含选项
  • 2025-11-12: 用户权限API的schema文件已创建，但路由文件尚未完成
  • 2025-11-12: 测试套件尚未创建，需要完成集成测试
  • 2025-11-12: 用户路由和管理员路由已创建，配置了数据权限控制
  • 2025-11-12: 用户路由和管理员路由的权限验证已完成，集成测试验证了数据权限控制
  • 2025-11-12: 修复了商品模块的类型检查问题，类型检查已通过
  • 2025-11-12: 公开商品路由已完成，配置了只读权限、状态过滤和关联关系加载
  • 2025-11-12: 测试套件已完成，55个集成测试全部通过，使用了shared-test-util
  • 2025-11-12: 已更新 docs/architecture/source-tree.md 文档，添加商品模块信息

File List

  • packages/goods-module/package.json
  • packages/goods-module/tsconfig.json
  • packages/goods-module/vitest.config.ts
  • packages/goods-module/src/index.ts
  • packages/goods-module/src/entities/goods.entity.ts
  • packages/goods-module/src/entities/goods-category.entity.ts
  • packages/goods-module/src/entities/index.ts
  • packages/goods-module/src/services/goods.service.ts
  • packages/goods-module/src/services/goods-category.service.ts
  • packages/goods-module/src/services/index.ts
  • packages/goods-module/src/schemas/goods.schema.ts
  • packages/goods-module/src/schemas/goods-category.schema.ts
  • packages/goods-module/src/schemas/random.schema.ts
  • packages/goods-module/src/schemas/user-goods.schema.ts
  • packages/goods-module/src/schemas/admin-goods.schema.ts
  • packages/goods-module/src/schemas/public-goods.schema.ts
  • packages/goods-module/src/schemas/index.ts
  • packages/goods-module/src/routes/admin-goods-categories.ts
  • packages/goods-module/src/routes/public-goods-random.ts
  • packages/goods-module/src/routes/user-goods-routes.ts
  • packages/goods-module/src/routes/admin-goods-routes.ts
  • packages/goods-module/src/routes/public-goods-routes.ts
  • packages/goods-module/src/routes/index.ts
  • packages/goods-module/src/types/goods.types.ts
  • packages/goods-module/src/types/index.ts

QA Results

此部分由QA代理在质量审查后填写