feat(appointments): Add projection support and request schema for list appointments endpoint

- Add ListAppointmentsRequest schema following SCM standard pattern with filters, skip, limit, and projection_list fields
- Refactor list_appointments_endpoint to accept request payload instead of individual query parameters
- Implement projection support in list_appointments service to selectively return appointment fields
- Convert merchant_id to UUID in service layer while maintaining string representation in responses
- Update appointment response conversion to handle merchant_id as string for API consistency
- Add backward compatibility for filter parameter extraction from request payload
- Return raw dict responses when projection is used, otherwise convert to AppointmentResponse models
- Remove unused Query import from router
- Align appointments list endpoint with existing SCM patterns used in staff and services endpoints

app/appointments/controllers/router.py

@@ -5,7 +5,7 @@ import logging
 from uuid import UUID
 from typing import Optional
 from datetime import datetime
-from fastapi import APIRouter, HTTPException, Query, status, Depends
+from fastapi import APIRouter, HTTPException, status, Depends
 
 from app.dependencies.auth import TokenUser
 from app.dependencies.pos_permissions import require_pos_permission
@@ -15,6 +15,7 @@ from app.appointments.schemas.schema import (
     UpdateStatusRequest,
     AppointmentResponse,
     AppointmentServiceResponse,
+    ListAppointmentsRequest,
     ListAppointmentsResponse,
     CheckoutResponse,
 )
