更新统一使用 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
 
 }
 
+
+
+
+
+

app/http/api/validation/EpayValidator.php

@@ -7,10 +7,15 @@ use support\validation\Validator;
 /**
  * ePay 兼容层请求校验器。
  *
- * 根据 submit、mapi、api.php 的不同入口场景做分场景校验，不依赖隐藏标记字段。
+ * 用于校验兼容层不同入口的请求参数。
  */
 class EpayValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'act' => 'required|string|in:query,settle,order,orders,refund',
         'pid' => 'required|integer|gt:0',
@@ -33,6 +38,11 @@ class EpayValidator extends Validator
         'page' => 'sometimes|integer|gt:0',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'act' => '操作类型',
         'pid' => '商户ID',
@@ -55,6 +65,11 @@ class EpayValidator extends Validator
         'page' => '页码',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'submit' => ['pid', 'type', 'out_trade_no', 'notify_url', 'return_url', 'name', 'money', 'sign', 'sign_type', 'param'],
         'mapi' => ['pid', 'type', 'out_trade_no', 'notify_url', 'return_url', 'name', 'money', 'clientip', 'device', 'sign', 'sign_type', 'param'],
@@ -67,6 +82,11 @@ class EpayValidator extends Validator
         'refund_out_trade_no' => ['act', 'pid', 'key', 'out_trade_no', 'money', 'refund_no', 'reason'],
     ];
 
+    /**
+     * 根据场景返回 ePay 兼容层校验规则。
+     *
+     * @return array 校验规则
+     */
     public function rules(): array
     {
         $rules = parent::rules();
@@ -111,3 +131,4 @@ class EpayValidator extends Validator
         };
     }
 }
+

app/http/api/validation/NotifyChannelValidator.php

@@ -11,6 +11,11 @@ use support\validation\Validator;
  */
 class NotifyChannelValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'notify_no' => 'sometimes|string|min:1|max:64',
         'channel_id' => 'required|integer|min:1|exists:ma_payment_channel,id',
@@ -27,6 +32,11 @@ class NotifyChannelValidator extends Validator
         'last_error' => 'nullable|string|max:255',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'notify_no' => '通知单号',
         'channel_id' => '通道ID',
@@ -43,7 +53,14 @@ class NotifyChannelValidator extends Validator
         'last_error' => '最后错误',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'store' => ['notify_no', 'channel_id', 'notify_type', 'biz_no', 'pay_no', 'channel_request_no', 'channel_trade_no', 'raw_payload', 'verify_status', 'process_status', 'retry_count', 'next_retry_at', 'last_error'],
     ];
 }
+
+

app/http/api/validation/NotifyMerchantValidator.php

@@ -11,6 +11,11 @@ use support\validation\Validator;
  */
 class NotifyMerchantValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'notify_no' => 'sometimes|string|min:1|max:64',
         'merchant_id' => 'required|integer|min:1|exists:ma_merchant,id',
@@ -26,6 +31,11 @@ class NotifyMerchantValidator extends Validator
         'last_response' => 'nullable|string|max:255',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'notify_no' => '通知单号',
         'merchant_id' => '商户ID',
@@ -34,14 +44,21 @@ class NotifyMerchantValidator extends Validator
         'pay_no' => '支付单号',
         'notify_url' => '通知地址',
         'notify_data' => '通知内容',
-        'status' => '状态',
+        'status' => '通知任务状态',
         'retry_count' => '重试次数',
         'next_retry_at' => '下次重试时间',
         'last_notify_at' => '最后通知时间',
         'last_response' => '最后响应',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'store' => ['notify_no', 'merchant_id', 'merchant_group_id', 'biz_no', 'pay_no', 'notify_url', 'notify_data', 'status', 'retry_count', 'next_retry_at', 'last_notify_at', 'last_response'],
     ];
 }
+
+

app/http/api/validation/PayCallbackValidator.php

@@ -7,10 +7,15 @@ use support\validation\Validator;
 /**
  * 支付回调参数校验器。
  *
- * 用于校验渠道回调和主动查单回传参数。
+ * 用于校验渠道回调和回调模拟入参。
  */
 class PayCallbackValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'pay_no' => 'required|string|min:1|max:64|exists:ma_pay_order,pay_no',
         'success' => 'required|boolean',
