yml/hfb_sys
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

后端提现增加

Browse Source
This commit is contained in:
yml
2026-06-06 10:08:39 +08:00
parent 082fd908e9
commit 8a2d2f2a18
15 changed files with 2763 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/提现功能API文档.md
+636
View File
@@ -0,0 +1,636 @@
# 提现功能 API 文档
## 目录
- [收款账号管理 API](#收款账号管理-api)
- [提现申请 API (用户端)](#提现申请-api-用户端)
- [提现管理 API (管理员端)](#提现管理-api-管理员端)
---
## 收款账号管理 API
### 1. 查询收款账号列表
**请求**
```
GET /api/payment-accounts?page=1&page_size=20
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"id": 1,
"user_id": 123,
"account_type": "alipay",
"account_name": "张三",
"account_no": "138****5678",
"bank_name": "",
"bank_branch": "",
"certificate_urls": ["https://..."],
"is_default": true,
"status": "active",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z"
}
],
"total": 1,
"page": 1,
"page_size": 20
}
}
```
### 2. 查询收款账号详情
**请求**
```
GET /api/payment-accounts/:id
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"user_id": 123,
"account_type": "alipay",
"account_name": "张三",
"account_no": "138****5678",
"bank_name": "",
"bank_branch": "",
"certificate_urls": ["https://..."],
"is_default": true,
"status": "active",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z"
}
}
```
### 3. 添加收款账号
**请求**
```
POST /api/payment-accounts
Authorization: Bearer {user_token}
Content-Type: application/json
{
"account_type": "alipay", // alipay | wechat | bank
"account_name": "张三", // 必须与实名认证姓名一致
"account_no": "13812345678", // 支付宝账号/微信号/银行卡号
"bank_name": "中国工商银行", // 银行卡必填
"bank_branch": "北京分行", // 银行卡可选
"certificate_urls": [ // 凭证截图（可选）
"https://..."
]
}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"user_id": 123,
"account_type": "alipay",
"account_name": "张三",
"account_no": "138****5678",
"is_default": false,
"status": "active",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z"
}
}
```
**错误响应**
```json
{
"code": 40001,
"message": "账户名必须与实名认证姓名一致"
}
```
```json
{
"code": 40002,
"message": "请先完成实名认证"
}
```
```json
{
"code": 40003,
"message": "收款账号数量已达上限（最多5个）"
}
```
### 4. 更新收款账号
**请求**
```
PUT /api/payment-accounts/:id
Authorization: Bearer {user_token}
Content-Type: application/json
{
"bank_branch": "北京朝阳支行",
"certificate_urls": ["https://..."]
}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"account_type": "bank",
"account_name": "张三",
"account_no": "6222****1234",
"bank_name": "中国工商银行",
"bank_branch": "北京朝阳支行",
"is_default": false,
"status": "active",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:05:00Z"
}
}
```
### 5. 删除收款账号
**请求**
```
DELETE /api/payment-accounts/:id
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"deleted": true
}
}
```
### 6. 设置默认收款账号
**请求**
```
POST /api/payment-accounts/:id/set-default
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"updated": true
}
}
```
---
## 提现申请 API (用户端)
### 1. 创建提现申请
**请求**
```
POST /api/withdrawals
Authorization: Bearer {user_token}
Content-Type: application/json
{
"payment_account_id": 1,
"amount": 100.00
}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"user_id": 123,
"amount": 100.00,
"fee": 0.00,
"actual_amount": 100.00,
"account_type": "alipay",
"account_name": "张三",
"account_no": "138****5678",
"bank_name": "",
"status": "pending",
"review_remark": "",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z",
"reviewed_at": null,
"paid_at": null
}
}
```
**错误响应**
```json
{
"code": 40001,
"message": "提现金额低于最小限额"
}
```
```json
{
"code": 40002,
"message": "提现金额超过最大限额"
}
```
```json
{
"code": 40003,
"message": "余额不足"
}
```
### 2. 查询提现列表
**请求**
```
GET /api/withdrawals?page=1&page_size=20
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"user_id": 123,
"amount": 100.00,
"fee": 0.00,
"actual_amount": 100.00,
"account_type": "alipay",
"account_name": "张三",
"account_no": "138****5678",
"bank_name": "",
"status": "completed",
"review_remark": "审核通过",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:30:00Z",
"reviewed_at": "2026-06-06T10:10:00Z",
"paid_at": "2026-06-06T10:30:00Z"
}
],
"total": 1,
"page": 1,
"page_size": 20
}
}
```
### 3. 查询提现详情
**请求**
```
GET /api/withdrawals/:id
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"user_id": 123,
"amount": 100.00,
"fee": 0.00,
"actual_amount": 100.00,
"account_type": "alipay",
"account_name": "张三",
"account_no": "138****5678",
"bank_name": "",
"status": "processing",
"review_remark": "审核通过",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:10:00Z",
"reviewed_at": "2026-06-06T10:10:00Z",
"paid_at": null
}
}
```
### 4. 取消提现申请
**请求**
```
POST /api/withdrawals/:id/cancel
Authorization: Bearer {user_token}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"cancelled": true
}
}
```
**错误响应**
```json
{
"code": 40001,
"message": "提现申请状态已锁定，无法操作"
}
```
---
## 提现管理 API (管理员端)
### 1. 查询提现列表
**请求**
```
GET /api/admin/withdrawals?status=pending&page=1&page_size=20
Authorization: Bearer {admin_token}
X-Required-Permission: withdrawal:list
```
**查询参数**
- `status`: 状态筛选 (pending | processing | completed | rejected | cancelled)
- `user_id`: 用户ID筛选
- `page`: 页码
- `page_size`: 每页数量
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"user_id": 123,
"user_nickname": "用户昵称",
"user_phone": "138****5678",
"amount": 100.00,
"fee": 0.00,
"actual_amount": 100.00,
"payment_account_id": 1,
"account_type": "alipay",
"account_name": "张三",
"account_no": "13812345678", // 管理员可见完整账号
"bank_name": "",
"bank_branch": "",
"status": "pending",
"reviewed_by": null,
"reviewed_by_name": "",
"reviewed_at": null,
"review_remark": "",
"paid_by": null,
"paid_by_name": "",
"paid_at": null,
"payment_proof_url": "",
"payment_remark": "",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z"
}
],
"total": 1,
"page": 1,
"page_size": 20
}
}
```
### 2. 查询提现详情
**请求**
```
GET /api/admin/withdrawals/:id
Authorization: Bearer {admin_token}
X-Required-Permission: withdrawal:detail
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"user_id": 123,
"user_nickname": "用户昵称",
"user_phone": "13812345678",
"amount": 100.00,
"fee": 0.00,
"actual_amount": 100.00,
"payment_account_id": 1,
"account_type": "alipay",
"account_name": "张三",
"account_no": "13812345678",
"bank_name": "",
"bank_branch": "",
"status": "pending",
"reviewed_by": null,
"reviewed_by_name": "",
"reviewed_at": null,
"review_remark": "",
"paid_by": null,
"paid_by_name": "",
"paid_at": null,
"payment_proof_url": "",
"payment_remark": "",
"created_at": "2026-06-06T10:00:00Z",
"updated_at": "2026-06-06T10:00:00Z"
}
}
```
### 3. 审核提现申请
**请求**
```
POST /api/admin/withdrawals/:id/review
Authorization: Bearer {admin_token}
X-Required-Permission: withdrawal:review
Content-Type: application/json
{
"approved": true,
"remark": "审核通过"
}
```
**审核通过响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"status": "processing",
"reviewed_by": 10,
"reviewed_by_name": "财务管理员",
"reviewed_at": "2026-06-06T10:10:00Z",
"review_remark": "审核通过",
...
}
}
```
**审核拒绝请求**
```json
{
"approved": false,
"remark": "账号信息不符"
}
```
**审核拒绝响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"status": "rejected",
"reviewed_by": 10,
"reviewed_by_name": "财务管理员",
"reviewed_at": "2026-06-06T10:10:00Z",
"review_remark": "账号信息不符",
...
}
}
```
### 4. 确认打款
**请求**
```
POST /api/admin/withdrawals/:id/confirm-payment
Authorization: Bearer {admin_token}
X-Required-Permission: withdrawal:pay
Content-Type: application/json
{
"payment_proof_url": "https://storage.example.com/proofs/proof_123.jpg",
"remark": "已通过支付宝转账"
}
```
**响应**
```json
{
"code": 0,
"message": "success",
"data": {
"id": 1,
"withdraw_no": "WD17362512001a2b3c4d",
"status": "completed",
"paid_by": 10,
"paid_by_name": "财务管理员",
"paid_at": "2026-06-06T10:30:00Z",
"payment_proof_url": "https://storage.example.com/proofs/proof_123.jpg",
"payment_remark": "已通过支付宝转账",
...
}
}
```
---
## 状态说明
### 提现状态 (status)
| 状态 | 说明 | 允许操作 |
|------|------|---------|
| `pending` | 待审核 | 用户可取消、管理员可审核 |
| `processing` | 处理中 | 管理员可确认打款 |
| `completed` | 已完成 | 无 |
| `rejected` | 已拒绝 | 无 |
| `cancelled` | 已取消 | 无 |
### 账号类型 (account_type)
| 类型 | 说明 |
|------|------|
| `alipay` | 支付宝 |
| `wechat` | 微信 |
| `bank` | 银行卡 |
---
## 错误码说明
| 错误码 | 说明 |
|--------|------|
| 40001 | 请求参数错误 |
| 40002 | 实名认证未通过 |
| 40003 | 账号数量限制 |
| 40004 | 提现金额错误 |
| 40005 | 余额不足 |
| 40006 | 状态锁定 |
| 40401 | 未找到资源 |
| 40301 | 未授权 |
| 50001 | 服务器错误 |
---
## 接口权限说明
### 用户端接口
所有用户端接口需要携带用户 Token (`Authorization: Bearer {user_token}`)
### 管理员端接口
所有管理员端接口需要：
1. 携带管理员 Token (`Authorization: Bearer {admin_token}`)
2. 拥有对应的权限
#### 提现管理权限列表
- `withdrawal:list` - 查看提现申请列表
- `withdrawal:detail` - 查看提现详情
- `withdrawal:review` - 审核提现申请
- `withdrawal:pay` - 确认打款
**财务角色 (finance)** 默认拥有以上所有权限。
docs/提现功能实施总结.md
+356
View File
@@ -0,0 +1,356 @@
# 手动提现功能实施完成总结
## 🎉 已完成的工作
### 1. 数据库迁移（✅ 完成）
**文件**: `backend/migrations/000002_add_withdrawal_tables.sql`
创建了两张新表：
#### user_payment_accounts (用户收款账号表)
- 支持三种账号类型：支付宝 (alipay)、微信 (wechat)、银行卡 (bank)
- 账号信息加密存储
- 支持上传认证凭证（收款码截图）
- 支持设置默认账号
- 每个用户最多5个收款账号
#### withdrawal_requests (提现申请表)
- 记录用户提现申请的完整信息
- 账号信息快照（防止用户修改收款账号影响已有提现）
- 支持手续费计算
- 完整的审核流程：pending → processing → completed
- 记录审核人、打款人、打款凭证等信息
#### 权限和角色
- 新增 4 个提现相关权限
- 新增 `finance` 财务管理员角色
- 关联权限到角色
### 2. 数据模型（✅ 完成）
**文件**:
- `backend/internal/model/payment_account.go` - 收款账号模型
- `backend/internal/model/withdrawal.go` - 提现申请模型
### 3. 收款账号管理模块（✅ 完成）
**目录**: `backend/internal/modules/paymentaccount/`
#### 核心功能：
- **增删改查**：用户管理自己的收款账号
- **实名验证**：账户名必须与实名认证姓名一致
- **加密存储**：使用 AES 加密存储账号信息
- **脱敏显示**：前端显示时自动脱敏（如：138****5678）
- **默认账号**：支持设置默认收款账号
- **数量限制**：每个用户最多 5 个收款账号
**文件**:
- `service.go` - 业务逻辑层
- `repository.go` - 数据访问层（含加密/解密/脱敏逻辑）
- `handler.go` - HTTP 接口处理
- `dto.go` - 数据传输对象
### 4. 提现申请模块（✅ 完成）
**目录**: `backend/internal/modules/withdrawal/`
#### 用户端功能：
- **创建提现申请**：选择收款账号、输入金额
- **查询提现列表**：查看自己的提现记录
- **查询提现详情**：查看单个提现申请
- **取消提现**：待审核状态可取消
#### 管理员端功能：
- **查询提现列表**：支持按状态、用户筛选
- **查询提现详情**：查看完整信息（包括完整账号）
- **审核提现**：通过/拒绝提现申请
- **确认打款**：上传打款凭证，完成提现
#### 核心流程：
1. **用户申请** → 冻结可用余额 → 创建提现记录（status=pending）
2. **财务审核** → 通过（status=processing）/ 拒绝（status=rejected，解冻余额）
3. **手动打款** → 上传凭证 → 确认完成（status=completed，扣除冻结余额）
#### 限额控制：
- 最低提现金额：10 元
- 最高单笔提现：5000 元
- 手续费率：0%（可配置）
**文件**:
- `service.go` - 业务逻辑层
- `repository.go` - 数据访问层（含钱包流水集成）
- `handler.go` - HTTP 接口处理
- `dto.go` - 数据传输对象
### 5. 路由配置（✅ 完成）
**文件**: `backend/internal/router/router.go`
#### 用户端 API:
```
POST /api/payment-accounts # 添加收款账号
GET /api/payment-accounts # 查询收款账号列表
GET /api/payment-accounts/:id # 查询收款账号详情
PUT /api/payment-accounts/:id # 更新收款账号
DELETE /api/payment-accounts/:id # 删除收款账号
POST /api/payment-accounts/:id/set-default # 设为默认
POST /api/withdrawals # 创建提现申请
GET /api/withdrawals # 查询提现列表
GET /api/withdrawals/:id # 查询提现详情
POST /api/withdrawals/:id/cancel # 取消提现
```
#### 管理员端 API:
```
GET /api/admin/withdrawals # 查询提现列表（需权限：withdrawal:list）
GET /api/admin/withdrawals/:id # 查询提现详情（需权限：withdrawal:detail）
POST /api/admin/withdrawals/:id/review # 审核提现（需权限：withdrawal:review）
POST /api/admin/withdrawals/:id/confirm-payment # 确认打款（需权限：withdrawal:pay）
```
### 6. 钱包模块更新（✅ 完成）
更新了 `wallet/service.go`，提现功能已迁移到独立的 withdrawal 模块。
---
## 📋 数据库表结构
### user_payment_accounts
```sql
id BIGINT 主键
user_id BIGINT 用户ID
account_type VARCHAR(32) 账号类型：alipay/wechat/bank
account_name VARCHAR(128) 账户名
account_no VARCHAR(255) 账号（加密存储）
bank_name VARCHAR(128) 银行名称
bank_branch VARCHAR(255) 开户行支行
certificate_urls JSON 认证凭证
is_default TINYINT 是否默认账号
status VARCHAR(32) 状态：active/disabled
created_at DATETIME
updated_at DATETIME
```
### withdrawal_requests
```sql
id BIGINT 主键
withdraw_no VARCHAR(64) 提现单号（唯一）
user_id BIGINT 用户ID
amount DECIMAL(12,2) 提现金额
fee DECIMAL(12,2) 手续费
actual_amount DECIMAL(12,2) 实际到账金额
payment_account_id BIGINT 收款账号ID
account_type VARCHAR(32) 账号类型（快照）
account_name VARCHAR(128) 账户名（快照）
account_no VARCHAR(128) 账号（快照，脱敏）
bank_name VARCHAR(128) 银行名称（快照）
bank_branch VARCHAR(255) 开户行支行（快照）
status VARCHAR(32) 状态：pending/processing/completed/rejected/cancelled
reviewed_by BIGINT 审核人ID
reviewed_at DATETIME 审核时间
review_remark VARCHAR(255) 审核备注
paid_by BIGINT 打款人ID
paid_at DATETIME 打款时间
payment_proof_url VARCHAR(512) 打款凭证URL
payment_remark VARCHAR(255) 打款备注
created_at DATETIME
updated_at DATETIME
```
---
## 🔐 安全措施
1. **账号加密存储**：使用 AES-256 加密收款账号
2. **实名验证**：账户名必须与实名认证姓名一致
3. **账号脱敏**：用户端仅显示脱敏账号（如 138****5678）
4. **权限控制**：管理员操作需要对应权限
5. **金额限制**：单笔提现限额、最低提现金额
6. **状态锁定**：审核中/已完成的提现无法修改
7. **快照机制**：提现申请创建时保存账号信息快照
---
## 🔄 业务流程
### 用户提现流程
```
1. 用户添加收款账号（需实名认证）
↓
2. 用户发起提现申请
↓
3. 系统冻结用户可用余额
↓
4. 创建提现申请（status=pending）
↓
5. 等待财务审核
```
### 财务审核流程
```
1. 财务管理员查看待审核列表
↓
2. 审核提现申请
├─ 通过：status → processing
└─ 拒绝：status → rejected，解冻余额
↓
3. 手动转账（支付宝/微信/银行）
↓
4. 上传打款凭证
↓
5. 确认完成（status → completed）
↓
6. 系统扣除冻结余额
```
---
## 📊 钱包流水业务类型
提现相关的 `biz_type`:
- `withdraw_freeze` - 提现冻结
- `withdraw_reject` - 提现拒绝（解冻）
- `withdraw_cancel` - 用户取消提现（解冻）
- `withdraw_complete` - 提现完成（扣除冻结余额）
---
## 🚀 部署步骤
### 1. 执行数据库迁移
```bash
mysql -u root -p your_database < backend/migrations/000002_add_withdrawal_tables.sql
```
### 2. 重新编译后端
```bash
cd backend
go build -o server cmd/api/main.go
```
### 3. 重启服务
```bash
./server
```
### 4. 配置财务管理员
```sql
-- 查询 finance 角色ID
SELECT id FROM roles WHERE code = 'finance';
-- 给管理员分配财务角色
INSERT INTO admin_user_roles (admin_user_id, role_id)
VALUES (你的管理员ID, 财务角色ID);
```
---
## ⚙️ 配置说明
### 加密密钥配置
文件：`backend/internal/modules/paymentaccount/repository.go`
**重要**：生产环境必须修改加密密钥！
```go
const encryptionKey = "your-32-byte-secret-key-here!!" // 32字节
```
建议从环境变量或配置文件读取：
```go
var encryptionKey = os.Getenv("PAYMENT_ACCOUNT_ENCRYPTION_KEY")
```
### 提现限额配置
文件：`backend/internal/modules/withdrawal/service.go`
```go
const (
MinWithdrawalAmount = 10.0 // 最低提现金额
MaxWithdrawalAmount = 5000.0 // 单笔最高提现金额
WithdrawalFeeRate = 0.0 // 手续费率
)
```
---
## ✅ 测试建议
### 1. 收款账号管理测试
- [ ] 添加支付宝账号
- [ ] 添加微信账号
- [ ] 添加银行卡账号
- [ ] 测试实名验证（账户名不匹配）
- [ ] 测试账号数量限制（最多5个）
- [ ] 测试设置默认账号
- [ ] 测试删除账号
- [ ] 验证账号加密和脱敏显示
### 2. 提现申请测试
- [ ] 测试最低金额限制（<10元）
- [ ] 测试最高金额限制（>5000元）
- [ ] 测试余额不足
- [ ] 测试正常提现申请
- [ ] 测试用户取消提现（pending状态）
- [ ] 测试无法取消已审核的提现
### 3. 财务审核测试
- [ ] 测试查询待审核列表
- [ ] 测试审核通过
- [ ] 测试审核拒绝（验证余额解冻）
- [ ] 测试确认打款（上传凭证）
- [ ] 测试管理员可见完整账号
### 4. 权限测试
- [ ] 测试非财务管理员无法访问审核接口
- [ ] 测试财务管理员可以访问所有提现接口
- [ ] 测试用户只能查看自己的提现记录
---
## 📝 后续优化建议
### 短期优化
1. **前端页面开发**：用户端收款账号管理、提现申请页面
2. **管理员前端**：提现审核列表、审核详情页面
3. **通知功能**：提现状态变更时发送通知
4. **文件上传**：集成打款凭证上传功能
### 中期优化
1. **自动化提现**：小额提现自动审核
2. **批量打款**：导出批量打款文件
3. **提现报表**：财务报表统计
4. **风控规则**：异常提现检测
### 长期优化
1. **支付网关对接**：集成自动打款接口
2. **银行接口对接**：企业网银直连
3. **实时到账**：T+0 实时提现
4. **多级审批**：大额提现多级审批流程
---
## ⚠️ 注意事项
1. **加密密钥**：生产环境必须使用强随机密钥，并妥善保管
2. **权限配置**：确保财务管理员权限配置正确
3. **余额校验**：提现前严格校验余额，防止超额提现
4. **状态机**：严格按照状态流转规则操作
5. **审计日志**：所有财务操作应记录审计日志
6. **测试环境**：充分测试后再上线生产环境
---
## 🎯 项目总结
本次实施完成了**手动提现功能的完整开发**，包括：
- ✅ 数据库设计和迁移
- ✅ 后端业务逻辑实现
- ✅ API 接口开发
- ✅ 权限和角色配置
- ✅ 安全措施实施
系统已具备完整的手动提现能力，财务管理员可以通过管理后台进行提现审核和打款确认操作。
**下一步**：前端界面开发 → 完整测试 → 生产环境部署