重构初始化

app/common/interface/PayPluginInterface.php

@@ -0,0 +1,61 @@
+<?php
+declare(strict_types=1);
+
+namespace app\common\interface;
+
+/**
+ * 支付插件“基础契约”接口
+ *
+ * 职责边界：
+ * - `PayPluginInterface`：插件生命周期 + 元信息（后台可展示/可配置/可路由）。
+ * - `PaymentInterface`：支付动作能力（下单/查询/关单/退款/回调）。
+ *
+ * 约定：
+ * - `init()` 会在每次发起支付/退款等动作前由服务层调用，用于注入该通道对应的插件配置。
+ * - 元信息方法应为“纯读取”，不要依赖外部状态或数据库。
+ */
+interface PayPluginInterface
+{
+    /**
+     * 初始化插件（注入通道配置）
+     *
+     * 典型来源：`ma_payment_plugin_conf.config`，并由服务层额外合并通道信息、支付方式声明等上下文。
+     * 插件应在这里完成：缓存配置、初始化 SDK/HTTP 客户端等。
+     *
+     * @param array<string, mixed> $channelConfig
+     */
+    public function init(array $channelConfig): void;
+
+    /** 插件代码（与 ma_payment_plugin.code 对应） */
+    public function getCode(): string;
+
+    /** 插件名称（用于后台展示） */
+    public function getName(): string;
+
+    /** 插件作者名称（用于后台展示） */
+    public function getAuthorName(): string;
+
+    /** 插件作者链接（用于后台展示） */
+    public function getAuthorLink(): string;
+
+    /** 插件版本号（用于后台展示） */
+    public function getVersion(): string;
+
+    /**
+     * 插件声明支持的支付方式编码
+     *
+     * @return array<string>
+     */
+    public function getEnabledPayTypes(): array;
+
+    /** 插件声明支持的转账方式编码 */
+    public function getEnabledTransferTypes(): array;
+
+    /**
+     * 插件配置结构（用于后台渲染表单/校验）
+     *
+     * @return array<string, mixed>
+     */
+    public function getConfigSchema(): array;
+}
+

app/common/interface/PaymentInterface.php

@@ -0,0 +1,99 @@
+<?php
+
+declare(strict_types=1);
+
+namespace app\common\interface;
+
+use app\exception\PaymentException;
+use support\Request;
+use support\Response;
+
+/**
+ * 支付插件接口
+ *
+ * 所有支付插件必须实现此接口，用于统一下单、订单查询、关闭、退款及回调通知等核心能力。
+ * 建议继承 BasePayment 获得 HTTP 请求等通用能力，再实现本接口。
+ *
+ * 异常约定：实现类在业务失败时应抛出 PaymentException，便于统一处理和返回。
+ */
+interface PaymentInterface
+{
+    // ==================== 订单操作 ====================
+
+    /**
+     * 统一下单
+     *
+     * @param array<string, mixed> $order 订单数据，通常包含：
+     *         - order_id: 系统支付单号，建议直接使用 pay_no
+     *         - amount: 金额（分）
+     *         - subject: 商品标题
+     *         - body: 商品描述
+     *         - callback_url: 第三方异步回调地址（回调到本系统）
+     *         - return_url: 支付完成跳转地址
+     * @return array<string, mixed> 支付参数，需包含 pay_params、chan_order_no、chan_trade_no
+     * @throws PaymentException 下单失败、渠道异常、参数错误等
+     */
+    public function pay(array $order): array;
+
+    /**
+     * 查询订单状态
+     *
+     * @param array<string, mixed> $order 订单数据（至少含 order_id、chan_order_no）
+     * @return array<string, mixed> 订单状态信息，通常包含：
+     *         - status: 订单状态
+     *         - chan_trade_no: 渠道交易号
+     *         - pay_amount: 实付金额
+     * @throws PaymentException 查询失败、渠道异常等
+     */
+    public function query(array $order): array;
+
+    /**
+     * 关闭订单
+     *
+     * @param array<string, mixed> $order 订单数据（至少含 order_id、chan_order_no）
+     * @return array<string, mixed> 关闭结果，通常包含 success、msg
+     * @throws PaymentException 关闭失败、渠道异常等
+     */
+    public function close(array $order): array;
+
+    /**
+     * 申请退款
+     *
+     * @param array<string, mixed> $order 退款数据，通常包含：
+     *         - order_id: 原支付单号
+     *         - chan_order_no: 渠道订单号
+     *         - refund_amount: 退款金额（分）
+     *         - refund_no: 退款单号
+     * @return array<string, mixed> 退款结果，通常包含 success、chan_refund_no、msg
+     * @throws PaymentException 退款失败、渠道异常等
+     */
+    public function refund(array $order): array;
+
+    // ==================== 异步通知 ====================
+
+    /**
+     * 解析并验证支付回调通知
+     *
+     * @param Request $request 支付渠道的异步通知请求（GET/POST 参数）
+     * @return array<string, mixed> 解析结果，通常包含：
+     *         - success: 是否支付成功
+     *         - status: 插件解析出的渠道状态文本
+     *         - pay_order_id: 系统支付单号
+     *         - chan_trade_no: 渠道交易号
+     *         - chan_order_no: 渠道订单号
+     *         - amount: 支付金额（分）
+     *         - paid_at: 支付成功时间
+     * @throws PaymentException 验签失败、数据异常等
+     */
+    public function notify(Request $request): array;
+
+    /**
+     * 回调处理成功时返回给第三方的平台响应。
+     */
+    public function notifySuccess(): string|Response;
+
+    /**
+     * 回调处理失败时返回给第三方的平台响应。
+     */
+    public function notifyFail(): string|Response;
+}