txagent-y/docs/dev/admin-api/ADMIN-API-05-财务管理.md

ADMIN-API-05 财务管理（FIN）

共 9 个接口：FIN-01~09

钱包写入规范（与 C 端一致）

后台所有涉及 wallet 写入的接口（退款、手动发币、提现打款、提现拒绝解冻等）必须复用 C 端同一套乐观锁 + 单事务模板，禁止任何 UPDATE wallet SET balance = :new_balance 形式的赋值。详细模板见 API-05 订阅系统 顶部"钱包扣款乐观锁规范"。

要点：

1. 任何对 wallet.balance / frozen_balance / total_* 的修改必须使用 balance = balance ± :amount, version = version + 1 WHERE version = :old_version 形式；受影响行数 = 0 → 回滚事务并重试。
2. 同一笔业务的 recharge_order/withdrawal_order/refund_order 状态变更、wallet 写入、wallet_transaction 流水写入必须在同一事务内提交。
3. 退款（FIN-退款）、手动发币（FIN-手动发币）、提现打款（FIN-提现审核打款）等接口在"接口逻辑"节明确写出"复用 API-05 钱包乐观锁模板 + 单事务"。
4. 审计日志（admin_operation_log）写入也包含在同一事务内，避免出现"金额变了但审计缺失"。

状态枚举映射

withdrawal_order.status（提现订单状态）：

DB值	API响应值	说明
1	pending	审核中
2	approved	已通过（待打款）
3	paid	已打款
4	rejected	已拒绝（余额解冻）

refund_order.status（退款订单状态）：

DB值	API响应值	说明
1	processing	处理中
2	completed	已完成
3	rejected	已拒绝

recharge_order.status（充值订单状态）：

DB值	API响应值	说明
1	pending	待支付
2	completed	已完成
3	expired	已超时
4	cancelled	已取消

---

FIN-01 提现审核列表

项目	说明
接口路径	GET /admin/api/v1/finance/withdrawals
接口用途	获取所有提现申请列表
权限要求	财务审核员
涉及表	withdrawal_order, user, withdrawal_account

接口逻辑：

1. 校验管理员权限（permission_key: finance:withdrawal:review）
2. 查询 withdrawal_order 表，支持按 status 筛选（读）
3. 关联 user 获取创作者信息（读）
4. 关联 withdrawal_account 获取收款方式信息（读）
5. 按 created_at 倒序，支持分页

请求参数（Query）：

字段	类型	必选	说明
status	string	否	状态筛选：pending/approved/paid/rejected
startDate	string	否	开始日期（YYYY-MM-DD）
endDate	string	否	结束日期（YYYY-MM-DD）
page	number	否	页码，默认1
pageSize	number	否	每页条数，默认20

响应数据：

字段	类型	说明
list	array	提现列表
list[].withdrawalId	string	提现ID
list[].creator	object	创作者信息
list[].creator.userId	string	用户ID
list[].creator.nickname	string	昵称
list[].creator.avatar	url	头像
list[].amount	number	提现金额（糖心币）
list[].accountType	string	收款类型：bank_card/usdt
list[].accountInfo	string	收款信息（脱敏）
list[].status	string	状态
list[].createdAt	timestamp	申请时间
list[].reviewedAt	timestamp	审核时间
list[].paidAt	timestamp	打款时间
pagination	object	分页信息

---

FIN-02 提现审核通过

项目	说明
接口路径	POST /admin/api/v1/finance/withdrawals/:withdrawalId/approve
接口用途	审核通过提现申请
权限要求	财务审核员
涉及表	withdrawal_order, admin_operation_log

接口逻辑：

1. 校验管理员权限（permission_key: finance:withdrawal:review）
2. 查询 withdrawal_order，校验 status=1（审核中）（读）
3. 更新 status=2（已通过），设置 reviewed_by、reviewed_at（更新）
4. 写入 admin_operation_log（action: approve_withdrawal）（写）

说明： 全部人工审核，不分金额。审核通过后等待线下手动打款。

路径参数：

字段	类型	必选	说明
withdrawalId	string	是	提现ID

请求参数： 无

响应数据：

字段	类型	说明
withdrawalId	string	提现ID
status	string	更新后状态：approved

---

FIN-03 提现审核拒绝

项目	说明
接口路径	POST /admin/api/v1/finance/withdrawals/:withdrawalId/reject
接口用途	拒绝提现申请
权限要求	财务审核员
涉及表	withdrawal_order, wallet, wallet_transaction, notification, admin_operation_log

接口逻辑：

1. 校验管理员权限（permission_key: finance:withdrawal:review）
2. 查询 withdrawal_order，校验 status=1（审核中）（读）
3. 更新 withdrawal_order status=4（已拒绝），设置 reject_reason、reviewed_by、reviewed_at（更新）
4. 解冻创作者钱包余额：复用 API-05 钱包乐观锁模板，单事务内 UPDATE wallet SET balance = balance + :amount, frozen_balance = frozen_balance - :amount, version = version + 1 WHERE user_id = :uid AND version = :old_version
5. 写入 wallet_transaction 流水记录（type=11 提现拒绝退回，direction=1收入）（写）
6. 写入 notification 通知创作者（写）
7. 写入 admin_operation_log（action: reject_withdrawal）（写）

