full/module/finance/wallet/README.md

Wallet Service

一个高性能、可扩展的钱包微服务，基于 gRPC 和 HTTP Gateway 架构，提供钱包管理、支付处理、充值提现等金融服务功能。

🚀 特性

• 💰 钱包管理: 用户钱包创建、余额查询、状态管理
• 💳 支付处理: 支持微信支付、支付宝等多种支付方式
• 🔄 交易记录: 完整的交易流水记录和查询
• 🏦 银行卡管理: 银行卡绑定、解绑、查询功能
• 💸 充值提现: 安全的充值和提现业务流程
• 🔒 安全加密: 支付密码加密、签名验证
• ⚡ 高性能: Redis缓存 + 数据库优化
• 🐳 容器化: 完整的Docker支持
• 📊 监控: 健康检查和APM集成

📋 目录

• 快速开始
• 项目结构
• 核心功能
• API文档
• 开发指南
• 部署说明
• 性能优化
• 故障排除

🚀 快速开始

环境要求

• Go: 1.25.1+
• PostgreSQL: 12+
• Redis: 6+
• Docker: 20.10+ (可选)
• Protocol Buffers: 3.15+ (开发需要)

快速安装

# 克隆项目
git clone bsm/full/module/finance/wallet.git
cd wallet

# 安装依赖
go mod tidy

# 生成代码
make proto

# 构建应用
go build -o wallet cmd/main/main.go

# 运行服务
./wallet

Docker 快速启动

# 构建镜像
docker build -t wallet-service .

# 运行容器
docker run -d --name wallet-service -p 12101:12101 -p 12102:12102 wallet-service

📁 项目结构

wallet/
├── 📁 cmd/                     # 应用程序入口
│   ├── 📁 main/               # 主服务入口
│   └── 📁 cli/                # 命令行工具
├── 📁 internal/               # 内部包
│   ├── 📁 config/             # 配置管理
│   ├── 📁 excode/             # 错误码定义
│   ├── 📁 impl/               # 实现层
│   ├── 📁 logic/              # 业务逻辑
│   │   ├── 📁 basic/          # 基础钱包逻辑
│   │   ├── 📁 payment/        # 支付相关逻辑
│   │   ├── 📁 alipay/         # 支付宝逻辑
│   │   └── 📁 wechat/         # 微信支付逻辑
│   ├── 📁 models/             # 数据模型
│   └── 📁 server/             # 服务器实现
├── 📁 pb/                     # Protocol Buffers 生成代码
├── 📁 proto/                  # Protocol Buffers 定义文件
├── 📁 swagger/                # API 文档
├── 📁 scripts/                # 脚本文件
├── 📁 test/                   # 测试文件
├── 📁 etc/                    # 配置文件
└── 📖 README.md              # 项目文档

🔧 核心功能

1. 基础钱包服务 (Basic Service)

💰 钱包管理

rpc GetWallet(GetWalletRequest) returns (GetWalletReply)
rpc SetPayPassword(SetPayPasswordRequest) returns (SetPayPasswordReply)

• 功能: 钱包信息查询、支付密码设置
• 特性: 余额查询、状态管理、密码加密

🏦 银行卡管理

rpc AddBankCard(AddBankCardRequest) returns (AddBankCardReply)
rpc GetBankCard(GetBankCardRequest) returns (GetBankCardReply)
rpc RemoveBankCard(RemoveBankCardRequest) returns (RemoveBankCardReply)

• 功能: 银行卡绑定、查询、解绑
• 特性: 多卡管理、安全验证

💸 提现申请

rpc ApplyCash(ApplyCashRequest) returns (ApplyCashReply)

• 功能: 用户提现申请处理
• 特性: 金额验证、状态跟踪

2. 支付服务 (Payment Service)

💳 支付处理

rpc PayByOrder(PayByOrderRequest) returns (PayByOrderReply)
rpc PayByCharge(PayByChargeRequest) returns (PayByChargeReply)

• 功能: 订单支付、充值支付
• 特性: 多种支付方式、状态回调

🔄 支付查询

rpc GetPayment(GetPaymentRequest) returns (GetPaymentReply)

• 功能: 支付状态查询
• 特性: 实时状态、历史记录

3. 微信支付服务 (WeChat Service)

📱 微信支付

