# 支付运行时数据契约

本文档约定支付链路里订单扩展字段、插件入参和插件返回值的结构。当前项目仍处于开发阶段，不保留旧平铺结构兼容。

## 1. `ext_json` 职责

`ext_json` 只保存单据恢复、页面承接、插件运行所需的轻量扩展信息。通知、回调、重试、原始报文不进入 `ext_json`。

专门表职责如下：

- `ma_pay_callback_log`：保存每一次渠道回调原始参数、请求摘要、验签状态、处理状态、插件解析结果。
- `ma_notify_task`：按 `event_type + ref_no` 保存商户通知内容、通知状态、重试次数、最后响应。
- `ma_channel_notify_log`：保存渠道通知或查单类日志。
- `ma_pay_order`：保存支付尝试当前状态、渠道单号、回调状态、错误码和页面承接快照。

## 2. `ma_biz_order.ext_json`

业务单只保存稳定业务上下文。同一商户订单号复用时会校验这些字段，支付载体参数不得放在业务单里。

```php
[
    '_protocol_version' => 'v1', // 顶层强语义字段，方便后台查询和排障
    'merchant' => [
        'param' => '商户透传参数',
        'buyer' => '商户侧买家标识，可选',
    ],
]
```

## 3. `ma_pay_order.ext_json`

支付单是一笔支付尝试的快照，可以保存本次支付载体和页面承接信息。

```php
[
    '_protocol_version' => 'v2',
    'merchant' => [
        'param' => '商户透传参数',
        'buyer' => '商户侧买家标识，可选',
    ],
    'payment' => [
        'method' => 'web|jump|jsapi|app|scan|applet',
        'auth_code' => '条码/付款码支付时的付款码',
        'sub_openid' => 'JSAPI 支付所需 openid',
        'sub_appid' => '服务商模式子应用 ID',
    ],
    'presentation' => [
        'params_type' => 'jump|qrcode|html|jsapi|urlscheme|json|error',
        'product' => 'alipay|wxpay|unionpay|...',
        'action' => '插件动作名',
        'params_snapshot' => [
            'type' => 'qrcode',
            'qrcode_url' => 'https://...',
        ],
    ],
    'plugin' => [
        'pay_result' => [],
        'close_result' => [],
        'active_query' => [
            'queried_at' => '2026-04-25 12:00:00',
            'status' => 'success|failed|closed|pending|unknown|error',
            'raw_status' => '渠道原始状态',
            'channel_status' => '渠道状态码',
            'message' => '查单说明或异常信息',
            'success' => true,
            'channel_order_no' => '渠道订单号',
            'channel_trade_no' => '渠道交易号',
            'query_count' => 1,
        ],
    ],
    'lifecycle' => [
        'close_reason' => '关闭原因',
        'timeout_reason' => '超时原因',
    ],
]
```

## 4. 插件 `pay()` 入参

系统调用插件下单时会传入结构化 `extra`。插件读取商户透传、支付载体或协议字段时，从对应分区取值。

```php
[
    'pay_no' => 'PAY...',
    'biz_no' => 'BIZ...',
    'channel_request_no' => 'REQ...',
    'merchant_id' => 1,
    'merchant_no' => 'M...',
    'pay_type_code' => 'alipay',
    'amount' => 100,
    'subject' => '订单标题',
    'callback_url' => 'https://platform/api/pay/PAY.../callback',
    'notify_url' => 'https://merchant/notify',
    'return_url' => 'https://merchant/return',
    'client_ip' => '127.0.0.1',
    '_env' => 'pc',
    'extra' => [
        '_protocol_version' => 'v2',
        'merchant' => [],
        'payment' => [],
    ],
]
```

## 5. 插件 `pay()` 返回值

插件下单必须返回系统可承接的标准结构。后端会在 `PayOrderChannelDispatchService` 中严格校验字段和 `pay_params.type` 所需载荷，校验通过后才会写入 `ma_pay_order.ext_json.presentation`。

```php
[
    'pay_product' => 'alipay',
    'pay_action' => 'jump',
    'pay_params' => [
        'type' => 'jump',
        'redirect_url' => 'https://...',
    ],
    'chan_order_no' => '渠道订单号',
    'chan_trade_no' => '渠道交易号，可选；未生成时返回空字符串',
    'ext_json' => [
        // 插件私有轻量信息，可选
    ],
]
```

`pay_params.type` 决定收银台如何承接：

- `jump` / `web` / `h5`：必须提供 `redirect_url`、`payurl`、`pay_url`、`mweb_url` 或 `url`。
- `qrcode`：必须提供 `qrcode_text`、`qrcode_data`、`qrcode_url` 或 `qrcode`。
- `html` / `form`：必须提供 `html` 或 `action`；`form` 会归一为 `html`。
- `jsapi` / `urlscheme` / `mini`：必须提供对应拉起参数、跳转参数或小程序参数。
- `pos` / `transfer`：展示结构化参数，适合收银设备或转账类场景。
- `json`：直接展示结构化参数，由业务端继续处理。
- `error`：展示插件返回的错误信息。

