yml/hfb_sys

Fork 0

Files

T

yml 8a2d2f2a18 后端提现增加

2026-06-06 10:08:39 +08:00

11 KiB

Raw Blame History

手动提现功能实施完成总结

🎉 已完成的工作

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/

用户端功能：

创建提现申请：选择收款账号、输入金额
查询提现列表：查看自己的提现记录
查询提现详情：查看单个提现申请
取消提现：待审核状态可取消

管理员端功能：

查询提现列表：支持按状态、用户筛选
查询提现详情：查看完整信息（包括完整账号）
审核提现：通过/拒绝提现申请
确认打款：上传打款凭证，完成提现

核心流程：

用户申请 → 冻结可用余额 → 创建提现记录（status=pending）
财务审核 → 通过（status=processing）/ 拒绝（status=rejected，解冻余额）
手动打款 → 上传凭证 → 确认完成（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

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

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

🔐 安全措施

账号加密存储：使用 AES-256 加密收款账号
实名验证：账户名必须与实名认证姓名一致
账号脱敏：用户端仅显示脱敏账号（如 138****5678）
权限控制：管理员操作需要对应权限
金额限制：单笔提现限额、最低提现金额
状态锁定：审核中/已完成的提现无法修改
快照机制：提现申请创建时保存账号信息快照

🔄 业务流程

用户提现流程

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. 执行数据库迁移

mysql -u root -p your_database < backend/migrations/000002_add_withdrawal_tables.sql

2. 重新编译后端

cd backend
go build -o server cmd/api/main.go

3. 重启服务

./server

4. 配置财务管理员

-- 查询 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

重要：生产环境必须修改加密密钥！

const encryptionKey = "your-32-byte-secret-key-here!!" // 32字节

建议从环境变量或配置文件读取：

var encryptionKey = os.Getenv("PAYMENT_ACCOUNT_ENCRYPTION_KEY")

提现限额配置

文件：backend/internal/modules/withdrawal/service.go

const (
    MinWithdrawalAmount = 10.0    // 最低提现金额
    MaxWithdrawalAmount = 5000.0  // 单笔最高提现金额
    WithdrawalFeeRate   = 0.0     // 手续费率
)

✅ 测试建议

1. 收款账号管理测试

添加支付宝账号
添加微信账号
添加银行卡账号
测试实名验证（账户名不匹配）
测试账号数量限制（最多5个）
测试设置默认账号
测试删除账号
验证账号加密和脱敏显示

2. 提现申请测试

测试最低金额限制（<10元）
测试最高金额限制（>5000元）
测试余额不足
测试正常提现申请
测试用户取消提现（pending状态）
测试无法取消已审核的提现

3. 财务审核测试

测试查询待审核列表
测试审核通过
测试审核拒绝（验证余额解冻）
测试确认打款（上传凭证）
测试管理员可见完整账号

4. 权限测试

测试非财务管理员无法访问审核接口
测试财务管理员可以访问所有提现接口
测试用户只能查看自己的提现记录

📝 后续优化建议

短期优化

前端页面开发：用户端收款账号管理、提现申请页面
管理员前端：提现审核列表、审核详情页面
通知功能：提现状态变更时发送通知
文件上传：集成打款凭证上传功能

中期优化

自动化提现：小额提现自动审核
批量打款：导出批量打款文件
提现报表：财务报表统计
风控规则：异常提现检测

长期优化

支付网关对接：集成自动打款接口
银行接口对接：企业网银直连
实时到账：T+0 实时提现
多级审批：大额提现多级审批流程

⚠️ 注意事项

加密密钥：生产环境必须使用强随机密钥，并妥善保管
权限配置：确保财务管理员权限配置正确
余额校验：提现前严格校验余额，防止超额提现
状态机：严格按照状态流转规则操作
审计日志：所有财务操作应记录审计日志
测试环境：充分测试后再上线生产环境

🎯 项目总结

本次实施完成了手动提现功能的完整开发，包括：

✅ 数据库设计和迁移
✅ 后端业务逻辑实现
✅ API 接口开发
✅ 权限和角色配置
✅ 安全措施实施

系统已具备完整的手动提现能力，财务管理员可以通过管理后台进行提现审核和打款确认操作。

下一步：前端界面开发 → 完整测试 → 生产环境部署

11 KiB Raw Blame History Unescape Escape