交易模块

交易模块记录账户所有资金变动明细，是钱包余额每一次变化的完整历史凭证。

交易类型说明

type 说明 金额方向
recharge 充值入账 正（+）
consume 模型调用消费 负（-）
refund 退款到账 正（+）
gift 赠送（代金券/活动） 正（+）
freeze 余额冻结 负（-）
unfreeze 余额解冻 正（+）
adjust 管理员手动调整 正或负

4.1 交易记录列表

GET /api/v1/transactions

查询参数

参数 类型 必填 说明
type string 否 交易类型，见上方枚举，支持多值逗号分隔：recharge,gift
start_date string 否 开始日期，格式 YYYY-MM-DD
end_date string 否 结束日期，格式 YYYY-MM-DD
page int 否 页码，默认 1
page_size int 否 每页条数，默认 20，最大 100
order string 否 排序方向：asc / desc，默认 desc

响应

{
  "code": 0,
  "data": {
    "items": [
      {
        "tx_id": "tx_20240101001",
        "type": "consume",
        "amount": "-0.038",
        "balance_after": "148.46",
        "gift_balance_after": "20.00",
        "currency": "CNY",
        "description": "调用 gpt-4o，768 tokens",
        "related_id": "req_abc123",
        "related_type": "model_request",
        "created_at": "2024-01-01T12:00:00Z"
      },
      {
        "tx_id": "tx_20240101000",
        "type": "recharge",
        "amount": "+100.00",
        "balance_after": "148.50",
        "gift_balance_after": "20.00",
        "currency": "CNY",
        "description": "支付宝充值",
        "related_id": "rch_20240101001",
        "related_type": "recharge_order",
        "created_at": "2024-01-01T11:55:00Z"
      }
    ],
    "total": 256,
    "page": 1,
    "page_size": 20,
    "total_pages": 13
  }
}

响应字段说明

字段 说明
tx_id 交易流水号
type 交易类型
amount 变动金额，正数为入账，负数为支出
balance_after 本次交易后的实账余额
gift_balance_after 本次交易后的赠送余额
related_id 关联业务 ID（请求 ID / 订单 ID 等）
related_type 关联业务类型：model_request / recharge_order / refund_order / voucher / manual_adjust

HTTP 状态码： 200 成功，401 未认证

4.2 交易详情

GET /api/v1/transactions/{tx_id}

{
  "code": 0,
  "data": {
    "tx_id": "tx_20240101001",
    "type": "consume",
    "amount": "-0.038",
    "balance_before": "148.50",
    "balance_after": "148.46",
    "gift_balance_before": "20.00",
    "gift_balance_after": "20.00",
    "currency": "CNY",
    "description": "调用 gpt-4o，768 tokens",
    "related_id": "req_abc123",
    "related_type": "model_request",
    "model_id": "gpt-4o",
    "input_tokens": 512,
    "output_tokens": 256,
    "total_tokens": 768,
    "api_key_id": "key_01HX...",
    "api_key_name": "生产环境",
    "created_at": "2024-01-01T12:00:00Z"
  }
}

HTTP 状态码： 200 成功，404 交易记录不存在

4.3 交易统计

GET /api/v1/transactions/stats

查询参数

参数 类型 必填 说明
period string 否 时间范围：today / week / month / custom，默认 month
start_date string custom 时必填 开始日期
end_date string custom 时必填 结束日期
group_by string 否 趋势聚合粒度：day / week / month，默认 day

响应

{
  "code": 0,
  "data": {
    "period": "month",
    "summary": {
      "total_recharge": "500.00",
      "total_consume": "423.60",
      "total_gift": "20.00",
      "total_refund": "0.00",
      "net_change": "+96.40",
      "transaction_count": 312
    },
    "trend": [
      { "date": "2024-01-01", "consume": "15.20", "recharge": "100.00", "gift": "20.00" },
      { "date": "2024-01-02", "consume": "8.40",  "recharge": "0.00",   "gift": "0.00"  },
      { "date": "2024-01-03", "consume": "12.80", "recharge": "0.00",   "gift": "0.00"  }
    ]
  }
}

4.4 导出交易记录

GET /api/v1/transactions/export

查询参数

参数 类型 必填 说明
format string 否 文件格式：csv / xlsx，默认 csv
start_date string 否 开始日期
end_date string 否 结束日期
type string 否 交易类型筛选

导出为异步任务，响应返回下载链接（有效期 10 分钟）。

响应

{
  "code": 0,
  "data": {
    "download_url": "https://oss.example.com/exports/tx_export_u001_20240101.csv",
    "expires_at": "2024-01-01T12:10:00Z",
    "record_count": 256,
    "file_size": "48KB"
  }
}

HTTP 状态码： 200 成功，400 参数错误（如时间范围超过 1 年）

4.5 管理员查询（管理端）

GET /admin/v1/transactions

在用户侧查询参数基础上，额外支持以下筛选：

参数 类型 说明
user_id string 按指定用户筛选
api_key_id string 按指定 API Key 筛选
min_amount string 最小金额（绝对值）
max_amount string 最大金额（绝对值）

GET /admin/v1/transactions/export

管理员导出支持全平台数据，可追加 user_id 参数导出指定用户的交易记录。