feat: import services and standardize Go 1.26.5
This commit is contained in:
553
apps/finance/wallet/README.md
Normal file
553
apps/finance/wallet/README.md
Normal file
@@ -0,0 +1,553 @@
|
||||
# Wallet Service
|
||||
|
||||
[](https://golang.org/)
|
||||
[](LICENSE)
|
||||
[](https://git.apinb.com/bsm-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 git.apinb.com/bsm-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 开发团队
|
||||
- **项目地址**: [git.apinb.com/bsm-finance/wallet](https://git.apinb.com/bsm-finance/wallet)
|
||||
|
||||
## 🔗 相关链接
|
||||
|
||||
- [BSM SDK](https://git.apinb.com/bsm-sdk)
|
||||
- [API 文档](https://docs.apinb.com/wallet)
|
||||
- [问题反馈](https://git.apinb.com/bsm-finance/wallet/issues)
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**⭐ 如果这个项目对你有帮助，请给它一个星标！**
|
||||
|
||||
Made with ❤️ by BSM Team
|
||||
|
||||
</div>
|
||||
Reference in New Issue
Block a user