路径参数：

字段	类型	必选	说明
withdrawalId	string	是	提现ID

请求参数（Body）：

字段	类型	必选	说明
rejectReason	string	是	拒绝原因

响应数据：

字段	类型	说明
withdrawalId	string	提现ID
status	string	更新后状态：rejected

---

FIN-04 确认打款

项目	说明
接口路径	POST /admin/api/v1/finance/withdrawals/:withdrawalId/confirm-paid
接口用途	审核通过后，确认已手动打款
权限要求	财务审核员
涉及表	withdrawal_order, wallet, wallet_transaction, admin_operation_log

接口逻辑：

1. 校验管理员权限（permission_key: finance:withdrawal:pay）
2. 查询 withdrawal_order，校验 status=2（已通过待打款）（读）
3. 更新 withdrawal_order status=3（已打款），设置 payment_proof、paid_at（更新）
4. 扣减 wallet 的 frozen_balance：复用 API-05 钱包乐观锁模板，单事务内 UPDATE wallet SET frozen_balance = frozen_balance - :amount, version = version + 1 WHERE user_id = :uid AND version = :old_version AND frozen_balance >= :amount
5. 写入 wallet_transaction 流水记录（type=10 提现完成，direction=2支出）（写）
6. 写入 admin_operation_log（action: confirm_withdrawal_paid）（写）

路径参数：

字段	类型	必选	说明
withdrawalId	string	是	提现ID

请求参数（Body）：

字段	类型	必选	说明
paymentProof	string	否	打款凭证/流水号

响应数据：

字段	类型	说明
withdrawalId	string	提现ID
status	string	更新后状态：paid
paidAt	timestamp	打款确认时间

---

FIN-05 退款处理

项目	说明
接口路径	POST /admin/api/v1/finance/refunds
接口用途	处理用户退款申请
权限要求	财务审核员/客服
涉及表	refund_order, wallet, wallet_transaction, recharge_order, admin_operation_log

接口逻辑：

1. 校验管理员权限（permission_key: finance:refund）
2. 查询 user + wallet 获取用户余额信息（读）
3. 查询 recharge_order 获取原充值订单信息（读）
4. 计算可退金额：只退未消费代币，扣 10% 手续费
   • refund_coin_amount = 可退糖心币数
   • fee_coin_amount = refund_coin_amount * 10%
   • refund_cny_amount = (refund_coin_amount - fee_coin_amount) 对应的人民币金额
5. 复用 API-05 钱包乐观锁模板（单事务）扣减 wallet：UPDATE wallet SET balance = balance - :refund_coin_amount, version = version + 1 WHERE user_id = :uid AND version = :old_version AND balance >= :refund_coin_amount，受影响行数 = 0 → 回滚整个事务
6. 写入 wallet_transaction 流水记录（type=refund）（写）
7. 写入 refund_order 表（status=1 处理中）（写）
8. 发起退款到原支付渠道（异步）
9. 写入 admin_operation_log（action: refund）（写）

请求参数（Body）：

字段	类型	必选	说明
userId	string	是	退款用户ID
rechargeOrderId	string	是	原充值订单ID
refundCoinAmount	number	是	退款糖心币数量
reason	string	是	退款原因

响应数据：

字段	类型	说明
refundId	string	退款单ID
orderNo	string	退款单号
refundCoinAmount	number	退款糖心币
feeCoinAmount	number	手续费糖心币
refundCnyAmount	number	退款人民币金额
payChannel	string	退款支付通道
status	string	状态：processing

---

FIN-06 退款记录列表

项目	说明
接口路径	GET /admin/api/v1/finance/refunds
接口用途	查看所有退款记录
权限要求	财务审核员
涉及表	refund_order, user

接口逻辑：

1. 校验管理员权限（permission_key: finance:refund）
2. 查询 refund_order 表，支持按 status 筛选（读）
3. 关联 user 获取用户信息（读）
4. 按 created_at 倒序，支持分页

请求参数（Query）：

字段	类型	必选	说明
status	string	否	状态筛选：processing/completed/rejected
startDate	string	否	开始日期（YYYY-MM-DD）
endDate	string	否	结束日期（YYYY-MM-DD）
page	number	否	页码，默认1
pageSize	number	否	每页条数，默认20

响应数据：

字段	类型	说明
list	array	退款列表
list[].refundId	string	退款ID
list[].orderNo	string	退款单号
list[].user	object	用户信息
list[].user.userId	string	用户ID
list[].user.nickname	string	昵称
list[].refundCoinAmount	number	退款糖心币
list[].feeCoinAmount	number	手续费
list[].refundCnyAmount	number	退款人民币
list[].payChannel	string	支付通道
list[].status	string	状态
list[].reason	string	退款原因
list[].handledBy	string	处理人
list[].createdAt	timestamp	创建时间
list[].handledAt	timestamp	处理时间
pagination	object	分页信息

