# 后台财务接口

所有接口需要后台登录令牌：

```http
Authorization: Bearer <token>
```

POST 请求使用 `Content-Type: application/json`。统一响应：`code = 0` 表示成功，业务数据在 `data`；失败时 `code != 0`，原因在 `msg`。金额字段均为保留两位小数的字符串。

## 1. 出入款汇总

### GET `/admin/funds/summary`

参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `start_date` | 否 | 开始日期，`Y-m-d`；与 `end_date` 同时传，不传时默认今天 |
| `end_date` | 否 | 结束日期，`Y-m-d`；与 `start_date` 同时传，不传时默认今天 |

返回：

```json
{
  "code": 0,
  "data": {
    "start_date": "2026-08-11",
    "end_date": "2026-08-11",
    "income": [
      {"key": "company_deposit", "label": "公司入款", "amount": "0.00", "people": 0},
      {"key": "third_party_deposit", "label": "第三方支付（入款）", "amount": "1000.00", "people": 1},
      {"key": "manual_credit", "label": "人工上分", "amount": "2000.00", "people": 1},
      {"key": "member_withdraw_deduction", "label": "会员出款扣除", "amount": "0.00", "people": 0}
    ],
    "expense": [
      {"key": "member_withdrawal", "label": "会员出款", "amount": "0.00", "people": 0},
      {"key": "manual_withdrawal", "label": "人工出款", "amount": "0.00", "people": 0},
      {"key": "vip_discount", "label": "给予优惠（VIP 折扣）", "amount": "0.00", "people": 0},
      {"key": "rebate", "label": "给予返点", "amount": "0.00", "people": 0},
      {"key": "bonus", "label": "优惠金", "amount": "0.00", "people": 0},
      {"key": "third_party_fee", "label": "第三方手续费", "amount": "0.00", "people": 0},
      {"key": "third_party_auto_withdrawal", "label": "第三方支付出款（自动出款）", "amount": "0.00", "people": 0},
      {"key": "third_party_auto_withdrawal_fee", "label": "第三方支付自动出款手续费", "amount": "0.00", "people": 0}
    ],
    "income_total": "3000.00",
    "expense_total": "0.00"
  }
}
```

前端直接遍历 `income`、`expense`。每项固定返回 `key`、`label`、`amount`、`people`。

汇总金额统一按钱包余额单位统计；USDT 会员出款使用订单实际扣减的钱包金额。

当前库没有独立的 VIP 折扣流水，因此 `vip_discount` 固定返回 `0.00 / 0人`。

## 2. 人工稽查

### GET `/admin/manualAudit`

参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `page` | 否 | 默认 `1` |
| `limit` | 否 | 默认 `20`，最大 `200` |
| `member_id` | 否 | 会员 ID |
| `first_name` | 否 | 会员昵称，模糊匹配 |
| `transaction_type` | 否 | `credit` 人工上分；`debit` 人工下分 |
| `change_type` | 否 | 上分类型或 `人工扣款` |
| `status` | 否 | `0` 失败；`1` 成功 |
| `start_date` | 否 | 交易开始日期，`Y-m-d` |
| `end_date` | 否 | 交易结束日期，`Y-m-d` |

返回 `data.total`、`data.data` 和筛选/表单选项 `data.options`。

列表项主要字段：

| 字段 | 说明 |
| --- | --- |
| `id` | 稽查记录 ID，查看详情时使用 |
| `request_id` | 本次人工操作的幂等请求 ID |
| `admin_id` | 操作管理员 ID；历史导入记录可能为 `null` |
| `balance_log_id` | 成功落账后的资金流水 ID；失败记录为 `null` |
| `member_id` / `username` / `first_name` | 会员 ID、账号、昵称 |
| `transaction_type` / `transaction_type_text` | `credit/debit`、人工上分/人工下分 |
| `change_type` | 充值类型或人工扣款 |
| `level_before_name` / `level_after_name` | 操作当时保存的会员等级名称 |
| `amount` | 显示金额，始终为正数 |
| `signed_amount` | 带正负号的实际变动金额 |
| `before_balance` / `after_balance` | 操作前后余额；用户或钱包不存在时可能为 `null` |
| `status` / `status_text` | `0/失败`、`1/成功` |
| `remark` / `failure_reason` / `created_at` | 说明、失败原因、交易时间 |

