# 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

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

- [x] Task 2: 迁移订单实体和类型定义 (AC: 2, 4)
  - [x] 迁移 Order 实体到 packages/orders-module/src/entities/
  - [x] 迁移 OrderGoods 实体到 packages/orders-module/src/entities/
  - [x] 迁移 OrderRefund 实体到 packages/orders-module/src/entities/
  - [x] 迁移 OrderSchema、CreateOrderDto、UpdateOrderDto 到 packages/orders-module/src/schemas/
  - [x] 迁移 OrderGoodsSchema、CreateOrderGoodsDto、UpdateOrderGoodsDto 到 packages/orders-module/src/schemas/
  - [x] 迁移 OrderRefundSchema、CreateOrderRefundDto、UpdateOrderRefundDto 到 packages/orders-module/src/schemas/
  - [x] 迁移 CreateOrderRequestDto、CreateOrderResponseDto 到 packages/orders-module/src/schemas/
  - [x] 创建类型定义文件 packages/orders-module/src/types/order.types.ts
  - [x] 更新实体导入路径，使用 workspace:* 依赖

- [x] Task 3: 迁移订单服务 (AC: 2, 3)
  - [x] 迁移 OrderService 到 packages/orders-module/src/services/
  - [x] 迁移 OrderGoodsService 到 packages/orders-module/src/services/
  - [x] 迁移 OrderRefundService 到 packages/orders-module/src/services/
  - [x] 重构服务使用 shared-crud 基础设施
  - [x] 更新服务依赖注入配置
  - [x] 确保订单创建的事务逻辑完整迁移

- [x] Task 4: 创建管理员路由 (AC: 3, 4)
  - [x] 创建管理员路由目录 `packages/orders-module/src/routes/admin/`
  - [x] 创建管理员订单路由 `packages/orders-module/src/routes/admin/orders.ts`
    - **迁移源**: `packages/server/src/api/orders/index.ts`
    - **配置**: 无数据权限限制，完整CRUD功能
    - **集成**: auth-module 认证中间件
  - [x] 创建管理员订单商品路由 `packages/orders-module/src/routes/admin/order-items.ts`
    - **迁移源**: `packages/server/src/api/orders-goods/index.ts`
    - **配置**: 无数据权限限制，完整CRUD功能
    - **集成**: auth-module 认证中间件
  - [x] 创建管理员退款路由 `packages/orders-module/src/routes/admin/refunds.ts`
    - **迁移源**: `packages/server/src/api/orders-refund/index.ts`
    - **配置**: 无数据权限限制，完整CRUD功能
    - **集成**: auth-module 认证中间件

- [x] Task 5: 创建用户路由 (AC: 3, 4, 6)
  - [x] 创建用户路由目录 `packages/orders-module/src/routes/user/`
  - [x] 创建用户订单路由 `packages/orders-module/src/routes/user/orders.ts`
    - **迁移源**: `packages/server/src/api/orders/index.ts`
    - **配置**: 数据权限 `{ enabled: true, userIdField: 'userId' }`
    - **集成**: auth-module 认证中间件
  - [x] 创建用户订单商品路由 `packages/orders-module/src/routes/user/order-items.ts`
    - **迁移源**: `packages/server/src/api/orders-goods/index.ts`
    - **配置**: 数据权限 `{ enabled: true, userIdField: 'order.userId' }`
    - **集成**: auth-module 认证中间件
  - [x] 创建用户退款路由 `packages/orders-module/src/routes/user/refunds.ts`
    - **迁移源**: `packages/server/src/api/orders-refund/index.ts`
    - **配置**: 数据权限 `{ enabled: true, userIdField: 'order.userId' }`
    - **集成**: auth-module 认证中间件

- [x] Task 6: 创建订单创建专用路由 (AC: 3, 4)
  - [x] 创建订单创建路由 `packages/orders-module/src/routes/create-order.ts`
    - **迁移源**: `packages/server/src/api/orders/create-order.ts`
    - **配置**: 自动注入当前用户ID，仅限用户使用
    - **集成**: auth-module 认证中间件

- [x] Task 7: 创建统一路由导出 (AC: 3, 4, 6)
  - [x] 创建统一路由导出 `packages/orders-module/src/routes/index.ts`
    - 导出管理员路由组 `/admin/*`
    - 导出用户路由组 `/user/*`
    - 导出订单创建路由 `/create-order`
  - [x] 配置用户追踪字段
  - [x] 验证权限控制逻辑

