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