# Story 003.001: 修复订单取消功能

## Status
Ready for Review

## Story
**As a** 小程序用户，
**I want** 能够在订单列表页和详情页实际取消订单，
**so that** 订单状态能正确更新，并且有明确的成功/失败反馈

## Acceptance Criteria
1. 在OrderButtonBar组件中实现实际的取消订单API调用
2. 在OrderDetailPage组件中集成取消订单mutation
3. 添加取消原因输入功能
4. 完善错误处理和用户反馈

## Tasks / Subtasks
- [x] **修复OrderButtonBar组件中的取消订单功能** (AC: 1)
  - [x] 添加取消订单API调用到handleCancelOrder函数 `mini/src/components/order/OrderButtonBar/index.tsx` [参考: `packages/orders-module-mt/src/routes/user/cancel-order.mt.ts`]
  - [x] 添加取消原因输入对话框 `mini/src/components/order/OrderButtonBar/index.tsx` [参考: Taro UI组件库]
  - [x] 完善成功和错误处理 `mini/src/components/order/OrderButtonBar/index.tsx`
  - [x] 添加取消后的订单状态更新 `mini/src/components/order/OrderButtonBar/index.tsx`
- [x] **修复OrderDetailPage组件中的取消订单功能** (AC: 2)
  - [x] 集成取消订单mutation到实际API调用 `mini/src/pages/order-detail/index.tsx` [参考: `packages/orders-module-mt/src/routes/user/cancel-order.mt.ts`]
  - [x] 添加取消原因输入功能 `mini/src/pages/order-detail/index.tsx`
  - [x] 完善错误处理和用户反馈 `mini/src/pages/order-detail/index.tsx`
  - [x] 确保取消后页面状态正确更新 `mini/src/pages/order-detail/index.tsx`
  - [ ] **修复OrderDetailPage测试问题** (后续任务)
    - [ ] 修复API路径匹配问题 [对照: `mini/tests/unit/components/order/OrderButtonBar.test.tsx`]
    - [ ] 修复对话框渲染测试 [对照: `mini/tests/unit/components/order/OrderButtonBar.test.tsx`]
    - [ ] 修复网络检查测试 [对照: `mini/tests/unit/components/order/OrderButtonBar.test.tsx`]
- [x] **添加取消原因输入功能** (AC: 3)
  - [x] 创建取消原因输入组件 `mini/src/components/common/CancelReasonDialog/index.tsx` [使用shadcn/ui Dialog组件]
  - [x] 集成到OrderButtonBar和OrderDetailPage `mini/src/components/order/OrderButtonBar/index.tsx`, `mini/src/pages/order-detail/index.tsx`
  - [x] 添加取消原因验证 `mini/src/components/common/CancelReasonDialog/index.tsx`
- [x] **完善错误处理和用户反馈** (AC: 4)
  - [x] 添加网络错误处理 `mini/src/components/order/OrderButtonBar/index.tsx`, `mini/src/pages/order-detail/index.tsx`
  - [x] 添加订单状态验证 `mini/src/components/order/OrderButtonBar/index.tsx`, `mini/src/pages/order-detail/index.tsx` [参考: `packages/orders-module-mt/src/services/order.mt.service.ts#cancelOrder`]
  - [x] 添加用户友好的错误消息 `mini/src/components/order/OrderButtonBar/index.tsx`, `mini/src/pages/order-detail/index.tsx`
  - [x] 添加加载状态指示器 `mini/src/components/order/OrderButtonBar/index.tsx`, `mini/src/pages/order-detail/index.tsx`

## Dev Notes

### 技术栈信息 [Source: architecture/tech-stack.md#现有技术栈维护]
- **前端框架**: React 19.1.0 + TypeScript
- **小程序框架**: Taro
- **状态管理**: @tanstack/react-query (服务端状态管理)
- **HTTP客户端**: 基于Hono Client的封装
- **API调用**: RPC类型安全

### 项目结构信息 [Source: architecture/source-tree.md#实际项目结构]
- **小程序项目**: `mini/src/`
- **订单组件**: `mini/src/components/order/`
  - `OrderButtonBar/index.tsx` - 订单操作按钮栏
  - `OrderCard/index.tsx` - 订单卡片组件
- **订单页面**: `mini/src/pages/order-detail/index.tsx` - 订单详情页
- **API客户端**: `mini/src/api.ts` - RPC客户端配置

