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

app/service/payment/trace/TradeTraceReportService.php

@@ -17,6 +17,14 @@ class TradeTraceReportService extends BaseService
 {
     /**
      * 汇总追踪统计数据。
+     *
+     * @param BizOrder|null $bizOrder 业务订单
+     * @param array $payOrders 支付订单列表
+     * @param array $refundOrders 退款订单列表
+     * @param array $settlementOrders 清算订单列表
+     * @param array $accountLedgers 账户流水列表
+     * @param array $payCallbacks 支付回调列表
+     * @return array<string, int|bool> 汇总统计
      */
     public function buildSummary(?BizOrder $bizOrder, array $payOrders, array $refundOrders, array $settlementOrders, array $accountLedgers, array $payCallbacks): array
     {
@@ -36,6 +44,14 @@ class TradeTraceReportService extends BaseService
 
     /**
      * 根据关联记录组装追踪时间线。
+     *
+     * @param BizOrder|null $bizOrder 业务订单
+     * @param array $payOrders 支付订单列表
+     * @param array $refundOrders 退款订单列表
+     * @param array $settlementOrders 清算订单列表
+     * @param array $accountLedgers 账户流水列表
+     * @param array $payCallbacks 支付回调列表
+     * @return array<int, array<string, mixed>> 时间线事件
      */
     public function buildTimeline(?BizOrder $bizOrder, array $payOrders, array $refundOrders, array $settlementOrders, array $accountLedgers, array $payCallbacks): array
     {
@@ -213,8 +229,17 @@ class TradeTraceReportService extends BaseService
 
     /**
      * 追加一条时间线事件。
+     *
+     * @param array<int, array<string, mixed>> $events 事件列表
+     * @param int $sortOrder 当前排序号
+     * @param string $type 事件类型
+     * @param string $sourceNo 事件来源单号
+     * @param string $status 事件状态
+     * @param \DateTimeInterface|int|string|float|null $at 事件时间
+     * @param array<string, mixed> $payload 事件载荷
+     * @return void
      */
-    private function pushEvent(array &$events, int &$sortOrder, string $type, string $sourceNo, string $status, mixed $at, array $payload = []): void
+    private function pushEvent(array &$events, int &$sortOrder, string $type, string $sourceNo, string $status, \DateTimeInterface|int|string|float|null $at, array $payload = []): void
     {
         $atText = $this->formatDateTime($at);
         if ($atText === '') {
@@ -235,6 +260,10 @@ class TradeTraceReportService extends BaseService
 
     /**
      * 汇总模型列表中的数值字段。
+     *
+     * @param array $items 模型列表
+     * @param string $field 字段名
+     * @return int 汇总值
      */
     private function sumBy(array $items, string $field): int
     {
@@ -246,3 +275,6 @@ class TradeTraceReportService extends BaseService
         return $total;
     }
 }
+
+
+

app/service/payment/trace/TradeTraceService.php

@@ -15,9 +15,29 @@ use app\repository\payment\settlement\SettlementOrderRepository;
 
 /**
  * 跨域交易追踪查询服务。
+ *
+ * @property TradeTraceReportService $tradeTraceReportService 交易追踪报表服务
+ * @property BizOrderRepository $bizOrderRepository 业务订单仓库
+ * @property PayOrderRepository $payOrderRepository 支付单仓库
+ * @property RefundOrderRepository $refundOrderRepository 退款单仓库
+ * @property SettlementOrderRepository $settlementOrderRepository 结算订单仓库
+ * @property MerchantAccountLedgerRepository $merchantAccountLedgerRepository 商户账户流水仓库
+ * @property PayCallbackLogRepository $payCallbackLogRepository 支付回调日志仓库
  */
 class TradeTraceService extends BaseService
 {
+    /**
+     * 构造方法。
+     *
+     * @param TradeTraceReportService $tradeTraceReportService 交易追踪报表服务
+     * @param BizOrderRepository $bizOrderRepository 业务订单仓库
+     * @param PayOrderRepository $payOrderRepository 支付订单仓库
+     * @param RefundOrderRepository $refundOrderRepository 退款单仓库
+     * @param SettlementOrderRepository $settlementOrderRepository 结算订单仓库
+     * @param MerchantAccountLedgerRepository $merchantAccountLedgerRepository 商户账户流水仓库
+     * @param PayCallbackLogRepository $payCallbackLogRepository 支付回调日志仓库
+     * @return void
+     */
     public function __construct(
         protected TradeTraceReportService $tradeTraceReportService,
         protected BizOrderRepository $bizOrderRepository,
@@ -31,6 +51,10 @@ class TradeTraceService extends BaseService
 
     /**
      * 根据追踪号查询完整交易链路。
+     *
+     * @param string $traceNo 追踪号
+     * @return array{trace_no: string, resolved_trace_no: string, matched_by: string, biz_order: BizOrder|null, pay_orders: array, refund_orders: array, settlement_orders: array, account_ledgers: array, pay_callbacks: array, summary: array, timeline: array} 追踪结果
+     * @throws ValidationException
      */
     public function queryByTraceNo(string $traceNo): array
     {
@@ -40,6 +64,7 @@ class TradeTraceService extends BaseService
         }
 
         $matchedBy = 'trace_no';
+        // 先按追踪号找，找不到再用业务单号兜底，尽量把同一条链路串起来。
         $bizOrder = $this->bizOrderRepository->findByTraceNo($traceNo);
         if (!$bizOrder) {
             $bizOrder = $this->bizOrderRepository->findByBizNo($traceNo);
@@ -58,6 +83,7 @@ class TradeTraceService extends BaseService
         $settlementOrders = $this->loadSettlementOrders($resolvedTraceNo);
 
         if (!$bizOrder) {
+            // 如果主单没直接查到，就从支付单或退款单反推业务单，保证追踪页尽量有完整链路。
             $bizOrder = $this->deriveBizOrder($payOrders, $refundOrders);
             if ($bizOrder) {
                 $matchedBy = $matchedBy === 'trace_no' ? 'derived' : $matchedBy;
@@ -102,9 +128,14 @@ class TradeTraceService extends BaseService
 
     /**
      * 加载支付单列表。
+     *
+     * @param string $traceNo 追踪号
+     * @param BizOrder|null $bizOrder 业务订单
+     * @return array<int, object> 支付订单列表
      */
     private function loadPayOrders(string $traceNo, ?BizOrder $bizOrder): array
     {
+        // 优先按 trace_no 查，缺失时再回到 biz_no，兼容早期单据没有完整追踪号的情况。
         $items = $this->collectionToArray($this->payOrderRepository->listByTraceNo($traceNo));
         if (!empty($items)) {
             return $items;
@@ -119,9 +150,14 @@ class TradeTraceService extends BaseService
 
     /**
      * 加载退款单列表。
+     *
+     * @param string $traceNo 追踪号
+     * @param BizOrder|null $bizOrder 业务订单
+     * @return array<int, object> 退款订单列表
      */
     private function loadRefundOrders(string $traceNo, ?BizOrder $bizOrder): array
     {
+        // 退款单同样先按追踪号查，再用业务单号兜底。
         $items = $this->collectionToArray($this->refundOrderRepository->listByTraceNo($traceNo));
         if (!empty($items)) {
             return $items;
@@ -136,6 +172,9 @@ class TradeTraceService extends BaseService
 
     /**
      * 加载清结算单列表。
+     *
+     * @param string $traceNo 追踪号
+     * @return array<int, object> 清算订单列表
      */
     private function loadSettlementOrders(string $traceNo): array
     {
@@ -144,11 +183,15 @@ class TradeTraceService extends BaseService
 
     /**
      * 加载支付回调日志列表。
+     *
+     * @param array<int, object> $payOrders 支付订单列表
+     * @return array<int, array<string, mixed>> 支付回调列表
      */
     private function loadPayCallbacks(array $payOrders): array
     {
         $callbacks = [];
         foreach ($payOrders as $payOrder) {
+            // 同一追踪号下可能有多次回调记录，这里把每笔支付单的回调都收进来统一展示。
             foreach ($this->payCallbackLogRepository->listByPayNo((string) $payOrder->pay_no) as $callback) {
                 $callbacks[] = [
                     'id' => (int) ($callback->id ?? 0),
@@ -168,6 +211,7 @@ class TradeTraceService extends BaseService
         }
 
         usort($callbacks, static function ($left, $right): int {
+            // 新的回调日志排在前面，时间线页面直接从近到远看。
             return ($right['id'] ?? 0) <=> ($left['id'] ?? 0);
         });
 
@@ -176,18 +220,27 @@ class TradeTraceService extends BaseService
 
     /**
      * 加载资金流水列表。
+     *
+     * @param string $traceNo 追踪号
+     * @param BizOrder|null $bizOrder 业务订单
+     * @param array<int, object> $payOrders 支付订单列表
+     * @param array<int, object> $refundOrders 退款订单列表
+     * @param array<int, object> $settlementOrders 清算订单列表
+     * @return array<int, object> 资金流水列表
      */
     private function loadLedgers(string $traceNo, ?BizOrder $bizOrder, array $payOrders, array $refundOrders, array $settlementOrders): array
     {
         $ledgers = [];
         $seen = [];
 
+        // 先合并 trace_no 命中的流水，再补查相关业务单号下的流水并去重。
         foreach ($this->collectionToArray($this->merchantAccountLedgerRepository->listByTraceNo($traceNo)) as $ledger) {
             $seen[(string) $ledger->ledger_no] = true;
             $ledgers[] = $ledger;
         }
 
         $bizNos = [];
+        // 资金流水有时挂在业务单号，有时挂在支付单号、退款单号或清算单号上，这里一并纳入兜底查询。
         if ($bizOrder) {
             $bizNos[] = (string) $bizOrder->biz_no;
         }
@@ -208,6 +261,7 @@ class TradeTraceService extends BaseService
         foreach ($bizNos as $bizNo) {
             foreach ($this->collectionToArray($this->merchantAccountLedgerRepository->listByBizNo($bizNo)) as $ledger) {
                 $ledgerNo = (string) ($ledger->ledger_no ?? '');
+                // 同一笔流水可能同时被 trace_no 和 biz_no 命中，这里只保留一份。
                 if ($ledgerNo !== '' && isset($seen[$ledgerNo])) {
                     continue;
                 }
@@ -227,10 +281,15 @@ class TradeTraceService extends BaseService
 
     /**
      * 从支付单或退款单反推出业务单。
+     *
+     * @param array<int, object> $payOrders 支付订单列表
+     * @param array<int, object> $refundOrders 退款订单列表
+     * @return BizOrder|null 业务订单模型
      */
     private function deriveBizOrder(array $payOrders, array $refundOrders): ?BizOrder
     {
         if (!empty($payOrders)) {
+            // 先从支付单反推业务单，支付单通常比退款单更早、更稳定。
             $bizNo = (string) ($payOrders[0]->biz_no ?? '');
             if ($bizNo !== '') {
                 $bizOrder = $this->bizOrderRepository->findByBizNo($bizNo);
@@ -241,6 +300,7 @@ class TradeTraceService extends BaseService
         }
 
         if (!empty($refundOrders)) {
+            // 没有支付单时，再用退款单反推业务单作为兜底。
             $bizNo = (string) ($refundOrders[0]->biz_no ?? '');
             if ($bizNo !== '') {
                 $bizOrder = $this->bizOrderRepository->findByBizNo($bizNo);
@@ -255,6 +315,9 @@ class TradeTraceService extends BaseService
 
     /**
      * 将可迭代对象转换为普通数组。
+     *
+     * @param iterable $items 可迭代对象
+     * @return array<int, mixed> 普通数组
      */
     private function collectionToArray(iterable $items): array
     {