bot-28/docs/admin-finance-api.md

后台财务接口

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

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 同时传，不传时默认今天

返回：

{
  "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

{
  "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

{
  "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：

{
  "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 优先返回订单表保存的三方单号；该字段为空时才从三方响应中提取交易编号，不会返回本系统商户订单号。