440 lines
15 KiB
Markdown
440 lines
15 KiB
Markdown
# 银行卡提现功能实施计划
|
||
|
||
## 一、功能概述
|
||
|
||
新增银行卡提现功能，与现有支付宝提现功能并行。银行卡提现采用申请-审核模式：
|
||
- 用户提交银行卡提现申请（银行卡号、开户支行、提现金额）
|
||
- 系统冻结申请金额
|
||
- 管理员审核（确认/拒绝）
|
||
- 确认后扣除金额，拒绝后解冻金额
|
||
- 实际转账由管理员线下手动完成
|
||
|
||
## 二、数据库变更
|
||
|
||
### 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个工作日**
|
||
|