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

2026-04-29 05:24:26 +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/service/account/funds/MerchantAccountCommandService.php
+++ b/app/service/account/funds/MerchantAccountCommandService.php
@@ -16,9 +16,19 @@ use app\repository\account\ledger\MerchantAccountLedgerRepository;
 * 商户账户命令服务。
 *
 * 只负责账户创建、冻结、扣减、释放和入账等资金变更。
+ *
+ * @property MerchantAccountRepository $accountRepository 账户仓库
+ * @property MerchantAccountLedgerRepository $ledgerRepository 流水仓库
 */
 class MerchantAccountCommandService extends BaseService
 {
+    /**
+     * 构造方法。
+     *
+     * @param MerchantAccountRepository $accountRepository 账户仓库
+     * @param MerchantAccountLedgerRepository $ledgerRepository 流水仓库
+     * @return void
+     */
    public function __construct(
        protected MerchantAccountRepository $accountRepository,
        protected MerchantAccountLedgerRepository $ledgerRepository
@@ -27,6 +37,9 @@ class MerchantAccountCommandService extends BaseService

    /**
     * 获取或创建商户账户。
+     *
+     * @param int $merchantId 商户ID
+     * @return MerchantAccount 账户记录
     */
    public function ensureAccount(int $merchantId): MerchantAccount
    {
@@ -37,6 +50,10 @@ class MerchantAccountCommandService extends BaseService

    /**
     * 在当前事务中获取或创建商户账户。
+     *
+     * @param int $merchantId 商户ID
+     * @return MerchantAccount 账户记录
+     * @throws ValidationException
     */
    public function ensureAccountInCurrentTransaction(int $merchantId): MerchantAccount
    {
@@ -59,6 +76,17 @@ class MerchantAccountCommandService extends BaseService
        return $account;
    }

+    /**
+     * 冻结可用余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function freezeAmount(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->transactionRetry(function () use ($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo) {
@@ -66,6 +94,19 @@ class MerchantAccountCommandService extends BaseService
        });
    }

+    /**
+     * 在当前事务中冻结可用余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     * @throws ValidationException
+     * @throws BalanceInsufficientException
+     */
    public function freezeAmountInCurrentTransaction(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        $this->assertPositiveAmount($amount);
@@ -108,6 +149,17 @@ class MerchantAccountCommandService extends BaseService
        ]);
    }

+    /**
+     * 扣减冻结余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function deductFrozenAmount(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->transactionRetry(function () use ($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo) {
@@ -115,6 +167,18 @@ class MerchantAccountCommandService extends BaseService
        });
    }

+    /**
+     * 在当前事务中扣减冻结余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     * @throws ValidationException
+     */
    public function deductFrozenAmountInCurrentTransaction(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        $this->assertPositiveAmount($amount);
@@ -160,6 +224,17 @@ class MerchantAccountCommandService extends BaseService
        ]);
    }

+    /**
+     * 释放冻结余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function releaseFrozenAmount(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->transactionRetry(function () use ($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo) {
@@ -167,6 +242,18 @@ class MerchantAccountCommandService extends BaseService
        });
    }

+    /**
+     * 在当前事务中释放冻结余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     * @throws ValidationException
+     */
    public function releaseFrozenAmountInCurrentTransaction(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        $this->assertPositiveAmount($amount);
@@ -213,6 +300,17 @@ class MerchantAccountCommandService extends BaseService
        ]);
    }

+    /**
+     * 增加可用余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function creditAvailableAmount(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->transactionRetry(function () use ($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo) {
@@ -220,6 +318,18 @@ class MerchantAccountCommandService extends BaseService
        });
    }

+    /**
+     * 在当前事务中增加可用余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     * @throws ValidationException
+     */
    public function creditAvailableAmountInCurrentTransaction(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        $this->assertPositiveAmount($amount);
@@ -257,6 +367,17 @@ class MerchantAccountCommandService extends BaseService
        ]);
    }

