feat(root): merge relations pagination and worker retry

- Relations GET /api/v1/relations returns PaginatedResponse
- Worker jobs use @with_retry() for transient HTTP error resilience
- OpenAPI schema and mobile client regenerated

Author: gahyun-git

apps/api/openapi.json

@@ -320,6 +320,29 @@
               "default": true,
               "title": "Active Only"
             }
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 1,
+              "title": "Page"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "maximum": 100,
+              "minimum": 1,
+              "default": 20,
+              "title": "Limit"
+            }
           }
         ],
         "responses": {
@@ -328,11 +351,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/CareRelationResponse"
-                  },
-                  "title": "Response List Care Relations Api V1 Relations Get"
+                  "$ref": "#/components/schemas/PaginatedResponse_CareRelationResponse_"
                 }
               }
             }
@@ -2025,6 +2044,26 @@
         "title": "OAuthLoginRequest",
         "description": "OAuth login request."
       },
+      "PaginatedResponse_CareRelationResponse_": {
+        "properties": {
+          "data": {
+            "items": {
+              "$ref": "#/components/schemas/CareRelationResponse"
+            },
+            "type": "array",
+            "title": "Data"
+          },
+          "meta": {
+            "$ref": "#/components/schemas/PaginationMeta"
+          }
+        },
+        "type": "object",
+        "required": [
+          "data",
+          "meta"
+        ],
+        "title": "PaginatedResponse[CareRelationResponse]"
+      },
       "PaginatedResponse_MedicationResponse_": {
         "properties": {
           "data": {

apps/api/src/lib/ai/tools/log_wellness.py

@@ -98,7 +98,7 @@ async def execute(
 
         # Alert caregivers on warning/emergency via worker
         if status_val in {"warning", "emergency"}:
-            relations = await relations_repo.find_by_host(db, host_id)
+            relations, _ = await relations_repo.find_by_host(db, host_id, limit=1000)
             all_tokens: list[str] = []
             for rel in relations:
                 tokens = await get_user_token_strings(db, rel.caregiver_id)

apps/api/src/relations/repository.py

@@ -2,7 +2,7 @@
 
 import uuid
 
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.relations.model import CareRelation
@@ -35,31 +35,41 @@ async def find_by_host(
     host_id: uuid.UUID,
     *,
     active_only: bool = True,
-) -> list[CareRelation]:
-    """Find all care relations for a given host."""
-    stmt = select(CareRelation).where(
-        CareRelation.host_id == host_id,
-    )
+    limit: int = 20,
+    offset: int = 0,
+) -> tuple[list[CareRelation], int]:
+    """Find care relations for a given host with pagination."""
+    base = select(CareRelation).where(CareRelation.host_id == host_id)
     if active_only:
-        stmt = stmt.where(CareRelation.is_active.is_(True))
+        base = base.where(CareRelation.is_active.is_(True))
+
+    count_stmt = select(func.count()).select_from(base.subquery())
+    total = (await db.execute(count_stmt)).scalar_one()
+
+    stmt = base.order_by(CareRelation.created_at.desc()).limit(limit).offset(offset)
     result = await db.execute(stmt)
-    return list(result.scalars().all())
+    return list(result.scalars().all()), total
 
 
 async def find_by_caregiver(
     db: AsyncSession,
     caregiver_id: uuid.UUID,
     *,
     active_only: bool = True,
-) -> list[CareRelation]:
-    """Find all care relations for a given caregiver."""
-    stmt = select(CareRelation).where(
-        CareRelation.caregiver_id == caregiver_id,
-    )
+    limit: int = 20,
+    offset: int = 0,
+) -> tuple[list[CareRelation], int]:
+    """Find care relations for a given caregiver with pagination."""
+    base = select(CareRelation).where(CareRelation.caregiver_id == caregiver_id)
     if active_only:
-        stmt = stmt.where(CareRelation.is_active.is_(True))
+        base = base.where(CareRelation.is_active.is_(True))
+
+    count_stmt = select(func.count()).select_from(base.subquery())
+    total = (await db.execute(count_stmt)).scalar_one()
+
+    stmt = base.order_by(CareRelation.created_at.desc()).limit(limit).offset(offset)
     result = await db.execute(stmt)
-    return list(result.scalars().all())
+    return list(result.scalars().all()), total
 
 
 async def save(

apps/api/src/relations/router.py

@@ -3,7 +3,8 @@
 from fastapi import APIRouter, HTTPException, Query, status
 
 from src.common.errors import AUTHZ_001, RES_001, raise_api_error
-from src.lib.authorization import authorize_relation_access
+from src.common.models import PaginatedResponse, PaginationParams
+from src.lib.authorization import authorize_host_access, authorize_relation_access
 from src.lib.dependencies import CurrentUser, DBSession
 from src.relations import service
 from src.relations.schemas import (
@@ -42,44 +43,56 @@ async def create_care_relation(
     return CareRelationResponse.model_validate(relation)
 
 
-@router.get("", response_model=list[CareRelationResponse])
+@router.get("", response_model=PaginatedResponse[CareRelationResponse])
 async def list_care_relations(
     db: DBSession,
     user: CurrentUser,
     host_id: uuid.UUID | None = Query(default=None),
     caregiver_id: uuid.UUID | None = Query(default=None),
     active_only: bool = Query(default=True),
-) -> list[CareRelationResponse]:
+    page: int = Query(default=1, ge=1),
+    limit: int = Query(default=20, ge=1, le=100),
+) -> PaginatedResponse[CareRelationResponse]:
     """List care relations filtered by host or caregiver.
 
     Users can only list relations they participate in.
     """
     user_uuid = uuid.UUID(user.id)
+    params = PaginationParams(page=page, limit=limit)
 
     if host_id:
         if user_uuid != host_id:
-            # Verify caller is a caregiver for this host
-            relations = await service.list_relations_for_host(
-                db, host_id, active_only=active_only
-            )
-            if not any(r.caregiver_id == user_uuid for r in relations):
-                raise_api_error(AUTHZ_001, status.HTTP_403_FORBIDDEN)
-            return [CareRelationResponse.model_validate(r) for r in relations]
-        relations = await service.list_relations_for_host(
-            db, host_id, active_only=active_only
+            await authorize_host_access(db, user=user, host_id=host_id)
+        relations, total = await service.list_relations_for_host(
+            db,
+            host_id,
+            active_only=active_only,
+            limit=params.limit,
+            offset=params.offset,
         )
     elif caregiver_id:
         if user_uuid != caregiver_id:
             raise_api_error(AUTHZ_001, status.HTTP_403_FORBIDDEN)
-        relations = await service.list_relations_for_caregiver(
-            db, caregiver_id, active_only=active_only
+        relations, total = await service.list_relations_for_caregiver(
+            db,
+            caregiver_id,
+            active_only=active_only,
+            limit=params.limit,
+            offset=params.offset,
         )
     else:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail="Either host_id or caregiver_id is required",
         )
-    return [CareRelationResponse.model_validate(r) for r in relations]
+
+    data = [CareRelationResponse.model_validate(r) for r in relations]
+    return PaginatedResponse[CareRelationResponse].create(
+        data=data,
+        total=total,
+        page=params.page,
+        limit=params.limit,
+    )
 
 
 @router.get("/{relation_id}", response_model=CareRelationResponse)

apps/api/src/relations/service.py

@@ -40,19 +40,27 @@ async def list_relations_for_host(
     host_id: uuid.UUID,
     *,
     active_only: bool = True,
-) -> list[CareRelation]:
-    """List all care relations where user is host."""
-    return await repository.find_by_host(db, host_id, active_only=active_only)
+    limit: int = 20,
+    offset: int = 0,
+) -> tuple[list[CareRelation], int]:
+    """List care relations where user is host with pagination."""
+    return await repository.find_by_host(
+        db, host_id, active_only=active_only, limit=limit, offset=offset
+    )
 
 
 async def list_relations_for_caregiver(
     db: AsyncSession,
     caregiver_id: uuid.UUID,
     *,
     active_only: bool = True,
-) -> list[CareRelation]:
-    """List all care relations where user is caregiver."""
-    return await repository.find_by_caregiver(db, caregiver_id, active_only=active_only)
+    limit: int = 20,
+    offset: int = 0,
+) -> tuple[list[CareRelation], int]:
+    """List care relations where user is caregiver with pagination."""
+    return await repository.find_by_caregiver(
+        db, caregiver_id, active_only=active_only, limit=limit, offset=offset
+    )
 
 
 async def get_relation(

apps/api/tests/e2e/test_relation_flow.py

@@ -54,9 +54,12 @@ async def test_list_relations_by_host(
             params={"host_id": str(HOST_USER_ID)},
         )
         assert resp.status_code == 200
-        data = resp.json()
-        assert len(data) >= 1
-        assert data[0]["host_id"] == str(HOST_USER_ID)
+        body = resp.json()
+        assert "data" in body
+        assert "meta" in body
+        assert len(body["data"]) >= 1
+        assert body["data"][0]["host_id"] == str(HOST_USER_ID)
+        assert body["meta"]["total"] >= 1
 
     async def test_list_relations_by_caregiver(
         self,
@@ -82,9 +85,12 @@ async def test_list_relations_by_caregiver(
             params={"caregiver_id": str(CAREGIVER_USER_ID)},
         )
         assert resp.status_code == 200
-        data = resp.json()
-        assert len(data) >= 1
-        assert data[0]["caregiver_id"] == str(CAREGIVER_USER_ID)
+        body = resp.json()
+        assert "data" in body
+        assert "meta" in body
+        assert len(body["data"]) >= 1
+        assert body["data"][0]["caregiver_id"] == str(CAREGIVER_USER_ID)
+        assert body["meta"]["total"] >= 1
 
     async def test_update_relation_deactivate(
         self,

apps/api/tests/test_ai_tools.py

@@ -143,7 +143,7 @@ class TestLogWellnessTool:
     @pytest.mark.asyncio
     @patch(_DISPATCH, new_callable=AsyncMock)
     @patch(_GET_TOKENS, new_callable=AsyncMock, return_value=[])
-    @patch(_FIND_BY_HOST, new_callable=AsyncMock, return_value=[])
+    @patch(_FIND_BY_HOST, new_callable=AsyncMock, return_value=([], 0))
     @patch(_CREATE_WELLNESS, new_callable=AsyncMock)
     async def test_log_wellness_success(
         self,
@@ -206,9 +206,10 @@ async def test_log_wellness_triggers_alert_on_emergency(
     ) -> None:
         caregiver_id = uuid.UUID("00000000-0000-4000-8000-000000000010")
         mock_create.return_value = _mock_wellness_log()
-        mock_find.return_value = [
-            MagicMock(caregiver_id=caregiver_id),
-        ]
+        mock_find.return_value = (
+            [MagicMock(caregiver_id=caregiver_id)],
+            1,
+        )
         mock_get_tokens.return_value = ["fcm-tok-cg1"]
 
         tool = LogWellnessTool()
@@ -244,10 +245,10 @@ async def test_log_wellness_triggers_alert_on_warning(
         cg1 = uuid.UUID("00000000-0000-4000-8000-000000000011")
         cg2 = uuid.UUID("00000000-0000-4000-8000-000000000012")
         mock_create.return_value = _mock_wellness_log()
-        mock_find.return_value = [
-            MagicMock(caregiver_id=cg1),
-            MagicMock(caregiver_id=cg2),
-        ]
+        mock_find.return_value = (
+            [MagicMock(caregiver_id=cg1), MagicMock(caregiver_id=cg2)],
+            2,
+        )
         mock_get_tokens.side_effect = [["tok-cg1"], ["tok-cg2"]]
 
         tool = LogWellnessTool()