# 多商户支付配置系统设计方案

## 📋 概述

将单商户硬编码的乐刷支付配置改造为支持多商户、可动态管理的数据库配置方案。

---

## 🎯 设计目标

✅ 支持多个乐刷商户号  
✅ 支持不同业务场景使用不同商户  
✅ 后台 GUI 管理（增删改查）  
✅ 密钥加密存储（AES-256-GCM）  
✅ 支持启用/禁用商户  
✅ 支持设置默认商户  
✅ 支持测试环境和生产环境  
✅ 使用统计和审计日志  
✅ 平滑迁移，向后兼容  

---

## 📊 数据库设计

### 1. 支付商户配置表 `payment_merchant_configs`

```sql
CREATE TABLE payment_merchant_configs (
  id                   BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
  name                 VARCHAR(128) NOT NULL,              -- 商户名称
  provider             VARCHAR(32) NOT NULL,               -- leshua/mock
  merchant_id          VARCHAR(128) NOT NULL,              -- 商户号
  gateway_url          VARCHAR(512) NOT NULL DEFAULT '',   -- 网关地址
  sign_key             VARCHAR(512) NOT NULL DEFAULT '',   -- 签名密钥（加密）
  notify_key           VARCHAR(512) NOT NULL DEFAULT '',   -- 通知密钥（加密）
  notify_url           VARCHAR(512) NOT NULL DEFAULT '',   -- 回调地址
  jump_url             VARCHAR(512) NOT NULL DEFAULT '',   -- 跳转地址
  pay_way              VARCHAR(32) NOT NULL DEFAULT 'ZFBZF',
  jspay_flag           VARCHAR(8) NOT NULL DEFAULT '2',
  sign_type            VARCHAR(16) NOT NULL DEFAULT 'MD5',
  extra_config         JSON NULL,                          -- 扩展配置
  is_default           TINYINT(1) NOT NULL DEFAULT 0,      -- 是否默认
  status               VARCHAR(32) NOT NULL DEFAULT 'active', -- active/disabled/testing
  environment          VARCHAR(16) NOT NULL DEFAULT 'production', -- production/sandbox
  business_tags        JSON NULL,                          -- 业务场景标签
  total_transactions   BIGINT NOT NULL DEFAULT 0,
  total_amount_cent    BIGINT NOT NULL DEFAULT 0,
  last_used_at         DATETIME NULL,
  created_by           BIGINT UNSIGNED NULL,
  updated_by           BIGINT UNSIGNED NULL,
  created_at           DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at           DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  
  KEY idx_payment_merchant_configs_provider (provider, status),
  KEY idx_payment_merchant_configs_default (provider, is_default)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

### 2. 配置使用日志表 `payment_config_usage_logs`（可选）

用于审计和统计分析。

---

## 🏗️ 后端架构

### 目录结构

```
backend/internal/modules/paymentconfig/
├── dto.go           # 数据传输对象、请求响应结构
├── encryptor.go     # AES-GCM 加密器
├── repository.go    # 数据库操作层
├── service.go       # 业务逻辑层
└── handler.go       # HTTP 处理层
```

### 核心功能

1. **加密存储**
   - 使用 AES-256-GCM 对称加密
   - 密钥从环境变量 `PAYMENT_CONFIG_ENCRYPTION_KEY` 读取（32字节）
   - 自动加密 `sign_key` 和 `notify_key`

2. **权限控制**
   - `payment_config:list` - 查看配置列表
   - `payment_config:create` - 创建配置
   - `payment_config:update` - 更新配置
   - `payment_config:delete` - 删除配置
   - `payment_config:view_secret` - 查看密钥明文

3. **默认商户管理**
   - 每个 `provider` 只能有一个默认商户
   - 设置新默认时自动取消旧默认
   - 支付模块优先使用默认商户

4. **使用统计**
   - 自动记录交易笔数、总金额
   - 记录最后使用时间
   - 可选：记录详细使用日志

---

## 🔌 API 接口

### 管理后台接口

```
GET    /admin/payment-configs              # 获取配置列表
GET    /admin/payment-configs/:id          # 获取单个配置
POST   /admin/payment-configs              # 创建配置
PUT    /admin/payment-configs/:id          # 更新配置
DELETE /admin/payment-configs/:id          # 删除配置
```

### 请求示例

**创建配置**
```json
POST /admin/payment-configs
{
  "name": "乐刷生产商户1",
  "provider": "leshua",
  "merchant_id": "123456789",
  "gateway_url": "https://paygate.leshuazf.com/cgi-bin/lepos_pay_gateway.cgi",
  "sign_key": "your-sign-key",
  "notify_key": "your-notify-key",
  "notify_url": "https://your-domain.com/api/payment/leshua/notify",
  "jump_url": "https://your-domain.com/payment/result",
  "pay_way": "ZFBZF",
  "jspay_flag": "2",
  "sign_type": "MD5",
  "is_default": true,
  "status": "active",
  "environment": "production",
  "business_tags": ["order_pay", "wallet_recharge"]
}
```

**查询配置（包含密钥）**
```
GET /admin/payment-configs/1?include_secret=true
```

---

## 🔄 支付模块集成

### 修改 payment 模块

1. **注入 paymentconfig.Service**
```go
type Repository struct {
    db              *gorm.DB
    cfg             config.PaymentConfig  // 保留作为兜底
    paymentConfigSvc *paymentconfig.Service // 新增
    orderRepo       *order.Repository
    walletRepo      *wallet.Repository
    leshua          *leshua.Client
    provider        string
    isMockMode      bool
}
```

2. **动态获取配置**
```go
func (r *Repository) getLeshuaConfig() (config.LeshuaPaymentConfig, error) {
    // 优先从数据库获取默认配置
    if r.paymentConfigSvc != nil {
        dto, err := r.paymentConfigSvc.GetDefaultConfig("leshua")
        if err == nil {
            return config.LeshuaPaymentConfig{
                GatewayURL: dto.GatewayURL,
                MerchantID: dto.MerchantID,
                SignKey:    dto.SignKey,
                NotifyKey:  dto.NotifyKey,
                NotifyURL:  dto.NotifyURL,
                JumpURL:    dto.JumpURL,
                PayWay:     dto.PayWay,
                JSPayFlag:  dto.JSPayFlag,
                SignType:   dto.SignType,
            }, nil
        }
    }
    
    // 兜底：使用 .env 配置
    return r.cfg.Leshua, nil
}
```

3. **支付时使用动态配置**
```go
func (r *Repository) Start(userID uint64, orderID uint64, req StartPaymentRequest, clientIP string) (*PaymentDTO, error) {
    // ...
    
    leshuaConfig, err := r.getLeshuaConfig()
    if err != nil {
        return nil, err
    }
    
    client := leshua.NewClient(leshuaConfig)
    resp, rawReq, err := client.CreatePayment(ctx, ...)
    
    // ...
}
```

---

## 🎨 前端管理界面

### 功能列表

1. **配置列表**
   - 显示所有支付配置
   - 筛选：服务商、状态、环境
   - 标识默认商户
   - 显示使用统计

2. **创建/编辑配置**
   - 表单验证
   - 密钥输入（敏感）
   - 默认商户切换
   - 状态管理

3. **查看密钥**
   - 需要 `payment_config:view_secret` 权限
   - 点击"查看密钥"按钮后调用API

4. **删除配置**
   - 确认对话框
   - 检查是否正在使用

### 路由

```typescript
{
  path: '/admin/payment-configs',
  component: () => import('@/features/admin/views/AdminPaymentConfigsView.vue'),
  meta: { requiresAuth: true, requiresAdmin: true }
}
```

---

## 🔐 安全考虑

1. **密钥加密**
   - 数据库存储加密密文
   - 传输使用 HTTPS
   - 日志不记录明文密钥

2. **权限控制**
   - 只有财务和超管可以管理
   - 查看密钥需要额外权限

3. **审计日志**
   - 记录所有配置变更
   - 记录查看密钥操作

---

## 🚀 部署步骤

### 1. 环境变量配置

```bash
# .env 添加加密密钥（32字节）
PAYMENT_CONFIG_ENCRYPTION_KEY=your-32-byte-key-here-abcdefgh
```

生成密钥：
```bash
openssl rand -hex 16
```

示例结果：`a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`（32个十六进制字符）

### 2. 数据库迁移

```bash
./scripts/dev.sh --reset-db
# 或手动执行迁移
mysql < backend/migrations/000002_add_payment_merchant_configs.sql
```

### 3. 初始化配置

通过后台管理界面添加第一个商户配置，或者应用启动时自动从 `.env` 迁移。

### 4. 向后兼容

如果数据库中没有配置，支付模块会回退使用 `.env` 中的配置。

---

## ✅ 优势

1. **灵活性** - 支持多商户、多场景
2. **安全性** - 密钥加密存储
3. **可维护性** - GUI 管理，无需重启
4. **可扩展性** - 易于支持其他支付渠道
5. **可审计** - 完整的操作日志
6. **高可用** - 兜底机制保证服务不中断

---

## 📝 下一步工作

- [ ] 执行数据库迁移
- [ ] 注册路由和依赖注入
- [ ] 实现前端管理界面
- [ ] 集成到支付模块
- [ ] 测试多商户切换
- [ ] 编写单元测试
- [ ] 更新部署文档
