bsm-infra/full
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5ea45a76fe59c8ceae0bd7185a24839371eb1bb1
full/module/finance/wallet/README.md

553 lines
13 KiB
Markdown
Raw Blame History

# Wallet Service
[![Go Version](https://img.shields.io/badge/Go-1.25.1-blue.svg)](https://golang.org/)
[![License](https://img.shields.io/badge/License-Internal-red.svg)](LICENSE)
[![Build Status](https://img.shields.io/badge/Build-Passing-green.svg)](https://bsm/full/module/finance/wallet)
一个高性能、可扩展的钱包微服务，基于 gRPC 和 HTTP Gateway 架构，提供钱包管理、支付处理、充值提现等金融服务功能。
## 🚀 特性
- **💰 钱包管理**: 用户钱包创建、余额查询、状态管理
- **💳 支付处理**: 支持微信支付、支付宝等多种支付方式
- **🔄 交易记录**: 完整的交易流水记录和查询
- **🏦 银行卡管理**: 银行卡绑定、解绑、查询功能
- **💸 充值提现**: 安全的充值和提现业务流程
- **🔒 安全加密**: 支付密码加密、签名验证
- **⚡ 高性能**: Redis缓存 + 数据库优化
- **🐳 容器化**: 完整的Docker支持
- **📊 监控**: 健康检查和APM集成
## 📋 目录
- [快速开始](#-快速开始)
- [项目结构](#-项目结构)
- [核心功能](#-核心功能)
- [API文档](#-api文档)
- [开发指南](#-开发指南)
- [部署说明](#-部署说明)
- [性能优化](#-性能优化)
- [故障排除](#-故障排除)
## 🚀 快速开始
### 环境要求
- **Go**: 1.25.1+
- **PostgreSQL**: 12+
- **Redis**: 6+
- **Docker**: 20.10+ (可选)
- **Protocol Buffers**: 3.15+ (开发需要)
### 快速安装
```bash
# 克隆项目
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 快速启动
```bash
# 构建镜像
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)
#### 💰 钱包管理
```protobuf
rpc GetWallet(GetWalletRequest) returns (GetWalletReply)
rpc SetPayPassword(SetPayPasswordRequest) returns (SetPayPasswordReply)
```
- **功能**: 钱包信息查询、支付密码设置
- **特性**: 余额查询、状态管理、密码加密
#### 🏦 银行卡管理
```protobuf
rpc AddBankCard(AddBankCardRequest) returns (AddBankCardReply)
rpc GetBankCard(GetBankCardRequest) returns (GetBankCardReply)
rpc RemoveBankCard(RemoveBankCardRequest) returns (RemoveBankCardReply)
```
- **功能**: 银行卡绑定、查询、解绑
- **特性**: 多卡管理、安全验证
#### 💸 提现申请
```protobuf
rpc ApplyCash(ApplyCashRequest) returns (ApplyCashReply)
```
- **功能**: 用户提现申请处理
- **特性**: 金额验证、状态跟踪
### 2. 支付服务 (Payment Service)
#### 💳 支付处理
```protobuf
rpc PayByOrder(PayByOrderRequest) returns (PayByOrderReply)
rpc PayByCharge(PayByChargeRequest) returns (PayByChargeReply)
```
- **功能**: 订单支付、充值支付
- **特性**: 多种支付方式、状态回调
#### 🔄 支付查询
```protobuf
rpc GetPayment(GetPaymentRequest) returns (GetPaymentReply)
```
- **功能**: 支付状态查询
- **特性**: 实时状态、历史记录
### 3. 微信支付服务 (WeChat Service)
#### 📱 微信支付
```protobuf
rpc JsapiPreOrder(JsapiPreOrderRequest) returns (JsapiPreOrderReply)
rpc NativePreOrder(NativePreOrderRequest) returns (NativePreOrderReply)
rpc AppPreOrder(AppPreOrderRequest) returns (AppPreOrderReply)
```
- **功能**: 微信JSAPI、Native、APP支付
- **特性**: 统一下单、签名验证
#### 💰 微信转账
```protobuf
rpc Transfer(TransferRequest) returns (TransferReply)
```
- **功能**: 微信企业转账
- **特性**: 实时到账、状态通知
### 4. 支付宝服务 (Alipay Service)
#### 💳 支付宝支付
```protobuf
rpc PagePay(PagePayRequest) returns (PagePayReply)
rpc WapPay(WapPayRequest) returns (WapPayReply)
rpc AppPay(AppPayRequest) returns (AppPayReply)
```
- **功能**: 支付宝网页、手机、APP支付
- **特性**: 多种支付场景、异步通知
#### 💰 支付宝转账
```protobuf
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 文档
## 🛠️ 开发指南
### 开发环境设置
```bash
# 安装开发工具
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
```
### 代码生成
```bash
# 生成 protobuf 代码
make proto
# 生成 Swagger 文档
make swagger
```
### 测试
```bash
# 运行所有测试
go test ./...
# 测试覆盖率
go test -cover ./...
# 代码检查
go vet ./...
# 代码格式化
gofmt -w .
```
## 🚀 部署说明
### 生产环境部署
1. **环境准备**
```bash
# 创建生产配置
cp etc/wallet_dev.yaml etc/wallet_prod.yaml
# 编辑生产配置...
```
2. **数据库初始化**
```bash
# 执行数据库迁移
go run cmd/main/main.go migrate
```
3. **服务启动**
```bash
# 构建生产版本
go build -o wallet cmd/main/main.go
# 启动服务
./wallet
```
### Kubernetes 部署
```yaml
# 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分钟 | 分页缓存 |
### 数据库优化
- **索引优化**: 关键字段建立复合索引
- **查询优化**: 使用预编译语句
- **连接池**: 配置合适的连接池大小
- **读写分离**: 支持主从数据库配置
### 监控指标
```bash
# 服务健康检查
curl http://localhost:12102/health
# 性能指标
curl http://localhost:12102/metrics
```
## 🔧 配置说明
### 环境配置文件
```yaml
# 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. **服务启动失败**
```bash
# 检查端口占用
netstat -tlnp | grep :12101
# 检查配置文件
go run cmd/main/main.go --config-check
```
2. **数据库连接失败**
```bash
# 测试数据库连接
psql -h your-db-host -U postgres -d wallet_db -c "SELECT 1;"
```
3. **Redis连接失败**
```bash
# 测试Redis连接
redis-cli -h your-redis-host ping
```
4. **支付接口调用失败**
```bash
# 检查支付配置
curl -X POST http://localhost:12102/wallet.Payment/Hello
```
### 日志分析
```bash
# 查看服务日志
tail -f logs/wallet.log
# 查看错误日志
grep ERROR logs/wallet.log
# 查看支付日志
grep "payment" logs/wallet.log
```
## 📊 数据模型
### 核心表结构
#### wallet_basic - 钱包基础表
```sql
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 - 支付记录表
```sql
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 - 交易记录表
```sql
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](https://bsm/full/module/finance/wallet)
## 🔗 相关链接
- [BSM SDK](https://git.apinb.com/bsm-sdk)
- [API 文档](https://docs.apinb.com/wallet)
- [问题反馈](https://bsm/full/module/finance/wallet/issues)
---
<div align="center">
**⭐ 如果这个项目对你有帮助，请给它一个星标！**
Made with ❤️ by BSM Team
</div>
Reference in New Issue View Git Blame Copy Permalink