### 多租户订单模块信息 [Source: packages/orders-module-mt/src/routes/user/cancel-order.mt.ts]
- **取消订单API**: `POST /api/v1/orders/cancel-order`
- **请求参数**:
  ```typescript
  {
    orderId: number, // 订单ID
    reason: string   // 取消原因
  }
  ```
- **响应格式**:
  ```typescript
  {
    success: boolean, // 操作是否成功
    message: string   // 操作结果消息
  }
  ```

### 订单状态定义 [Source: packages/orders-module-mt/src/entities/order.mt.entity.ts]
- **支付状态 (payState)**:
  - `0`: 未支付
  - `2`: 支付成功
  - `5`: 订单关闭
- **订单状态 (state)**:
  - `0`: 未发货
  - `1`: 已发货
  - `2`: 收货成功
  - `3`: 已退货

### 取消订单业务逻辑 [Source: packages/orders-module-mt/src/services/order.mt.service.ts#cancelOrder]
- **状态验证**: 仅允许取消未发货且支付状态为0或2的订单
- **已支付订单**: 自动触发退款流程
- **未支付订单**: 恢复商品库存
- **数据更新**: 更新订单状态为5（订单关闭），记录取消原因和时间

### 后端模块测试要求 [Source: docs/architecture/testing-strategy.md#测试金字塔策略]
- **单元测试**: 服务逻辑测试，验证业务规则和数据处理
- **集成测试**: 验证API路由和服务集成
- **测试框架**: Vitest
- **测试位置**: `packages/orders-module-mt/tests/unit/` 目录

### 编码标准 [Source: architecture/coding-standards.md#关键集成规则]
- **RPC客户端架构**: 直接使用导出的客户端实例
- **类型安全**: 使用Hono的InferRequestType和InferResponseType
- **组件调用规范**: 直接调用 `api.$method` 方法
- **错误处理**: 完善的错误处理和用户反馈机制

## Testing

### 小程序前端测试
#### 测试标准 [Source: docs/architecture/testing-strategy.md#小程序测试架构]
- **测试框架**: Jest + Testing Library
- **测试类型**: 组件单元测试 + 集成测试
- **测试位置**: `mini/tests/unit/` 目录
- **覆盖率要求**: 核心业务逻辑 > 80%

#### 具体测试要求
- **OrderButtonBar组件测试** `mini/tests/unit/components/order/OrderButtonBar.test.tsx`
  - 验证取消订单API调用正确
  - 验证取消原因输入功能
  - 验证成功和错误处理
  - 验证订单状态更新
  - 验证用户反馈机制

- **OrderDetailPage组件测试** `mini/tests/unit/pages/order-detail/order-detail.test.tsx`
  - 验证取消订单mutation集成
  - 验证取消原因输入功能
  - 验证页面状态正确更新
  - 验证错误处理和用户反馈

- **CancelReasonDialog组件测试** `mini/tests/unit/components/common/CancelReasonDialog.test.tsx`
  - 验证取消原因输入验证
  - 验证对话框显示/隐藏逻辑
  - 验证表单提交功能

### 后端模块测试
#### 测试标准 [Source: packages/orders-module-mt/package.json#测试配置]
- **测试框架**: Vitest
- **测试类型**: 单元测试 + 集成测试
- **测试位置**: `packages/orders-module-mt/tests/unit/` 目录
- **覆盖率要求**: 核心业务逻辑 > 80%

#### 具体测试要求
- **取消订单服务测试** `packages/orders-module-mt/tests/unit/services/order.mt.service.test.ts`
  - 验证订单状态验证逻辑
  - 验证退款流程触发
  - 验证库存恢复逻辑
  - 验证事务处理正确性

- **取消订单路由测试** `packages/orders-module-mt/tests/unit/routes/user/cancel-order.mt.test.ts`
  - 验证请求参数验证
  - 验证身份认证中间件
  - 验证错误响应格式
  - 验证成功响应格式

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|---------|
| 2025-11-22 | 1.0 | 初始故事创建 | Bob |

## Dev Agent Record
*This section is populated by the development agent during implementation*

### Agent Model Used
*To be filled by dev agent*

### Debug Log References
*To be filled by dev agent*

### Completion Notes List
*To be filled by dev agent*

### File List
*To be filled by dev agent*

## QA Results
*Results from QA Agent QA review of the completed story implementation*