357 lines
11 KiB
Markdown
357 lines
11 KiB
Markdown
# 手动提现功能实施完成总结
|
||
|
||
## 🎉 已完成的工作
|
||
|
||
### 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 接口开发
|
||
- ✅ 权限和角色配置
|
||
- ✅ 安全措施实施
|
||
|
||
系统已具备完整的手动提现能力，财务管理员可以通过管理后台进行提现审核和打款确认操作。
|
||
|
||
**下一步**：前端界面开发 → 完整测试 → 生产环境部署
|