+    /**
+     * 扣减可用余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function debitAvailableAmount(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->transactionRetry(function () use ($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo) {
@@ -264,6 +385,19 @@ class MerchantAccountCommandService extends BaseService
        });
    }

+    /**
+     * 在当前事务中扣减可用余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     * @throws ValidationException
+     * @throws BalanceInsufficientException
+     */
    public function debitAvailableAmountInCurrentTransaction(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        $this->assertPositiveAmount($amount);
@@ -305,6 +439,12 @@ class MerchantAccountCommandService extends BaseService
        ]);
    }

+    /**
+     * 创建账户流水。
+     *
+     * @param array $data 流水数据
+     * @return MerchantAccountLedger 流水记录
+     */
    private function createLedger(array $data): MerchantAccountLedger
    {
        $data['ledger_no'] = $data['ledger_no'] ?? $this->generateNo('LG');
@@ -314,11 +454,24 @@ class MerchantAccountCommandService extends BaseService
        return $this->ledgerRepository->create($data);
    }

+    /**
+     * 按幂等键查询流水。
+     *
+     * @param string $idempotencyKey 幂等键
+     * @return MerchantAccountLedger|null 流水记录
+     */
    private function findLedgerByIdempotencyKey(string $idempotencyKey): ?MerchantAccountLedger
    {
        return $this->ledgerRepository->findByIdempotencyKey($idempotencyKey);
    }

+    /**
+     * 校验金额必须大于 0。
+     *
+     * @param int $amount 金额（分）
+     * @return void
+     * @throws ValidationException
+     */
    private function assertPositiveAmount(int $amount): void
    {
        if ($amount <= 0) {
@@ -326,6 +479,17 @@ class MerchantAccountCommandService extends BaseService
        }
    }

+    /**
+     * 校验幂等流水与当前请求一致。
+     *
+     * @param MerchantAccountLedger $ledger 流水
+     * @param int $bizType 业务类型
+     * @param string $bizNo 业务单号
+     * @param int $amount 金额（分）
+     * @param int $direction 流向
+     * @return void
+     * @throws ConflictException
+     */
    private function assertLedgerMatch(MerchantAccountLedger $ledger, int $bizType, string $bizNo, int $amount, int $direction): void
    {
        if ((int) $ledger->biz_type !== $bizType || (int) $ledger->amount !== $amount || (string) $ledger->biz_no !== $bizNo || (int) $ledger->direction !== $direction) {
@@ -337,6 +501,13 @@ class MerchantAccountCommandService extends BaseService
        }
    }

+    /**
+     * 归一化追踪号。
+     *
+     * @param string $traceNo 追踪号
+     * @param string $bizNo 业务单号
+     * @return string 追踪号
+     */
    private function normalizeTraceNo(string $traceNo, string $bizNo): string
    {
        $traceNo = trim($traceNo);
@@ -347,3 +518,8 @@ class MerchantAccountCommandService extends BaseService
        return $bizNo;
    }
 }
+
+
+
+
+
--- a/app/service/account/funds/MerchantAccountQueryService.php
+++ b/app/service/account/funds/MerchantAccountQueryService.php
@@ -11,9 +11,19 @@ use app\repository\account\ledger\MerchantAccountLedgerRepository;
 * 商户账户查询服务。
 *
 * 只负责账户列表、概览和快照查询，不承载资金变更逻辑。
