4.1 KiB
4.1 KiB
财务功能实施计划
目标
在后台左侧主导航增加“财务”，提供按中国时区日期筛选的全站财务总览、每日账目和资金明细。首版复用现有订单、打手资金申请、钱包流水和售后数据，不改变接单、充值、提现的现有业务流程。
已实现范围
/admin/finance页面和主导航入口。/api/v1/admin/finance/summary：返回日期范围内的日报和汇总指标。/api/v1/admin/finance/transactions：返回分页资金明细，并支持账目类型、渠道筛选。- 日期范围支持
YYYY-MM-DD HH:mm，精确到分钟；日报仍按Asia/Shanghai自然日切桶。 - 日界线固定为
Asia/Shanghai，前端金额展示为元，数据库金额仍使用分。 - 总览指标：订单收款、订单退款、打手报酬、已确认提现、充值入账、售后追缴退还、净现金流、当前钱包余额/冻结/待解冻/待提现。
- 渠道日报按“日期 + 渠道 + 账目类型”汇总笔数和金额，订单渠道显示为
provider/platform，打手资金显示为提现/充值渠道。 - 原“接单平台 → 资金”页签继续用于打手资金申请审核和资金配置。
- 新增独立
finance后台角色：仅显示财务和资金审核入口，可访问财务报表、资金申请列表/审核，不可访问订单、任务和系统概览。 - 管理员拥有全部财务权限，普通运营保留查看/审核权限，客服不获得财务权限。
财务口径
- 订单收款按
paid_at（缺失时回退created_at）归属日期。 - 退款首版按订单
pay_status=refunded的订单金额统计；部分退款明细需要后续接入独立退款流水。 - 打手报酬取
reward_settlement、sharing_reward钱包流水。 - 已确认提现取资金申请
status=approved且有reviewed_at的金额，避免和钱包withdraw_paid零金额流水重复计算。 - 充值入账取已通过的充值申请；押金冻结/解冻只作为资金占用变化，不计入收入。
- 净现金流 = 收款 + 充值 + 打手资金回收 - 订单退款 - 打手提现 - 售后追缴退还。
后续迭代
二期：人工打款可追踪
- 将提现审核和实际打款拆分。
- 增加打款时间、操作人、流水号、付款凭证和备注。
- 增加“审核通过待打款”“已打款”状态，历史
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