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

2026-04-26 03:54:25 +08:00 · 2026-04-21 08:38:59 +08:00
parent dcd58e24ce
commit 9a16a88640
252 changed files with 9218 additions and 659 deletions
--- a/app/http/admin/controller/account/MerchantAccountController.php
+++ b/app/http/admin/controller/account/MerchantAccountController.php
@@ -10,11 +10,16 @@ use support\Response;

 /**
 * 商户账户控制器。
+ *
+ * @property MerchantAccountService $merchantAccountService 商户账户服务
 */
 class MerchantAccountController extends BaseController
 {
    /**
-     * 构造函数，注入商户账户服务。
+     * 构造方法。
+     *
+     * @param MerchantAccountService $merchantAccountService 商户账户服务
+     * @return void
     */
    public function __construct(
        protected MerchantAccountService $merchantAccountService
@@ -23,6 +28,9 @@ class MerchantAccountController extends BaseController

    /**
     * 查询商户账户列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -39,6 +47,9 @@ class MerchantAccountController extends BaseController

    /**
     * 资金中心概览。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function summary(Request $request): Response
    {
@@ -47,6 +58,10 @@ class MerchantAccountController extends BaseController

    /**
     * 查询商户账户详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 商户账户ID
+     * @return Response 响应对象
     */
    public function show(Request $request, string $id): Response
    {
@@ -61,3 +76,8 @@ class MerchantAccountController extends BaseController
    }
 }

+
+
+
+
+
--- a/app/http/admin/controller/account/MerchantAccountLedgerController.php
+++ b/app/http/admin/controller/account/MerchantAccountLedgerController.php
@@ -10,11 +10,16 @@ use support\Response;

 /**
 * 商户账户流水控制器。
+ *
+ * @property MerchantAccountLedgerService $merchantAccountLedgerService 商户账户流水服务
 */
 class MerchantAccountLedgerController extends BaseController
 {
    /**
-     * 构造函数，注入账户流水服务。
+     * 构造方法。
+     *
+     * @param MerchantAccountLedgerService $merchantAccountLedgerService 商户账户流水服务
+     * @return void
     */
    public function __construct(
        protected MerchantAccountLedgerService $merchantAccountLedgerService
@@ -23,6 +28,9 @@ class MerchantAccountLedgerController extends BaseController

    /**
     * 查询账户流水列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -39,6 +47,10 @@ class MerchantAccountLedgerController extends BaseController

    /**
     * 查询账户流水详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 商户账户流水ID
+     * @return Response 响应对象
     */
    public function show(Request $request, string $id): Response
    {
@@ -52,3 +64,8 @@ class MerchantAccountLedgerController extends BaseController
        return $this->success($ledger);
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/file/FileRecordController.php
+++ b/app/http/admin/controller/file/FileRecordController.php
@@ -3,6 +3,7 @@
 namespace app\http\admin\controller\file;

 use app\common\base\BaseController;
+use app\exception\ValidationException;
 use app\http\admin\validation\FileRecordValidator;
 use app\service\file\FileRecordService;
 use Webman\Http\UploadFile;
@@ -11,14 +12,28 @@ use support\Response;

 /**
 * 文件控制器。
+ *
+ * @property FileRecordService $fileRecordService 文件记录服务
 */
 class FileRecordController extends BaseController
 {
+    /**
+ * 构造方法。
+     *
+     * @param FileRecordService $fileRecordService 文件记录服务
+     * @return void
+     */
    public function __construct(
        protected FileRecordService $fileRecordService
    ) {
    }

+    /**
+     * 查询文件记录列表
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function index(Request $request): Response
    {
        $data = $this->validated($request->all(), FileRecordValidator::class, 'index');
@@ -32,11 +47,24 @@ class FileRecordController extends BaseController
        );
    }

+    /**
+     * 获取文件记录选项
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function options(Request $request): Response
    {
        return $this->success($this->fileRecordService->options());
    }

+    /**
+     * 查询文件记录详情
+     *
+     * @param Request $request 请求对象
+     * @param string $id 文件记录ID
+     * @return Response 响应对象
+     */
    public function show(Request $request, string $id): Response
    {
        $data = $this->validated(['id' => (int) $id], FileRecordValidator::class, 'show');
@@ -44,12 +72,19 @@ class FileRecordController extends BaseController
        return $this->success($this->fileRecordService->detail((int) $data['id']));
    }

+    /**
+     * 上传文件记录
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     * @throws ValidationException
+     */
    public function upload(Request $request): Response
    {
        $data = $this->validated(array_merge($this->payload($request), ['scene' => $request->input('scene')]), FileRecordValidator::class, 'store');
        $uploadedFile = $request->file('file');
        if ($uploadedFile === null) {
-            return $this->fail('请先选择上传文件', 400);
+            throw new ValidationException('请先选择上传文件');
        }

        $createdBy = $this->currentAdminId($request);
@@ -63,6 +98,10 @@ class FileRecordController extends BaseController
                }
            }

+            if ($items === []) {
+                throw new ValidationException('上传文件无效');
+            }
+
            return $this->success([
                'list' => $items,
                'total' => count($items),
@@ -70,12 +109,18 @@ class FileRecordController extends BaseController
        }

        if (!$uploadedFile instanceof UploadFile) {
-            return $this->fail('上传文件无效', 400);
+            throw new ValidationException('上传文件无效');
        }

        return $this->success($this->fileRecordService->upload($uploadedFile, $data, $createdBy, $createdByName));
    }

+    /**
+     * 导入远程文件记录
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function importRemote(Request $request): Response
    {
        $data = $this->validated($this->payload($request), FileRecordValidator::class, 'importRemote');
@@ -92,6 +137,13 @@ class FileRecordController extends BaseController
        );
    }

+    /**
+     * 获取文件预览响应。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 文件记录ID
+     * @return Response 响应对象
+     */
    public function preview(Request $request, string $id): Response
    {
        $data = $this->validated(['id' => (int) $id], FileRecordValidator::class, 'preview');
@@ -99,6 +151,13 @@ class FileRecordController extends BaseController
        return $this->fileRecordService->previewResponse((int) $data['id']);
    }

+    /**
+     * 获取文件下载响应。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 文件记录ID
+     * @return Response 响应对象
+     */
    public function download(Request $request, string $id): Response
    {
        $data = $this->validated(['id' => (int) $id], FileRecordValidator::class, 'download');
@@ -106,13 +165,23 @@ class FileRecordController extends BaseController
        return $this->fileRecordService->downloadResponse((int) $data['id']);
    }

+    /**
+     * 删除文件记录
+     *
+     * @param Request $request 请求对象
+     * @param string $id 文件记录ID
+     * @return Response 响应对象
+     */
    public function destroy(Request $request, string $id): Response
    {
        $data = $this->validated(['id' => (int) $id], FileRecordValidator::class, 'destroy');
-        if (!$this->fileRecordService->delete((int) $data['id'])) {
-            return $this->fail('文件不存在', 404);
-        }
+        $this->fileRecordService->delete((int) $data['id']);

        return $this->success(true);
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/merchant/MerchantApiCredentialController.php
+++ b/app/http/admin/controller/merchant/MerchantApiCredentialController.php
@@ -9,12 +9,17 @@ use support\Request;
 use support\Response;

 /**
- * 商户接口凭证管理控制器。
+ * 商户 API 凭证管理控制器。
+ *
+ * @property MerchantApiCredentialService $merchantApiCredentialService 商户 API 凭证服务
 */
 class MerchantApiCredentialController extends BaseController
 {
    /**
-     * 构造函数，注入商户 API 凭证服务。
+     * 构造方法。
+     *
+     * @param MerchantApiCredentialService $merchantApiCredentialService 商户 API 凭证服务
+     * @return void
     */
    public function __construct(
        protected MerchantApiCredentialService $merchantApiCredentialService
@@ -23,6 +28,9 @@ class MerchantApiCredentialController extends BaseController

    /**
     * 查询商户 API 凭证列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -39,6 +47,10 @@ class MerchantApiCredentialController extends BaseController

    /**
     * 查询商户 API 凭证详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 商户 API 凭证ID
+     * @return Response 响应对象
     */
    public function show(Request $request, string $id): Response
    {
@@ -46,7 +58,7 @@ class MerchantApiCredentialController extends BaseController
        $credential = $this->merchantApiCredentialService->findById((int) $data['id']);

        if (!$credential) {
-            return $this->fail('商户接口凭证不存在', 404);
+            return $this->fail('商户 API 凭证不存在', 404);
        }

        return $this->success($credential);
@@ -54,6 +66,9 @@ class MerchantApiCredentialController extends BaseController

    /**
     * 新增商户 API 凭证。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function store(Request $request): Response
    {
@@ -64,6 +79,10 @@ class MerchantApiCredentialController extends BaseController

    /**
     * 修改商户 API 凭证。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 商户 API 凭证ID
+     * @return Response 响应对象
     */
    public function update(Request $request, string $id): Response
    {
@@ -75,7 +94,7 @@ class MerchantApiCredentialController extends BaseController

        $credential = $this->merchantApiCredentialService->update((int) $data['id'], $data);
        if (!$credential) {
-            return $this->fail('商户接口凭证不存在', 404);
+            return $this->fail('商户 API 凭证不存在', 404);
        }

        return $this->success($credential);
@@ -83,6 +102,10 @@ class MerchantApiCredentialController extends BaseController

    /**
     * 删除商户 API 凭证。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 商户 API 凭证ID
+     * @return Response 响应对象
     */
    public function destroy(Request $request, string $id): Response
    {
@@ -90,14 +113,19 @@ class MerchantApiCredentialController extends BaseController
        $credential = $this->merchantApiCredentialService->findById((int) $data['id']);

        if (!$credential) {
-            return $this->fail('商户接口凭证不存在', 404);
+            return $this->fail('商户 API 凭证不存在', 404);
        }

        if (!$this->merchantApiCredentialService->delete((int) $data['id'])) {
-            return $this->fail('商户接口凭证删除失败');
+            return $this->fail('商户 API 凭证删除失败');
        }

        return $this->success(true);
    }
 }

+
+
+
+
+
--- a/app/http/admin/controller/merchant/MerchantController.php
+++ b/app/http/admin/controller/merchant/MerchantController.php
@@ -12,11 +12,16 @@ use support\Response;
 * 商户管理控制器。
 *
 * 当前先提供商户列表查询，后续可继续扩展商户详情、新增、编辑等能力。
+ *
+ * @property MerchantService $merchantService 商户服务
 */
 class MerchantController extends BaseController
 {
    /**
-     * 构造函数，注入商户服务。
+     * 构造方法。
+     *
+     * @param MerchantService $merchantService 商户服务
+     * @return void
     */
    public function __construct(
        protected MerchantService $merchantService
@@ -27,6 +32,9 @@ class MerchantController extends BaseController
     * 查询商户列表。
     *
     * 返回值里额外携带启用中的商户分组选项，方便前端一次性渲染筛选条件。
+     * 
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -39,6 +47,10 @@ class MerchantController extends BaseController

    /**
     * 查询商户详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 商户ID
+     * @return Response 响应对象
     */
    public function show(Request $request, string $id): Response
    {
@@ -54,6 +66,9 @@ class MerchantController extends BaseController

    /**
     * 新增商户。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function store(Request $request): Response
    {
@@ -63,6 +78,10 @@ class MerchantController extends BaseController

    /**
     * 更新商户。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 商户ID
+     * @return Response 响应对象
     */
    public function update(Request $request, string $id): Response
    {
@@ -80,6 +99,10 @@ class MerchantController extends BaseController

    /**
     * 删除商户。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 商户ID
+     * @return Response 响应对象
     */
    public function destroy(Request $request, string $id): Response
    {
@@ -90,6 +113,10 @@ class MerchantController extends BaseController

    /**
     * 重置商户登录密码。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 商户ID
+     * @return Response 响应对象
     */
    public function resetPassword(Request $request, string $id): Response
    {
@@ -100,7 +127,11 @@ class MerchantController extends BaseController
    }

    /**
-     * 生成或重置商户接口凭证。
+     * 生成或重置商户 API 凭证。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 商户ID
+     * @return Response 响应对象
     */
    public function issueCredential(Request $request, string $id): Response
    {
@@ -111,6 +142,10 @@ class MerchantController extends BaseController

    /**
     * 查询商户总览。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 商户ID
+     * @return Response 响应对象
     */
    public function overview(Request $request, string $id): Response
    {
@@ -121,6 +156,9 @@ class MerchantController extends BaseController

    /**
     * 查询商户下拉选项。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function options(Request $request): Response
    {
@@ -129,6 +167,9 @@ class MerchantController extends BaseController

    /**
     * 远程查询商户选择项。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function selectOptions(Request $request): Response
    {
@@ -139,3 +180,9 @@ class MerchantController extends BaseController
    }
 }

+
+
+
+
+
+
--- a/app/http/admin/controller/merchant/MerchantGroupController.php
+++ b/app/http/admin/controller/merchant/MerchantGroupController.php
@@ -12,11 +12,16 @@ use support\Response;
 * 商户分组管理控制器。
 *
 * 负责商户分组的列表、详情、新增、修改和删除。
+ *
+ * @property MerchantGroupService $merchantGroupService 商户分组服务
 */
 class MerchantGroupController extends BaseController
 {
    /**
-     * 构造函数，注入商户分组服务。
+     * 构造方法。
+     *
+     * @param MerchantGroupService $merchantGroupService 商户分组服务
+     * @return void
     */
    public function __construct(
        protected MerchantGroupService $merchantGroupService
@@ -24,9 +29,10 @@ class MerchantGroupController extends BaseController
    }

    /**
-     * GET /admin/merchant-groups
-     *
     * 查询商户分组列表。
+     * 
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -42,9 +48,11 @@ class MerchantGroupController extends BaseController
    }

    /**
-     * GET /admin/merchant-groups/{id}
-     *
     * 查询商户分组详情。
+     * 
+     * @param Request $request 请求对象
+     * @param string $id 商户分组ID
+     * @return Response 响应对象
     */
    public function show(Request $request, string $id): Response
    {
@@ -59,9 +67,10 @@ class MerchantGroupController extends BaseController
    }

    /**
-     * POST /admin/merchant-groups
-     *
     * 新增商户分组。
+     * 
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function store(Request $request): Response
    {
@@ -71,9 +80,11 @@ class MerchantGroupController extends BaseController
    }

    /**
-     * PUT /admin/merchant-groups/{id}
-     *
     * 修改商户分组。
+     * 
+     * @param Request $request 请求对象
+     * @param string $id 商户分组ID
+     * @return Response 响应对象
     */
    public function update(Request $request, string $id): Response
    {
@@ -92,9 +103,11 @@ class MerchantGroupController extends BaseController
    }

    /**
-     * DELETE /admin/merchant-groups/{id}
-     *
     * 删除商户分组。
+     * 
+     * @param Request $request 请求对象
+     * @param string $id 商户分组ID
+     * @return Response 响应对象
     */
    public function destroy(Request $request, string $id): Response
    {
@@ -109,6 +122,9 @@ class MerchantGroupController extends BaseController

    /**
     * 查询商户分组下拉选项。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function options(Request $request): Response
    {
@@ -116,3 +132,8 @@ class MerchantGroupController extends BaseController
    }
 }

+
+
+
+
+
--- a/app/http/admin/controller/merchant/MerchantPolicyController.php
+++ b/app/http/admin/controller/merchant/MerchantPolicyController.php
@@ -10,14 +10,28 @@ use support\Response;

 /**
 * 商户策略控制器。
+ *
+ * @property MerchantPolicyService $merchantPolicyService 商户策略服务
 */
 class MerchantPolicyController extends BaseController
 {
+    /**
+     * 构造方法。
+     *
+     * @param MerchantPolicyService $merchantPolicyService 商户策略服务
+     * @return void
+     */
    public function __construct(
        protected MerchantPolicyService $merchantPolicyService
    ) {
    }

+    /**
+     * 查询商户策略列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function index(Request $request): Response
    {
        $data = $this->validated($request->all(), MerchantPolicyValidator::class, 'index');
@@ -31,6 +45,13 @@ class MerchantPolicyController extends BaseController
        );
    }

+    /**
+     * 查询商户策略详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $merchantId 商户ID
+     * @return Response 响应对象
+     */
    public function show(Request $request, string $merchantId): Response
    {
        $data = $this->validated(['merchant_id' => (int) $merchantId], MerchantPolicyValidator::class, 'show');
@@ -38,6 +59,12 @@ class MerchantPolicyController extends BaseController
        return $this->success($this->merchantPolicyService->findByMerchantId((int) $data['merchant_id']));
    }

+    /**
+     * 新增商户策略。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function store(Request $request): Response
    {
        $data = $this->validated($request->all(), MerchantPolicyValidator::class, 'store');
@@ -45,6 +72,13 @@ class MerchantPolicyController extends BaseController
        return $this->success($this->merchantPolicyService->saveByMerchantId((int) $data['merchant_id'], $data));
    }

+    /**
+     * 更新商户策略。
+     *
+     * @param Request $request 请求对象
+     * @param string $merchantId 商户ID
+     * @return Response 响应对象
+     */
    public function update(Request $request, string $merchantId): Response
    {
        $data = $this->validated(
@@ -56,6 +90,13 @@ class MerchantPolicyController extends BaseController
        return $this->success($this->merchantPolicyService->saveByMerchantId((int) $data['merchant_id'], $data));
    }

+    /**
+     * 删除商户策略。
+     *
+     * @param Request $request 请求对象
+     * @param string $merchantId 商户ID
+     * @return Response 响应对象
+     */
    public function destroy(Request $request, string $merchantId): Response
    {
        $data = $this->validated(['merchant_id' => (int) $merchantId], MerchantPolicyValidator::class, 'show');
@@ -64,3 +105,8 @@ class MerchantPolicyController extends BaseController
    }
 }

+
+
+
+
+
--- a/app/http/admin/controller/ops/ChannelDailyStatController.php
+++ b/app/http/admin/controller/ops/ChannelDailyStatController.php
@@ -10,11 +10,16 @@ use support\Response;

 /**
 * 通道日统计控制器。
+ *
+ * @property ChannelDailyStatService $channelDailyStatService 渠道日统计服务
 */
 class ChannelDailyStatController extends BaseController
 {
    /**
-     * 构造函数，注入通道日统计服务。
+     * 构造方法。
+     *
+     * @param ChannelDailyStatService $channelDailyStatService 渠道日统计服务
+     * @return void
     */
    public function __construct(
        protected ChannelDailyStatService $channelDailyStatService
@@ -23,6 +28,9 @@ class ChannelDailyStatController extends BaseController

    /**
     * 查询通道日统计列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -39,6 +47,10 @@ class ChannelDailyStatController extends BaseController

    /**
     * 查询通道日统计详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 渠道日统计ID
+     * @return Response 响应对象
     */
    public function show(Request $request, string $id): Response
    {
@@ -52,3 +64,8 @@ class ChannelDailyStatController extends BaseController
        return $this->success($stat);
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/ops/ChannelNotifyLogController.php
+++ b/app/http/admin/controller/ops/ChannelNotifyLogController.php
@@ -10,11 +10,16 @@ use support\Response;

 /**
 * 渠道通知日志控制器。
+ *
+ * @property ChannelNotifyLogService $channelNotifyLogService 渠道通知日志服务
 */
 class ChannelNotifyLogController extends BaseController
 {
    /**
-     * 构造函数，注入渠道通知日志服务。
+     * 构造方法。
+     *
+     * @param ChannelNotifyLogService $channelNotifyLogService 渠道通知日志服务
+     * @return void
     */
    public function __construct(
        protected ChannelNotifyLogService $channelNotifyLogService
@@ -23,6 +28,9 @@ class ChannelNotifyLogController extends BaseController

    /**
     * 查询渠道通知日志列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -39,6 +47,10 @@ class ChannelNotifyLogController extends BaseController

    /**
     * 查询渠道通知日志详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 渠道通知日志ID
+     * @return Response 响应对象
     */
    public function show(Request $request, string $id): Response
    {
@@ -52,3 +64,8 @@ class ChannelNotifyLogController extends BaseController
        return $this->success($log);
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/ops/PayCallbackLogController.php
+++ b/app/http/admin/controller/ops/PayCallbackLogController.php
@@ -10,11 +10,16 @@ use support\Response;

 /**
 * 支付回调日志控制器。
+ *
+ * @property PayCallbackLogService $payCallbackLogService 支付回调日志服务
 */
 class PayCallbackLogController extends BaseController
 {
    /**
-     * 构造函数，注入支付回调日志服务。
+     * 构造方法。
+     *
+     * @param PayCallbackLogService $payCallbackLogService 支付回调日志服务
+     * @return void
     */
    public function __construct(
        protected PayCallbackLogService $payCallbackLogService
@@ -23,6 +28,9 @@ class PayCallbackLogController extends BaseController

    /**
     * 查询支付回调日志列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -39,6 +47,10 @@ class PayCallbackLogController extends BaseController

    /**
     * 查询支付回调日志详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 支付回调日志ID
+     * @return Response 响应对象
     */
    public function show(Request $request, string $id): Response
    {
@@ -52,3 +64,8 @@ class PayCallbackLogController extends BaseController
        return $this->success($log);
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/payment/PaymentChannelController.php
+++ b/app/http/admin/controller/payment/PaymentChannelController.php
@@ -12,11 +12,16 @@ use support\Response;
 * 支付通道管理控制器。
 *
 * 负责支付通道的列表、详情、新增、修改和删除。
+ *
+ * @property PaymentChannelService $paymentChannelService 支付渠道服务
 */
 class PaymentChannelController extends BaseController
 {
    /**
-     * 构造函数，注入支付通道服务。
+     * 构造方法。
+     *
+     * @param PaymentChannelService $paymentChannelService 支付渠道服务
+     * @return void
     */
    public function __construct(
        protected PaymentChannelService $paymentChannelService
@@ -24,9 +29,10 @@ class PaymentChannelController extends BaseController
    }

    /**
-     * GET /admin/payment-channels
-     *
     * 查询支付通道列表。
+     * 
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -42,9 +48,11 @@ class PaymentChannelController extends BaseController
    }

    /**
-     * GET /admin/payment-channels/{id}
-     *
     * 查询支付通道详情。
+     * 
+     * @param Request $request 请求对象
+     * @param string $id 支付渠道ID
+     * @return Response 响应对象
     */
    public function show(Request $request, string $id): Response
    {
@@ -59,9 +67,10 @@ class PaymentChannelController extends BaseController
    }

    /**
-     * POST /admin/payment-channels
-     *
     * 新增支付通道。
+     * 
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function store(Request $request): Response
    {
@@ -71,9 +80,11 @@ class PaymentChannelController extends BaseController
    }

    /**
-     * PUT /admin/payment-channels/{id}
-     *
     * 修改支付通道。
+     * 
+     * @param Request $request 请求对象
+     * @param string $id 支付渠道ID
+     * @return Response 响应对象
     */
    public function update(Request $request, string $id): Response
    {
@@ -94,9 +105,11 @@ class PaymentChannelController extends BaseController
    }

    /**
-     * DELETE /admin/payment-channels/{id}
-     *
     * 删除支付通道。
+     * 
+     * @param Request $request 请求对象
+     * @param string $id 支付渠道ID
+     * @return Response 响应对象
     */
    public function destroy(Request $request, string $id): Response
    {
@@ -111,6 +124,9 @@ class PaymentChannelController extends BaseController

    /**
     * 查询启用中的通道选项。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function options(Request $request): Response
    {
@@ -119,6 +135,9 @@ class PaymentChannelController extends BaseController

    /**
     * 查询路由编排场景下的通道选项。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function routeOptions(Request $request): Response
    {
@@ -127,6 +146,9 @@ class PaymentChannelController extends BaseController

    /**
     * 远程查询支付通道选择项。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function selectOptions(Request $request): Response
    {
@@ -136,3 +158,8 @@ class PaymentChannelController extends BaseController
        return $this->success($this->paymentChannelService->searchOptions($request->all(), $page, $pageSize));
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/payment/PaymentPluginConfController.php
+++ b/app/http/admin/controller/payment/PaymentPluginConfController.php
@@ -12,14 +12,28 @@ use support\Response;
 * 支付插件配置控制器。
 *
 * 负责插件公共配置的列表、详情、增删改和选项输出。
+ *
+ * @property PaymentPluginConfService $paymentPluginConfService 支付插件配置服务
 */
 class PaymentPluginConfController extends BaseController
 {
+    /**
+     * 构造方法。
+     *
+     * @param PaymentPluginConfService $paymentPluginConfService 支付插件配置服务
+     * @return void
+     */
    public function __construct(
        protected PaymentPluginConfService $paymentPluginConfService
    ) {
    }

+    /**
+     * 查询支付插件配置列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function index(Request $request): Response
    {
        $data = $this->validated($request->all(), PaymentPluginConfValidator::class, 'index');
@@ -29,6 +43,13 @@ class PaymentPluginConfController extends BaseController
        return $this->page($this->paymentPluginConfService->paginate($data, $page, $pageSize));
    }

+    /**
+     * 查询支付插件配置详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 支付插件配置ID
+     * @return Response 响应对象
+     */
    public function show(Request $request, string $id): Response
    {
        $data = $this->validated(['id' => (int) $id], PaymentPluginConfValidator::class, 'show');
@@ -41,6 +62,12 @@ class PaymentPluginConfController extends BaseController
        return $this->success($pluginConf);
    }

+    /**
+     * 新增支付插件配置。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function store(Request $request): Response
    {
        $data = $this->validated($request->all(), PaymentPluginConfValidator::class, 'store');
@@ -48,6 +75,13 @@ class PaymentPluginConfController extends BaseController
        return $this->success($this->paymentPluginConfService->create($data));
    }

+    /**
+     * 更新支付插件配置。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 支付插件配置ID
+     * @return Response 响应对象
+     */
    public function update(Request $request, string $id): Response
    {
        $data = $this->validated(
@@ -64,6 +98,13 @@ class PaymentPluginConfController extends BaseController
        return $this->success($pluginConf);
    }

+    /**
+     * 删除支付插件配置。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 支付插件配置ID
+     * @return Response 响应对象
+     */
    public function destroy(Request $request, string $id): Response
    {
        $data = $this->validated(['id' => (int) $id], PaymentPluginConfValidator::class, 'destroy');
@@ -75,6 +116,12 @@ class PaymentPluginConfController extends BaseController
        return $this->success(true);
    }

+    /**
+     * 获取支付插件配置选项。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function options(Request $request): Response
    {
        $data = $this->validated($request->all(), PaymentPluginConfValidator::class, 'options');
@@ -86,6 +133,9 @@ class PaymentPluginConfController extends BaseController

    /**
     * 远程查询插件配置选项。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function selectOptions(Request $request): Response
    {
@@ -96,3 +146,8 @@ class PaymentPluginConfController extends BaseController
        return $this->success($this->paymentPluginConfService->searchOptions($data, $page, $pageSize));
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/payment/PaymentPluginController.php
+++ b/app/http/admin/controller/payment/PaymentPluginController.php
@@ -12,11 +12,16 @@ use support\Response;
 * 支付插件管理控制器。
 *
 * 负责插件字典的列表、详情、刷新同步和状态备注维护。
+ *
+ * @property PaymentPluginService $paymentPluginService 支付插件服务
 */
 class PaymentPluginController extends BaseController
 {
    /**
-     * 构造函数，注入支付插件服务。
+     * 构造方法。
+     *
+     * @param PaymentPluginService $paymentPluginService 支付插件服务
+     * @return void
     */
    public function __construct(
        protected PaymentPluginService $paymentPluginService
@@ -25,6 +30,9 @@ class PaymentPluginController extends BaseController

    /**
     * 查询支付插件列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -37,6 +45,10 @@ class PaymentPluginController extends BaseController

    /**
     * 查询支付插件详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $code 编码
+     * @return Response 响应对象
     */
    public function show(Request $request, string $code): Response
    {
@@ -52,6 +64,10 @@ class PaymentPluginController extends BaseController

    /**
     * 修改支付插件。
+     *
+     * @param Request $request 请求对象
+     * @param string $code 编码
+     * @return Response 响应对象
     */
    public function update(Request $request, string $code): Response
    {
@@ -73,6 +89,9 @@ class PaymentPluginController extends BaseController

    /**
     * 从插件目录刷新同步支付插件。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function refresh(Request $request): Response
    {
@@ -81,6 +100,9 @@ class PaymentPluginController extends BaseController

    /**
     * 查询支付插件下拉选项。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function options(Request $request): Response
    {
@@ -91,6 +113,9 @@ class PaymentPluginController extends BaseController

    /**
     * 远程查询支付插件选项。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function selectOptions(Request $request): Response
    {
@@ -103,6 +128,9 @@ class PaymentPluginController extends BaseController

    /**
     * 查询通道配置场景下的插件选项。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function channelOptions(Request $request): Response
    {
@@ -113,6 +141,10 @@ class PaymentPluginController extends BaseController

    /**
     * 查询插件配置结构。
+     *
+     * @param Request $request 请求对象
+     * @param string $code 编码
+     * @return Response 响应对象
     */
    public function schema(Request $request, string $code): Response
    {
@@ -121,3 +153,8 @@ class PaymentPluginController extends BaseController
        return $this->success($this->paymentPluginService->getSchema((string) $data['code']));
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/payment/PaymentPollGroupBindController.php
+++ b/app/http/admin/controller/payment/PaymentPollGroupBindController.php
@@ -10,14 +10,28 @@ use support\Response;

 /**
 * 商户分组路由绑定控制器。
+ *
+ * @property PaymentPollGroupBindService $paymentPollGroupBindService 支付轮询分组绑定服务
 */
 class PaymentPollGroupBindController extends BaseController
 {
+    /**
+ * 构造方法。
+     *
+     * @param PaymentPollGroupBindService $paymentPollGroupBindService 支付轮询分组绑定服务
+     * @return void
+     */
    public function __construct(
        protected PaymentPollGroupBindService $paymentPollGroupBindService
    ) {
    }

+    /**
+     * 查询支付轮询分组绑定列表
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function index(Request $request): Response
    {
        $data = $this->validated($request->all(), PaymentPollGroupBindValidator::class, 'index');
@@ -31,6 +45,13 @@ class PaymentPollGroupBindController extends BaseController
        );
    }

+    /**
+     * 查询支付轮询分组绑定详情
+     *
+     * @param Request $request 请求对象
+     * @param string $id 支付轮询分组绑定ID
+     * @return Response 响应对象
+     */
    public function show(Request $request, string $id): Response
    {
        $data = $this->validated(['id' => (int) $id], PaymentPollGroupBindValidator::class, 'show');
@@ -42,6 +63,12 @@ class PaymentPollGroupBindController extends BaseController
        return $this->success($row);
    }

+    /**
+     * 新增支付轮询分组绑定
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function store(Request $request): Response
    {
        $data = $this->validated($request->all(), PaymentPollGroupBindValidator::class, 'store');
@@ -49,6 +76,13 @@ class PaymentPollGroupBindController extends BaseController
        return $this->success($this->paymentPollGroupBindService->create($data));
    }

+    /**
+     * 更新支付轮询分组绑定
+     *
+     * @param Request $request 请求对象
+     * @param string $id 支付轮询分组绑定ID
+     * @return Response 响应对象
+     */
    public function update(Request $request, string $id): Response
    {
        $data = $this->validated(
@@ -65,6 +99,13 @@ class PaymentPollGroupBindController extends BaseController
        return $this->success($row);
    }

+    /**
+     * 删除支付轮询分组绑定
+     *
+     * @param Request $request 请求对象
+     * @param string $id 支付轮询分组绑定ID
+     * @return Response 响应对象
+     */
    public function destroy(Request $request, string $id): Response
    {
        $data = $this->validated(['id' => (int) $id], PaymentPollGroupBindValidator::class, 'destroy');
@@ -75,3 +116,8 @@ class PaymentPollGroupBindController extends BaseController
        return $this->success(true);
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/payment/PaymentPollGroupChannelController.php
+++ b/app/http/admin/controller/payment/PaymentPollGroupChannelController.php
@@ -10,14 +10,28 @@ use support\Response;

 /**
 * 轮询组通道编排控制器。
+ *
+ * @property PaymentPollGroupChannelService $paymentPollGroupChannelService 支付轮询分组渠道服务
 */
 class PaymentPollGroupChannelController extends BaseController
 {
+    /**
+ * 构造方法。
+     *
+     * @param PaymentPollGroupChannelService $paymentPollGroupChannelService 支付轮询分组渠道服务
+     * @return void
+     */
    public function __construct(
        protected PaymentPollGroupChannelService $paymentPollGroupChannelService
    ) {
    }

+    /**
+     * 查询支付轮询分组渠道列表
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function index(Request $request): Response
    {
        $data = $this->validated($request->all(), PaymentPollGroupChannelValidator::class, 'index');
@@ -31,6 +45,13 @@ class PaymentPollGroupChannelController extends BaseController
        );
    }

+    /**
+     * 查询支付轮询分组渠道详情
+     *
+     * @param Request $request 请求对象
+     * @param string $id 支付轮询分组渠道ID
+     * @return Response 响应对象
+     */
    public function show(Request $request, string $id): Response
    {
        $data = $this->validated(['id' => (int) $id], PaymentPollGroupChannelValidator::class, 'show');
@@ -42,6 +63,12 @@ class PaymentPollGroupChannelController extends BaseController
        return $this->success($row);
    }

+    /**
+     * 新增支付轮询分组渠道
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function store(Request $request): Response
    {
        $data = $this->validated($request->all(), PaymentPollGroupChannelValidator::class, 'store');
@@ -49,6 +76,13 @@ class PaymentPollGroupChannelController extends BaseController
        return $this->success($this->paymentPollGroupChannelService->create($data));
    }

+    /**
+     * 更新支付轮询分组渠道
+     *
+     * @param Request $request 请求对象
+     * @param string $id 支付轮询分组渠道ID
+     * @return Response 响应对象
+     */
    public function update(Request $request, string $id): Response
    {
        $payload = $request->all();
@@ -67,6 +101,13 @@ class PaymentPollGroupChannelController extends BaseController
        return $this->success($row);
    }

+    /**
+     * 删除支付轮询分组渠道
+     *
+     * @param Request $request 请求对象
+     * @param string $id 支付轮询分组渠道ID
+     * @return Response 响应对象
+     */
    public function destroy(Request $request, string $id): Response
    {
        $data = $this->validated(['id' => (int) $id], PaymentPollGroupChannelValidator::class, 'destroy');
@@ -77,3 +118,8 @@ class PaymentPollGroupChannelController extends BaseController
        return $this->success(true);
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/payment/PaymentPollGroupController.php
+++ b/app/http/admin/controller/payment/PaymentPollGroupController.php
@@ -12,11 +12,16 @@ use support\Response;
 * 支付轮询组管理控制器。
 *
 * 负责轮询组的列表、详情、新增、修改和删除。
+ *
+ * @property PaymentPollGroupService $paymentPollGroupService 支付轮询分组服务
 */
 class PaymentPollGroupController extends BaseController
 {
    /**
-     * 构造函数，注入轮询组服务。
+     * 构造方法。
+     *
+     * @param PaymentPollGroupService $paymentPollGroupService 支付轮询分组服务
+     * @return void
     */
    public function __construct(
        protected PaymentPollGroupService $paymentPollGroupService
@@ -24,9 +29,10 @@ class PaymentPollGroupController extends BaseController
    }

    /**
-     * GET /admin/payment-poll-groups
-     *
     * 查询轮询组列表。
+     * 
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -42,9 +48,11 @@ class PaymentPollGroupController extends BaseController
    }

    /**
-     * GET /admin/payment-poll-groups/{id}
-     *
     * 查询轮询组详情。
+     * 
+     * @param Request $request 请求对象
+     * @param string $id 支付轮询分组ID
+     * @return Response 响应对象
     */
    public function show(Request $request, string $id): Response
    {
@@ -59,9 +67,10 @@ class PaymentPollGroupController extends BaseController
    }

    /**
-     * POST /admin/payment-poll-groups
-     *
     * 新增轮询组。
+     * 
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function store(Request $request): Response
    {
@@ -71,9 +80,11 @@ class PaymentPollGroupController extends BaseController
    }

    /**
-     * PUT /admin/payment-poll-groups/{id}
-     *
     * 修改轮询组。
+     * 
+     * @param Request $request 请求对象
+     * @param string $id 支付轮询分组ID
+     * @return Response 响应对象
     */
    public function update(Request $request, string $id): Response
    {
@@ -94,9 +105,11 @@ class PaymentPollGroupController extends BaseController
    }

    /**
-     * DELETE /admin/payment-poll-groups/{id}
-     *
     * 删除轮询组。
+     * 
+     * @param Request $request 请求对象
+     * @param string $id 支付轮询分组ID
+     * @return Response 响应对象
     */
    public function destroy(Request $request, string $id): Response
    {
@@ -111,9 +124,17 @@ class PaymentPollGroupController extends BaseController

    /**
     * 查询轮询组下拉选项。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function options(Request $request): Response
    {
        return $this->success($this->paymentPollGroupService->enabledOptions($request->all()));
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/payment/PaymentTypeController.php
+++ b/app/http/admin/controller/payment/PaymentTypeController.php
@@ -12,11 +12,16 @@ use support\Response;
 * 支付方式管理控制器。
 *
 * 负责支付方式字典的列表、详情、新增、修改、删除和选项输出。
+ *
+ * @property PaymentTypeService $paymentTypeService 支付类型服务
 */
 class PaymentTypeController extends BaseController
 {
    /**
-     * 构造函数，注入支付方式服务。
+     * 构造方法。
+     *
+     * @param PaymentTypeService $paymentTypeService 支付类型服务
+     * @return void
     */
    public function __construct(
        protected PaymentTypeService $paymentTypeService
@@ -25,6 +30,9 @@ class PaymentTypeController extends BaseController

    /**
     * 查询支付方式列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -37,6 +45,10 @@ class PaymentTypeController extends BaseController

    /**
     * 查询支付方式详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 支付类型ID
+     * @return Response 响应对象
     */
    public function show(Request $request, string $id): Response
    {
@@ -52,6 +64,9 @@ class PaymentTypeController extends BaseController

    /**
     * 新增支付方式。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function store(Request $request): Response
    {
@@ -62,6 +77,10 @@ class PaymentTypeController extends BaseController

    /**
     * 修改支付方式。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 支付类型ID
+     * @return Response 响应对象
     */
    public function update(Request $request, string $id): Response
    {
@@ -83,6 +102,10 @@ class PaymentTypeController extends BaseController

    /**
     * 删除支付方式。
+     *
+     * @param Request $request 请求对象
+     * @param string $id 支付类型ID
+     * @return Response 响应对象
     */
    public function destroy(Request $request, string $id): Response
    {
@@ -97,9 +120,17 @@ class PaymentTypeController extends BaseController

    /**
     * 查询支付方式下拉选项。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function options(Request $request): Response
    {
        return $this->success($this->paymentTypeService->enabledOptions());
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/payment/RouteController.php
+++ b/app/http/admin/controller/payment/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,10 @@ class RouteController extends BaseController
    }

    /**
-     * GET /admin/routes/resolve
-     *
     * 解析路由结果。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function resolve(Request $request): Response
    {
@@ -41,3 +47,8 @@ class RouteController extends BaseController
    }
 }

+
+
+
+
+
--- a/app/http/admin/controller/system/AdminUserController.php
+++ b/app/http/admin/controller/system/AdminUserController.php
@@ -12,11 +12,16 @@ use support\Response;
 * 管理员用户管理控制器。
 *
 * 负责管理员账号的列表、详情、新增、修改和删除。
+ *
+ * @property AdminUserService $adminUserService 管理用户服务
 */
 class AdminUserController extends BaseController
 {
    /**
-     * 构造函数，注入管理员用户服务。
+     * 构造方法。
+     *
+     * @param AdminUserService $adminUserService 管理用户服务
+     * @return void
     */
    public function __construct(
        protected AdminUserService $adminUserService
@@ -24,9 +29,10 @@ class AdminUserController extends BaseController
    }

    /**
-     * GET /adminapi/admin-users
-     *
     * 查询管理员用户列表。
+     * 
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -42,9 +48,11 @@ class AdminUserController extends BaseController
    }

    /**
-     * GET /adminapi/admin-users/{id}
-     *
     * 查询管理员用户详情。
+     * 
+     * @param Request $request 请求对象
+     * @param string $id 管理用户ID
+     * @return Response 响应对象
     */
    public function show(Request $request, string $id): Response
    {
@@ -59,9 +67,10 @@ class AdminUserController extends BaseController
    }

    /**
-     * POST /adminapi/admin-users
-     *
     * 新增管理员用户。
+     * 
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function store(Request $request): Response
    {
@@ -71,9 +80,11 @@ class AdminUserController extends BaseController
    }

    /**
-     * PUT /adminapi/admin-users/{id}
-     *
     * 修改管理员用户。
+     * 
+     * @param Request $request 请求对象
+     * @param string $id 管理用户ID
+     * @return Response 响应对象
     */
    public function update(Request $request, string $id): Response
    {
@@ -92,9 +103,11 @@ class AdminUserController extends BaseController
    }

    /**
-     * DELETE /adminapi/admin-users/{id}
-     *
     * 删除管理员用户。
+     * 
+     * @param Request $request 请求对象
+     * @param string $id 管理用户ID
+     * @return Response 响应对象
     */
    public function destroy(Request $request, string $id): Response
    {
@@ -120,3 +133,8 @@ class AdminUserController extends BaseController
        return $this->success(true);
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/system/AuthController.php
+++ b/app/http/admin/controller/system/AuthController.php
@@ -11,15 +11,31 @@ use support\Response;

 /**
 * 管理员认证控制器。
+ *
+ * @property AdminAuthService $adminAuthService 管理认证服务
+ * @property AdminUserService $adminUserService 管理用户服务
 */
 class AuthController extends BaseController
 {
+    /**
+ * 构造方法。
+     *
+     * @param AdminAuthService $adminAuthService 管理认证服务
+     * @param AdminUserService $adminUserService 管理用户服务
+     * @return void
+     */
    public function __construct(
        protected AdminAuthService $adminAuthService,
        protected AdminUserService $adminUserService
    ) {
    }

+    /**
+     * 管理员登录。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function login(Request $request): Response
    {
        $data = $this->validated($request->all(), AuthValidator::class, 'login');
@@ -32,6 +48,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-admin-token', '')));
@@ -47,7 +69,10 @@ class AuthController extends BaseController
    }

    /**
-     * 获取当前登录管理员的信息
+     * 获取当前登录管理员信息。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function profile(Request $request): Response
    {
@@ -63,3 +88,8 @@ class AuthController extends BaseController
    }
 }

+
+
+
+
+
--- a/app/http/admin/controller/system/SystemConfigPageController.php
+++ b/app/http/admin/controller/system/SystemConfigPageController.php
@@ -8,18 +8,42 @@ use app\service\system\config\SystemConfigPageService;
 use support\Request;
 use support\Response;

+/**
+ * 系统配置页面控制器
+ *
+ * @property SystemConfigPageService $systemConfigPageService 系统配置页面服务
+ */
 class SystemConfigPageController extends BaseController
 {
+    /**
+ * 构造方法。
+     *
+     * @param SystemConfigPageService $systemConfigPageService 系统配置页面服务
+     * @return void
+     */
    public function __construct(
        protected SystemConfigPageService $systemConfigPageService
    ) {
    }

+    /**
+     * 查询系统配置页面列表
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function index(Request $request): Response
    {
        return $this->success($this->systemConfigPageService->tabs());
    }

+    /**
+     * 查询系统配置页面详情
+     *
+     * @param Request $request 请求对象
+     * @param string $groupCode 分组Code
+     * @return Response 响应对象
+     */
    public function show(Request $request, string $groupCode): Response
    {
        $data = $this->validated(['group_code' => $groupCode], SystemConfigPageValidator::class, 'show');
@@ -27,6 +51,13 @@ class SystemConfigPageController extends BaseController
        return $this->success($this->systemConfigPageService->detail((string) $data['group_code']));
    }

+    /**
+     * 新增系统配置页面
+     *
+     * @param Request $request 请求对象
+     * @param string $groupCode 分组Code
+     * @return Response 响应对象
+     */
    public function store(Request $request, string $groupCode): Response
    {
        $data = $this->validated(
@@ -40,3 +71,8 @@ class SystemConfigPageController extends BaseController
        );
    }
 }
+
+
+
+
+
--- a/app/http/admin/controller/system/SystemController.php
+++ b/app/http/admin/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('admin'));
    }

+    /**
+     * 获取系统字典项
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
+     */
    public function dictItems(Request $request): Response
    {
        return $this->success($this->systemBootstrapService->getDictItems((string) $request->get('code', '')));
    }
 }

+
+
+
+
+
--- a/app/http/admin/controller/trade/PayOrderController.php
+++ b/app/http/admin/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
    {
@@ -36,3 +44,8 @@ class PayOrderController extends BaseController
    }
 }

+
+
+
+
+
--- a/app/http/admin/controller/trade/RefundOrderController.php
+++ b/app/http/admin/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
    {
@@ -33,6 +44,10 @@ class RefundOrderController extends BaseController

    /**
     * 查询退款订单详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $refundNo 退款单号
+     * @return Response 响应对象
     */
    public function show(Request $request, string $refundNo): Response
    {
@@ -41,6 +56,10 @@ class RefundOrderController extends BaseController

    /**
     * 重试退款。
+     *
+     * @param Request $request 请求对象
+     * @param string $refundNo 退款单号
+     * @return Response 响应对象
     */
    public function retry(Request $request, string $refundNo): Response
    {
@@ -54,3 +73,8 @@ class RefundOrderController extends BaseController
    }
 }

+
+
+
+
+
--- a/app/http/admin/controller/trade/SettlementOrderController.php
+++ b/app/http/admin/controller/trade/SettlementOrderController.php
@@ -11,11 +11,16 @@ use support\Response;

 /**
 * 清算订单控制器。
+ *
+ * @property SettlementOrderQueryService $settlementOrderQueryService 结算订单查询服务
 */
 class SettlementOrderController extends BaseController
 {
    /**
-     * 构造函数，注入清算订单服务。
+     * 构造方法。
+     *
+     * @param SettlementOrderQueryService $settlementOrderQueryService 结算订单查询服务
+     * @return void
     */
    public function __construct(
        protected SettlementOrderQueryService $settlementOrderQueryService
@@ -24,6 +29,9 @@ class SettlementOrderController extends BaseController

    /**
     * 查询清算订单列表。
+     *
+     * @param Request $request 请求对象
+     * @return Response 响应对象
     */
    public function index(Request $request): Response
    {
@@ -40,6 +48,10 @@ class SettlementOrderController extends BaseController

    /**
     * 查询清算订单详情。
+     *
+     * @param Request $request 请求对象
+     * @param string $settleNo 结算单号
+     * @return Response 响应对象
     */
    public function show(Request $request, string $settleNo): Response
    {
@@ -51,3 +63,8 @@ class SettlementOrderController extends BaseController
        }
    }
 }
+
+
+
+
+