`pay_params.type` 的兼容别名只在平台内部归一化使用，插件文档和新插件代码应直接返回标准值。常见别名包括：`scan|qr|code -> qrcode`、`redirect|url -> jump`、`wap -> h5`、`form -> html`、`app -> urlscheme`、`applet|wxplugin -> mini`。

## 6. 插件 `query()` 返回值

主动查单由 `PaymentRuntimeProcess` 定时触发，只处理 `status=支付中` 且已超过最小等待时间的支付单。插件 `query()` 应尽量返回标准字段：

```php
[
    'success' => true,
    'status' => 'success|failed|closed|pending',
    'channel_order_no' => '渠道订单号',
    'channel_trade_no' => '渠道交易号',
    'channel_status' => 'TRADE_SUCCESS',
    'message' => '渠道说明，可选',
    'paid_at' => '2026-04-25 12:00:00',
    'failed_at' => null,
    'ext_json' => [
        // 插件私有轻量补充信息，可选
    ],
]
```

处理规则：

- `success`：推进支付单成功，并发出 `payment.pay_order.succeeded` 事件。
- `failed`：推进支付单失败。
- `closed`：推进支付单关闭。
- `pending` / `unknown` / 查单异常：不推进终态，只把轻量快照写入 `ma_pay_order.ext_json.plugin.active_query`。

主动查单快照只保存状态、说明、渠道单号、时间和次数，不保存完整上游响应；完整回调仍以 `ma_pay_callback_log` 为准。

## 7. 插件 `notify()` 返回值

插件回调只负责验签和归一化结果。完整回调原文和该返回值会写入 `ma_pay_callback_log`，不会再回灌支付单 `ext_json`。

```php
[
    'status' => 'success|failed|pending',
    'message' => '渠道状态说明',
    'channel_order_no' => '渠道订单号',
    'channel_trade_no' => '渠道交易号',
    'channel_status' => 'TRADE_SUCCESS',
    'channel_error_code' => '',
    'channel_error_msg' => '',
    'paid_at' => '2026-04-25 12:00:00',
    'failed_at' => null,
    'fee_actual_amount' => null,
    'ext_json' => [
        // 插件私有轻量补充信息，可选
    ],
]
```

`status=pending` 只记录回调日志，不推进支付单终态。`success` 和 `failed` 会推进支付单状态，并按需要创建商户通知任务。

## 8. 商户通知任务事件模型

`ma_notify_task` 不再以 `pay_no` 作为唯一业务键。通知任务统一按事件建模：

```php
[
    'event_type' => 'PAY_SUCCESS|REFUND_SUCCESS|SETTLEMENT_SUCCESS',
    'ref_no' => '事件引用单号，例如 pay_no/refund_no/settle_no',
    'biz_no' => '业务单号',
    'pay_no' => '支付单号，支付相关事件保留',
    'notify_data' => [
        // 发送给商户的已签名参数
    ],
]
```

这样同一笔支付后续可以同时存在支付成功、退款成功、清算完成等多类通知，不会因为复用 `pay_no` 被唯一键挡住。

## 9. 回调日志留痕规则

渠道回调日志按“每次请求一条”写入，不做 `pay_no + callback_type` 覆盖或复用。

`request_hash` 是原始请求载荷的 SHA-256 摘要，用来在后台识别重复通知；重复通知是否推进业务状态，由支付单生命周期幂等控制。

## 10. 支付运行时维护

运行时维护使用 Webman 自定义进程 `payment-runtime`，对应 `app/process/PaymentRuntimeProcess.php`。进程只负责定时调度，具体业务由 `PaymentRuntimeMaintenanceService` 完成。

当前维护任务：

- 商户通知重试：扫描到期 `ma_notify_task` 并重新派发。
- 支付单超时：扫描已过期且未终态的支付单，推进为超时并释放冻结手续费。
- 主动查单：扫描支付中订单，调用插件 `query()` 补偿异步通知丢失或延迟。

当前阶段采用自定义进程直接执行，代码路径更短、部署依赖更少。后续如果商户通知量明显增大，建议引入 Redis 队列：支付成功监听器只负责投递队列，队列消费者负责 HTTP 通知派发和重试。

可在管理后台“支付配置”中维护以下系统配置：

- `pay_runtime_enabled`：运行时维护总开关。
- `pay_notify_retry_scan_interval_seconds` / `pay_notify_retry_batch_size`：通知重试扫描间隔和批量。
- `pay_order_timeout_scan_interval_seconds` / `pay_order_timeout_batch_size`：超时订单扫描间隔和批量。
- `pay_active_query_enabled` / `pay_active_query_interval_seconds` / `pay_active_query_min_age_seconds` / `pay_active_query_batch_size`：主动查单开关、间隔、等待时间和批量。

系统配置保存后会触发 `system.config.changed` 事件刷新运行时缓存，维护进程下一轮心跳读取新值。

## 11. 支付域事件

支付生命周期服务只负责状态推进和资金动作。支付单首次进入成功态后，会发送事件：

```php
PaymentEventConstant::PAY_ORDER_SUCCEEDED // payment.pay_order.succeeded
```

当前监听器 `PayOrderSucceededListener` 负责创建并派发商户支付成功通知。后续如果引入 Redis 队列，可以只替换监听器内部实现，把通知派发入队，而不用改订单生命周期服务。