perf(billing,settlement): paginate claims and wallet transactions (H9, H10)

GET /billing/claims loaded every tenant claim with no limit. Add
findByTenant(page, limit) + countByTenant (shared query builder), default
limit 50 / max 100, and expose totals as data.meta — kept inside the existing
{ data: { data: [...] } } envelope so current clients are unaffected.

GET /wallet/transactions was already bounded (findByUser defaulted to limit 50)
but page-less; add page/offset + countByUser + the same additive meta.

Regression: tests/Billing/ClaimsListPaginationTest,
tests/Settlement/WalletTransactionsPaginationTest.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/Billing/Controller/BillingController.php

@@ -184,9 +184,23 @@ class BillingController extends BaseController
             'to'           => $request->query->get('to') ?: null,
             'q'            => $request->query->get('q') ?: null,
         ];
-        $claims = $this->claimRepo->findByTenant($entityType, $entityId, $filters);
 
-        return $this->success(['data' => $this->enrichClaims($claims)]);
+        $page  = max(1, (int) $request->query->get('page', 1));
+        $limit = min(100, max(1, (int) $request->query->get('limit', 50)));
+
+        $claims = $this->claimRepo->findByTenant($entityType, $entityId, $filters, $page, $limit);
+        $total  = $this->claimRepo->countByTenant($entityType, $entityId, $filters);
+
+        // meta added inside the existing { data: { data: [...] } } envelope so
+        // existing clients keep reading data.data unchanged.
+        return $this->success([
+            'data' => $this->enrichClaims($claims),
+            'meta' => [
+                'totalRecords' => $total,
+                'totalPages'   => (int) ceil($total / $limit),
+                'currentPage'  => $page,
+            ],
+        ]);
     }
 
     #[Route('/api/v1/billing/claims/{uuid}/{action}', methods: ['POST'], requirements: ['action' => 'submit|approve|reject|pay'])]

src/Billing/Repository/ClaimRepository.php

@@ -22,14 +22,31 @@ class ClaimRepository extends ServiceEntityRepository
      * @param array{status?:?string, insurance_id?:?int, from?:?int, to?:?int, q?:?string} $filters
      * @return Claim[]
      */
-    public function findByTenant(string $entityType, int $entityId, array $filters = []): array
+    public function findByTenant(string $entityType, int $entityId, array $filters = [], int $page = 1, int $limit = 50): array
+    {
+        return $this->tenantQb($entityType, $entityId, $filters)
+            ->orderBy('c.id', 'DESC')
+            ->setFirstResult(($page - 1) * $limit)
+            ->setMaxResults($limit)
+            ->getQuery()
+            ->getResult();
+    }
+
+    public function countByTenant(string $entityType, int $entityId, array $filters = []): int
+    {
+        return (int) $this->tenantQb($entityType, $entityId, $filters)
+            ->select('COUNT(c.id)')
+            ->getQuery()
+            ->getSingleScalarResult();
+    }
+
+    private function tenantQb(string $entityType, int $entityId, array $filters): \Doctrine\ORM\QueryBuilder
     {
         $qb = $this->createQueryBuilder('c')
             ->where('c.entityType = :type')
             ->andWhere('c.entityId = :id')
             ->setParameter('type', $entityType)
-            ->setParameter('id', $entityId)
-            ->orderBy('c.id', 'DESC');
+            ->setParameter('id', $entityId);
 
         if (!empty($filters['status'])) {
             $qb->andWhere('c.status = :status')->setParameter('status', $filters['status']);
@@ -61,7 +78,7 @@ class ClaimRepository extends ServiceEntityRepository
             )->setParameter('q', '%' . $q . '%');
         }
 
-        return $qb->getQuery()->getResult();
+        return $qb;
     }
 
     /**

src/Settlement/Controller/SettlementController.php

@@ -86,14 +86,27 @@ class SettlementController extends BaseController
         ]
     )]
     #[Route('/api/v1/wallet/transactions', methods: ['GET'])]
-    public function transactions(#[CurrentUser] User $user): JsonResponse
+    public function transactions(Request $request, #[CurrentUser] User $user): JsonResponse
     {
+        $page  = max(1, (int) $request->query->get('page', 1));
+        $limit = min(100, max(1, (int) $request->query->get('limit', 50)));
+
         $transactions = array_map(
             fn(WalletTransaction $t) => $t->toArray(),
-            $this->walletRepo->findByUser($user)
+            $this->walletRepo->findByUser($user, $limit, ($page - 1) * $limit)
         );
+        $total = $this->walletRepo->countByUser($user);
 
-        return $this->success(['data' => $transactions]);
+        // meta added inside the existing { data: { data: [...] } } envelope so
+        // existing clients keep reading data.data unchanged.
+        return $this->success([
+            'data' => $transactions,
+            'meta' => [
+                'totalRecords' => $total,
+                'totalPages'   => (int) ceil($total / $limit),
+                'currentPage'  => $page,
+            ],
+        ]);
     }
 
     // ── Settlement Requests ───────────────────────────────────────────────────

src/Settlement/Repository/WalletTransactionRepository.php

@@ -15,9 +15,14 @@ class WalletTransactionRepository extends ServiceEntityRepository
     }
 
     /** @return WalletTransaction[] */
-    public function findByUser(User $user, int $limit = 50): array
+    public function findByUser(User $user, int $limit = 50, int $offset = 0): array
     {
-        return $this->findBy(['user' => $user], ['createdAt' => 'DESC'], $limit);
+        return $this->findBy(['user' => $user], ['createdAt' => 'DESC'], $limit, $offset);
+    }
+
+    public function countByUser(User $user): int
+    {
+        return $this->count(['user' => $user]);
     }
 
     public function save(WalletTransaction $entity, bool $flush = true): void