更新统一使用 PHPDoc + PSR-19 标准注释

app/common/interface/PayPluginInterface.php

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

app/common/interface/PaymentInterface.php

@@ -9,91 +9,74 @@ use support\Request;
 use support\Response;
 
 /**
- * 支付插件接口
+ * 支付动作能力接口。
  *
- * 所有支付插件必须实现此接口，用于统一下单、订单查询、关闭、退款及回调通知等核心能力。
- * 建议继承 BasePayment 获得 HTTP 请求等通用能力，再实现本接口。
+ * 所有支付插件必须实现此接口，用于统一下单、订单查询、关闭、退款和回调通知。
+ * 建议先继承 `BasePayment` 获取 HTTP 请求等通用能力，再实现本接口。
  *
- * 异常约定：实现类在业务失败时应抛出 PaymentException，便于统一处理和返回。
+ * 异常约定：实现类在业务失败时应抛出 `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 下单失败、渠道异常、参数错误等
+     * @param array $order 订单参数
+     * @return array 下单结果
      */
     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 查询失败、渠道异常等
+     * @param array $order 订单参数
+     * @return array 查询结果
      */
     public function query(array $order): array;
 
     /**
-     * 关闭订单
+     * 关闭订单。
      *
-     * @param array<string, mixed> $order 订单数据（至少含 order_id、chan_order_no）
-     * @return array<string, mixed> 关闭结果，通常包含 success、msg
-     * @throws PaymentException 关闭失败、渠道异常等
+     * @param array $order 订单参数
+     * @return array 关闭结果
      */
     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 退款失败、渠道异常等
+     * @param array $order 订单参数
+     * @return array 退款结果
      */
     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 验签失败、数据异常等
+     * @param Request $request 请求对象
+     * @return array 回调结果
      */
     public function notify(Request $request): array;
 
     /**
      * 回调处理成功时返回给第三方的平台响应。
+     *
+     * @return string|Response 响应内容
      */
     public function notifySuccess(): string|Response;
 
     /**
      * 回调处理失败时返回给第三方的平台响应。
+     *
+     * @return string|Response 响应内容
      */
     public function notifyFail(): string|Response;
 }
+
+
+
+