---
name: order-management
description: 订单管理模块的业务规则、订单流转状态机、支付与退款逻辑。当涉及订单相关功能开发时必须参考此 Skill。
---

# 订单管理 (Order Management) 业务 Skill

## 适用范围

当任务涉及以下场景时，必须加载并遵循此 Skill：

- 订单列表、订单详情、订单创建
- 支付流程、退款流程
- 发货与物流跟踪
- 订单统计与报表

## 业务规则

### 1. 订单状态机

```
待支付 (pending_payment)
  ├─ 支付成功 → 待发货 (pending_shipment)
  │                ├─ 发货 → 运输中 (shipping)
  │                │            ├─ 签收 → 已完成 (completed)
  │                │            └─ 拒收 → 退回中 (returning)
  │                └─ 申请退款 → 退款中 (refunding)
  ├─ 超时未付 → 已取消 (cancelled) [系统自动, 30分钟]
  └─ 用户取消 → 已取消 (cancelled)
```

**关键约束**:

- 超时取消: 下单后 **30 分钟**未支付自动取消，释放库存
- 退款窗口: 仅在「待发货」状态可申请全额退款
- 已发货订单: 需走退货退款流程（用户寄回 → 确认收货 → 退款）
- 已完成订单: 签收后 **7 天**内可申请售后

### 2. 金额计算规则

- **订单总额** = Σ(商品售价 × 数量) - 优惠金额 + 运费
- **金额精度**: 所有金额计算统一使用 **分 (cent)** 为单位（整数运算），前端展示时 ÷ 100 并保留 2 位小数
- **⚠️ 严禁浮点运算**: 禁止使用 `0.1 + 0.2` 等浮点计算，必须转换为整数

### 3. 订单号规则

- 格式: `ORD{YYYYMMDD}{6位序号}`
- 示例: `ORD2026021600001`
- 订单号由后端生成，前端仅用于展示

## 数据模型

### 核心接口

```typescript
// src/services/order.ts
export async function getOrderList(
  params: OrderQueryParams,
): Promise<API.PageResult<OrderItem>> {}
export async function getOrderDetail(orderId: string): Promise<OrderDetail> {}
export async function cancelOrder(
  orderId: string,
  reason: string,
): Promise<void> {}
export async function shipOrder(
  orderId: string,
  logistics: LogisticsInfo,
): Promise<void> {}
export async function refundOrder(
  orderId: string,
  refundData: RefundRequest,
): Promise<void> {}
```

### 关键类型

```typescript
// src/pages/Order/data.d.ts
type OrderStatus =
  | 'pending_payment'
  | 'pending_shipment'
  | 'shipping'
  | 'completed'
  | 'cancelled'
  | 'refunding'
  | 'returning';

interface OrderItem {
  orderId: string;
  orderNo: string;
  userId: string;
  userName: string;
  items: OrderProduct[];
  totalAmount: number; // 单位: 分
  discountAmount: number; // 单位: 分
  shippingFee: number; // 单位: 分
  payableAmount: number; // 单位: 分 (实付)
  status: OrderStatus;
  paymentMethod?: string;
  paidAt?: string;
  shippedAt?: string;
  completedAt?: string;
  createdAt: string;
  remark?: string;
}

interface OrderProduct {
  productId: string;
  productName: string;
  skuId: string;
  price: number; // 单位: 分
  quantity: number;
  subtotal: number; // 单位: 分
}
```

## UI 交互规范

### 1. 订单列表页

- **组件**: 独立 `QueryFilter` + `ProTable`（字段 ≥ 4）
- **必须筛选项**: 订单号、订单状态、下单时间范围、用户名
- **状态标签颜色**:
  - pending_payment → 橙色 (warning)
  - pending_shipment → 蓝色 (processing)
  - shipping → 青色 (cyan)
  - completed → 绿色 (success)
  - cancelled → 灰色 (default)
  - refunding → 红色 (error)
- **金额展示**: 使用 `valueType: 'money'`，需自定义 render 将分转换为元

### 2. 订单详情页

- **组件**: `ProDescriptions` + `Steps`（状态流转进度条）
- **布局**: 顶部状态进度条 + 基本信息 + 商品清单 + 操作按钮
- **操作按钮**: 根据当前状态动态显示（如待发货显示「发货」按钮，待支付显示「取消」按钮）

### 3. 金额格式化工具函数

```typescript
// src/utils/currency.ts
export const centToYuan = (cent: number): string => (cent / 100).toFixed(2);
export const yuanToCent = (yuan: number): number => Math.round(yuan * 100);
```

## i18n Key 规范

- 菜单: `menu.order.*`
- 页面: `pages.order.*`
- 表单: `order.form.*`
- 状态: `order.status.*`