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

app/http/api/controller/adapter/EpayController.php

@@ -12,12 +12,17 @@ use support\Response;
 /**
  * Epay 协议兼容控制器。
  *
- * 负责 submit.php、mapi.php 和 api.php 的入口场景校验与结果分发。
+ * 负责兼容入口场景的校验与结果分发。
+ *
+ * @property EpayCompatService $epayCompatService Epay 兼容服务
  */
 class EpayController extends BaseController
 {
     /**
-     * 构造函数，注入兼容服务。
+     * 构造方法。
+     *
+     * @param EpayCompatService $epayCompatService Epay 兼容服务
+     * @return void
      */
     public function __construct(
         protected EpayCompatService $epayCompatService
@@ -25,6 +30,9 @@ class EpayController extends BaseController
 
     /**
      * 页面跳转支付入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function submit(Request $request): Response
     {
@@ -47,6 +55,9 @@ class EpayController extends BaseController
 
     /**
      * API 接口支付入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function mapi(Request $request): Response
     {
@@ -69,6 +80,9 @@ class EpayController extends BaseController
 
     /**
      * 标准 API 接口入口。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function api(Request $request): Response
     {
@@ -98,3 +112,8 @@ class EpayController extends BaseController
         }
     }
 }
+
+
+
+
+

app/http/api/controller/notify/NotifyController.php

@@ -10,14 +10,19 @@ use support\Request;
 use support\Response;
 
 /**
- * 通知与回调记录控制器。
+ * 通知记录控制器。
  *
- * 负责渠道通知日志和商户通知任务的接入。
+ * 负责渠道通知日志和商户通知任务的接入，不承担真实业务回调处理。
+ *
+ * @property NotifyService $notifyService 通知服务
  */
 class NotifyController extends BaseController
 {
     /**
-     * 构造函数，注入通知服务。
+     * 构造方法。
+     *
+     * @param NotifyService $notifyService 通知服务
+     * @return void
      */
     public function __construct(
         protected NotifyService $notifyService
@@ -25,9 +30,12 @@ class NotifyController extends BaseController
     }
 
     /**
-     * POST /api/notify/channel
-     *
      * 记录渠道通知日志。
+     *
+     * 用于保存外部渠道发来的通知原文，便于后续排查和审计。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function channel(Request $request): Response
     {
@@ -37,9 +45,12 @@ class NotifyController extends BaseController
     }
 
     /**
-     * POST /api/notify/merchant
-     *
      * 创建商户通知任务。
+     *
+     * 由支付或结算完成后触发，把通知任务交给异步通知链路处理。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function merchant(Request $request): Response
     {
@@ -49,3 +60,8 @@ class NotifyController extends BaseController
     }
 }
 
+
+
+
+
+

app/http/api/controller/route/RouteController.php

@@ -9,14 +9,19 @@ use support\Request;
 use support\Response;
 
 /**
- * 路由预览控制器。
+ * 路由解析控制器。
  *
- * 用于返回指定商户分组、支付方式和金额条件下的路由解析结果。
+ * 用于根据商户分组、支付方式和金额条件返回路由候选与最终选中通道。
+ *
+ * @property PaymentRouteService $paymentRouteService 支付路由服务
  */
 class RouteController extends BaseController
 {
     /**
-     * 构造函数，注入路由服务。
+     * 构造方法。
+     *
+     * @param PaymentRouteService $paymentRouteService 支付路由服务
+     * @return void
      */
     public function __construct(
         protected PaymentRouteService $paymentRouteService
@@ -24,9 +29,12 @@ class RouteController extends BaseController
     }
 
     /**
-     * GET /api/routes/resolve
-     *
      * 解析支付路由。
+     *
+     * 这个接口会返回当前条件下的候选通道和最终命中的通道信息，通常用于下单前查看结果。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function resolve(Request $request): Response
     {
@@ -41,3 +49,8 @@ class RouteController extends BaseController
     }
 }
 
+
+
+
+
+

app/http/api/controller/settlement/SettlementController.php

@@ -13,12 +13,17 @@ use support\Response;
 /**
  * 清算接口控制器。
  *
- * 负责清算单创建、查询和清算状态推进。
+ * 负责清算单创建、查询和清算终态推进。
+ *
+ * @property SettlementService $settlementService 结算服务
  */
 class SettlementController extends BaseController
 {
     /**
-     * 构造函数，注入清算相关依赖。
+     * 构造方法。
+     *
+     * @param SettlementService $settlementService 结算服务
+     * @return void
      */
     public function __construct(
         protected SettlementService $settlementService,
@@ -26,7 +31,12 @@ class SettlementController extends BaseController
     }
 
     /**
-     * 创建清结算单。
+     * 创建清算单。
+     *
+     * 会把传入的清算明细和汇总一起交给清算生命周期服务落库。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function create(Request $request): Response
     {
@@ -37,7 +47,13 @@ class SettlementController extends BaseController
     }
 
     /**
-     * 查询清结算单详情。
+     * 查询清算单详情。
+     *
+     * 用于查看批次金额、状态和关联支付单明细。
+     *
+     * @param Request $request 请求对象
+     * @param string $settleNo 结算单号
+     * @return Response 响应对象
      */
     public function show(Request $request, string $settleNo): Response
     {
@@ -49,7 +65,13 @@ class SettlementController extends BaseController
     }
 
     /**
-     * 标记清结算成功。
+     * 标记清算成功。
+     *
+     * 会触发商户余额入账，并同步清算单、清算明细和关联支付单状态。
+     *
+     * @param Request $request 请求对象
+     * @param string $settleNo 结算单号
+     * @return Response 响应对象
      */
     public function complete(Request $request, string $settleNo): Response
     {
@@ -63,7 +85,13 @@ class SettlementController extends BaseController
     }
 
     /**
-     * 标记清结算失败。
+     * 标记清算失败。
+     *
+     * 仅在清算批次未成功入账时使用，用于把批次推进到失败终态并保留原因。
+     *
+     * @param Request $request 请求对象
+     * @param string $settleNo 结算单号
+     * @return Response 响应对象
      */
     public function failSettlement(Request $request, string $settleNo): Response
     {
@@ -76,3 +104,7 @@ class SettlementController extends BaseController
         return $this->success($this->settlementService->failSettlement($settleNo, (string) ($data['reason'] ?? '')));
     }
 }
+
+
+
+

app/http/api/controller/trace/TraceController.php

@@ -10,9 +10,17 @@ use support\Response;
 
 /**
  * 统一追踪查询控制器。
+ *
+ * @property TradeTraceService $tradeTraceService 交易追踪服务
  */
 class TraceController extends BaseController
 {
+    /**
+ * 构造方法。
+     *
+     * @param TradeTraceService $tradeTraceService 交易追踪服务
+     * @return void
+     */
     public function __construct(
         protected TradeTraceService $tradeTraceService
     ) {
@@ -20,6 +28,10 @@ class TraceController extends BaseController
 
     /**
      * 查询指定追踪号对应的完整交易链路。
+     *
+     * @param Request $request 请求对象
+     * @param string $traceNo 追踪号
+     * @return Response 响应对象
      */
     public function show(Request $request, string $traceNo): Response
     {
@@ -37,3 +49,8 @@ class TraceController extends BaseController
         return $this->success($result);
     }
 }
+
+
+
+
+

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
 
 }
 
+
+
+
+
+