# 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>