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

app/http/mer/controller/account/AccountController.php

@@ -13,11 +13,18 @@ use support\Response;
  * 商户账户控制器。
  *
  * 负责商户余额查询等账户类接口。
+ *
+ * @property MerchantService $merchantService 商户服务
+ * @property MerchantAccountService $merchantAccountService 商户账户服务
  */
 class AccountController extends BaseController
 {
     /**
-     * 构造函数，注入商户与账户服务。
+     * 构造方法。
+     *
+     * @param MerchantService $merchantService 商户服务
+     * @param MerchantAccountService $merchantAccountService 商户账户服务
+     * @return void
      */
     public function __construct(
         protected MerchantService $merchantService,
@@ -26,9 +33,11 @@ class AccountController extends BaseController
     }
 
     /**
-     * GET /mer/merchant/{merchantNo}/balance
-     *
      * 查询商户余额。
+     *
+     * @param Request $request 请求对象
+     * @param string $merchantNo 商户号
+     * @return Response 响应对象
      */
     public function balance(Request $request, string $merchantNo): Response
     {
@@ -45,3 +54,8 @@ class AccountController extends BaseController
     }
 }
 
+
+
+
+
+

app/http/mer/controller/merchant/MerchantPortalController.php

@@ -12,9 +12,17 @@ use support\Response;
  * 商户后台基础页面控制器。
  *
  * 统一承接当前商户可见的资料、通道、路由、凭证、清算和资金页面数据。