@@ -29,15 +34,20 @@ class PayCallbackValidator extends Validator
         'ext_json' => 'nullable|array',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'pay_no' => '支付单号',
-        'success' => '是否成功',
+        'success' => '支付是否成功',
         'channel_id' => '通道ID',
         'callback_type' => '回调类型',
         'request_data' => '原始回调数据',
         'verify_status' => '验签状态',
         'process_status' => '处理状态',
-        'process_result' => '处理结果',
+        'process_result' => '处理详情',
         'channel_trade_no' => '渠道交易号',
         'channel_order_no' => '渠道订单号',
         'fee_actual_amount' => '实际手续费',
@@ -47,7 +57,14 @@ class PayCallbackValidator extends Validator
         'ext_json' => '扩展信息',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'callback' => ['pay_no', 'success', 'channel_id', 'callback_type', 'request_data', 'verify_status', 'process_status', 'process_result', 'channel_trade_no', 'channel_order_no', 'fee_actual_amount', 'paid_at', 'channel_error_code', 'channel_error_msg', 'ext_json'],
     ];
 }
+
+

app/http/api/validation/PayCloseValidator.php

@@ -11,6 +11,11 @@ use support\validation\Validator;
  */
 class PayCloseValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'pay_no' => 'required|string|min:1|max:64|exists:ma_pay_order,pay_no',
         'reason' => 'nullable|string|max:255',
@@ -18,6 +23,11 @@ class PayCloseValidator extends Validator
         'ext_json' => 'nullable|array',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'pay_no' => '支付单号',
         'reason' => '关闭原因',
@@ -25,7 +35,14 @@ class PayCloseValidator extends Validator
         'ext_json' => '扩展信息',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'close' => ['pay_no', 'reason', 'closed_at', 'ext_json'],
     ];
 }
+
+

app/http/api/validation/PayPrepareValidator.php

@@ -11,6 +11,11 @@ use support\validation\Validator;
  */
 class PayPrepareValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'merchant_id' => 'required|integer|min:1|exists:ma_merchant,id',
         'merchant_order_no' => 'required|string|min:1|max:64',
@@ -21,6 +26,11 @@ class PayPrepareValidator extends Validator
         'ext_json' => 'nullable|array',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'merchant_id' => '商户ID',
         'merchant_order_no' => '商户订单号',
@@ -31,7 +41,14 @@ class PayPrepareValidator extends Validator
         'ext_json' => '扩展信息',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'prepare' => ['merchant_id', 'merchant_order_no', 'pay_type_id', 'pay_amount', 'subject', 'body', 'ext_json'],
     ];
 }
+
+

app/http/api/validation/PayTimeoutValidator.php

@@ -11,6 +11,11 @@ use support\validation\Validator;
  */
 class PayTimeoutValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'pay_no' => 'required|string|min:1|max:64|exists:ma_pay_order,pay_no',
         'reason' => 'nullable|string|max:255',
@@ -18,6 +23,11 @@ class PayTimeoutValidator extends Validator
         'ext_json' => 'nullable|array',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'pay_no' => '支付单号',
         'reason' => '超时原因',
@@ -25,7 +35,14 @@ class PayTimeoutValidator extends Validator
         'ext_json' => '扩展信息',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'timeout' => ['pay_no', 'reason', 'timeout_at', 'ext_json'],
     ];
 }
+
+

app/http/api/validation/RefundActionValidator.php

@@ -11,6 +11,11 @@ use support\validation\Validator;
  */
 class RefundActionValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'refund_no' => 'required|string|min:1|max:64|exists:ma_refund_order,refund_no',
         'reason' => 'nullable|string|max:255',
@@ -20,6 +25,11 @@ class RefundActionValidator extends Validator
         'ext_json' => 'nullable|array',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'refund_no' => '退款单号',
         'reason' => '原因',
@@ -29,9 +39,16 @@ class RefundActionValidator extends Validator
         'ext_json' => '扩展信息',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'processing' => ['refund_no', 'reason', 'last_error', 'processing_at', 'ext_json'],
         'retry' => ['refund_no', 'reason', 'last_error', 'processing_at', 'ext_json'],
         'fail' => ['refund_no', 'reason', 'last_error', 'failed_at', 'ext_json'],
     ];
 }
