agent/.opencode/skills/business/order-management/SKILL.md

name, description

name	description
order-management	订单管理模块的业务规则、订单流转状态机、支付与退款逻辑。当涉及订单相关功能开发时必须参考此 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
• 订单号由后端生成，前端仅用于展示

数据模型

核心接口

// 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> {}

关键类型

// 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. 金额格式化工具函数

// 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.*