# 财务功能实施计划

## 目标

在后台左侧主导航增加“财务”，提供按中国时区日期筛选的全站财务总览、每日账目和资金明细。首版复用现有订单、打手资金申请、钱包流水和售后数据，不改变接单、充值、提现的现有业务流程。

## 已实现范围

- `/admin/finance` 页面和主导航入口。
- `/api/v1/admin/finance/summary`：返回日期范围内的日报和汇总指标。
- `/api/v1/admin/finance/transactions`：返回分页资金明细，并支持账目类型、渠道筛选。
- 日期范围支持 `YYYY-MM-DD HH:mm`，精确到分钟；日报仍按 `Asia/Shanghai` 自然日切桶。
- 日界线固定为 `Asia/Shanghai`，前端金额展示为元，数据库金额仍使用分。
- 总览指标：订单收款、订单退款、打手报酬、已确认提现、充值入账、售后追缴退还、净现金流、当前钱包余额/冻结/待解冻/待提现。
- 渠道日报按“日期 + 渠道 + 账目类型”汇总笔数和金额，订单渠道显示为 `provider/platform`，打手资金显示为提现/充值渠道。
- 原“接单平台 → 资金”页签继续用于打手资金申请审核和资金配置。
- 新增独立 `finance` 后台角色：仅显示财务和资金审核入口，可访问财务报表、资金申请列表/审核，不可访问订单、任务和系统概览。
- 管理员拥有全部财务权限，普通运营保留查看/审核权限，客服不获得财务权限。

## 财务口径

1. 订单收款按 `paid_at`（缺失时回退 `created_at`）归属日期。
2. 退款首版按订单 `pay_status=refunded` 的订单金额统计；部分退款明细需要后续接入独立退款流水。
3. 打手报酬取 `reward_settlement`、`sharing_reward` 钱包流水。
4. 已确认提现取资金申请 `status=approved` 且有 `reviewed_at` 的金额，避免和钱包 `withdraw_paid` 零金额流水重复计算。
5. 充值入账取已通过的充值申请；押金冻结/解冻只作为资金占用变化，不计入收入。
6. 净现金流 = 收款 + 充值 + 打手资金回收 - 订单退款 - 打手提现 - 售后追缴退还。

## 后续迭代

### 二期：人工打款可追踪

- 将提现审核和实际打款拆分。
- 增加打款时间、操作人、流水号、付款凭证和备注。
- 增加“审核通过待打款”“已打款”状态，历史 `approved` 数据保持兼容。

### 三期：统一财务总账

- 新增 append-only `finance_transactions` 表。
- 对订单收款、退款、充值、提现、结算和售后资金动作双写统一流水。
- 增加对账、CSV/Excel 导出、幂等键和异常金额检查。

## RBAC 设计

权限键：

- `finance.view`：财务总览、日报和明细
- `finance.review`：充值/提现申请审核
- `finance.config`：财务规则配置
- `finance.export`：导出财务数据

角色矩阵：

| 角色 | 财务报表 | 资金审核 | 财务配置 | 订单/任务 |
|---|---|---|---|---|
| 管理员 | 是 | 是 | 是 | 是 |
| 普通运营 | 是 | 是 | 否 | 是 |
| 财务 | 是 | 是 | 否 | 否 |
| 客服 | 否 | 否 | 否 | 是（客服范围） |

## 验收标准

- 日期范围包含起止两天，日报为空时仍返回完整日期行。
- 日报各列合计与顶部总览一致。
- 提现不被申请表和钱包流水重复计入。
- 每笔明细包含来源类型、来源编号、发生时间和关联单号/渠道。
- 选择具体时间段时只统计起止时间内的事件；渠道日报能分别展示同一渠道不同日期的金额。
- 刷新、分页和账目类型筛选保持当前日期范围。
- 管理员、普通运营可访问；客服访问接口返回角色错误且不显示主导航。

## 主要文件

- 前端：`apps/frontend/src/pages/admin/AdminFinancePage.tsx`、`apps/frontend/src/services/admin/finance.ts`、`apps/frontend/src/types/admin/finance.ts`、`apps/frontend/src/layouts/AdminLayout.tsx`、`apps/frontend/src/App.tsx`
- 后端：`apps/backend/src/services/admin/admin-finance-service.ts`、`apps/backend/src/routes/admin/finance.ts`、`apps/backend/src/routes/admin.ts`
- 测试：`apps/backend/src/services/admin/admin-finance-service.test.ts`