+
+

app/http/api/validation/RefundCreateValidator.php

@@ -11,6 +11,11 @@ use support\validation\Validator;
  */
 class RefundCreateValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'pay_no' => 'required|string|min:1|max:64|exists:ma_pay_order,pay_no',
         'merchant_refund_no' => 'sometimes|string|min:1|max:64',
@@ -19,6 +24,11 @@ class RefundCreateValidator extends Validator
         'ext_json' => 'nullable|array',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'pay_no' => '支付单号',
         'merchant_refund_no' => '商户退款单号',
@@ -27,7 +37,14 @@ class RefundCreateValidator extends Validator
         'ext_json' => '扩展信息',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'store' => ['pay_no', 'merchant_refund_no', 'refund_amount', 'reason', 'ext_json'],
     ];
 }
+
+

app/http/api/validation/RouteResolveValidator.php

@@ -7,10 +7,15 @@ use support\validation\Validator;
 /**
  * 路由解析参数校验器。
  *
- * 用于校验路由预览所需参数。
+ * 用于校验路由解析所需参数。
  */
 class RouteResolveValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'merchant_group_id' => 'required|integer|min:1|exists:ma_merchant_group,id',
         'pay_type_id' => 'required|integer|min:1|exists:ma_payment_type,id',
@@ -18,6 +23,11 @@ class RouteResolveValidator extends Validator
         'stat_date' => 'nullable|date_format:Y-m-d',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'merchant_group_id' => '商户分组ID',
         'pay_type_id' => '支付方式',
@@ -25,7 +35,14 @@ class RouteResolveValidator extends Validator
         'stat_date' => '统计日期',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'resolve' => ['merchant_group_id', 'pay_type_id', 'pay_amount', 'stat_date'],
     ];
 }
+
+

app/http/api/validation/SettlementActionValidator.php

@@ -11,20 +11,37 @@ use support\validation\Validator;
  */
 class SettlementActionValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'settle_no' => 'required|string|min:1|max:64|exists:ma_settlement_order,settle_no',
         'reason' => 'nullable|string|max:255',
         'ext_json' => 'nullable|array',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'settle_no' => '清算单号',
         'reason' => '原因',
         'ext_json' => '扩展信息',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'complete' => ['settle_no'],
         'fail' => ['settle_no', 'reason', 'ext_json'],
     ];
 }
+
+

app/http/api/validation/SettlementCreateValidator.php

@@ -11,6 +11,11 @@ use support\validation\Validator;
  */
 class SettlementCreateValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'settle_no' => 'sometimes|string|min:1|max:64',
         'merchant_id' => 'required|integer|min:1|exists:ma_merchant,id',
@@ -38,6 +43,11 @@ class SettlementCreateValidator extends Validator
         'items.*.item_status' => 'sometimes|integer|min:0',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'settle_no' => '清算单号',
         'merchant_id' => '商户ID',
@@ -45,7 +55,7 @@ class SettlementCreateValidator extends Validator
         'channel_id' => '通道ID',
         'cycle_type' => '结算周期类型',
         'cycle_key' => '结算周期键',
-        'status' => '状态',
+        'status' => '清算单状态',
         'generated_at' => '生成时间',
         'accounted_amount' => '入账金额',
         'gross_amount' => '交易总额',
@@ -57,7 +67,14 @@ class SettlementCreateValidator extends Validator
         'items' => '清算明细',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'store' => ['settle_no', 'merchant_id', 'merchant_group_id', 'channel_id', 'cycle_type', 'cycle_key', 'status', 'generated_at', 'accounted_amount', 'gross_amount', 'fee_amount', 'refund_amount', 'fee_reverse_amount', 'net_amount', 'ext_json', 'items', 'items.*.pay_no', 'items.*.refund_no', 'items.*.pay_amount', 'items.*.fee_amount', 'items.*.refund_amount', 'items.*.fee_reverse_amount', 'items.*.net_amount', 'items.*.item_status'],
     ];
 }
+
+

app/http/api/validation/TraceQueryValidator.php

@@ -9,15 +9,32 @@ use support\validation\Validator;
  */
 class TraceQueryValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'trace_no' => 'required|string|min:1|max:64',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'trace_no' => '追踪号',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'show' => ['trace_no'],
     ];
 }
+
+