订单模块

订单是发起支付的载体，支持充值订单和会员套餐购买订单两种类型。

订单状态流转

pending（待支付）
  ├── → paid（已支付）→ refunding（退款中）→ refunded（已退款）
  └── → cancelled（已取消）/ expired（已过期）

5.1 订单列表

GET /api/v1/orders

响应：

{
  "code": 0,
  "data": {
    "items": [
      {
        "order_id": "ord_20240101001",
        "type": "recharge",
        "status": "paid",
        "amount": "100.00",
        "currency": "CNY",
        "channel": "alipay",
        "description": "钱包充值 100 元",
        "paid_at": "2024-01-01T12:05:00Z",
        "created_at": "2024-01-01T12:00:00Z"
      }
    ],
    "total": 12,
    "page": 1,
    "page_size": 20
  }
}

5.2 创建订单

POST /api/v1/orders

{
  "type": "membership",
  "plan_id": "plan_basic",
  "period": "yearly",
  "voucher_id": "v_01HX..."
}

响应：

{
  "code": 0,
  "data": {
    "order_id": "ord_20240101002",
    "type": "membership",
    "status": "pending",
    "amount": "490.00",
    "discount_amount": "20.00",
    "final_amount": "470.00",
    "currency": "CNY",
    "expire_at": "2024-01-01T12:30:00Z"
  }
}

5.3 订单详情

GET /api/v1/orders/{order_id}

{
  "code": 0,
  "data": {
    "order_id": "ord_20240101001",
    "type": "recharge",
    "status": "paid",
    "amount": "100.00",
    "discount_amount": "0.00",
    "final_amount": "100.00",
    "currency": "CNY",
    "channel": "alipay",
    "channel_trade_no": "2024010122001XXXX",
    "description": "钱包充值 100 元",
    "voucher_id": null,
    "paid_at": "2024-01-01T12:05:00Z",
    "created_at": "2024-01-01T12:00:00Z",
    "expire_at": "2024-01-01T12:30:00Z"
  }
}

5.4 发起支付

POST /api/v1/orders/{order_id}/pay

{
  "channel": "wechat",
  "client_type": "web",
  "return_url": "https://console.example.com/membership"
}

响应（微信扫码）：

{
  "code": 0,
  "data": {
    "order_id": "ord_20240101002",
    "channel": "wechat",
    "pay_params": {
      "type": "qrcode",
      "code_url": "weixin://wxpay/bizpayurl?pr=xxx"
    },
    "expire_at": "2024-01-01T12:30:00Z"
  }
}

5.5 查询支付状态

GET /api/v1/orders/{order_id}/payment-status

前端可轮询此接口（建议间隔 2 秒），直到 status 为 paid 或超时。

{
  "code": 0,
  "data": {
    "order_id": "ord_20240101002",
    "status": "paid",
    "paid_at": "2024-01-01T12:08:00Z"
  }
}

5.6 取消订单

POST /api/v1/orders/{order_id}/cancel

仅 pending 状态的订单可取消。

{ "reason": "不想买了" }

5.7 申请退款

POST /api/v1/orders/{order_id}/refund

仅 paid 状态且满足退款条件的订单可申请。

{
  "reason": "误操作重复购买",
  "amount": "100.00"
}

响应：

{
  "code": 0,
  "data": {
    "refund_id": "ref_01HX...",
    "order_id": "ord_20240101001",
    "refund_amount": "100.00",
    "status": "processing",
    "estimated_days": 3,
    "created_at": "2024-01-01T15:00:00Z"
  }
}

5.8 导出订单

GET /api/v1/orders/export

响应： 返回文件下载链接（有效期 10 分钟）