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

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'],
     ];
 }
+
+