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

app/http/api/controller/trade/PayController.php

@@ -15,14 +15,23 @@ use support\Request;
 use support\Response;
 
 /**
- * 支付接口控制器。
+ * 收银台支付接口控制器。
  *
- * 负责支付预下单、支付查询、支付关闭和渠道回调入口。
+ * 负责支付预下单、支付单查询、支付关闭、超时收口和渠道回调入口。
+ *
+ * @property PayOrderService $payOrderService 支付订单服务
+ * @property MerchantApiCredentialService $merchantApiCredentialService 商户 API 凭证服务
+ * @property PaymentTypeService $paymentTypeService 支付方式服务
  */
 class PayController extends BaseController
 {
     /**
-     * 构造函数，注入支付单相关依赖。
+     * 构造方法。
+     *
+     * @param PayOrderService $payOrderService 支付订单服务
+     * @param MerchantApiCredentialService $merchantApiCredentialService 商户 API 凭证服务
+     * @param PaymentTypeService $paymentTypeService 支付类型服务
+     * @return void
      */
     public function __construct(
         protected PayOrderService $payOrderService,
@@ -32,7 +41,12 @@ class PayController extends BaseController
     }
 
     /**
-     * 支付预下单。
+     * 创建支付预下单并返回支付尝试结果。
+     *
+     * 先对外部支付参数完成验签和归一化，再交给支付单尝试服务选择路由并创建支付单。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function prepare(Request $request): Response
     {
@@ -47,6 +61,12 @@ class PayController extends BaseController
 
     /**
      * 查询支付单详情。
+     *
+     * 用于前端轮询支付结果或展示支付单当前状态。
+     *
+     * @param Request $request 请求对象
+     * @param string $payNo 支付单号
+     * @return Response 响应对象
      */
     public function show(Request $request, string $payNo): Response
     {
@@ -59,6 +79,12 @@ class PayController extends BaseController
 
     /**
      * 关闭支付单。
+     *
+     * 仅对尚未完成的支付单生效，通常由业务系统在用户主动取消时调用。
+     *
+     * @param Request $request 请求对象
+     * @param string $payNo 支付单号
+     * @return Response 响应对象
      */
     public function close(Request $request, string $payNo): Response
     {
@@ -73,6 +99,12 @@ class PayController extends BaseController
 
     /**
      * 标记支付单超时。
+     *
+     * 用于订单到达超时时间后的状态收口，后续由生命周期服务统一处理手续费释放和订单同步。
+     *
+     * @param Request $request 请求对象
+     * @param string $payNo 支付单号
+     * @return Response 响应对象
      */
     public function timeout(Request $request, string $payNo): Response
     {
@@ -86,7 +118,14 @@ class PayController extends BaseController
     }
 
     /**
-     * 处理渠道回调。
+     * 处理支付回调。
+     *
+     * 当路径里携带 `payNo` 时，进入第三方插件回调链路；
+     * 当未携带 `payNo` 时，按平台统一回调载荷进入渠道回调处理。
+     *
+     * @param Request $request 请求对象
+     * @param string $payNo 支付单号
+     * @return Response|string 字符串或响应对象
      */
     public function callback(Request $request, string $payNo = ''): Response|string
     {
@@ -103,6 +142,13 @@ class PayController extends BaseController
      * 归一化外部支付下单参数并完成签名校验。
      *
      * 这层逻辑保留在控制器内，避免中间件承担业务验签职责。
+     * 同时把外部字段映射为系统内部支付单入参，并将回调基址写入扩展信息。
+     *
+     * @param Request $request 请求对象
+     * @param array $payload 请求载荷
+     * @return array 支付下单参数
+     * @throws \app\exception\ResourceNotFoundException
+     * @throws \app\exception\ValidationException
      */
     private function normalizePreparePayload(Request $request, array $payload): array
     {
@@ -113,6 +159,7 @@ class PayController extends BaseController
         $typeCode = (string) $paymentType->code;
 
         $money = (string) ($payload['money'] ?? '0');
+        // 外部协议按“元”传金额，系统内部统一转成“分”存储和计算。
         $amount = (int) round(((float) $money) * 100);
 
         return [
@@ -130,9 +177,16 @@ class PayController extends BaseController
                 'clientip' => (string) ($payload['clientip'] ?? ''),
                 'device' => (string) ($payload['device'] ?? ''),
                 'sign_type' => (string) ($payload['sign_type'] ?? 'MD5'),
+                // 回调基址会被插件和支付单后续流程复用。
                 'channel_callback_base_url' => (string) sys_config('site_url') . '/api/pay',
             ],
         ];
     }
 }
 
+
+
+
+
+
+

app/http/api/controller/trade/RefundController.php

@@ -13,12 +13,17 @@ use support\Response;
 /**
  * 退款接口控制器。
  *
- * 负责退款单创建与退款单查询。
+ * 负责退款单创建、查询和终态推进入口。
+ *
+ * @property RefundService $refundService 退款服务
  */
 class RefundController extends BaseController
 {
     /**
-     * 构造函数，注入退款相关依赖。
+     * 构造方法。
+     *
+     * @param RefundService $refundService 退款服务
+     * @return void
      */
     public function __construct(
         protected RefundService $refundService,
@@ -27,6 +32,11 @@ class RefundController extends BaseController
 
     /**
      * 创建退款单。
+     *
+     * 以原支付单为基准创建退款申请，后续由退款生命周期服务推进处理中、成功或失败状态。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function create(Request $request): Response
     {
@@ -37,6 +47,12 @@ class RefundController extends BaseController
 
     /**
      * 查询退款单详情。
+     *
+     * 用于退款进度展示和后台对账。
+     *
+     * @param Request $request 请求对象
+     * @param string $refundNo 退款单号
+     * @return Response 响应对象
      */
     public function show(Request $request, string $refundNo): Response
     {
@@ -49,6 +65,12 @@ class RefundController extends BaseController
 
     /**
      * 标记退款处理中。
+     *
+     * 由渠道侧或任务调度侧在退款请求已经受理后调用，用于推进退款状态机。
+     *
+     * @param Request $request 请求对象
+     * @param string $refundNo 退款单号
+     * @return Response 响应对象
      */
     public function processing(Request $request, string $refundNo): Response
     {
@@ -63,6 +85,12 @@ class RefundController extends BaseController
 
     /**
      * 退款重试。
+     *
+     * 仅用于失败态退款单重新发起处理，保持退款链路幂等和可恢复。
+     *
+     * @param Request $request 请求对象
+     * @param string $refundNo 退款单号
+     * @return Response 响应对象
      */
     public function retry(Request $request, string $refundNo): Response
     {
@@ -77,6 +105,12 @@ class RefundController extends BaseController
 
     /**
      * 标记退款失败。
+     *
+     * 用于把退款单推进到终态失败，并记录失败原因供运营和对账排查。
+     *
+     * @param Request $request 请求对象
+     * @param string $refundNo 退款单号
+     * @return Response 响应对象
      */
     public function markFail(Request $request, string $refundNo): Response
     {
@@ -91,3 +125,8 @@ class RefundController extends BaseController
 
 }
 
+
+
+
+
+