rent/apps/server/docs/finance-api.md

财务模块 API 接口文档

概述

财务模块已完成所有核心服务和 API 接口的开发，包括账户管理、交易流水、结算对账、提现管理等功能。

模块结构

finance/
├── entities/
│   ├── user-account.entity.ts               # 用户账户实体
│   ├── merchant-account.entity.ts           # 商家账户实体
│   ├── platform-account.entity.ts           # 平台账户实体
│   ├── system-account.entity.ts             # 系统总账户实体
│   ├── user-transaction.entity.ts           # 用户交易流水实体
│   ├── merchant-transaction.entity.ts       # 商家交易流水实体
│   ├── platform-transaction.entity.ts       # 平台交易流水实体
│   ├── system-transaction.entity.ts         # 系统总账户交易流水实体
│   ├── settlement.entity.ts                 # 结算单实体
│   ├── settlement-item.entity.ts            # 结算明细实体
│   ├── user-withdrawal.entity.ts            # 用户提现实体
│   ├── merchant-withdrawal.entity.ts        # 商家提现实体
│   ├── platform-withdrawal.entity.ts        # 平台提现实体
│   └── daily-reconciliation.entity.ts       # 日对账实体
├── services/
│   ├── account.service.ts                   # 账户服务（转账、冻结、解冻）
│   ├── transaction.service.ts               # 交易流水服务
│   ├── settlement.service.ts                # 结算服务（周结算定时任务）
│   ├── withdrawal.service.ts                # 提现服务
│   ├── reconciliation.service.ts            # 对账服务（日对账定时任务）
│   └── finance.service.ts                   # 财务综合服务
├── controllers/
│   ├── finance-user.controller.ts           # 用户端财务接口
│   ├── finance-seller.controller.ts         # 商家端财务接口
│   ├── finance-admin.controller.ts          # 管理端财务接口
│   ├── transaction-seller.controller.ts     # 商家端交易流水接口
│   ├── transaction-admin.controller.ts      # 管理端交易流水接口
│   └── reconciliation-admin.controller.ts   # 管理端对账接口
└── dto/
    └── finance.dto.ts                       # 所有 DTO 定义

API 接口清单

1. 用户端接口 (C端用户)

路由前缀: /api/finance

方法	路径	说明	认证
GET	/wallet	获取钱包信息	JWT
POST	/withdraw	申请提现	JWT
GET	/withdrawals	提现记录列表	JWT
GET	/transactions	交易流水列表	JWT

功能说明:

• 用户可查看钱包余额（可用余额、冻结余额）
• 用户可申请提现到微信/支付宝（最低10元）
• 用户可查看提现记录和交易流水

---

2. 商家端接口 (B端商家)

2.1 财务管理

路由前缀: /api/seller/finance

方法	路径	说明	认证
GET	/wallet	获取钱包信息	Seller JWT
PUT	/bank	更新银行卡信息	Seller JWT
POST	/withdraw	申请提现	Seller JWT
GET	/settlements	对账单列表	Seller JWT
GET	/settlements/:id	对账单详情	Seller JWT
GET	/withdrawals	提现记录列表	Seller JWT

功能说明:

• 商家可查看钱包余额和银行卡信息
• 商家可申请提现（最低100元）
• 商家可查看周结算对账单和提现记录

2.2 交易流水

路由前缀: /api/seller/transactions

方法	路径	说明	认证
GET	/	交易流水列表	Seller JWT
GET	/statistics	交易统计	Seller JWT

功能说明:

• 商家可查看自己的交易流水
• 商家可查看收入/支出统计

---

3. 管理端接口 (平台管理员)

3.1 财务管理

路由前缀: /api/admin/finance

方法	路径	说明	认证
GET	/settlements	对账单列表	Admin JWT
GET	/settlements/:id	对账单详情	Admin JWT
PUT	/settlements/:id/approve	审核通过对账单	Admin JWT
PUT	/settlements/:id/reject	拒绝对账单	Admin JWT
GET	/withdrawals	提现申请列表	Admin JWT
PUT	/withdrawals/:id/approve	审核通过提现	Admin JWT
PUT	/withdrawals/:id/reject	拒绝提现	Admin JWT
PUT	/withdrawals/:id/pay	确认打款	Admin JWT
GET	/earnings	平台收益统计	Admin JWT

