152 lines
4.2 KiB
Markdown
152 lines
4.2 KiB
Markdown
---
|
||
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.*`
|