Главная Обзор Помощь
Регистрация Вход
186-template-175
/
mini-starter
ответвлено от 155-template-138/mini-starter
2
0
Ответвить 0
Файлы
Дерево: 2fceb13bda
Ветки Метки
mini-starter
/
docs
/
stories
/
005.013.orders-module.story.md

005.013.orders-module.story.md 15 KB
История Исходник

Story 005.013: Orders Module

Status

Draft

Story

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

Acceptance Criteria

  1. 创建 @d8d/orders-module package，包含完整的订单、订单商品和退款管理功能
  2. 从 packages/server/src/modules/orders 迁移订单服务代码，包括订单创建、状态管理、库存更新等业务逻辑
  3. 实现订单的完整CRUD功能，包括订单状态管理、支付状态管理、退款处理等
  4. 提供完整的 TypeScript 类型定义和 API 文档
  5. 集成到现有的认证系统、用户管理系统、商品管理系统和支付系统
  6. 保持与现有认证系统的兼容性
  7. 提供单元测试和集成测试，覆盖率满足要求
  8. 更新 server package 依赖关系，支持按需引入

Tasks / Subtasks

  • [ ] Task 1: 创建 orders-module package 基础结构 (AC: 1)

    • 创建 packages/orders-module 目录结构
    • 配置 package.json，参考商户模块的依赖版本 [Source: packages/merchant-module/package.json#L1-L16]
    • 配置 tsconfig.json，参考商户模块配置 [Source: packages/merchant-module/tsconfig.json#L1-L16]
    • 配置 vitest.config.ts，参考商户模块配置 [Source: packages/merchant-module/vitest.config.ts#L1-L21]
    • 创建 src/index.ts 导出文件

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

    • 迁移 Order 实体到 packages/orders-module/src/entities/
    • 迁移 OrderGoods 实体到 packages/orders-module/src/entities/
    • 迁移 OrderRefund 实体到 packages/orders-module/src/entities/
    • 迁移 OrderSchema、CreateOrderDto、UpdateOrderDto 到 packages/orders-module/src/schemas/
    • 迁移 OrderGoodsSchema、CreateOrderGoodsDto、UpdateOrderGoodsDto 到 packages/orders-module/src/schemas/
    • 迁移 OrderRefundSchema、CreateOrderRefundDto、UpdateOrderRefundDto 到 packages/orders-module/src/schemas/
    • 迁移 CreateOrderRequestDto、CreateOrderResponseDto 到 packages/orders-module/src/schemas/
    • 创建类型定义文件 packages/orders-module/src/types/order.types.ts
    • 更新实体导入路径，使用 workspace:* 依赖

  • [ ] Task 3: 迁移订单服务 (AC: 2, 3)

    • 迁移 OrderService 到 packages/orders-module/src/services/
    • 迁移 OrderGoodsService 到 packages/orders-module/src/services/
    • 迁移 OrderRefundService 到 packages/orders-module/src/services/
    • 重构服务使用 shared-crud 基础设施
    • 更新服务依赖注入配置
    • 确保订单创建的事务逻辑完整迁移

  • [ ] Task 4: 创建订单路由 (AC: 3, 4)

    • 创建订单管理路由 packages/orders-module/src/routes/index.ts
    • 迁移订单的完整CRUD路由，使用 shared-crud 基础设施
    • 迁移订单商品路由
    • 迁移订单退款路由
    • 迁移订单创建专用路由
    • 集成认证中间件
    • 配置用户追踪字段

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

    • 创建 packages/orders-module/src/schemas/user-order.schema.ts - 用户专用schema
    • 移除userId字段，自动使用当前登录用户权限
    • 创建 packages/orders-module/src/schemas/admin-order.schema.ts - 管理员专用schema
    • 保留userId字段，允许管理员指定用户
    • 创建 packages/orders-module/src/routes/user-routes.ts - 仅限当前用户使用的路由
    • 配置数据权限控制，使用 shared-crud 的 dataPermission 配置 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L21-L50]
    • 设置 userIdField: 'userId'，确保用户只能操作自己的数据
    • 使用用户专用schema
    • 创建 packages/orders-module/src/routes/admin-routes.ts - 管理员使用的完整权限路由
    • 配置管理员路由不使用数据权限控制，保持完整CRUD功能
    • 使用管理员专用schema
    • 更新 packages/orders-module/src/routes/index.ts 导出两个路由集合
    • 验证用户路由只能访问和操作当前用户的数据
    • 验证管理员路由可以访问所有用户的数据

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

    • 创建用户路由集成测试 packages/orders-module/tests/integration/user-routes.integration.test.ts
    • 测试用户路由只能访问和操作当前用户的数据
    • 验证用户创建订单时自动使用当前用户ID
    • 验证用户无法访问其他用户的数据
    • 创建管理员路由集成测试 packages/orders-module/tests/integration/admin-routes.integration.test.ts
    • 测试管理员路由可以访问所有用户的数据
    • 验证管理员可以为其他用户创建订单
    • 验证管理员可以更新和删除任何用户的订单
    • 配置测试数据库连接，使用 shared-test-util [Source: packages/shared-test-util/src/integration-test-db.ts#L1-L30]
    • 添加订单状态管理测试场景
    • 测试订单创建的事务逻辑
    • 测试库存更新功能
    • 确保测试覆盖率满足要求

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

    • 更新 server package 依赖，添加 @d8d/orders-module
    • 在 server 中注册订单路由
    • 验证与用户模块的集成
    • 验证与商品模块的集成
    • 验证与配送地址模块的集成
    • 验证与商户模块的集成
    • 验证与供应商模块的集成
    • 确保订单创建功能正常工作

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

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

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/orders-module/ [Source: architecture/source-tree.md#实际项目结构]
  • 代码结构: 遵循现有模块化包模式 [Source: architecture/source-tree.md#包架构层次]
  • 依赖层次: orders-module → auth-module → user-module → shared-crud → shared-utils → shared-types [Source: docs/prd/epic-005-mini-auth-modules-integration.md#依赖层次]

订单功能详情

  • 订单实体: Order 实体包含订单号、用户ID、金额、支付状态、订单状态、收货信息等字段 [Source: packages/server/src/modules/orders/order.entity.ts:1-139]
  • 订单商品实体: OrderGoods 实体包含订单ID、商品ID、数量、价格、状态等字段 [Source: packages/server/src/modules/orders/order-goods.entity.ts:1-82]
  • 订单退款实体: OrderRefund 实体包含订单号、退款订单号、退款金额、状态等字段 [Source: packages/server/src/modules/orders/order-refund.entity.ts:1-40]
  • 服务层: 使用 GenericCrudService 提供标准CRUD操作，OrderService 包含复杂的订单创建事务逻辑 [Source: packages/server/src/modules/orders/order.service.ts:1-180]
  • API路由: 使用 createCrudRoutes 创建完整CRUD路由，包含专用订单创建路由 [Source: packages/server/src/api/orders/index.ts:1-30]

实体设计

Order 实体关键字段:

  • orderNo: 订单号 (varchar(50), unique)
  • userId: 用户ID (int, unsigned)
  • amount: 订单金额 (decimal(10,2), default: 0.00)
  • costAmount: 成本金额 (decimal(10,2), default: 0.00)
  • payAmount: 实际支付金额 (decimal(10,2), default: 0.00)
  • orderType: 订单类型 (int, default: 1, 1实物订单 2虚拟订单)
  • payType: 支付类型 (int, default: 0, 1积分2礼券)
  • payState: 支付状态 (int, default: 0, 0未支付1支付中2支付成功3已退款4支付失败5订单关闭)
  • state: 订单状态 (int, default: 0, 0未发货1已发货2收货成功3已退货)
  • createdBy: 创建用户ID (int, nullable)
  • updatedBy: 更新用户ID (int, nullable)

OrderGoods 实体关键字段:

  • orderId: 订单ID (int, unsigned)
  • goodsId: 商品ID (int, unsigned)
  • goodsName: 商品名称 (varchar(255), nullable)
  • price: 售价 (decimal(10,2), default: 0.00)
  • num: 数量 (int, default: 0)
  • state: 状态 (int, default: 0, 0未发货1已发货)

OrderRefund 实体关键字段:

  • orderNo: 订单号 (varchar(32), nullable)
  • refundOrderNo: 退款订单号 (varchar(32), nullable)
  • refundAmount: 退款金额 (decimal(10,2), nullable)
  • state: 状态 (int, default: 0, 0未退款1退款中2退款成功3退款失败)

集成点

  • 认证集成: 使用 auth-module 的认证中间件 [Source: packages/auth-module/src/middleware/auth.middleware.ts:1]
  • 用户集成: 依赖 user-module 获取用户信息 [Source: packages/server/src/modules/orders/order.entity.ts:124-126]
  • 商品集成: 依赖 goods-module 验证商品信息和更新库存 [Source: packages/server/src/modules/orders/order.service.ts:45-56]
  • 配送地址集成: 依赖 delivery-address-module 获取收货地址信息 [Source: packages/server/src/modules/orders/order.service.ts:73-82]
  • 商户集成: 依赖 merchant-module 获取商户信息 [Source: packages/server/src/modules/orders/order.entity.ts:128-130]
  • 供应商集成: 依赖 supplier-module 获取供应商信息 [Source: packages/server/src/modules/orders/order.entity.ts:132-134]
  • 数据库: 使用现有 TypeORM 数据源 [Source: architecture/source-tree.md:74]
  • API 设计: 遵循现有 RESTful API 模式 [Source: architecture/api-design-integration.md#API集成策略]

环境配置要求

  • 数据库表: 需要 orders、orders_goods、orders_refund 表 [Source: packages/server/src/modules/orders/order.entity.ts:7]
  • 认证配置: 需要配置 JWT 认证 [Source: architecture/api-design-integration.md#API集成策略]

依赖关系

  • 基础设施依赖:
    • @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/goods-module - 商品管理 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L211-L214]
    • @d8d/delivery-address-module - 配送地址管理 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L207-L210]
    • @d8d/merchant-module - 商户管理 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L208-L211]
    • @d8d/supplier-module - 供应商管理 [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L231-L234]
  • 测试依赖: @d8d/shared-test-util [Source: docs/prd/epic-005-mini-auth-modules-integration.md#L294-L306]

配置参考

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

当前用户权限API路由设计

  • 用户路由: packages/orders-module/src/routes/user-routes.ts - 仅限当前用户使用 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L21-L50]
  • 管理员路由: packages/orders-module/src/routes/admin-routes.ts - 管理员使用的完整权限路由 [Source: docs/stories/006.001.shared-crud-data-permission.story.md#L21-L50]
  • 用户专用Schema: packages/orders-module/src/schemas/user-order.schema.ts - 移除请求schema中的用户权限相关字段，自动使用当前登录用户权限（响应schema保持完整字段）
  • 管理员专用Schema: packages/orders-module/src/schemas/admin-order.schema.ts - 保留完整权限字段，允许管理员指定权限
  • 数据权限配置: 使用 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/orders-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]

关键测试场景

  • 订单CRUD操作
  • 订单状态管理
  • 订单支付状态管理
  • 订单退款处理
  • 订单创建的事务逻辑
  • 库存更新功能
  • 认证和权限验证
  • 用户路由权限测试:
    • 验证用户只能访问和操作授权的数据
    • 验证用户创建订单时自动使用当前用户权限
    • 验证用户无法访问其他权限的数据
  • 管理员路由权限测试:
    • 验证管理员可以访问所有数据
    • 验证管理员可以为其他权限创建订单
    • 验证管理员可以更新任何订单
    • 验证管理员可以删除任何订单
  • 数据权限配置测试: 验证 dataPermission 配置正确工作
  • 订单创建事务测试: 验证订单创建、商品明细创建、库存更新的原子性

Change Log

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

Dev Agent Record

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

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results

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