功能说明:

• 管理员审核商家对账单（审核通过后金额进入商家钱包）
• 管理员审核提现申请（审核通过后可确认打款）
• 管理员查看平台收益统计

3.2 交易流水

路由前缀: /api/admin/transactions

方法	路径	说明	认证
GET	/	交易流水列表	Admin JWT
GET	/statistics	交易统计	Admin JWT
GET	/daily	按日统计交易	Admin JWT

功能说明:

• 管理员可查看所有账户的交易流水
• 支持按账户类型、所有者、交易类型筛选
• 提供交易统计和按日统计功能

3.3 对账管理

路由前缀: /api/admin/reconciliation

方法	路径	说明	认证
POST	/manual	手动执行对账	Admin JWT
GET	/records	对账记录列表	Admin JWT
GET	/account-summary	账户余额汇总	Admin JWT
GET	/transaction-stats	交易统计	Admin JWT
GET	/check-consistency/:accountId	检查账户余额一致性	Admin JWT

功能说明:

• 管理员可手动触发对账（系统每天凌晨3点自动对账）
• 管理员可查看对账记录（平衡/不平衡）
• 管理员可查看账户余额汇总（平台/商家/用户）
• 管理员可检查单个账户的余额一致性

---

核心业务流程

1. 订单支付流程

用户支付 → 平台账户收入 → 记录交易流水

2. 周结算流程

每周一凌晨2点自动执行:
1. 查询上周已完成订单
2. 按商家分组计算结算金额
3. 生成结算单和结算明细
4. 平台账户 → 商家账户（转账）
5. 记录交易流水

3. 商家提现流程

1. 商家申请提现 → 冻结商家账户余额
2. 管理员审核通过 → 状态变为已审核
3. 管理员确认打款 → 扣减余额 + 解冻 → 状态变为已打款
4. 记录交易流水

4. 日对账流程

每天凌晨3点自动执行:
1. 统计各账户余额（平台/商家/用户）
2. 统计当日各类交易金额
3. 检查借贷平衡（收入总额 = 支出总额）
4. 记录对账结果
5. 如有异常发送告警

---

定时任务

任务	执行时间	说明
周结算	每周一 02:00	自动生成上周的商家结算单
日对账	每天 03:00	自动执行日对账检查

---

数据库表

表名	说明
system_accounts	系统总账户表
system_transactions	系统总账户交易流水表
platform_accounts	平台账户表
platform_transactions	平台交易流水表
merchant_accounts	商家账户表
merchant_transactions	商家交易流水表
user_accounts	用户账户表
user_transactions	用户交易流水表
settlements	结算单表
settlement_items	结算明细表
user_withdrawals	用户提现表
merchant_withdrawals	商家提现表
platform_withdrawals	平台提现表
daily_reconciliations	日对账记录表

---

技术特性

1. 分表设计: 账户和交易流水按角色分表（用户/商家/平台/系统）
2. 乐观锁: 账户余额更新使用版本号防止并发问题
3. 事务保证: 所有涉及金额变动的操作都在事务中执行
4. 冻结机制: 提现时先冻结余额，审核通过后扣减
5. 自动对账: 每日自动检查账户余额和交易流水一致性
6. 定时结算: 每周自动生成商家结算单
7. 资金守恒: 系统总账户 = 商家账户 + 用户账户 + 平台账户

---

Swagger 文档

启动服务后访问: http://localhost:3000/api/docs

所有接口都已添加 Swagger 注解，包括：

• 接口描述
• 请求参数
• 响应格式
• 认证方式

---

下一步工作

1. ✅ 创建数据库迁移脚本
2. ✅ 编写单元测试
3. ✅ 集成到订单模块（订单支付时调用账户服务）
4. ✅ 添加告警通知（对账异常时发送通知）
5. ✅ 前端页面开发（小程序、商家后台、平台后台）