t

2025-12-24 17:38:08 +08:00
parent e1fdf7e77f
commit d633c6741e
15 changed files with 1162 additions and 34 deletions
--- a/银行卡提现功能实施计划.md
+++ b/银行卡提现功能实施计划.md
@@ -0,0 +1,439 @@
+# 银行卡提现功能实施计划
+
+## 一、功能概述
+
+新增银行卡提现功能，与现有支付宝提现功能并行。银行卡提现采用申请-审核模式：
+- 用户提交银行卡提现申请（银行卡号、开户支行、提现金额）
+- 系统冻结申请金额
+- 管理员审核（确认/拒绝）
+- 确认后扣除金额，拒绝后解冻金额
+- 实际转账由管理员线下手动完成
+
+## 二、数据库变更
+
+### 2.1 修改 `agent_withdrawal` 表
+
+需要新增以下字段：
+```sql
+ALTER TABLE `agent_withdrawal` 
+ADD COLUMN `withdraw_type` TINYINT NOT NULL DEFAULT 1 COMMENT '提现类型:1-支付宝,2-银行卡' AFTER `agent_id`,
+ADD COLUMN `bank_card_no` VARCHAR(50) DEFAULT NULL COMMENT '银行卡号' AFTER `payee_account`,
+ADD COLUMN `bank_name` VARCHAR(100) DEFAULT NULL COMMENT '开户支行' AFTER `bank_card_no`,
+ADD COLUMN `payee_name` VARCHAR(50) DEFAULT NULL COMMENT '收款人姓名' AFTER `bank_name`;
+```
+
+**说明：**
+- `withdraw_type`: 区分提现类型（1=支付宝，2=银行卡）
+- `bank_card_no`: 银行卡号（仅银行卡提现使用）
+- `bank_name`: 开户支行（仅银行卡提现使用）
+- `payee_name`: 收款人姓名（银行卡提现需要，支付宝提现已有但字段名不同）
+
+### 2.2 新增银行卡信息记录表（可选，用于历史记录）
+
+如果需要保存用户的历史银行卡信息以便自动填充：
+```sql
+CREATE TABLE `agent_bank_card` (
+  `id` BIGINT NOT NULL AUTO_INCREMENT,
+  `agent_id` BIGINT NOT NULL COMMENT '代理ID',
+  `bank_card_no` VARCHAR(50) NOT NULL COMMENT '银行卡号',
+  `bank_name` VARCHAR(100) NOT NULL COMMENT '开户支行',
+  `payee_name` VARCHAR(50) NOT NULL COMMENT '收款人姓名',
+  `is_default` TINYINT DEFAULT 0 COMMENT '是否默认:0-否,1-是',
+  `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  `delete_time` DATETIME DEFAULT NULL,
+  `del_state` TINYINT DEFAULT 0 COMMENT '删除状态:0-未删除,1-已删除',
+  PRIMARY KEY (`id`),
+  KEY `idx_agent_id` (`agent_id`),
+  KEY `idx_del_state` (`del_state`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='代理银行卡信息表';
+```
+
+## 三、后端开发
+
+### 3.1 API接口定义
+
+#### 3.1.1 前端接口（`app/main/api/desc/front/agent.api`）
+
+**新增银行卡提现申请接口：**
+```go
+// 银行卡提现申请
+@handler BankCardWithdrawal
+post /withdrawal/bank-card (BankCardWithdrawalReq) returns (WithdrawalResp)
+
+type (
+    BankCardWithdrawalReq {
+        BankCardNo string  `json:"bank_card_no"` // 银行卡号
+        BankName   string  `json:"bank_name"`    // 开户支行
+        Amount     float64 `json:"amount"`       // 提现金额
+    }
+)
+```
+
+**新增获取历史银行卡信息接口（可选）：**
+```go
+// 获取历史银行卡信息
+@handler GetBankCardInfo
+get /withdrawal/bank-card/info (GetBankCardInfoReq) returns (GetBankCardInfoResp)
+
+type (
+    GetBankCardInfoReq  {}
+    GetBankCardInfoResp {
+        BankCardNo string `json:"bank_card_no"` // 银行卡号
+        BankName   string `json:"bank_name"`     // 开户支行
+        PayeeName  string `json:"payee_name"`   // 收款人姓名
+        IdCard     string `json:"id_card"`      // 身份证号
+    }
+)
+```
+
+#### 3.1.2 管理员接口（`app/main/api/desc/admin/admin_agent.api`）
+
+**新增银行卡提现审核接口：**
+```go
+// 银行卡提现审核（确认/拒绝）
+@handler AdminReviewBankCardWithdrawal
+post /agent-withdrawal/bank-card/review (AdminReviewBankCardWithdrawalReq) returns (AdminReviewBankCardWithdrawalResp)
+
+type (
+    AdminReviewBankCardWithdrawalReq {
+        WithdrawalId int64  `json:"withdrawal_id"` // 提现记录ID
+        Action       int64  `json:"action"`        // 操作:1-确认,2-拒绝
+        Remark       string `json:"remark"`       // 备注（拒绝时必填）
+    }
+    
+    AdminReviewBankCardWithdrawalResp {
+        Success bool `json:"success"`
+    }
+)
+```
+
+**修改现有提现列表接口：**
+- 在 `AdminGetAgentWithdrawalListResp` 的 `AgentWithdrawalListItem` 中新增字段：
+  - `WithdrawType int64` - 提现类型
+  - `BankCardNo string` - 银行卡号
+  - `BankName string` - 开户支行
+  - `PayeeName string` - 收款人姓名
+
+### 3.2 业务逻辑实现
+
+#### 3.2.1 银行卡提现申请逻辑（`BankCardWithdrawalLogic`）
+
+**文件位置：** `app/main/api/internal/logic/agent/bankcardwithdrawallogic.go`
+
+**核心流程：**
+1. 验证用户实名认证状态
+2. 验证银行卡信息与实名信息匹配（姓名需一致）
+3. 验证可提现金额
+4. 计算税费（6%）
+5. 冻结资金（事务内）
+6. 创建提现记录（状态=申请中，withdraw_type=2）
+7. 创建扣税记录（状态=待扣税）
+8. 保存银行卡信息到历史记录表（可选）
+
+**关键代码逻辑：**
+```go
+// 参考 AgentWithdrawalLogic，但：
+// 1. 不调用支付宝接口
+// 2. 状态直接设为 StatusProcessing（申请中）
+// 3. 添加银行卡信息字段
+// 4. 验证银行卡号格式
+// 5. 验证姓名与实名认证信息一致
+```
+
+#### 3.2.2 银行卡提现审核逻辑（`AdminReviewBankCardWithdrawalLogic`）
+
+**文件位置：** `app/main/api/internal/logic/admin_agent/adminreviewbankcardwithdrawallogic.go`
+
+**确认提现流程：**
+1. 验证提现记录存在且状态为申请中
+2. 验证提现类型为银行卡
+3. 事务内操作：
+   - 更新提现记录状态为成功
+   - 解冻资金并扣除（FrozenBalance -= amount, Balance不变）
+   - 更新扣税记录状态为成功
+   - 发放提现奖励（如果有）
+
+**拒绝提现流程：**
+1. 验证提现记录存在且状态为申请中
+2. 验证提现类型为银行卡
+3. 事务内操作：
+   - 更新提现记录状态为失败，记录拒绝原因
+   - 解冻资金（FrozenBalance -= amount, Balance += amount）
+   - 更新扣税记录状态为失败
+
+#### 3.2.3 修改现有逻辑
+
+**修改 `AgentWithdrawalLogic`：**
+- 在创建提现记录时，设置 `withdraw_type = 1`（支付宝）
+- 在 `PayeeAccount` 字段存储支付宝账号
+
+**修改 `AdminGetAgentWithdrawalListLogic`：**
+- 查询时关联银行卡信息字段
+- 返回时包含提现类型和银行卡信息
+
+### 3.3 数据模型
+
+#### 3.3.1 修改 `AgentWithdrawal` 模型
+
+**文件：** `app/main/model/agentWithdrawalModel_gen.go`（由goctl生成，需重新生成）
+
+**新增字段：**
+- `WithdrawType int64` - 提现类型
+- `BankCardNo sql.NullString` - 银行卡号
+- `BankName sql.NullString` - 开户支行
+- `PayeeName sql.NullString` - 收款人姓名
+
+#### 3.3.2 新增 `AgentBankCard` 模型（可选）
+
+如果实现历史记录功能，需要：
+1. 创建 `agent_bank_card.sql` 表结构文件
+2. 使用 goctl 生成模型：
+   ```bash
+   goctl model mysql datasource -url="user:password@tcp(host:port)/database" -table="agent_bank_card" -dir="./app/main/model" -cache=true --style=goZero
+   ```
+
+### 3.4 状态管理
+
+**提现状态常量：**
+```go
+const (
+    StatusPending   = 1 // 申请中/处理中（支付宝和银行卡共用）
+    StatusSuccess   = 2 // 成功
+    StatusFailed    = 3 // 失败
+)
+
+const (
+    WithdrawTypeAlipay   = 1 // 支付宝提现
+    WithdrawTypeBankCard = 2 // 银行卡提现
+)
+```
+
+**银行卡提现状态流转：**
+- 申请 → StatusPending（申请中）
+- 管理员确认 → StatusSuccess（成功）
+- 管理员拒绝 → StatusFailed（失败）
+
+## 四、前端开发
+
+### 4.1 用户端（tydata-webview-v2）
+
+#### 4.1.1 修改提现页面（`src/views/Withdraw.vue`）
+
+**方案A：在同一页面添加切换标签**
+- 添加"支付宝提现"和"银行卡提现"两个标签页
+- 根据选择的标签显示不同的表单字段
+
+**方案B：创建新的银行卡提现页面**
+- 创建 `src/views/BankCardWithdraw.vue`
+- 在路由中添加银行卡提现入口
+
+**推荐方案A，用户体验更好**
+
+**银行卡提现表单字段：**
+- 银行卡号（必填，格式验证）
+- 开户支行（必填）
+- 提现金额（必填，验证规则同支付宝）
+- 显示实名信息（姓名、身份证号，只读）
+- 提示：银行卡信息需与实名信息一致
+
+**功能点：**
+1. 页面加载时调用接口获取历史银行卡信息，自动填充
+2. 显示用户实名认证信息（姓名、身份证号）
+3. 表单验证：
+   - 银行卡号格式（16-19位数字）
+   - 开户支行不能为空
+   - 金额验证（≥50，≤可提现金额）
+4. 提交后显示申请成功提示
+5. 可在提现记录中查看审核状态
+
+#### 4.1.2 修改提现记录页面（`src/views/WithdrawDetails.vue`）
+
+- 显示提现类型（支付宝/银行卡）
+- 银行卡提现显示银行卡号和开户支行
+- 显示审核状态（申请中/已确认/已拒绝）
+
+#### 4.1.3 API接口调用
+
+**新增接口调用：**
+```javascript
+// src/api/withdraw.js 或相应文件
+export const bankCardWithdrawal = (data) => {
+  return useApiFetch('/agent/withdrawal/bank-card')
+    .post(data)
+    .json();
+};
+
+export const getBankCardInfo = () => {
+  return useApiFetch('/agent/withdrawal/bank-card/info')
+    .get()
+    .json();
+};
+```
+
+### 4.2 管理端（tydata-admin）
+
+#### 4.2.1 修改提现列表页面（`apps/web-antd/src/views/agent/agent-withdrawal/list.vue`）
+
+**新增功能：**
+1. 列表显示提现类型（支付宝/银行卡）
+2. 银行卡提现显示银行卡号和开户支行
+3. 银行卡提现申请中状态显示"审核"操作按钮
+4. 点击审核按钮打开审核弹窗
+
+#### 4.2.2 新增审核弹窗组件
+
+**文件：** `apps/web-antd/src/views/agent/agent-withdrawal/modules/review-modal.vue`
+
+**功能：**
+- 显示提现详情（金额、银行卡信息、用户信息等）
+- 确认/拒绝操作
+- 拒绝时必填拒绝原因
+- 提交审核结果
+
+#### 4.2.3 修改列表数据配置（`apps/web-antd/src/views/agent/agent-withdrawal/data.ts`）
+
+**新增列：**
+- 提现类型列
+- 银行卡号列（仅银行卡提现显示）
+- 开户支行列（仅银行卡提现显示）
+- 操作列（银行卡申请中状态显示审核按钮）
+
+#### 4.2.4 API接口调用
+
+**新增接口：**
+```typescript
+// apps/web-antd/src/api/agent.ts
+export function reviewBankCardWithdrawal(data: {
+  withdrawal_id: number;
+  action: 1 | 2; // 1-确认, 2-拒绝
+  remark?: string;
+}) {
+  return request.post('/admin/agent-withdrawal/bank-card/review', data);
+}
+```
+
+## 五、实施步骤
+
+### 阶段一：数据库准备（1-2天）
+1. ✅ 编写数据库变更SQL脚本
+2. ✅ 执行SQL脚本更新数据库表结构
+3. ✅ 如果实现历史记录功能，创建 `agent_bank_card` 表
+
+### 阶段二：后端开发（3-5天）
+1. ✅ 修改API定义文件（`agent.api`、`admin_agent.api`）
+2. ✅ 使用goctl重新生成代码（包括模型和类型定义）
+3. ✅ 实现银行卡提现申请逻辑（`BankCardWithdrawalLogic`）
+4. ✅ 实现银行卡提现审核逻辑（`AdminReviewBankCardWithdrawalLogic`）
+5. ✅ 修改现有提现列表逻辑，支持银行卡信息查询
+6. ✅ 实现获取历史银行卡信息接口（可选）
+7. ✅ 单元测试和接口测试
+
+### 阶段三：前端开发（3-5天）
+
+#### 用户端（tydata-webview-v2）
+1. ✅ 修改提现页面，添加银行卡提现选项
+2. ✅ 实现银行卡提现表单和验证
+3. ✅ 实现历史信息自动填充
+4. ✅ 修改提现记录页面，显示银行卡信息
+5. ✅ 测试提现流程
+
+#### 管理端（tydata-admin）
+1. ✅ 修改提现列表页面，显示银行卡信息
+2. ✅ 实现审核弹窗组件
+3. ✅ 实现审核操作逻辑
+4. ✅ 测试审核流程
+
+### 阶段四：测试与优化（2-3天）
+1. ✅ 功能测试（申请、审核、拒绝流程）
+2. ✅ 边界测试（金额、状态、并发等）
+3. ✅ 性能测试
+4. ✅ Bug修复
+5. ✅ 代码审查
+
+### 阶段五：部署上线（1天）
+1. ✅ 数据库迁移脚本执行
+2. ✅ 后端服务部署
+3. ✅ 前端应用部署
+4. ✅ 生产环境验证
+
+## 六、注意事项
+
+### 6.1 数据兼容性
+- 现有支付宝提现记录的 `withdraw_type` 默认为1（支付宝）
+- 现有记录的 `bank_card_no`、`bank_name`、`payee_name` 为NULL（正常）
+
+### 6.2 安全性
+- 银行卡号需要加密存储（建议使用AES加密）
+- 前端传输时使用HTTPS
+- 审核操作需要管理员权限验证
+
+### 6.3 业务规则
+- 银行卡提现最低金额：50元（与支付宝一致）
+- 银行卡提现税率：6%（与支付宝一致）
+- 银行卡提现需要实名认证通过
+- 银行卡信息需与实名认证姓名一致
+
+### 6.4 用户体验
+- 历史银行卡信息自动填充，减少用户输入
+- 明确提示银行卡信息需与实名信息一致
+- 审核状态及时反馈给用户
+
+### 6.5 错误处理
+- 银行卡号格式验证
+- 金额不足提示
+- 审核操作失败回滚
+- 异常情况日志记录
+
+## 七、风险评估
+
+### 7.1 技术风险
+- **数据库迁移风险**：表结构变更可能影响现有功能
+  - **应对**：先在测试环境验证，做好数据备份
+  
+- **并发问题**：审核操作可能并发执行
+  - **应对**：使用数据库事务和版本号控制
+
+### 7.2 业务风险
+- **资金安全**：银行卡提现涉及资金操作
+  - **应对**：严格权限控制，操作日志记录
+  
+- **审核效率**：管理员需要手动审核，可能影响用户体验
+  - **应对**：提供审核提醒功能，优化审核流程
+
+## 八、后续优化建议
+
+1. **审核提醒**：管理员审核列表增加待审核数量提醒
+2. **批量审核**：支持批量确认/拒绝操作
+3. **审核历史**：记录审核操作人和操作时间
+4. **银行卡管理**：用户可管理多张银行卡，设置默认卡
+5. **提现限额**：银行卡提现可设置不同的限额规则
+
+## 九、文件清单
+
+### 后端文件
+- `app/main/api/desc/front/agent.api` - 前端API定义（修改）
+- `app/main/api/desc/admin/admin_agent.api` - 管理员API定义（修改）
+- `app/main/api/internal/logic/agent/bankcardwithdrawallogic.go` - 银行卡提现申请逻辑（新增）
+- `app/main/api/internal/logic/admin_agent/adminreviewbankcardwithdrawallogic.go` - 银行卡提现审核逻辑（新增）
+- `app/main/model/agentWithdrawalModel_gen.go` - 提现模型（重新生成）
+- `app/main/model/agentBankCardModel.go` - 银行卡信息模型（可选，新增）
+
+### 前端文件（用户端）
+- `src/views/Withdraw.vue` - 提现页面（修改）
+- `src/views/WithdrawDetails.vue` - 提现记录页面（修改）
+- `src/api/withdraw.js` - API接口（修改）
+
+### 前端文件（管理端）
+- `apps/web-antd/src/views/agent/agent-withdrawal/list.vue` - 提现列表（修改）
+- `apps/web-antd/src/views/agent/agent-withdrawal/modules/review-modal.vue` - 审核弹窗（新增）
+- `apps/web-antd/src/views/agent/agent-withdrawal/data.ts` - 列表配置（修改）
+- `apps/web-antd/src/api/agent.ts` - API接口（修改）
+
+### 数据库文件
+- `deploy/sql/bank_card_withdrawal.sql` - 数据库变更脚本（新增）
+
+---
+
+**预计总工期：10-15个工作日**
+