# SMANAGE 抽象支付网关 — 设计文档

## 一、设计目标

SMANAGE 是 SAAS 系统，不绑定具体业务。支付网关抽象层提供**多平台支付能力的统一接入**，子服务只需要关心"付了多少钱"和"通过哪个渠道付"，SAAS 负责"怎么付"。

### 核心原则

| 原则 | 说明 |
|------|------|
| **适配器模式** | 每个支付平台是一个适配器，新增平台只需实现接口 + 注册一行 |
| **密钥走构造传参** | `PaymentCredentials` 在网关实例创建时注入，网关层不持有状态 |
| **租户隔离** | 所有操作通过 `X-Tenant-UUID` 头识别租户，配置和交易记录完全分离 |
| **加密存储** | 密钥使用 XOR + Base64 加密，密钥通过 `settings.PAYMENT_ENCRYPTION_KEY` 管理 |
| **回调不认证** | 回调端点关闭 DRF 认证，由网关自身 `VerifyNotify()` 签名验证保证安全 |

---

## 二、架构分层

```
子服务（如阿龙电竞）
    │
    ├── 注入租户密钥 → PaymentGatewayConfig（SAAS配置）
    │
    └── 调用 PaymentManager.pay(platform='wechat', amount=100)
            │
            ├── 根据 platform 从 GatewayRegistry 获取适配器类
            ├── 网关实例由密钥创建（构造时传参，非来自数据库）
            └── 执行 Pay / Query / Refund / Transfer / Close
```

---

## 三、文件清单（12 个文件）

| 层级 | 文件 | 职责 |
|------|------|------|
| **抽象层** | `gateways/base.py` | `AbstractPaymentGateway` 抽象基类 + 7 个数据模型 |
| **注册表** | `gateways/registry.py` | `GatewayRegistry` 渠道注册工厂 + `payment_registry` 全局单例 |
| **适配器** | `gateways/wechat.py` | `WechatPaymentGateway` — 微信支付（JSAPI/Native/H5/小程序 + 转账 + 回调验签） |
| **适配器** | `gateways/alipay.py` | `AlipayPaymentGateway` — 支付宝（APP/H5/Native + 转账 + 回调验签） |
| **适配器** | `gateways/bank.py` | `BankPaymentGateway` — 银行卡（银联/网银 + 代付到银行卡） |
| **模型** | `models.py` | `PaymentGatewayConfig`（密钥加密存储）+ `PaymentTransaction`（交易流水） |
| **编排器** | `manager.py` | `PaymentManager` — 配置/支付/查询/退款/转账/回调六合一 |
| **API** | `views.py` | 7 个 REST 端点（含无需认证的 NotifyView） |
| **序列化** | `serializers.py` | 5 个 Serializer |
| **路由** | `urls.py` | 7 个 URL 路由 |
| **配置** | `apps.py` | AppConfig，`ready()` 时自动注册三个渠道 |
| **管理** | `admin.py` | Django Admin 注册 |

---

## 四、核心数据模型

### 4.1 PaymentCredentials（非持久化）

网关实例创建时传入，不存储到数据库：

```python
@dataclass
class PaymentCredentials:
    AppID: str = ''
    MchID: str = ''
    APIKey: str = ''
    PrivateKey: str = ''
    PublicKey: str = ''
    CertPath: str = ''
    CertKeyPath: str = ''
    NotifyURL: str = ''
    ReturnURL: str = ''
    Extra: Dict[str, str] = field(default_factory=dict)
```

### 4.2 PaymentGatewayConfig（数据库持久化—加密）

每个租户每个渠道一条配置，密钥字段加密存储：

| 字段 | 类型 | 说明 |
|------|------|------|
| ConfigUUID | UUID | 主键 |
| TenantUUID | UUID | 租户标识 |
| Platform | CharField(32) | wechat / alipay / bank |
| AppID | CharField(64) | 应用ID |
| MchID | CharField(64) | 商户号 |
| APIKeyEncrypted | CharField(512) | 加密的 API 密钥 |
| PrivateKeyEncrypted | TextField | 加密的私钥 |
| NotifyURL | CharField(512) | 回调地址 |
| ConfigStatus | SmallIntegerField | 1=启用 0=禁用 |

### 4.3 PaymentTransaction（数据库持久化）

每笔支付/退款/转账操作的统一流水记录：

| 字段 | 类型 | 说明 |
|------|------|------|
| TransactionUUID | UUID | 主键 |
| TenantUUID | UUID | 租户 |
| Platform | CharField(32) | 支付平台 |
| TransactionType | CharField(16) | pay / refund / transfer |
| OutTradeNO | CharField(64) | 商户订单号（唯一） |
| TotalAmount | DecimalField | 金额（最大18位，4位小数） |
| TransactionStatus | SmallIntegerField | 0=处理中 1=成功 2=失败 3=已关闭 |

### 4.4 请求/响应数据模型（dataclass，非持久化）

| 数据类 | 用途 |
|--------|------|
| `PaymentRequest` | 支付请求标准化入参 |
| `PaymentResponse` | 支付响应标准化出参（含 `PrepayID` 属性） |
| `RefundRequest` | 退款请求 |
| `RefundResponse` | 退款响应 |
| `TransferRequest` | 转账请求（企业付款到零钱/银行卡） |
| `TransferResponse` | 转账响应 |
| `QueryResponse` | 订单查询响应（含 `IsPaid`/`IsRefunded` 属性） |