+ *
+ * @property MerchantPortalService $merchantPortalService 商户门户服务
  */
 class MerchantPortalController extends BaseController
 {
+    /**
+ * 构造方法。
+     *
+     * @param MerchantPortalService $merchantPortalService 商户门户服务
+     * @return void
+     */
     public function __construct(
         protected MerchantPortalService $merchantPortalService
     ) {
@@ -22,6 +30,9 @@ class MerchantPortalController extends BaseController
 
     /**
      * 当前商户资料。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function profile(Request $request): Response
     {
@@ -35,6 +46,9 @@ class MerchantPortalController extends BaseController
 
     /**
      * 更新当前商户资料。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function updateProfile(Request $request): Response
     {
@@ -50,6 +64,9 @@ class MerchantPortalController extends BaseController
 
     /**
      * 修改当前商户登录密码。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function changePassword(Request $request): Response
     {
@@ -65,6 +82,9 @@ class MerchantPortalController extends BaseController
 
     /**
      * 我的通道列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function myChannels(Request $request): Response
     {
@@ -81,7 +101,10 @@ class MerchantPortalController extends BaseController
     }
 
     /**
-     * 路由预览。
+     * 获取路由解析结果。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function routePreview(Request $request): Response
     {
@@ -99,7 +122,10 @@ class MerchantPortalController extends BaseController
     }
 
     /**
-     * 当前商户接口凭证。
+     * 当前商户 API 凭证。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function apiCredential(Request $request): Response
     {
@@ -113,6 +139,9 @@ class MerchantPortalController extends BaseController
 
     /**
      * 生成或重置接口凭证。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function issueCredential(Request $request): Response
     {
@@ -126,6 +155,9 @@ class MerchantPortalController extends BaseController
 
     /**
      * 当前商户的清算记录列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function settlementRecords(Request $request): Response
     {
@@ -143,6 +175,10 @@ class MerchantPortalController extends BaseController
 
     /**
      * 当前商户的清算记录详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $settleNo 结算单号
+     * @return Response 响应对象
      */
     public function settlementRecordShow(Request $request, string $settleNo): Response
     {
@@ -161,6 +197,9 @@ class MerchantPortalController extends BaseController
 
     /**
      * 当前商户可提现余额快照。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function withdrawableBalance(Request $request): Response
     {
@@ -174,6 +213,9 @@ class MerchantPortalController extends BaseController
 
     /**
      * 当前商户资金流水列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function balanceFlows(Request $request): Response
     {
@@ -189,3 +231,8 @@ class MerchantPortalController extends BaseController
         return $this->success($this->merchantPortalService->balanceFlows($payload, $merchantId, $page, $pageSize));
     }
 }
+
+
+
+
+

app/http/mer/controller/system/AuthController.php

@@ -10,14 +10,28 @@ use support\Response;
 
 /**
  * 商户认证控制器。
+ *
+ * @property MerchantAuthService $merchantAuthService 商户认证服务
  */
 class AuthController extends BaseController
 {
+    /**
+ * 构造方法。
+     *
+     * @param MerchantAuthService $merchantAuthService 商户认证服务
+     * @return void
+     */
     public function __construct(
         protected MerchantAuthService $merchantAuthService
     ) {
     }
 
+    /**
+     * 商户登录。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
     public function login(Request $request): Response
     {
         $data = $this->validated($request->all(), AuthValidator::class, 'login');
@@ -30,6 +44,12 @@ class AuthController extends BaseController
         ));
     }
 
+    /**
+     * 商户退出登录。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
     public function logout(Request $request): Response
     {
         $token = trim((string) ($request->header('authorization', '') ?: $request->header('x-merchant-token', '')));
@@ -45,7 +65,10 @@ class AuthController extends BaseController
     }
 
     /**
-     * 获取当前登录商户的信息
+     * 获取当前登录商户信息。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function profile(Request $request): Response
     {
@@ -59,3 +82,8 @@ class AuthController extends BaseController
     }
 }
 
+
+
+
+
+

app/http/mer/controller/system/SystemController.php

@@ -9,22 +9,47 @@ use support\Response;
 
 /**
  * 商户后台系统数据控制器。
+ *
+ * @property SystemBootstrapService $systemBootstrapService 系统引导服务
  */
 class SystemController extends BaseController
 {
+    /**
+ * 构造方法。
+     *
+     * @param SystemBootstrapService $systemBootstrapService 系统引导服务
+     * @return void
+     */
     public function __construct(
         protected SystemBootstrapService $systemBootstrapService
     ) {
     }
 
+    /**
+     * 获取系统菜单树
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
     public function menuTree(Request $request): Response
     {
         return $this->success($this->systemBootstrapService->getMenuTree('merchant'));
     }
 
+    /**
+     * 获取系统字典项
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
     public function dictItems(Request $request): Response
     {
         return $this->success($this->systemBootstrapService->getDictItems((string) $request->get('code', '')));
     }
 }
 
+
+
+
+
+

app/http/mer/controller/trade/PayOrderController.php

@@ -12,11 +12,16 @@ use support\Response;
  * 商户后台支付订单控制器。
  *
  * 商户后台只能看到当前登录商户自己的支付订单。
+ *
+ * @property PayOrderService $payOrderService 支付订单服务
  */
 class PayOrderController extends BaseController
 {
     /**
-     * 构造函数，注入支付订单服务。
+     * 构造方法。
+     *
+     * @param PayOrderService $payOrderService 支付订单服务
+     * @return void
      */
     public function __construct(
         protected PayOrderService $payOrderService
@@ -25,6 +30,9 @@ class PayOrderController extends BaseController
 
     /**
      * 查询当前商户的支付订单列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function index(Request $request): Response
     {
@@ -42,3 +50,8 @@ class PayOrderController extends BaseController
     }
 }
 
+
+
+
+
+

app/http/mer/controller/trade/RefundOrderController.php

@@ -11,9 +11,17 @@ use support\Response;
 
 /**
  * 商户后台退款订单控制器。
+ *
+ * @property RefundService $refundService 退款服务
  */
 class RefundOrderController extends BaseController
 {
+    /**
+ * 构造方法。
+     *
+     * @param RefundService $refundService 退款服务
+     * @return void
+     */
     public function __construct(
         protected RefundService $refundService
     ) {
@@ -21,6 +29,9 @@ class RefundOrderController extends BaseController
 
     /**
      * 查询当前商户的退款订单列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
      */
     public function index(Request $request): Response
     {
@@ -39,6 +50,10 @@ class RefundOrderController extends BaseController
 
     /**
      * 查询当前商户的退款订单详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $refundNo 退款单号
+     * @return Response 响应对象
      */
     public function show(Request $request, string $refundNo): Response
     {
@@ -52,6 +67,10 @@ class RefundOrderController extends BaseController
 
     /**
      * 重试当前商户的退款单。
+     *
+     * @param Request $request 请求对象
+     * @param string $refundNo 退款单号
+     * @return Response 响应对象
      */
     public function retry(Request $request, string $refundNo): Response
     {
@@ -70,3 +89,8 @@ class RefundOrderController extends BaseController
     }
 }
 
+
+
+
+
+

app/http/mer/middleware/MerchantAuthMiddleware.php

@@ -12,11 +12,16 @@ use Webman\MiddlewareInterface;
  * 商户认证中间件。
  *
  * 负责读取商户 token，并把商户身份写入请求上下文。
+ *
+ * @property MerchantAuthService $merchantAuthService 商户认证服务
  */
 class MerchantAuthMiddleware implements MiddlewareInterface
 {
     /**
-     * 构造函数，注入对应依赖。
+     * 构造方法。
+     *
+     * @param MerchantAuthService $merchantAuthService 商户认证服务
+     * @return void
      */
     public function __construct(
         protected MerchantAuthService $merchantAuthService
@@ -25,6 +30,10 @@ class MerchantAuthMiddleware implements MiddlewareInterface
 
     /**
      * 处理请求。
+     *
+     * @param Request $request 请求对象
+     * @param callable $handler handler
+     * @return Response 响应对象
      */
     public function process(Request $request, callable $handler): Response
     {
@@ -61,3 +70,8 @@ class MerchantAuthMiddleware implements MiddlewareInterface
     }
 }
 
+
+
+
+
+

app/http/mer/validation/AuthValidator.php

@@ -9,17 +9,34 @@ use support\validation\Validator;
  */
 class AuthValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'merchant_no' => 'required|string|min:1|max:32',
         'password' => 'required|string|min:6|max:32',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'merchant_no' => '商户号',
         'password' => '登录密码',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'login' => ['merchant_no', 'password'],
     ];
 }
+
+

app/http/mer/validation/BalanceValidator.php

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

app/http/mer/validation/MerchantPortalValidator.php

@@ -9,6 +9,11 @@ use support\validation\Validator;
  */
 class MerchantPortalValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'merchant_short_name' => 'sometimes|string|max:64',
         'contact_name' => 'sometimes|string|max:64',
@@ -26,6 +31,11 @@ class MerchantPortalValidator extends Validator
         'stat_date' => 'sometimes|date',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'merchant_short_name' => '商户简称',
         'contact_name' => '联系人',
@@ -43,6 +53,11 @@ class MerchantPortalValidator extends Validator
         'stat_date' => '统计日期',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'profileUpdate' => [
             'merchant_short_name',
@@ -58,3 +73,5 @@ class MerchantPortalValidator extends Validator
         'routePreview' => ['pay_type_id', 'pay_amount', 'stat_date'],
     ];
 }
+
+

app/http/mer/validation/PayOrderValidator.php

@@ -11,6 +11,11 @@ use support\validation\Validator;
  */
 class PayOrderValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'keyword' => 'sometimes|string|max:128',
         'merchant_id' => 'sometimes|integer|min:1',
@@ -22,18 +27,29 @@ class PayOrderValidator extends Validator
         'page_size' => 'sometimes|integer|min:1|max:100',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'keyword' => '关键字',
         'merchant_id' => '商户ID',
         'pay_type_id' => '支付方式',
-        'status' => '状态',
+        'status' => '支付单状态',
         'channel_mode' => '通道模式',
-        'callback_status' => '回调状态',
+        'callback_status' => '回调处理状态',
         'page' => '页码',
         'page_size' => '每页条数',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'index' => ['keyword', 'merchant_id', 'pay_type_id', 'status', 'channel_mode', 'callback_status', 'page', 'page_size'],
     ];
 }
+

app/http/mer/validation/RefundActionValidator.php

@@ -11,6 +11,11 @@ use support\validation\Validator;
  */
 class RefundActionValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'refund_no' => 'required|string|max:64',
         'processing_at' => 'sometimes|date_format:Y-m-d H:i:s',
@@ -19,6 +24,11 @@ class RefundActionValidator extends Validator
         'channel_refund_no' => 'sometimes|string|max:64',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'refund_no' => '退款单号',
         'processing_at' => '处理时间',
@@ -27,6 +37,11 @@ class RefundActionValidator extends Validator
         'channel_refund_no' => '渠道退款单号',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'retry' => ['refund_no', 'processing_at'],
         'mark_fail' => ['refund_no', 'failed_at', 'last_error'],
@@ -34,3 +49,5 @@ class RefundActionValidator extends Validator
         'mark_success' => ['refund_no', 'channel_refund_no'],
     ];
 }
+
+

app/http/mer/validation/RefundOrderValidator.php

@@ -11,6 +11,11 @@ use support\validation\Validator;
  */
 class RefundOrderValidator extends Validator
 {
+    /**
+     * 校验规则
+     *
+     * @var array
+     */
     protected array $rules = [
         'keyword' => 'sometimes|string|max:128',
         'merchant_id' => 'sometimes|integer|min:1',
@@ -21,6 +26,11 @@ class RefundOrderValidator extends Validator
         'page_size' => 'sometimes|integer|min:1|max:100',
     ];
 
+    /**
+     * 字段别名
+     *
+     * @var array
+     */
     protected array $attributes = [
         'keyword' => '关键字',
         'merchant_id' => '商户ID',
@@ -31,7 +41,14 @@ class RefundOrderValidator extends Validator
         'page_size' => '每页条数',
     ];
 
+    /**
+     * 校验场景
+     *
+     * @var array
+     */
     protected array $scenes = [
         'index' => ['keyword', 'merchant_id', 'pay_type_id', 'status', 'channel_mode', 'page', 'page_size'],
     ];
 }
+
+