开发文档

版本号	修改	修改时间	备注
v1.0.0	王小琱	2024.12.20	初次修订

1. 项目简介

• 服务名称：exchange-bank-bridge-backend
• 服务描述：本项目为银行间资金桥接、账户管理、银行卡管理等金融业务提供后端服务，支持银行账户、银行卡、商户、银行中转等多种实体的管理与操作，适用于交易所、金融等场景。
• 所属模块：金融基础服务组件。
• 负责人：王小琱（wang746277441@gmail.com）

2. 功能描述

• 用户虚拟收款账号的创建、查询与管理
• 银行卡信息的创建、查询与管理
• 银行信息及中转银行信息的管理
• 商户信息管理
• 银行交易流水（如众安银行流水）记录
• 支持出金、入金、回调等银行业务流程
• 支持 RabbitMQ 消息队列、MySQL 数据库、Prometheus 监控等基础设施

3. 系统架构

3.1 主要技术栈

• 编程语言：[Go / Protocol Buffers v3]
• 服务框架：[Go Micro / GORM]
• 数据库：[MySQL]
• 消息队列：RabbitMQ
• API接口：[gRPC]
• 监控：[Prometheus]
• 容器编排：[Docker]

备注：具体依赖版本详见go.mod文件。

3.2 架构图

3.3 架构概括

• 业务层（Business Layer）

  业务系统（如交易所、金融平台）通过 gRPC 调用本服务，实现银行账户、银行卡、出入金等业务。

• 服务层（Service Layer）

  Bank Bridge Service 负责业务逻辑处理、数据持久化、消息推送等。

• 基础服务层（Infrastructure Layer）

  依赖 MySQL 存储数据，RabbitMQ 进行消息通信，Prometheus 监控服务运行状态。

3.4 业务流程

3.4.1 出金业务流程

3.4.2 入金回调业务流程

4. 依赖组件

组件	版本	说明
MySQL	8.x	关系型数据库
RabbitMQ	3.x	消息队列

5. 接口设计

见接口文档

使用make doc可以重新生成接口文档。

6. 数据库设计

见数据库设计文档

7. 项目部署

见部署文档

8. 错误码定义

错误码	错误信息	说明
ErrSystem	内部错误	服务内部异常
ErrNoMerchantInfo	商户信息不存在	商户信息不存在
ErrNoBankInfo	银行信息不存在	银行信息不存在
ErrCallZaintl	调用众安银行接口失败	调用众安银行接口失败
ErrFailed	银行接口异常	调用银行API失败
ErrNotFound	消息队列异常	RabbitMQ相关错误

9. FAQ

1. 如何创建用户虚拟收款账号？

请调用接口 CreateBankWalletInfo，传入用户ID、真实姓名、证件号码等信息，系统会自动为用户创建虚拟收款账号并返回 walletId。

2. 如何绑定银行卡？

请调用接口 BindBankCard，传入用户ID、真实姓名、证件号码、银行卡号等信息，系统会为用户绑定银行卡并返回 walletId。

3. 如何发起出金操作？

请调用接口 InitiateWithdrawal，传入 userId 及转账相关信息（如收款人账号、金额、币种等），系统会自动补全商户信息、子账户等，调用银行API发起出金，并返回结果。

4. 如何处理银行回调（入金/出金）？

银行侧会回调 OnTransactionReceived（入金）或 OnWithdrawalRequested（出金），系统会自动验签、记录流水，并通过消息队列推送业务消息。

5. 如何扩展业务表结构？

请参考 数据库设计文档 的命名规范和表结构，新增或修改表，并同步更新 entity 结构体。

6. 如何排查出金/入金失败？

• 检查请求参数是否完整、正确
• 检查银行API返回的错误码和信息
• 查看服务日志，定位具体失败原因
• 检查数据库和消息队列服务是否正常

7. 如何安全地修改生产环境配置？

建议通过环境变量或 .env 文件进行配置修改，修改后重启服务生效。所有敏感信息（如私钥、数据库密码）请妥善保管。

8. API信息以及商户信息如何录入到数据库中？

• bank_anget_info表中录入中转银行信息。
• bank_merchants表中录入商户信息。
• bank_info表中录入银行信息。

10. 参考资料

• 众安官方文档

11. 致谢

感谢 众安银行 提供的银行API服务。