---

## 五、抽象网关接口

```python
class AbstractPaymentGateway(ABC):
    Channel: PaymentChannel = 'custom'
    Name: str = 'Abstract'

    def __init__(self, credentials: PaymentCredentials):
        self._credentials = credentials
        self._validate_credentials()

    @abstractmethod
    def Pay(self, request: PaymentRequest) -> PaymentResponse: ...

    @abstractmethod
    def Query(self, out_trade_no: str) -> QueryResponse: ...

    @abstractmethod
    def Refund(self, request: RefundRequest) -> RefundResponse: ...

    @abstractmethod
    def Close(self, out_trade_no: str) -> bool: ...

    @abstractmethod
    def VerifyNotify(self, raw_data: bytes, headers: Dict[str, str]) -> bool: ...

    @abstractmethod
    def ParseNotify(self, raw_data: bytes) -> Dict[str, Any]: ...

    def Transfer(self, request: TransferRequest) -> TransferResponse:
        raise NotImplementedError(f'{self.Name} 不支持转账功能')
```

### 已实现适配器

| 渠道 | Channel | 类名 | 支持的方法 | Transfer |
|------|---------|------|------------|----------|
| 微信支付 | `wechat` | `WechatPaymentGateway` | jsapi / native / h5 / miniapp | 支持 |
| 支付宝 | `alipay` | `AlipayPaymentGateway` | app / h5 / native | 支持 |
| 银行卡 | `bank` | `BankPaymentGateway` | app / h5 / native | 仅 bank 类型 |

### 新增支付渠道只需三步

```python
# 1. 实现适配器
class FooPaymentGateway(AbstractPaymentGateway):
    Channel = 'foo'
    Name = '某支付'

    def Pay(self, request: PaymentRequest) -> PaymentResponse:
        ...

# 2. 在 apps.py 注册
payment_registry.register('foo', FooPaymentGateway)

# 3. 子服务配置密钥后即可使用
manager = PaymentManager(tenant_uuid)
manager.Pay(platform='foo', amount=100)
```

---

## 六、PaymentManager 编排器

```python
class PaymentManager:
    def __init__(self, tenant_uuid)

    def ConfigureGateway(platform, app_id, mch_id, api_key, ...)    # 配置支付渠道
    def Pay(platform, amount, subject, method, ...)                   # 发起支付
    def Query(out_trade_no, platform=None)                            # 查询订单
    def Refund(out_trade_no, amount, reason, ...)                     # 发起退款
    def Transfer(platform, amount, payee_account, ...)                # 企业付款
    def HandleNotify(platform, raw_data, headers=None)                # 处理回调
    def GetGatewayInstance(platform)                                  # 获取网关实例（供子服务自定义）
```

---

## 七、API 端点

```
POST   /api/payment/config/         # 配置支付渠道（SAAS管理员）
GET    /api/payment/config/         # 查看已配置渠道列表
DELETE /api/payment/config/         # 禁用渠道

POST   /api/payment/pay/            # 发起支付
GET    /api/payment/query/<out_trade_no>/   # 查询订单
POST   /api/payment/refund/         # 发起退款
POST   /api/payment/transfer/       # 企业付款

POST   /api/payment/notify/<platform>/   # 支付回调（微信/支付宝等）
GET    /api/payment/channels/       # 列出所有可用渠道
```

---

## 八、子服务集成示例

```python
from gvsds.apps.payment.manager import PaymentManager, PaymentError

manager = PaymentManager(tenant_uuid='al_long_001')

# 配置微信支付
manager.ConfigureGateway(
    platform='wechat',
    app_id='wx1234567890',
    mch_id='1234567890',
    api_key='your_api_key',
    notify_url='https://al_long.gvsds.com/api/payment/notify/wechat/',
)

# 发起支付
tx = manager.Pay(
    platform='wechat',
    amount=Decimal('100.00'),
    subject='订单支付',
    method='jsapi',
    open_id='user_openid',
)

# tx._prepay_info 包含前端调起支付所需的参数
return {'prepay_info': tx._prepay_info}

# 查询订单
result = manager.Query(out_trade_no='PY-ABC123')
if result.IsPaid:
    # 更新子服务订单状态
    ...

# 退款
tx = manager.Refund(out_trade_no='PY-ABC123', amount=Decimal('100.00'))
```

---

## 九、安全设计

1. **密钥加密存储**：`APIKey`、`PrivateKey`、`PublicKey` 使用 XOR + Base64 加密后入库
2. **加密密钥外置**：通过 `settings.PAYMENT_ENCRYPTION_KEY`（从 secrets 文件读取）管理
3. **回调签名验证**：每个网关适配器自行实现 `VerifyNotify()` 验证回调签名的合法性
4. **回调端点不认证**：`NotifyView` 关闭 DRF 的认证和权限类，但网关层签名验证保证安全
5. **密钥不输出**：`PaymentCredentials.AsDict()` 方法中 `api_key` 显示为 `***`
6. **幂等保护**：`OutTradeNO` 唯一约束，防止重复支付记录