- [x] Task 8: 创建测试套件 (AC: 7)
  - [x] 创建用户订单路由集成测试 packages/orders-module/tests/integration/user-orders.integration.test.ts
    - **参考**: `packages/goods-module/tests/integration/user-goods-routes.integration.test.ts`
    - 测试用户订单路由只能访问和操作当前用户的数据
    - 验证用户创建订单时自动使用当前用户ID
    - 验证用户无法访问其他用户的订单
  - [x] 创建用户订单商品路由集成测试 packages/orders-module/tests/integration/user-order-items.integration.test.ts
    - **参考**: `packages/goods-module/tests/integration/user-goods-routes.integration.test.ts`
    - 测试用户只能查看自己订单的商品
    - 验证用户无法访问其他用户订单的商品
  - [x] 创建用户退款路由集成测试 packages/orders-module/tests/integration/user-refunds.integration.test.ts
    - **参考**: `packages/goods-module/tests/integration/user-goods-routes.integration.test.ts`
    - 测试用户只能申请自己订单的退款
    - 验证用户无法访问其他用户的退款记录
  - [x] 创建管理员订单路由集成测试 packages/orders-module/tests/integration/admin-orders.integration.test.ts
    - **参考**: `packages/goods-module/tests/integration/admin-goods-routes.integration.test.ts`
    - 测试管理员可以访问所有用户的订单数据
    - 验证管理员可以为其他用户创建订单
    - 验证管理员可以更新和删除任何用户的订单
  - [x] 创建管理员订单商品路由集成测试 packages/orders-module/tests/integration/admin-order-items.integration.test.ts
    - **参考**: `packages/goods-module/tests/integration/admin-goods-routes.integration.test.ts`
    - 测试管理员可以访问所有订单的商品数据
    - 验证管理员可以管理任何订单的商品
  - [x] 创建管理员退款路由集成测试 packages/orders-module/tests/integration/admin-refunds.integration.test.ts
    - **参考**: `packages/goods-module/tests/integration/admin-goods-routes.integration.test.ts`
    - 测试管理员可以访问所有用户的退款记录
    - 验证管理员可以处理任何用户的退款申请
  - [x] 创建订单创建路由集成测试 packages/orders-module/tests/integration/create-order.integration.test.ts
    - **参考**: `packages/goods-module/tests/integration/admin-goods-routes.integration.test.ts`
    - 测试订单创建功能正常工作
    - 验证订单创建时自动注入当前用户ID
    - 测试订单创建的事务逻辑
  - [x] 配置测试数据库连接，使用 shared-test-util [Source: packages/shared-test-util/src/integration-test-db.ts#L1-L30]
  - [x] 添加订单状态管理测试场景
  - [x] 测试库存更新功能
  - [x] 确保测试覆盖率满足要求

- [ ] Task 9: 集成到现有系统 (AC: 5, 6, 8)
  - [ ] 更新 server package 依赖，添加 @d8d/orders-module
  - [ ] 在 server 中注册订单路由
  - [ ] 验证与用户模块的集成
  - [ ] 验证与商品模块的集成
  - [ ] 验证与配送地址模块的集成
  - [ ] 验证与商户模块的集成
  - [ ] 验证与供应商模块的集成
  - [ ] 确保订单创建功能正常工作

- [ ] Task 10: 验证和文档 (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]

### 管理员/用户权限路由设计
- **管理员路由**: `packages/orders-module/src/routes/admin/` - 管理员使用的完整权限路由
  - `orders.ts` - 管理员订单管理（无数据权限限制）
  - `order-items.ts` - 管理员订单商品管理（无数据权限限制）
  - `refunds.ts` - 管理员退款管理（无数据权限限制）
- **用户路由**: `packages/orders-module/src/routes/user/` - 仅限当前用户使用的路由
  - `orders.ts` - 用户订单操作（数据权限：userIdField: 'userId'）
  - `order-items.ts` - 用户订单商品查看（数据权限：userIdField: 'userId'）
  - `refunds.ts` - 用户退款申请（数据权限：userIdField: 'userId'）
- **订单创建路由**: `packages/orders-module/src/routes/create-order.ts` - 专用订单创建路由
- **认证集成**: 使用 auth-module 认证中间件 [Source: packages/auth-module/src/middleware/auth.middleware.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操作
- 订单状态管理
- 订单支付状态管理
- 订单退款处理
- 订单创建的事务逻辑
- 库存更新功能
- 认证和权限验证
- **用户订单路由权限测试**:
  - 验证用户只能访问和操作自己的订单数据
  - 验证用户创建订单时自动使用当前用户ID
  - 验证用户无法访问其他用户的订单
- **用户订单商品路由权限测试**:
  - 验证用户只能查看自己订单的商品
  - 验证用户无法访问其他用户订单的商品
- **用户退款路由权限测试**:
  - 验证用户只能申请自己订单的退款
  - 验证用户无法访问其他用户的退款记录
- **管理员订单路由权限测试**:
  - 验证管理员可以访问所有用户的订单数据
  - 验证管理员可以为其他用户创建订单
  - 验证管理员可以更新和删除任何用户的订单
- **管理员订单商品路由权限测试**:
  - 验证管理员可以访问所有订单的商品数据
  - 验证管理员可以管理任何订单的商品
- **管理员退款路由权限测试**:
  - 验证管理员可以访问所有用户的退款记录
  - 验证管理员可以处理任何用户的退款申请
- **订单创建路由测试**:
  - 验证订单创建功能正常工作
  - 验证订单创建时自动注入当前用户ID
  - 测试订单创建的事务逻辑
- **数据权限配置测试**: 验证 dataPermission 配置正确工作
- **订单创建事务测试**: 验证订单创建、商品明细创建、库存更新的原子性

## Change Log

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

## Dev Agent Record

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

### Agent Model Used
- Claude Code (d8d-model)

### Completion Notes List
- ✅ 已完成任务1-7：创建独立的 @d8d/orders-module 包
- ✅ 迁移了完整的订单管理功能，包括实体、服务、路由和类型定义
- ✅ 实现了管理员和用户权限分离的路由设计
- ✅ 保留了订单创建的事务逻辑和库存更新功能
- ✅ 配置了完整的数据权限控制和认证集成
- ✅ 创建了27个文件，1825行代码
- ✅ 修复所有TypeScript类型错误，类型检查完全通过
- ✅ 使用共享工具包 `@d8d/shared-utils` 的 `AppDataSource`
- ✅ 使用共享类型包 `@d8d/shared-types` 的 `AuthContext`
- ✅ 修复数据权限配置，使用正确的 `DataPermissionOptions` 格式
- ✅ 已完成任务8：创建完整的测试套件
  - ✅ 创建了8个集成测试文件，77个测试用例
  - ✅ 所有77个集成测试全部通过
  - ✅ 创建了测试数据工厂 `OrdersTestDataFactory` 提高代码复用性
  - ✅ 修复了Schema验证和关联数据问题
  - ✅ 重构用户退款路由为自定义路由处理权限验证
  - ✅ 重命名简单测试文件为 `entity-configuration.integration.test.ts`
- 🔄 剩余任务9-10：系统集成、验证文档

### File List
- packages/orders-module/package.json
- packages/orders-module/tsconfig.json
- packages/orders-module/vitest.config.ts
- packages/orders-module/src/index.ts
- packages/orders-module/src/entities/index.ts
- packages/orders-module/src/entities/order.entity.ts
- packages/orders-module/src/entities/order-goods.entity.ts
- packages/orders-module/src/entities/order-refund.entity.ts
- packages/orders-module/src/schemas/index.ts
- packages/orders-module/src/schemas/order.schema.ts
- packages/orders-module/src/schemas/order-goods.schema.ts
- packages/orders-module/src/schemas/order-refund.schema.ts
- packages/orders-module/src/schemas/create-order.schema.ts
- packages/orders-module/src/services/index.ts
- packages/orders-module/src/services/order.service.ts
- packages/orders-module/src/services/order-goods.service.ts
- packages/orders-module/src/services/order-refund.service.ts
- packages/orders-module/src/services/user-refunds.service.ts
- packages/orders-module/src/routes/index.ts
- packages/orders-module/src/routes/admin/orders.ts
- packages/orders-module/src/routes/admin/order-items.ts
- packages/orders-module/src/routes/admin/refunds.ts
- packages/orders-module/src/routes/user/orders.ts
- packages/orders-module/src/routes/user/order-items.ts
- packages/orders-module/src/routes/user/refunds.ts
- packages/orders-module/src/routes/create-order.ts
- packages/orders-module/src/types/index.ts
- packages/orders-module/src/types/order.types.ts
- packages/orders-module/tests/integration/entity-configuration.integration.test.ts
- packages/orders-module/tests/integration/create-order.integration.test.ts
- packages/orders-module/tests/integration/user-orders.integration.test.ts
- packages/orders-module/tests/integration/user-order-items.integration.test.ts
- packages/orders-module/tests/integration/admin-orders.integration.test.ts
- packages/orders-module/tests/integration/admin-order-items.integration.test.ts
- packages/orders-module/tests/integration/user-refunds.integration.test.ts
- packages/orders-module/tests/integration/admin-refunds.integration.test.ts
- packages/orders-module/tests/utils/test-data-factory.ts

## QA Results

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