+ *
+ * @property MerchantAccountRepository $accountRepository 账户仓库
+ * @property MerchantAccountLedgerRepository $ledgerRepository 流水仓库
 */
 class MerchantAccountQueryService extends BaseService
 {
+    /**
+     * 构造方法。
+     *
+     * @param MerchantAccountRepository $accountRepository 账户仓库
+     * @param MerchantAccountLedgerRepository $ledgerRepository 流水仓库
+     * @return void
+     */
    public function __construct(
        protected MerchantAccountRepository $accountRepository,
        protected MerchantAccountLedgerRepository $ledgerRepository
@@ -22,6 +32,11 @@ class MerchantAccountQueryService extends BaseService

    /**
     * 分页查询商户账户。
+     *
+     * @param array $filters 筛选条件
+     * @param int $page 页码
+     * @param int $pageSize 每页条数
+     * @return \Illuminate\Contracts\Pagination\LengthAwarePaginator 分页结果
     */
    public function paginate(array $filters = [], int $page = 1, int $pageSize = 10)
    {
@@ -73,6 +88,8 @@ class MerchantAccountQueryService extends BaseService

    /**
     * 资金中心概览。
+     *
+     * @return array 概览数据
     */
    public function summary(): array
    {
@@ -103,6 +120,9 @@ class MerchantAccountQueryService extends BaseService
     * 获取商户余额快照。
     *
     * 用于后台展示和接口返回，不修改任何账户数据。
+     *
+     * @param int $merchantId 商户ID
+     * @return array 快照数据
     */
    public function getBalanceSnapshot(int $merchantId): array
    {
@@ -125,6 +145,9 @@ class MerchantAccountQueryService extends BaseService

    /**
     * 查询商户账户详情。
+     *
+     * @param int $id 商户账户查询ID
+     * @return MerchantAccount|null 账户记录
     */
    public function findById(int $id): ?MerchantAccount
    {
@@ -158,3 +181,6 @@ class MerchantAccountQueryService extends BaseService
    }

 }
+
+
+
--- a/app/service/account/funds/MerchantAccountService.php
+++ b/app/service/account/funds/MerchantAccountService.php
@@ -7,95 +7,252 @@ use app\model\merchant\MerchantAccount;
 use app\model\merchant\MerchantAccountLedger;

 /**
- * 商户余额门面服务。
+ * 商户余额服务。
 *
- * 对外保留原有调用契约，内部委托给查询和命令两个子服务。
+ * @property MerchantAccountQueryService $queryService 查询服务
+ * @property MerchantAccountCommandService $commandService 命令服务
 */
 class MerchantAccountService extends BaseService
 {
+    /**
+     * 构造方法。
+     *
+     * @param MerchantAccountQueryService $queryService 查询服务
+     * @param MerchantAccountCommandService $commandService 命令服务
+     * @return void
+     */
    public function __construct(
        protected MerchantAccountQueryService $queryService,
        protected MerchantAccountCommandService $commandService
    ) {
    }

+    /**
+     * 分页查询商户账户列表。
+     *
+     * @param array $filters 筛选条件
+     * @param int $page 页码
+     * @param int $pageSize 每页条数
+     * @return \Illuminate\Contracts\Pagination\LengthAwarePaginator 分页结果
+     */
    public function paginate(array $filters = [], int $page = 1, int $pageSize = 10)
    {
        return $this->queryService->paginate($filters, $page, $pageSize);
    }

+    /**
+     * 获取商户账户总览。
+     *
+     * @return array 总览数据
+     */
    public function summary(): array
    {
        return $this->queryService->summary();
    }

+    /**
+     * 获取或创建商户账户。
+     *
+     * @param int $merchantId 商户ID
+     * @return MerchantAccount 账户记录
+     */
    public function ensureAccount(int $merchantId): MerchantAccount
    {
        return $this->commandService->ensureAccount($merchantId);
    }

+    /**
+     * 在当前事务中获取或创建商户账户。
+     *
+     * @param int $merchantId 商户ID
+     * @return MerchantAccount 账户记录
+     */
    public function ensureAccountInCurrentTransaction(int $merchantId): MerchantAccount
    {
        return $this->commandService->ensureAccountInCurrentTransaction($merchantId);
    }

+    /**
+     * 冻结可用余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function freezeAmount(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->commandService->freezeAmount($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo);
    }

+    /**
+     * 在当前事务中冻结可用余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function freezeAmountInCurrentTransaction(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->commandService->freezeAmountInCurrentTransaction($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo);
    }

+    /**
+     * 扣减冻结余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function deductFrozenAmount(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->commandService->deductFrozenAmount($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo);
    }

+    /**
+     * 在当前事务中扣减冻结余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function deductFrozenAmountInCurrentTransaction(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->commandService->deductFrozenAmountInCurrentTransaction($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo);
    }

+    /**
+     * 释放冻结余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function releaseFrozenAmount(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->commandService->releaseFrozenAmount($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo);
    }

+    /**
+     * 在当前事务中释放冻结余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function releaseFrozenAmountInCurrentTransaction(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->commandService->releaseFrozenAmountInCurrentTransaction($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo);
    }

+    /**
+     * 增加可用余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function creditAvailableAmount(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->commandService->creditAvailableAmount($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo);
    }

+    /**
+     * 在当前事务中增加可用余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function creditAvailableAmountInCurrentTransaction(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->commandService->creditAvailableAmountInCurrentTransaction($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo);
    }

+    /**
+     * 扣减可用余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function debitAvailableAmount(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->commandService->debitAvailableAmount($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo);
    }

+    /**
+     * 在当前事务中扣减可用余额。
+     *
+     * @param int $merchantId 商户ID
+     * @param int $amount 金额（分）
+     * @param string $bizNo 业务单号
+     * @param string $idempotencyKey 幂等键
+     * @param array $extJson 扩展字段
+     * @param string $traceNo 追踪号
+     * @return MerchantAccountLedger 流水记录
+     */
    public function debitAvailableAmountInCurrentTransaction(int $merchantId, int $amount, string $bizNo, string $idempotencyKey, array $extJson = [], string $traceNo = ''): MerchantAccountLedger
    {
        return $this->commandService->debitAvailableAmountInCurrentTransaction($merchantId, $amount, $bizNo, $idempotencyKey, $extJson, $traceNo);
    }

+    /**
+     * 获取余额快照。
+     *
+     * @param int $merchantId 商户ID
+     * @return array 快照数据
+     */
    public function getBalanceSnapshot(int $merchantId): array
    {
        return $this->queryService->getBalanceSnapshot($merchantId);
    }

+    /**
+     * 按ID查询商户账户。
+     *
+     * @param int $id 商户账户ID
+     * @return MerchantAccount|null 账户记录
+     */
    public function findById(int $id): ?MerchantAccount
    {
        return $this->queryService->findById($id);
    }
 }
+
+
--- a/app/service/account/ledger/MerchantAccountLedgerService.php
+++ b/app/service/account/ledger/MerchantAccountLedgerService.php
@@ -9,11 +9,18 @@ use app\repository\account\ledger\MerchantAccountLedgerRepository;

 /**
 * 商户账户流水查询服务。
+ *
+ * 负责商户账户流水的列表、详情和展示字段装配。
+ *
+ * @property MerchantAccountLedgerRepository $merchantAccountLedgerRepository 商户账户流水仓库
 */
 class MerchantAccountLedgerService extends BaseService
 {
    /**
-     * 构造函数，注入流水仓库。
+     * 构造方法。
+     *
+     * @param MerchantAccountLedgerRepository $merchantAccountLedgerRepository 商户账户流水仓库
+     * @return void
     */
    public function __construct(
        protected MerchantAccountLedgerRepository $merchantAccountLedgerRepository
@@ -22,6 +29,11 @@ class MerchantAccountLedgerService extends BaseService

    /**
     * 分页查询账户流水。
+     *
+     * @param array $filters 筛选条件
+     * @param int $page 页码
+     * @param int $pageSize 每页条数
+     * @return \Illuminate\Contracts\Pagination\LengthAwarePaginator 分页结果
     */
    public function paginate(array $filters = [], int $page = 1, int $pageSize = 10)
    {
@@ -72,6 +84,9 @@ class MerchantAccountLedgerService extends BaseService

    /**
     * 查询流水详情。
+     *
+     * @param int $id 商户账户流水ID
+     * @return MerchantAccountLedger|null 流水模型
     */
    public function findById(int $id): ?MerchantAccountLedger
    {
@@ -84,6 +99,9 @@ class MerchantAccountLedgerService extends BaseService

    /**
     * 格式化记录。
+     *
+     * @param object $row 原始查询行
+     * @return object 格式化后的记录
     */
    private function decorateRow(object $row): object
    {
@@ -103,6 +121,8 @@ class MerchantAccountLedgerService extends BaseService

    /**
     * 构建查询。
+     *
+     * @return \Illuminate\Database\Eloquent\Builder 查询构造器
     */
    private function baseQuery()
    {
@@ -136,3 +156,6 @@ class MerchantAccountLedgerService extends BaseService
    }

 }
+
+
+