rpc JsapiPreOrder(JsapiPreOrderRequest) returns (JsapiPreOrderReply)
rpc NativePreOrder(NativePreOrderRequest) returns (NativePreOrderReply)
rpc AppPreOrder(AppPreOrderRequest) returns (AppPreOrderReply)

• 功能: 微信JSAPI、Native、APP支付
• 特性: 统一下单、签名验证

💰 微信转账

rpc Transfer(TransferRequest) returns (TransferReply)

• 功能: 微信企业转账
• 特性: 实时到账、状态通知

4. 支付宝服务 (Alipay Service)

💳 支付宝支付

rpc PagePay(PagePayRequest) returns (PagePayReply)
rpc WapPay(WapPayRequest) returns (WapPayReply)
rpc AppPay(AppPayRequest) returns (AppPayReply)

• 功能: 支付宝网页、手机、APP支付
• 特性: 多种支付场景、异步通知

💰 支付宝转账

rpc Transfer(TransferRequest) returns (TransferReply)

• 功能: 支付宝转账
• 特性: 批量转账、状态查询

📚 API文档

gRPC 服务

服务	方法	描述	端口
Basic	GetWallet	获取钱包信息	12101
Basic	SetPayPassword	设置支付密码	12101
Basic	AddBankCard	添加银行卡	12101
Basic	ApplyCash	申请提现	12101
Payment	PayByOrder	订单支付	12101
Payment	PayByCharge	充值支付	12101
WeChat	JsapiPreOrder	微信JSAPI支付	12101
WeChat	NativePreOrder	微信扫码支付	12101
Alipay	PagePay	支付宝网页支付	12101
Alipay	WapPay	支付宝手机支付	12101

HTTP Gateway

端点	方法	描述
/wallet.Basic/GetWallet	POST	获取钱包信息
/wallet.Basic/SetPayPassword	POST	设置支付密码
/wallet.Basic/AddBankCard	POST	添加银行卡
/wallet.Payment/PayByOrder	POST	订单支付
/wallet.WeChat/JsapiPreOrder	POST	微信JSAPI支付
/wallet.Alipay/PagePay	POST	支付宝网页支付

Swagger 文档

• 本地: http://localhost:12102/wallet.swagger.json
• 在线: 通过 HTTP Gateway 访问完整的 API 文档

🛠️ 开发指南

开发环境设置

# 安装开发工具
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# 生成 protobuf 代码
make proto

# 启动开发模式
go run cmd/main/main.go

代码生成

# 生成 protobuf 代码
make proto

# 生成 Swagger 文档
make swagger

测试

# 运行所有测试
go test ./...

# 测试覆盖率
go test -cover ./...

# 代码检查
go vet ./...

# 代码格式化
gofmt -w .

🚀 部署说明

生产环境部署

1. 环境准备

   # 创建生产配置
   cp etc/wallet_dev.yaml etc/wallet_prod.yaml
   # 编辑生产配置...
   

2. 数据库初始化

   # 执行数据库迁移
   go run cmd/main/main.go migrate
   

3. 服务启动

   # 构建生产版本
   go build -o wallet cmd/main/main.go
   
   # 启动服务
   ./wallet
   

Kubernetes 部署

# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: wallet-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: wallet-service
  template:
    metadata:
      labels:
        app: wallet-service
    spec:
      containers:
      - name: wallet-service
        image: wallet:latest
        ports:
        - containerPort: 12101
        - containerPort: 12102
        env:
        - name: SERVICE_ENV
          value: "production"

⚡ 性能优化

缓存策略

数据类型	缓存时间	策略
钱包信息	5分钟	按用户缓存
支付状态	1分钟	按订单缓存
银行卡信息	10分钟	按用户缓存
交易记录	30分钟	分页缓存

数据库优化

• 索引优化: 关键字段建立复合索引
• 查询优化: 使用预编译语句
• 连接池: 配置合适的连接池大小
• 读写分离: 支持主从数据库配置

监控指标

# 服务健康检查
curl http://localhost:12102/health

# 性能指标
curl http://localhost:12102/metrics

🔧 配置说明

环境配置文件

# etc/wallet_prod.yaml
Service: wallet
Port: 12101

# 数据库配置
Databases:
  Driver: postgres
  Source:
    - host=db-host user=postgres password=*** dbname=wallet_db port=5432 sslmode=require