---

FIN-07 充值订单列表

项目	说明
接口路径	GET /admin/api/v1/finance/recharge-orders
接口用途	查看所有充值订单（用于对账）
权限要求	财务审核员
涉及表	recharge_order, user

接口逻辑：

1. 校验管理员权限（permission_key: finance:order:view）
2. 查询 recharge_order 表，支持按 status、pay_channel、时间范围筛选（读）
3. 关联 user 获取用户信息（读）
4. 按 created_at 倒序，支持分页

请求参数（Query）：

字段	类型	必选	说明
status	string	否	状态筛选：pending/completed/expired/cancelled
payChannel	string	否	支付通道筛选
startDate	string	否	开始日期（YYYY-MM-DD）
endDate	string	否	结束日期（YYYY-MM-DD）
page	number	否	页码，默认1
pageSize	number	否	每页条数，默认20

响应数据：

字段	类型	说明
list	array	充值订单列表
list[].orderId	string	订单ID
list[].orderNo	string	订单号
list[].user	object	用户信息
list[].user.userId	string	用户ID
list[].user.nickname	string	昵称
list[].cnyAmount	number	人民币金额
list[].coinAmount	number	到账糖心币
list[].bonusCoinAmount	number	赠送糖心币
list[].payChannel	string	支付通道
list[].status	string	状态
list[].paidAt	timestamp	支付时间
list[].createdAt	timestamp	创建时间
pagination	object	分页信息

---

FIN-08 平台收入统计

项目	说明
接口路径	GET /admin/api/v1/finance/revenue
接口用途	查看平台收入汇总
权限要求	财务审核员/超级管理员
涉及表	recharge_order, revenue_share_record, withdrawal_order

接口逻辑：

1. 校验管理员权限（permission_key: stats:finance）
2. 根据时间维度（日/周/月）和时间范围聚合查询：
   • 总充值金额：聚合 recharge_order（status=2 已完成）的 pay_amount（读）
   • 订阅收入（平台分成部分）：聚合 revenue_share_record（order_type=1）的 platform_amount（读）
   • PPV收入（平台分成部分）：聚合 revenue_share_record（order_type=2）的 platform_amount（读）
   • 总提现金额：聚合 withdrawal_order（status=3 已打款）的 amount（读）
   • 平台净收入 = 平台分成收入 - 已提现金额
3. 返回汇总和趋势数据

请求参数（Query）：

字段	类型	必选	说明
granularity	string	否	时间维度：day/week/month，默认 day
startDate	string	否	开始日期（YYYY-MM-DD）
endDate	string	否	结束日期（YYYY-MM-DD）

响应数据：

字段	类型	说明
summary	object	汇总数据
summary.totalRecharge	number	总充值金额（人民币）
summary.subscriptionRevenue	number	订阅收入（平台分成）
summary.ppvRevenue	number	PPV收入（平台分成）
summary.totalWithdrawal	number	总提现金额
summary.netRevenue	number	平台净收入
trend	array	趋势数据
trend[].date	string	日期
trend[].recharge	number	充值金额
trend[].subscriptionRevenue	number	订阅收入
trend[].ppvRevenue	number	PPV收入
trend[].withdrawal	number	提现金额

---

FIN-09 钱包交易流水列表（全站）

项目	说明
接口路径	GET /admin/api/v1/finance/transactions
接口用途	查询全站 wallet_transaction 流水（对账、风控、客服支撑）
权限要求	财务审核员（与充值订单查看一致）
涉及表	wallet_transaction, user

接口逻辑：

1. 校验管理员权限（permission_key: finance:order:view）
2. 查询 wallet_transaction，支持按 userId、type、direction、时间范围筛选（读）
3. 关联 user 获取用户昵称（读）
4. 按 created_at 倒序，支持分页

请求参数（Query）：

字段	类型	必选	说明
userId	string	否	用户 ID 筛选
type	string	否	流水类型，见 API-03 wallet_transaction.type（如 recharge、subscribe、ppv 等）
direction	string	否	方向筛选：in 收入 / out 支出
startDate	string	否	开始日期（YYYY-MM-DD）
endDate	string	否	结束日期（YYYY-MM-DD）
page	number	否	页码，默认 1
pageSize	number	否	每页条数，默认 20

响应数据：

字段	类型	说明
list	array	流水列表
list[].transactionId	string	流水 ID
list[].userId	string	用户 ID
list[].user	object	用户信息（可选）
list[].user.userId	string	用户 ID
list[].user.nickname	string	昵称
list[].type	string	流水类型（与 DB/API-03 枚举一致）
list[].amount	number	金额（糖心币，正数）
list[].direction	string	in 收入 / out 支出
list[].description	string	描述/备注
list[].createdAt	timestamp	创建时间
pagination	object	分页信息