`data.options.credit_types` 用于人工上分弹窗的充值类型下拉框。

列表同时返回成功和失败记录，`data.options.statuses` 可直接用于状态筛选。

### POST `/admin/manualAudit/topUp`

```json
{
  "request_id": "7fd7a3cb-95f9-4acd-84e2-1ccbd211af92",
  "member_id": "10001",
  "change_type": "人工充值",
  "amount": 2000,
  "remark": "人工上分"
}
```

`request_id` 必填，前端每次确认操作时生成一个 UUID（可使用 `crypto.randomUUID()`）。网络超时重试必须沿用同一个 UUID；新操作必须生成新 UUID。

`change_type` 可选值由列表接口的 `options.credit_types` 提供。`remark` 可不传。成功时 `data` 返回完整稽查记录。

人工上分不会触发前台充值活动赠送。

### POST `/admin/manualAudit/debit`

```json
{
  "request_id": "10c2c632-92ee-419a-b550-e459454a2802",
  "member_id": "10001",
  "amount": 1000,
  "remark": "人工下分"
}
```

`request_id` 规则与人工上分相同。余额不足、用户不存在或钱包不存在时返回非零 `code`，同时 `data` 返回已保存的失败稽查记录；成功时 `data` 返回完整稽查记录。

### GET `/admin/manualAudit/detail?id=1`

返回字段与列表项相同，供“查看”弹窗使用。

## 3. 第三方入款

### GET `/admin/thirdPartyDeposit`

参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `page` / `limit` | 否 | 默认 `1/20`，`limit` 最大 `200` |
| `member_id` | 否 | 会员 ID |
| `payment_company` | 否 | `sanjin`、`jd`、`no`、`zimu` |
| `payment_method` | 否 | 支付方式，使用返回的选项值 |
| `channel` | 否 | 通道编号 |
| `status` | 否 | `0` 待处理、`1` 处理中、`2` 成功、`3` 失败 |
| `platform` | 否 | PC、Android、iOS、WeChat 等，使用返回的选项值 |
| `submit_start_date` / `submit_end_date` | 否 | 提交日期范围，`Y-m-d` |
| `credit_start_date` / `credit_end_date` | 否 | 到账日期范围，`Y-m-d` |

返回 `data.total`、`data.data` 和全部筛选项 `data.options`：

```json
{
  "code": 0,
  "data": {
    "total": 1,
    "data": [
      {
        "id": 1,
        "member_id": "10001",
        "username": "test01",
        "first_name": "test01",
        "payment_company": "zimu",
        "payment_company_name": "808支付",
        "payment_method": "微信",
        "channel_code": "ZIMUpay",
        "amount": "1000.00",
        "fee": "20.00",
        "before_balance": "5000.00",
        "after_balance": "6000.00",
        "order_no": "order_001",
        "gateway_order_no": "gateway_001",
        "gateway_response": "gateway_001",
        "submitted_at": "2026-08-05 10:20:30",
        "credited_at": "2026-08-05 10:25:10",
        "platform": "PC",
        "status": 2,
        "status_text": "成功"
      }
    ],
    "options": {
      "payment_companies": [],
      "payment_methods": [],
      "statuses": [],
      "platforms": []
    }
  }
}
```

未到账订单的 `before_balance`、`after_balance`、`credited_at` 为 `null`。

`platform` 取该会员提交订单前最近一次成功登录的平台；没有平台登录记录时返回空字符串。

### GET `/admin/thirdPartyDeposit/detail?id=1`

返回列表项全部字段，另外包含：

| 字段 | 说明 |
| --- | --- |
| `remark` | 订单备注 |
| `admin_note` | 后台备注 |
| `pay_data` | 发起支付时的三方响应，敏感签名字段已移除 |
| `callback_data` | 三方回调内容，敏感签名字段已移除 |

`gateway_response` 优先返回订单表保存的三方单号；该字段为空时才从三方响应中提取交易编号，不会返回本系统商户订单号。