# 缓存配置
Cache: redis://username:password@redis-host:6379/0

# 网关配置
Gateway:
  Enable: true
  Port: 12102

# 微服务配置
MicroService:
  Enable: true
  Registry: etcd://etcd-cluster:2379

# 微信支付配置
WeChat:
  AppID: "your-app-id"
  AppSecret: "your-app-secret"
  MchID: "your-merchant-id"
  APIV3Key: "your-api-v3-key"

# 支付宝配置
Alipay:
  AppID: "your-app-id"
  AppSecret: "your-app-secret"
  IsProd: true

# 钱包配置
Wallet:
  Name: "BSM Wallet"
  AlipyIsOpen: true
  WechatpayIsOpen: true
  WalletIsOpen: true

环境变量

变量名	描述	默认值
SERVICE_ENV	运行环境	development
CONFIG_FILE	配置文件路径	etc/wallet_dev.yaml
LOG_LEVEL	日志级别	info
TZ	时区设置	Asia/Shanghai

🐛 故障排除

常见问题

1. 服务启动失败

   # 检查端口占用
   netstat -tlnp | grep :12101
   
   # 检查配置文件
   go run cmd/main/main.go --config-check
   

2. 数据库连接失败

   # 测试数据库连接
   psql -h your-db-host -U postgres -d wallet_db -c "SELECT 1;"
   

3. Redis连接失败

   # 测试Redis连接
   redis-cli -h your-redis-host ping
   

4. 支付接口调用失败

   # 检查支付配置
   curl -X POST http://localhost:12102/wallet.Payment/Hello
   

日志分析

# 查看服务日志
tail -f logs/wallet.log

# 查看错误日志
grep ERROR logs/wallet.log

# 查看支付日志
grep "payment" logs/wallet.log

📊 数据模型

核心表结构

wallet_basic - 钱包基础表

CREATE TABLE wallet_basic (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(255) NOT NULL,
    passport_id BIGINT NOT NULL,
    passport_identity VARCHAR(255) NOT NULL,
    alipay_id VARCHAR(64) DEFAULT '',
    wxpay_id VARCHAR(64) DEFAULT '',
    pay_password VARCHAR(255) DEFAULT '',
    balance BIGINT DEFAULT 0,
    withdrawal_balance BIGINT DEFAULT 0,
    status INTEGER DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

wallet_payment - 支付记录表

CREATE TABLE wallet_payment (
    id SERIAL PRIMARY KEY,
    identity VARCHAR(255) NOT NULL,
    passport_identity VARCHAR(255) NOT NULL,
    order_no VARCHAR(255) NOT NULL,
    amount BIGINT NOT NULL,
    pay_type INTEGER NOT NULL,
    status INTEGER DEFAULT 0,
    call_back_msg TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

wallet_record - 交易记录表

CREATE TABLE wallet_record (
    id SERIAL PRIMARY KEY,
    wallet_identity VARCHAR(255) NOT NULL,
    passport_identity VARCHAR(255) NOT NULL,
    trans_type INTEGER NOT NULL,
    trade_type INTEGER NOT NULL,
    money BIGINT NOT NULL,
    in_trade_no VARCHAR(255),
    out_trade_no VARCHAR(255),
    pay_channel INTEGER,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

🤝 贡献指南

开发流程

1. Fork 项目
2. 创建特性分支: git checkout -b feature/amazing-feature
3. 提交更改: git commit -m 'Add amazing feature'
4. 推送分支: git push origin feature/amazing-feature
5. 创建 Pull Request

代码规范

• 遵循 Go 官方代码规范
• 使用 gofmt 格式化代码
• 添加必要的注释和文档
• 编写单元测试

提交规范

type(scope): description

[optional body]

[optional footer]

类型:

• feat: 新功能
• fix: 修复bug
• docs: 文档更新
• style: 代码格式
• refactor: 重构
• test: 测试
• chore: 构建过程或辅助工具的变动

📄 许可证

本项目采用内部许可证，仅供 BSM 内部使用。

👥 团队

• 作者: David Yan (david.yan@qq.com)
• 维护者: BSM 开发团队
• 项目地址: bsm/full/module/finance/wallet

🔗 相关链接

• BSM SDK
• API 文档
• 问题反馈

---

⭐ 如果这个项目对你有帮助，请给它一个星标！

Made with ❤️ by BSM Team