# 财务模块 API 接口文档

## 概述

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

## 模块结构

```
finance/
├── entities/
│   ├── account.entity.ts                    # 账户实体
│   ├── 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 | 自动执行日对账检查 |

---

## 数据库表

| 表名 | 说明 |
|------|------|
| `accounts` | 账户表（用户/商家/平台） |
| `transactions` | 交易流水表（复式记账） |
| `settlements` | 结算单表 |
| `settlement_items` | 结算明细表 |
| `user_withdrawals` | 用户提现表 |
| `merchant_withdrawals` | 商家提现表 |
| `platform_withdrawals` | 平台提现表 |
| `daily_reconciliations` | 日对账记录表 |

---

## 技术特性

1. **复式记账**: 每笔转账生成两条交易流水（支出+收入）
2. **乐观锁**: 账户余额更新使用版本号防止并发问题
3. **事务保证**: 所有涉及金额变动的操作都在事务中执行
4. **冻结机制**: 提现时先冻结余额，审核通过后扣减
5. **自动对账**: 每日自动检查账户余额和交易流水一致性
6. **定时结算**: 每周自动生成商家结算单

---

## Swagger 文档

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

所有接口都已添加 Swagger 注解，包括：
- 接口描述
- 请求参数
- 响应格式
- 认证方式

---

## 下一步工作

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