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

> 共 9 个接口：FIN-01~09

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

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

要点：
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 | 分页信息 |