@@ -51,7 +52,7 @@ async def create_appointment_endpoint(
             merchant_id = current_user.merchant_id
         
         aid = await create_appointment(
-            merchant_id=merchant_id,
+            merchant_id=UUID(merchant_id),
             source=req.source,
             booking_channel=req.booking_channel,
             customer_id=req.customer_id,
@@ -70,25 +71,32 @@ async def create_appointment_endpoint(
 
 @router.post("/list", response_model=ListAppointmentsResponse)
 async def list_appointments_endpoint(
-    merchant_id: Optional[str] = None,
-    start_from: Optional[datetime] = Query(None),
-    start_to: Optional[datetime] = Query(None),
-    staff_id: Optional[UUID] = Query(None),
-    status: Optional[str] = Query(None),
-    source: Optional[str] = Query(None),
-    skip: int = Query(0, ge=0),
-    limit: int = Query(100, ge=1, le=1000),
+    payload: ListAppointmentsRequest,
     current_user: TokenUser = Depends(require_pos_permission("retail_appointments", "view"))
 ):
-    # Use merchant_id from token if not provided in request
-    if merchant_id is None:
-        if not current_user.merchant_id:
-            raise HTTPException(status_code=400, detail="merchant_id must be provided in request or token")
-        # Use merchant_id directly as string from JWT token
-        merchant_id = current_user.merchant_id
+    # Extract filters and parameters from payload
+    filters = payload.filters or {}
+    skip = payload.skip or 0
+    limit = payload.limit or 100
+    projection_list = payload.projection_list
+    
+    # Use merchant_id from token (following SCM pattern)
+    if not current_user.merchant_id:
+        raise HTTPException(status_code=400, detail="merchant_id must be available in token")
+    
+    # Extract individual filter parameters for backward compatibility
+    start_from = None
+    start_to = None
+    if filters.get("start_from"):
+        start_from = filters["start_from"] if isinstance(filters["start_from"], datetime) else datetime.fromisoformat(filters["start_from"])
+    if filters.get("start_to"):
+        start_to = filters["start_to"] if isinstance(filters["start_to"], datetime) else datetime.fromisoformat(filters["start_to"])
+    staff_id = UUID(filters["staff_id"]) if filters.get("staff_id") else None
+    status = filters.get("status")
+    source = filters.get("source")
     
     items, total = await list_appointments(
-        merchant_id=merchant_id,
+        merchant_id=UUID(current_user.merchant_id),
         start_from=start_from,
         start_to=start_to,
         staff_id=staff_id,
@@ -96,9 +104,15 @@ async def list_appointments_endpoint(
         source=source,
         skip=skip,
         limit=limit,
+        projection_list=projection_list,
     )
-    responses = [await _to_appt_response(i) for i in items]
-    return ListAppointmentsResponse(items=responses, total=total)
+    
+    # Return raw dict if projection used, otherwise convert to response models
+    if projection_list:
+        return {"items": items, "total": total}
+    else:
+        responses = [await _to_appt_response(i) for i in items]
+        return ListAppointmentsResponse(items=responses, total=total)
 
 @router.get("/{appointment_id}", response_model=AppointmentResponse)
 async def get_appointment_endpoint(
@@ -168,7 +182,7 @@ async def _to_appt_response(appt: dict) -> AppointmentResponse:
     ) for s in appt.get("services", [])]
     return AppointmentResponse(
         appointment_id=UUID(appt["appointment_id"]) if isinstance(appt["appointment_id"], str) else appt["appointment_id"],
-        merchant_id=appt["merchant_id"],
+        merchant_id=str(appt["merchant_id"]) if appt["merchant_id"] else None,
         source=appt["source"],
         booking_channel=appt.get("booking_channel"),
         customer_id=UUID(appt["customer_id"]) if appt.get("customer_id") and isinstance(appt["customer_id"], str) else appt.get("customer_id"),

app/appointments/schemas/schema.py

@@ -1,7 +1,7 @@
 """
 Pydantic schemas for Appointment APIs.
 """
-from typing import List, Optional
+from typing import List, Optional, Dict, Any
 from pydantic import BaseModel, Field
 from uuid import UUID
 from datetime import datetime
@@ -58,6 +58,28 @@ class AppointmentResponse(BaseModel):
     created_by: Optional[UUID]
     services: List[AppointmentServiceResponse] = []
 
+class ListAppointmentsRequest(BaseModel):
+    """List appointments request following SCM standard pattern"""
+    filters: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Filter criteria for appointments"
+    )
+    skip: Optional[int] = Field(
+        0,
+        ge=0,
+        description="Number of records to skip"
+    )
+    limit: Optional[int] = Field(
+        100,
+        ge=1,
+        le=1000,
+        description="Maximum records to return (1-1000)"
+    )
+    projection_list: Optional[List[str]] = Field(
+        None,
+        description="List of fields to include in response"
+    )
+
 class ListAppointmentsResponse(BaseModel):
     items: List[AppointmentResponse]
     total: int

app/appointments/services/service.py

@@ -137,6 +137,7 @@ async def list_appointments(
     source: Optional[str] = None,
     skip: int = 0,
     limit: int = 100,
+    projection_list: Optional[List[str]] = None,
 ) -> Tuple[List[dict], int]:
     async with get_postgres_session() as session:
         if session is None:
@@ -158,9 +159,38 @@ async def list_appointments(
         if staff_id:
             where.append("EXISTS (SELECT 1 FROM trans.pos_appointment_service s WHERE s.appointment_id = pa.appointment_id AND s.staff_id = :sid)")
             params["sid"] = str(staff_id)
-        sql = f"SELECT * FROM trans.pos_appointment pa WHERE {' AND '.join(where)} ORDER BY pa.start_time DESC OFFSET :skip LIMIT :limit"
+        
+        # Build SELECT clause based on projection_list
+        if projection_list:
+            # For PostgreSQL, we need to map projection fields to actual columns
+            select_fields = []
+            for field in projection_list:
+                if field in ["appointment_id", "merchant_id", "source", "booking_channel", 
+                           "customer_id", "customer_name", "customer_phone", "status", 
+                           "start_time", "end_time", "notes", "created_by"]:
+                    select_fields.append(f"pa.{field}")
+            if not select_fields:
+                select_fields = ["pa.*"]  # fallback
+            select_clause = ", ".join(select_fields)
+        else:
+            select_clause = "pa.*"
+            
+        sql = f"SELECT {select_clause} FROM trans.pos_appointment pa WHERE {' AND '.join(where)} ORDER BY pa.start_time DESC OFFSET :skip LIMIT :limit"
         rs = await session.execute(text(sql), params)
         items = [dict(r._mapping) for r in rs.fetchall()]
+        
+        # If projection_list is used, return raw dict without services
+        if projection_list:
+            # total
+            rsc = await session.execute(text(f"SELECT COUNT(*) FROM trans.pos_appointment pa WHERE {' AND '.join(where)}"), {k: v for k, v in params.items() if k not in ("skip", "limit")})
+            total = int(rsc.scalar() or 0)
+            return items, total
+        
+        # For full response, add services to each appointment
+        for item in items:
+            svc_rs = await session.execute(text("SELECT * FROM trans.pos_appointment_service WHERE appointment_id=:aid"), {"aid": item["appointment_id"]})
+            item["services"] = [dict(r._mapping) for r in svc_rs.fetchall()]
+        
         # total
         rsc = await session.execute(text(f"SELECT COUNT(*) FROM trans.pos_appointment pa WHERE {' AND '.join(where)}"), {k: v for k, v in params.items() if k not in ("skip", "limit")})
         total = int(rsc.scalar() or 0)

create_seed_data_simple.py

@@ -19,7 +19,8 @@ load_dotenv()
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
-MERCHANT_ID = "company_cuatro_beauty_ltd"
+# Use standard UUID for consistency across services
+MERCHANT_ID = "01234567-89ab-cdef-0123-456789abcdef"  # Cuatro Beauty Ltd UUID
 
 # MongoDB connection from .env
 MONGODB_URI = os.getenv("MONGODB_URI", "mongodb://localhost:27017")

scripts/seed_data.py

@@ -21,7 +21,8 @@ sys.path.insert(0, str(Path(__file__).parent.parent))
 from app.nosql import connect_to_mongo, close_mongo_connection, get_database
 from app.core.config import settings
 
-MERCHANT_ID = "11111111-1111-1111-1111-111111111111"
+# Use standard UUID for consistency across services  
+MERCHANT_ID = "01234567-89ab-cdef-0123-456789abcdef"  # Cuatro Beauty Ltd UUID
 
 # Sample Services
 SAMPLE_SERVICES = [