feat(logging): implement structured logging across services

Add centralized logging utility with structured logging format
Update all services to use new logger with contextual metadata
Enhance error handling with detailed error logging
Add global exception handlers with proper logging
Include operation context in all log entries

app/appointments/controllers/router.py

@@ -9,6 +9,7 @@ from datetime import datetime
 from fastapi import APIRouter, HTTPException, status, Depends
 from fastapi.responses import JSONResponse
 
+from app.core.logging import get_logger
 from app.dependencies.auth import TokenUser
 from app.dependencies.pos_permissions import require_pos_permission
 from app.appointments.schemas.schema import (
@@ -31,7 +32,7 @@ from app.appointments.services.service import (
     checkout_appointment,
 )
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 def convert_uuids_to_strings(data):
     """Convert UUID objects to strings for JSON serialization"""
@@ -78,10 +79,35 @@ async def create_appointment_endpoint(
             created_by=req.created_by,
         )
         appt = await get_appointment(aid)
+        
+        logger.info(
+            "Appointment created successfully",
+            extra={
+                "operation": "create_appointment",
+                "appointment_id": str(aid),
+                "merchant_id": str(merchant_id),
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
+        
         return await _to_appt_response(appt)
+    except HTTPException:
+        raise
     except Exception as e:
-        logger.error(f"Create appointment failed: {e}")
-        raise HTTPException(status_code=400, detail=str(e))
+        logger.error(
+            "Create appointment failed",
+            extra={
+                "operation": "create_appointment",
+                "error": str(e),
+                "error_type": type(e).__name__,
+                "merchant_id": str(merchant_id) if 'merchant_id' in locals() else None
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to create appointment"
+        )
 
 @router.post("/list", response_model=None)
 async def list_appointments_endpoint(
@@ -156,9 +182,40 @@ async def update_appointment_endpoint(
 ):
     try:
         appt = await update_appointment(appointment_id, req.start_time, [s.model_dump() for s in req.services], req.notes)
+        
+        logger.info(
+            "Appointment updated",
+            extra={
+                "operation": "update_appointment",
+                "appointment_id": str(appointment_id),
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
         return await _to_appt_response(appt)
+    except HTTPException:
+        raise
+    except ValueError as e:
+        logger.warning(
+            "Update appointment validation failed",
+            extra={
+                "operation": "update_appointment",
+                "appointment_id": str(appointment_id),
+                "error": str(e)
+            }
+        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
     except Exception as e:
-        raise HTTPException(status_code=400, detail=str(e))
+        logger.error(
+            "Update appointment failed",
+            extra={
+                "operation": "update_appointment",
+                "appointment_id": str(appointment_id),
+                "error": str(e),
+                "error_type": type(e).__name__
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to update appointment")
 
 @router.patch("/{appointment_id}/status", response_model=AppointmentResponse)
 async def update_status_endpoint(
@@ -168,9 +225,41 @@ async def update_status_endpoint(
 ):
     try:
         appt = await update_status(appointment_id, req.status)
+        
+        logger.info(
+            "Appointment status updated",
+            extra={
+                "operation": "update_status",
+                "appointment_id": str(appointment_id),
+                "status": req.status,
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
         return await _to_appt_response(appt)
+    except HTTPException:
+        raise
+    except ValueError as e:
+        logger.warning(
+            "Update status validation failed",
+            extra={
+                "operation": "update_status",
+                "appointment_id": str(appointment_id),
+                "error": str(e)
+            }
+        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
     except Exception as e:
-        raise HTTPException(status_code=400, detail=str(e))
+        logger.error(
+            "Update status failed",
+            extra={
+                "operation": "update_status",
+                "appointment_id": str(appointment_id),
+                "error": str(e),
+                "error_type": type(e).__name__
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to update status")
 
 @router.post("/{appointment_id}/cancel", response_model=AppointmentResponse)
 async def cancel_appointment_endpoint(
@@ -179,9 +268,40 @@ async def cancel_appointment_endpoint(
 ):
     try:
         appt = await cancel_appointment(appointment_id)
+        
+        logger.info(
+            "Appointment cancelled",
+            extra={
+                "operation": "cancel_appointment",
+                "appointment_id": str(appointment_id),
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
         return await _to_appt_response(appt)
+    except HTTPException:
+        raise
+    except ValueError as e:
+        logger.warning(
+            "Cancel appointment validation failed",
+            extra={
+                "operation": "cancel_appointment",
+                "appointment_id": str(appointment_id),
+                "error": str(e)
+            }
+        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
     except Exception as e:
-        raise HTTPException(status_code=400, detail=str(e))
+        logger.error(
+            "Cancel appointment failed",
+            extra={
+                "operation": "cancel_appointment",
+                "appointment_id": str(appointment_id),
+                "error": str(e),
+                "error_type": type(e).__name__
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to cancel appointment")
 
 @router.post("/{appointment_id}/checkout", response_model=CheckoutResponse)
 async def checkout_appointment_endpoint(
@@ -190,9 +310,41 @@ async def checkout_appointment_endpoint(
 ):
     try:
         sale_id, sale = await checkout_appointment(appointment_id)
+        
+        logger.info(
+            "Appointment checkout successful",
+            extra={
+                "operation": "checkout_appointment",
+                "appointment_id": str(appointment_id),
+                "sale_id": str(sale_id),
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
         return CheckoutResponse(appointment_id=appointment_id, sale_id=sale_id, status="billed")
+    except HTTPException:
+        raise
+    except ValueError as e:
+        logger.warning(
+            "Checkout validation failed",
+            extra={
+                "operation": "checkout_appointment",
+                "appointment_id": str(appointment_id),
+                "error": str(e)
+            }
+        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
     except Exception as e:
-        raise HTTPException(status_code=400, detail=str(e))
+        logger.error(
+            "Checkout failed",
+            extra={
+                "operation": "checkout_appointment",
+                "appointment_id": str(appointment_id),
+                "error": str(e),
+                "error_type": type(e).__name__
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to checkout appointment")
 
 async def _to_appt_response(appt: dict) -> AppointmentResponse:
     services = [AppointmentServiceResponse(

app/appointments/services/service.py

@@ -7,9 +7,10 @@ from typing import Optional, List, Tuple
 from datetime import timedelta
 from sqlalchemy import text
 
+from app.core.logging import get_logger
 from app.sql import get_postgres_session
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 def _service_details_from_input(s: dict) -> Tuple[str, int, float]:
     """Derive service details from input without Mongo.
@@ -104,11 +105,24 @@ async def create_appointment(
                     "price": e["service_price"],
                 })
             await session.commit()
-            logger.info(f"Created appointment {appointment_id} with {len(enriched)} services")
+            logger.info(
+                "Created appointment",
+                extra={
+                    "appointment_id": str(appointment_id),
+                    "service_count": len(enriched)
+                }
+            )
             return appointment_id
         except Exception as e:
             await session.rollback()
-            logger.error(f"Failed to create appointment: {e}")
+            logger.error(
+                "Failed to create appointment",
+                extra={
+                    "error": str(e),
+                    "error_type": type(e).__name__
+                },
+                exc_info=True
+            )
             raise
 
 async def get_appointment(appointment_id: UUID) -> Optional[dict]:
@@ -247,7 +261,15 @@ async def update_appointment(appointment_id: UUID, start_time, services: List[di
             await session.commit()
         except Exception as e:
             await session.rollback()
-            logger.error(f"Failed to update appointment: {e}")
+            logger.error(
+                "Failed to update appointment",
+                extra={
+                    "appointment_id": str(appointment_id),
+                    "error": str(e),
+                    "error_type": type(e).__name__
+                },
+                exc_info=True
+            )
             raise
     appt = await get_appointment(appointment_id)
     return appt
@@ -271,7 +293,16 @@ async def update_status(appointment_id: UUID, status: str) -> dict:
             await session.commit()
         except Exception as e:
             await session.rollback()
-            logger.error(f"Failed to update status: {e}")
+            logger.error(
+                "Failed to update status",
+                extra={
+                    "appointment_id": str(appointment_id),
+                    "status": status,
+                    "error": str(e),
+                    "error_type": type(e).__name__
+                },
+                exc_info=True
+            )
             raise
     return await get_appointment(appointment_id)
 

app/catalogue_services/controllers/router.py

@@ -5,6 +5,7 @@ import logging
 from typing import Optional
 from fastapi import APIRouter, HTTPException, Query, status, Depends
 
+from app.core.logging import get_logger
 from app.dependencies.auth import TokenUser
 from app.dependencies.pos_permissions import require_pos_permission
 from app.catalogue_services.schemas.schema import (
@@ -24,7 +25,7 @@ from app.catalogue_services.services.service import (
     delete_service,
 )
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 router = APIRouter(
     prefix="/pos/catalogue/services",
@@ -56,10 +57,42 @@ async def create_service_endpoint(
             price=req.price,
             gst_rate=req.gst_rate,
         )
+        
+        logger.info(
+            "Service created successfully",
+            extra={
+                "operation": "create_service",
+                "service_id": str(doc["_id"]),
+                "merchant_id": str(merchant_id),
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
+        
         return _to_response(doc)
+    except HTTPException:
+        raise
+    except ValueError as e:
+        logger.warning(
+             "Create service validation failed",
+             extra={
+                 "operation": "create_service",
+                 "error": str(e),
+                 "merchant_id": str(merchant_id) if 'merchant_id' in locals() else None
+             }
+        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
     except Exception as e:
-        logger.error(f"Create service failed: {e}")
-        raise HTTPException(status_code=400, detail=str(e))
+        logger.error(
+            "Create service failed",
+            extra={
+                "operation": "create_service",
+                "error": str(e),
+                "error_type": type(e).__name__,
+                "merchant_id": str(merchant_id) if 'merchant_id' in locals() else None
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to create service")
 
 @router.post("/list", response_model=ListServicesResponse)
 async def list_services_endpoint(
@@ -84,23 +117,59 @@ async def list_services_endpoint(
             projection_list=req.projection_list
         )
         
+        logger.info(
+            "Services listed",
+            extra={
+                "operation": "list_services",
+                "count": total,
+                "merchant_id": str(merchant_id),
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
+        
         return ListServicesResponse(
             items=items,  # Service layer returns raw dicts
             total=total
         )
+    except HTTPException:
+        raise
     except Exception as e:
-        logger.error(f"List services failed: {e}")
-        raise HTTPException(status_code=400, detail=str(e))
+        logger.error(
+            "List services failed",
+            extra={
+                "operation": "list_services",
+                "error": str(e),
+                "error_type": type(e).__name__,
+                "merchant_id": str(merchant_id) if 'merchant_id' in locals() else None
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to list services")
 
 @router.get("/{service_id}", response_model=ServiceResponse)
 async def get_service_endpoint(
     service_id: str,  # Changed from UUID to str
     current_user: TokenUser = Depends(require_pos_permission("retail_catalogue", "view"))
 ):
-    doc = await get_service(service_id)
-    if not doc:
-        raise HTTPException(status_code=404, detail="Service not found")
-    return _to_response(doc)
+    try:
+        doc = await get_service(service_id)
+        if not doc:
+            raise HTTPException(status_code=404, detail="Service not found")
+        return _to_response(doc)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Get service failed",
+            extra={
+                "operation": "get_service",
+                "service_id": service_id,
+                "error": str(e),
+                "error_type": type(e).__name__
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to get service")
 
 @router.put("/{service_id}", response_model=ServiceResponse)
 async def update_service_endpoint(
@@ -120,9 +189,40 @@ async def update_service_endpoint(
             price=req.price,
             gst_rate=req.gst_rate,
         )
+        
+        logger.info(
+            "Service updated",
+            extra={
+                "operation": "update_service",
+                "service_id": service_id,
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
         return _to_response(doc)
+    except HTTPException:
+        raise
+    except ValueError as e:
+        logger.warning(
+            "Update service validation failed",
+            extra={
+                "operation": "update_service",
+                "service_id": service_id,
+                "error": str(e)
+            }
+        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
     except Exception as e:
-        raise HTTPException(status_code=400, detail=str(e))
+        logger.error(
+            "Update service failed",
+            extra={
+                "operation": "update_service",
+                "service_id": service_id,
+                "error": str(e),
+                "error_type": type(e).__name__
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to update service")
 
 @router.patch("/{service_id}/status", response_model=ServiceResponse)
 async def update_status_endpoint(
@@ -132,9 +232,41 @@ async def update_status_endpoint(
 ):
     try:
         doc = await update_status(service_id, req.status)
+        
+        logger.info(
+            "Service status updated",
+            extra={
+                "operation": "update_status",
+                "service_id": service_id,
+                "status": req.status,
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
         return _to_response(doc)
+    except HTTPException:
+        raise
+    except ValueError as e:
+        logger.warning(
+            "Update status validation failed",
+            extra={
+                "operation": "update_status",
+                "service_id": service_id,
+                "error": str(e)
+            }
+        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
     except Exception as e:
-        raise HTTPException(status_code=400, detail=str(e))
+        logger.error(
+            "Update status failed",
+            extra={
+                "operation": "update_status",
+                "service_id": service_id,
+                "error": str(e),
+                "error_type": type(e).__name__
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to update status")
 
 @router.delete("/{service_id}", response_model=ServiceResponse)
 async def delete_service_endpoint(
@@ -143,9 +275,40 @@ async def delete_service_endpoint(
 ):
     try:
         doc = await delete_service(service_id)
+        
+        logger.info(
+            "Service deleted",
+            extra={
+                "operation": "delete_service",
+                "service_id": service_id,
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
         return _to_response(doc)
+    except HTTPException:
+        raise
+    except ValueError as e:
+        logger.warning(
+            "Delete service validation failed",
+            extra={
+                "operation": "delete_service",
+                "service_id": service_id,
+                "error": str(e)
+            }
+        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
     except Exception as e:
-        raise HTTPException(status_code=400, detail=str(e))
+        logger.error(
+            "Delete service failed",
+            extra={
+                "operation": "delete_service",
+                "service_id": service_id,
+                "error": str(e),
+                "error_type": type(e).__name__
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to delete service")
 
 def _to_response(doc: dict) -> ServiceResponse:
     return ServiceResponse(

app/catalogue_services/services/service.py

@@ -7,10 +7,11 @@ from typing import Optional, List, Tuple
 from datetime import datetime
 from sqlalchemy import text
 
+from app.core.logging import get_logger
 from app.nosql import get_database
 from app.sql import get_postgres_session
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 CATALOGUE_SERVICES_COLLECTION = "pos_catalogue_services"
 
@@ -52,9 +53,25 @@ async def _sync_to_postgres(service_doc: dict):
                 "status": service_doc.get("status", "active"),
             })
             await session.commit()
-            logger.info(f"Synced service {service_doc['_id']} to Postgres")
+            logger.info(
+                f"Synced service {service_doc['_id']} to Postgres",
+                extra={
+                    "operation": "sync_to_postgres",
+                    "service_id": service_doc["_id"],
+                    "merchant_id": service_doc["merchant_id"]
+                }
+            )
         except Exception as e:
-            logger.error(f"Failed to sync service to Postgres: {e}")
+            logger.error(
+                f"Failed to sync service to Postgres: {e}",
+                extra={
+                    "operation": "sync_to_postgres",
+                    "service_id": service_doc["_id"],
+                    "merchant_id": service_doc["merchant_id"],
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             await session.rollback()
 
 async def create_service(
@@ -104,7 +121,14 @@ async def create_service(
     }
     
     await db[CATALOGUE_SERVICES_COLLECTION].insert_one(doc)
-    logger.info(f"Created service {service_id} in MongoDB")
+    logger.info(
+        f"Created service {service_id} in MongoDB",
+        extra={
+            "operation": "create_service_mongo",
+            "service_id": service_id,
+            "merchant_id": str(merchant_id)
+        }
+    )
     
     # Sync to Postgres
     await _sync_to_postgres(doc)
@@ -266,7 +290,13 @@ async def update_service(
     
     # Get updated doc
     updated = await db[CATALOGUE_SERVICES_COLLECTION].find_one({"_id": service_id})
-    logger.info(f"Updated service {service_id} in MongoDB")
+    logger.info(
+        f"Updated service {service_id} in MongoDB",
+        extra={
+            "operation": "update_service_mongo",
+            "service_id": service_id
+        }
+    )
     
     # Sync to Postgres
     await _sync_to_postgres(updated)
@@ -289,7 +319,14 @@ async def update_status(service_id: str, status: str) -> dict:  # Changed from U
     )
     
     updated = await db[CATALOGUE_SERVICES_COLLECTION].find_one({"_id": service_id})
-    logger.info(f"Updated service {service_id} status to {status}")
+    logger.info(
+        f"Updated service {service_id} status to {status}",
+        extra={
+            "operation": "update_status_mongo",
+            "service_id": service_id,
+            "status": status
+        }
+    )
     
     # Sync to Postgres
     await _sync_to_postgres(updated)

app/core/logging.py

@@ -0,0 +1,13 @@
+import logging
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger instance with the specified name.
+    
+    Args:
+        name: The name of the logger, typically __name__
+        
+    Returns:
+        logging.Logger: The configured logger instance
+    """
+    return logging.getLogger(name)

app/customers/controllers/router.py

@@ -4,6 +4,7 @@ Customer API router for POS microservice.
 from typing import Optional
 from fastapi import APIRouter, HTTPException, Query, status, Depends
 
+from app.core.logging import get_logger
 from app.dependencies.auth import TokenUser
 from app.dependencies.pos_permissions import require_pos_permission
 from app.customers.schemas.schema import (
@@ -15,6 +16,8 @@ from app.customers.schemas.schema import (
 )
 from app.customers.services.service import CustomerService
 
+logger = get_logger(__name__)
+
 router = APIRouter(
     prefix="/customers",
     tags=["Customers"],
@@ -33,10 +36,46 @@ async def create_customer(
     **Note:** merchant_id from request payload is ignored. The merchant_id from the authentication token is used instead.
     This ensures proper merchant isolation and UUID format consistency.
     """
-    if not current_user.merchant_id:
-        raise HTTPException(status_code=400, detail="merchant_id must be available in token")
-    
-    return await CustomerService.create_customer(payload, current_user.merchant_id)
+    try:
+        if not current_user.merchant_id:
+            raise HTTPException(status_code=400, detail="merchant_id must be available in token")
+        
+        customer = await CustomerService.create_customer(payload, current_user.merchant_id)
+        
+        logger.info(
+            "Customer created successfully",
+            extra={
+                "operation": "create_customer",
+                "customer_id": customer.customer_id,
+                "merchant_id": str(current_user.merchant_id),
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
+        return customer
+    except HTTPException:
+        raise
+    except ValueError as e:
+        logger.warning(
+            "Create customer validation failed",
+            extra={
+                "operation": "create_customer",
+                "error": str(e),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            }
+        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+    except Exception as e:
+        logger.error(
+            "Create customer failed",
+            extra={
+                "operation": "create_customer",
+                "error": str(e),
+                "error_type": type(e).__name__,
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to create customer")
 
 
 @router.get("/{customer_id}", response_model=CustomerResponse, summary="Get customer by ID")
@@ -44,14 +83,29 @@ async def get_customer(
     customer_id: str,
     current_user: TokenUser = Depends(require_pos_permission("customers", "view"))
 ) -> CustomerResponse:
-    customer = await CustomerService.get_customer(
-        customer_id=customer_id,
-        merchant_id=current_user.merchant_id,
-        merchant_type=current_user.merchant_type
-    )
-    if not customer:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Customer not found")
-    return customer
+    try:
+        customer = await CustomerService.get_customer(
+            customer_id=customer_id,
+            merchant_id=current_user.merchant_id,
+            merchant_type=current_user.merchant_type
+        )
+        if not customer:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Customer not found")
+        return customer
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Get customer failed",
+            extra={
+                "operation": "get_customer",
+                "customer_id": customer_id,
+                "error": str(e),
+                "error_type": type(e).__name__
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to get customer")
 
 
 @router.post("/list", response_model=None, summary="List customers")
@@ -78,40 +132,65 @@ async def list_customers(
     - skip: Records to skip (default: 0)
     - limit: Max records to return (default: 50, max: 500)
     """
-    # Extract filters and parameters from payload
-    filters = payload.filters or {}
-    skip = payload.skip or 0
-    limit = payload.limit or 50
-    projection_list = payload.projection_list
-    
-    # Always use merchant_id from token
-    if not current_user.merchant_id:
-        raise HTTPException(status_code=400, detail="merchant_id must be available in token")
-    
-    customers, total = await CustomerService.list_customers(
-        merchant_id=current_user.merchant_id,
-        merchant_type=current_user.merchant_type,
-        filters=filters,
-        skip=skip,
-        limit=limit,
-        projection_list=projection_list
-    )
-    
-    # Return raw dict if projection used, model otherwise
-    if projection_list:
-        return CustomerListResponse(
-            customers=customers,  # Raw dicts when projection is used
-            total=total,
+    try:
+        # Extract filters and parameters from payload
+        filters = payload.filters or {}
+        skip = payload.skip or 0
+        limit = payload.limit or 50
+        projection_list = payload.projection_list
+        
+        # Always use merchant_id from token
+        if not current_user.merchant_id:
+            raise HTTPException(status_code=400, detail="merchant_id must be available in token")
+        
+        customers, total = await CustomerService.list_customers(
+            merchant_id=current_user.merchant_id,
+            merchant_type=current_user.merchant_type,
+            filters=filters,
             skip=skip,
-            limit=limit
+            limit=limit,
+            projection_list=projection_list
         )
-    else:
-        return CustomerListResponse(
-            customers=customers,  # CustomerResponse objects when no projection
-            total=total,
-            skip=skip,
-            limit=limit
+        
+        logger.info(
+            "Customers listed",
+            extra={
+                "operation": "list_customers",
+                "count": total,
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None,
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
+        
+        # Return raw dict if projection used, model otherwise
+        if projection_list:
+            return CustomerListResponse(
+                customers=customers,  # Raw dicts when projection is used
+                total=total,
+                skip=skip,
+                limit=limit
+            )
+        else:
+            return CustomerListResponse(
+                customers=customers,  # CustomerResponse objects when no projection
+                total=total,
+                skip=skip,
+                limit=limit
+            )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "List customers failed",
+            extra={
+                "operation": "list_customers",
+                "error": str(e),
+                "error_type": type(e).__name__,
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            },
+            exc_info=True
         )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to list customers")
 
 
 @router.put("/{customer_id}", response_model=CustomerResponse, summary="Update customer")
@@ -120,12 +199,47 @@ async def update_customer(
     payload: CustomerUpdate,
     current_user: TokenUser = Depends(require_pos_permission("customers", "update"))
 ) -> CustomerResponse:
-    return await CustomerService.update_customer(
-        customer_id=customer_id,
-        payload=payload,
-        merchant_id=current_user.merchant_id,
-        merchant_type=current_user.merchant_type
-    )
+    try:
+        customer = await CustomerService.update_customer(
+            customer_id=customer_id,
+            payload=payload,
+            merchant_id=current_user.merchant_id,
+            merchant_type=current_user.merchant_type
+        )
+        
+        logger.info(
+            "Customer updated",
+            extra={
+                "operation": "update_customer",
+                "customer_id": customer_id,
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
+        return customer
+    except HTTPException:
+        raise
+    except ValueError as e:
+        logger.warning(
+            "Update customer validation failed",
+            extra={
+                "operation": "update_customer",
+                "customer_id": customer_id,
+                "error": str(e)
+            }
+        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+    except Exception as e:
+        logger.error(
+            "Update customer failed",
+            extra={
+                "operation": "update_customer",
+                "customer_id": customer_id,
+                "error": str(e),
+                "error_type": type(e).__name__
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to update customer")
 
 
 @router.delete("/{customer_id}", status_code=status.HTTP_204_NO_CONTENT, summary="Delete customer (soft)")
@@ -133,9 +247,33 @@ async def delete_customer(
     customer_id: str,
     current_user: TokenUser = Depends(require_pos_permission("customers", "delete"))
 ):
-    await CustomerService.delete_customer(
-        customer_id=customer_id,
-        merchant_id=current_user.merchant_id,
-        merchant_type=current_user.merchant_type
-    )
-    return None
+    try:
+        await CustomerService.delete_customer(
+            customer_id=customer_id,
+            merchant_id=current_user.merchant_id,
+            merchant_type=current_user.merchant_type
+        )
+        
+        logger.info(
+            "Customer deleted",
+            extra={
+                "operation": "delete_customer",
+                "customer_id": customer_id,
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
+        return None
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Delete customer failed",
+            extra={
+                "operation": "delete_customer",
+                "customer_id": customer_id,
+                "error": str(e),
+                "error_type": type(e).__name__
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to delete customer")

app/customers/services/service.py

@@ -8,6 +8,7 @@ from typing import Optional, List, Tuple
 from fastapi import HTTPException, status
 from sqlalchemy import text
 
+from app.core.logging import get_logger
 from app.nosql import get_database
 from app.constants.collections import POS_CUSTOMERS_COLLECTION
 from app.sql import get_postgres_session
@@ -19,7 +20,7 @@ from app.customers.schemas.schema import (
     CustomerListResponse,
 )
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class CustomerService:
@@ -38,7 +39,13 @@ class CustomerService:
         """Upsert customer into trans.pos_customer_ref using token merchant_id for UUID compatibility."""
         async with get_postgres_session() as session:
             if session is None:
-                logger.warning("PostgreSQL session unavailable; skipping customer sync")
+                logger.warning(
+                    "PostgreSQL session unavailable; skipping customer sync",
+                    extra={
+                        "operation": "sync_to_postgres",
+                        "customer_id": customer.customer_id
+                    }
+                )
                 return
 
             # Use token merchant_id if provided (UUID format), otherwise use customer merchant_id
@@ -73,7 +80,15 @@ class CustomerService:
                 "updated_at": customer.updated_at,
             })
             await session.commit()
-            logger.info("Synced customer %s to Postgres with merchant_id %s", customer.customer_id, sync_merchant_id)
+            
+            logger.info(
+                f"Synced customer {customer.customer_id} to Postgres",
+                extra={
+                    "operation": "sync_to_postgres",
+                    "customer_id": customer.customer_id,
+                    "merchant_id": sync_merchant_id
+                }
+            )
 
     @classmethod
     async def create_customer(cls, payload: CustomerCreate, token_merchant_id: Optional[str] = None) -> CustomerResponse:
@@ -95,7 +110,16 @@ class CustomerService:
         try:
             await cls._sync_to_postgres(customer, token_merchant_id)
         except Exception as e:
-            logger.error("Postgres sync failed for customer %s: %s", customer_id, e)
+            logger.error(
+                f"Postgres sync failed for customer {customer_id}",
+                extra={
+                    "operation": "create_customer_sync",
+                    "customer_id": customer_id,
+                    "error": str(e),
+                    "merchant_id": token_merchant_id
+                },
+                exc_info=True
+            )
 
         return customer
 
@@ -203,7 +227,16 @@ class CustomerService:
         try:
             await cls._sync_to_postgres(customer, merchant_id)
         except Exception as e:
-            logger.error("Postgres sync failed for customer %s: %s", customer_id, e)
+            logger.error(
+                f"Postgres sync failed for customer {customer_id}",
+                extra={
+                    "operation": "update_customer_sync",
+                    "customer_id": customer_id,
+                    "error": str(e),
+                    "merchant_id": merchant_id
+                },
+                exc_info=True
+            )
 
         return customer
 
@@ -237,6 +270,15 @@ class CustomerService:
         try:
             await cls._sync_to_postgres(customer, merchant_id)
         except Exception as e:
-            logger.error("Postgres sync failed for customer %s: %s", customer_id, e)
+            logger.error(
+                f"Postgres sync failed for customer {customer_id}",
+                extra={
+                    "operation": "delete_customer_sync",
+                    "customer_id": customer_id,
+                    "error": str(e),
+                    "merchant_id": merchant_id
+                },
+                exc_info=True
+            )
 
         return None

app/main.py

@@ -7,10 +7,11 @@ from fastapi.exceptions import RequestValidationError
 from starlette.exceptions import HTTPException as StarletteHTTPException
 from fastapi.responses import JSONResponse
 from fastapi.middleware.cors import CORSMiddleware
-import logging  # TODO: Uncomment when package is available
-from pymongo.errors import PyMongoError, ConnectionFailure
+from pymongo.errors import PyMongoError, ConnectionFailure, OperationFailure
+from jose import JWTError
 
 from app.core.config import settings
+from app.core.logging import get_logger
 from app.utils.response import error_response
 from app.middleware.logging_middleware import RequestLoggingMiddleware
 
@@ -22,8 +23,7 @@ from app.customers.controllers.router import router as customers_router
 from app.sales.retail.controllers.router import router as sales_router
 from app.appointments.controllers.router import router as appointments_router
 
-# # logger = get_logger(__name__)  # TODO: Uncomment when insightfy_utils is available
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 logging.basicConfig(level=logging.INFO)
 
 # Create FastAPI app
@@ -52,16 +52,25 @@ app.add_middleware(
 @app.exception_handler(RequestValidationError)
 async def validation_exception_handler(request: Request, exc: RequestValidationError):
     """Handle validation errors"""
-    errors = []
-    for e in exc.errors():
-        # Get field name from loc (last element), default to "body" or "unknown"
-        field = str(e["loc"][-1]) if e["loc"] else "unknown"
-        errors.append({
-            "field": field,
-            "message": e["msg"],
-            "type": e["type"]
-        })
-        
+    errors = [
+        {
+            "field": " -> ".join(str(loc) for loc in error["loc"]),
+            "message": error["msg"],
+            "type": error["type"]
+        }
+        for error in exc.errors()
+    ]
+    
+    logger.warning(
+        "Validation error",
+        extra={
+            "path": request.url.path,
+            "method": request.method,
+            "error_count": len(errors),
+            "errors": errors
+        }
+    )
+    
     return JSONResponse(
         status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
         content=error_response(
@@ -73,6 +82,28 @@ async def validation_exception_handler(request: Request, exc: RequestValidationE
     )
 
 
+@app.exception_handler(JWTError)
+async def jwt_exception_handler(request: Request, exc: JWTError):
+    """Handle JWT errors"""
+    logger.warning(
+        "JWT authentication failed",
+        extra={
+            "path": request.url.path,
+            "error": str(exc),
+            "client_ip": request.client.host if request.client else None
+        }
+    )
+    
+    return JSONResponse(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        content=error_response(
+            error="Unauthorized",
+            detail="Invalid or expired token",
+            request_id=getattr(request.state, "request_id", None)
+        )
+    )
+
+
 @app.exception_handler(status.HTTP_404_NOT_FOUND)
 async def not_found_exception_handler(request: Request, exc: Exception):
     """Handle 404 errors"""
@@ -113,43 +144,56 @@ async def http_exception_handler(request: Request, exc: StarletteHTTPException):
     )
 
 
-@app.exception_handler(ConnectionFailure)
-async def mongo_connection_exception_handler(request: Request, exc: ConnectionFailure):
-    """Handle MongoDB connection errors"""
-    logger.error(f"Database connection error: {exc}", exc_info=True)
-    return JSONResponse(
-        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-        content=error_response(
-            error="Database Connection Error",
-            detail="Unable to connect to the database. Please try again later.",
-            request_id=getattr(request.state, "request_id", None)
-        )
-    )
-
-
 @app.exception_handler(PyMongoError)
-async def mongo_exception_handler(request: Request, exc: PyMongoError):
-    """Handle general MongoDB errors"""
-    logger.error(f"Database error: {exc}", exc_info=True)
+async def mongodb_exception_handler(request: Request, exc: PyMongoError):
+    """Handle MongoDB errors"""
+    logger.error(
+        "Database error",
+        extra={
+            "path": request.url.path,
+            "error": str(exc),
+            "error_type": type(exc).__name__
+        },
+        exc_info=True
+    )
+    
+    if isinstance(exc, ConnectionFailure):
+        status_code = status.HTTP_503_SERVICE_UNAVAILABLE
+        detail = "Database connection failed"
+    elif isinstance(exc, OperationFailure):
+        status_code = status.HTTP_500_INTERNAL_SERVER_ERROR
+        detail = "Database operation failed"
+    else:
+        status_code = status.HTTP_500_INTERNAL_SERVER_ERROR
+        detail = "Database error occurred"
+    
     return JSONResponse(
-        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        status_code=status_code,
         content=error_response(
             error="Database Error",
-            detail="An unexpected database error occurred.",
+            detail=detail,
             request_id=getattr(request.state, "request_id", None)
         )
     )
 
 
-# Handle generic HTTPException (catch-all for other HTTP exceptions)
 @app.exception_handler(Exception)
-async def generic_exception_handler(request: Request, exc: Exception):
+async def general_exception_handler(request: Request, exc: Exception):
     """
     Handle all unhandled exceptions.
-    
-    In production, we should not expose internal error details.
     """
-    logger.error(f"Unhandled exception: {exc}", exc_info=True)
+    logger.error(
+        "Unhandled exception",
+        extra={
+            "method": request.method,
+            "path": request.url.path,
+            "error": str(exc),
+            "error_type": type(exc).__name__,
+            "client_ip": request.client.host if request.client else None
+        },
+        exc_info=True
+    )
+    
     return JSONResponse(
         status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
         content=error_response(

app/sales/orders/controllers/router.py

@@ -3,8 +3,7 @@ Sales Order API router - FastAPI endpoints for sales order operations.
 """
 from typing import Optional
 from fastapi import APIRouter, HTTPException, Query, Header, status, Depends
-# from insightfy_utils.logging import get_logger  # TODO: Uncomment when package is available
-import logging
+from app.core.logging import get_logger
 
 from app.dependencies.auth import TokenUser
 from app.dependencies.pos_permissions import require_pos_permission
@@ -20,8 +19,7 @@ from app.sales.orders.schemas.schema import (
 from app.sales.orders.services.service import SalesOrderService
 from app.utils.response import success_response, paginated_response
 
-# logger = get_logger(__name__)  # TODO: Uncomment when insightfy_utils is available
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 router = APIRouter(
     prefix="/sales",
@@ -64,14 +62,32 @@ async def list_sales_orders(
     - field: Field to sort by (default: order_date)
     - order: Sort order (asc/desc, default: desc)
     """
-    result = await SalesOrderService.list_sales_orders(request)
-    return paginated_response(
-        documents=[doc.dict() if hasattr(doc, 'dict') else doc for doc in result["documents"]],
-        total=result["total"],
-        page=result["page"],
-        limit=result["limit"],
-        correlation_id=x_correlation_id
-    )
+    try:
+        result = await SalesOrderService.list_sales_orders(request)
+        return paginated_response(
+            documents=[doc.dict() if hasattr(doc, 'dict') else doc for doc in result["documents"]],
+            total=result["total"],
+            page=result["page"],
+            limit=result["limit"],
+            correlation_id=x_correlation_id
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Error listing sales orders",
+            extra={
+                "operation": "list_sales_orders",
+                "merchant_id": x_merchant_id,
+                "error": str(e),
+                "filters": str(request.filters) if request.filters else None
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Error listing sales orders"
+        )
 
 
 @router.get(
@@ -96,7 +112,25 @@ async def get_sales_order(
     - Shipment information
     - Invoice details (if generated)
     """
-    return await SalesOrderService.get_sales_order(sales_order_id)
+    try:
+        return await SalesOrderService.get_sales_order(sales_order_id)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            f"Error retrieving sales order {sales_order_id}",
+            extra={
+                "operation": "get_sales_order",
+                "sales_order_id": sales_order_id,
+                "merchant_id": x_merchant_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Error retrieving sales order"
+        )
 
 
 @router.post(
@@ -141,16 +175,45 @@ async def create_sales_order(
     - credit/cod → unpaid (amount_paid = 0)
     - partial → partial (custom amount_paid)
     """
-    sales_order = await SalesOrderService.create_sales_order(payload, x_merchant_id)
-    return success_response(
-        data={
-            "sales_order_id": sales_order.sales_order_id,
-            "order_number": sales_order.order_number,
-            "summary": sales_order.summary.dict()
-        },
-        message="Sales order created successfully",
-        correlation_id=x_correlation_id
-    )
+    try:
+        sales_order = await SalesOrderService.create_sales_order(payload, x_merchant_id)
+        
+        logger.info(
+            "Sales order created",
+            extra={
+                "operation": "create_sales_order",
+                "sales_order_id": sales_order.sales_order_id,
+                "merchant_id": x_merchant_id,
+                "user_id": payload.created_by
+            }
+        )
+        
+        return success_response(
+            data={
+                "sales_order_id": sales_order.sales_order_id,
+                "order_number": sales_order.order_number,
+                "summary": sales_order.summary.dict()
+            },
+            message="Sales order created successfully",
+            correlation_id=x_correlation_id
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Error creating sales order",
+            extra={
+                "operation": "create_sales_order",
+                "merchant_id": x_merchant_id,
+                "user_id": payload.created_by,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Error creating sales order"
+        )
 
 
 @router.put(
@@ -181,20 +244,50 @@ async def update_sales_order(
     - internal_notes: Internal notes
     - status: Order status
     """
-    sales_order = await SalesOrderService.update_sales_order(
-        sales_order_id,
-        payload,
-        x_user_id
-    )
-    return success_response(
-        data={
-            "sales_order_id": sales_order.sales_order_id,
-            "order_number": sales_order.order_number,
-            "summary": sales_order.summary.dict()
-        },
-        message="Sales order updated successfully",
-        correlation_id=x_correlation_id
-    )
+    try:
+        sales_order = await SalesOrderService.update_sales_order(
+            sales_order_id,
+            payload,
+            x_user_id
+        )
+        
+        logger.info(
+            f"Sales order {sales_order_id} updated",
+            extra={
+                "operation": "update_sales_order",
+                "sales_order_id": sales_order_id,
+                "merchant_id": x_merchant_id,
+                "user_id": x_user_id
+            }
+        )
+        
+        return success_response(
+            data={
+                "sales_order_id": sales_order.sales_order_id,
+                "order_number": sales_order.order_number,
+                "summary": sales_order.summary.dict()
+            },
+            message="Sales order updated successfully",
+            correlation_id=x_correlation_id
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            f"Error updating sales order {sales_order_id}",
+            extra={
+                "operation": "update_sales_order",
+                "sales_order_id": sales_order_id,
+                "merchant_id": x_merchant_id,
+                "user_id": x_user_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Error updating sales order"
+        )
 
 
 @router.post(
@@ -223,12 +316,41 @@ async def generate_invoice(
     - Invoice not already generated
     - Order must be in confirmed or processing status (not enforced)
     """
-    invoice = await SalesOrderService.generate_invoice(sales_order_id, request)
-    return success_response(
-        data=invoice.dict(),
-        message="Invoice generated successfully",
-        correlation_id=x_correlation_id
-    )
+    try:
+        invoice = await SalesOrderService.generate_invoice(sales_order_id, request)
+        
+        logger.info(
+            f"Invoice generated for sales order {sales_order_id}",
+            extra={
+                "operation": "generate_invoice",
+                "sales_order_id": sales_order_id,
+                "invoice_id": invoice.invoice_id,
+                "merchant_id": x_merchant_id
+            }
+        )
+        
+        return success_response(
+            data=invoice.dict(),
+            message="Invoice generated successfully",
+            correlation_id=x_correlation_id
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            f"Error generating invoice for sales order {sales_order_id}",
+            extra={
+                "operation": "generate_invoice",
+                "sales_order_id": sales_order_id,
+                "merchant_id": x_merchant_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Error generating invoice"
+        )
 
 
 @router.get(
@@ -252,4 +374,21 @@ async def get_sales_widgets(
     
     All metrics are scoped to the merchant.
     """
-    return await SalesOrderService.get_sales_widgets(x_merchant_id)
+    try:
+        return await SalesOrderService.get_sales_widgets(x_merchant_id)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Error retrieving sales widgets",
+            extra={
+                "operation": "get_sales_widgets",
+                "merchant_id": x_merchant_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Error retrieving sales widgets"
+        )

app/sales/orders/services/service.py

@@ -5,8 +5,7 @@ from datetime import datetime
 from typing import Optional, List, Dict, Any
 from decimal import Decimal
 from fastapi import HTTPException, status
-# from insightfy_utils.logging import get_logger  # TODO: Uncomment when package is available
-import logging
+from app.core.logging import get_logger
 import secrets
 
 from app.nosql import get_database
@@ -30,8 +29,7 @@ from app.sales.orders.schemas.schema import (
     FulfillmentStatus
 )
 
-# logger = get_logger(__name__)  # TODO: Uncomment when insightfy_utils is available
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 def generate_sales_order_id() -> str:
@@ -245,6 +243,7 @@ class SalesOrderService:
             logger.info(
                 f"Created sales order {sales_order_id}",
                 extra={
+                    "operation": "create_sales_order",
                     "sales_order_id": sales_order_id,
                     "order_number": order_number,
                     "merchant_id": merchant_id,
@@ -255,7 +254,15 @@ class SalesOrderService:
             return SalesOrderResponse(**sales_order)
             
         except Exception as e:
-            logger.error(f"Error creating sales order", exc_info=e)
+            logger.error(
+                "Error creating sales order",
+                extra={
+                    "operation": "create_sales_order",
+                    "error": str(e),
+                    "merchant_id": merchant_id
+                },
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail=f"Error creating sales order: {str(e)}"
@@ -264,17 +271,34 @@ class SalesOrderService:
     @staticmethod
     async def get_sales_order(sales_order_id: str) -> SalesOrderResponse:
         """Get sales order by ID."""
-        sales_order = await get_database()[SCM_SALES_ORDERS_COLLECTION].find_one(
-            {"sales_order_id": sales_order_id}
-        )
-        
-        if not sales_order:
+        try:
+            sales_order = await get_database()[SCM_SALES_ORDERS_COLLECTION].find_one(
+                {"sales_order_id": sales_order_id}
+            )
+            
+            if not sales_order:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail=f"Sales order {sales_order_id} not found"
+                )
+            
+            return SalesOrderResponse(**sales_order)
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(
+                f"Error getting sales order {sales_order_id}",
+                extra={
+                    "operation": "get_sales_order",
+                    "sales_order_id": sales_order_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"Sales order {sales_order_id} not found"
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Error getting sales order: {str(e)}"
             )
-        
-        return SalesOrderResponse(**sales_order)
 
     @staticmethod
     async def list_sales_orders(request: SalesOrderListRequest) -> Dict[str, Any]:
@@ -344,7 +368,15 @@ class SalesOrderService:
                 }
             
         except Exception as e:
-            logger.error("Error listing sales orders", exc_info=e)
+            logger.error(
+                "Error listing sales orders",
+                extra={
+                    "operation": "list_sales_orders",
+                    "error": str(e),
+                    "filters": str(request.filters) if request.filters else None
+                },
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail="Error listing sales orders"
@@ -405,6 +437,7 @@ class SalesOrderService:
             logger.info(
                 f"Updated sales order {sales_order_id}",
                 extra={
+                    "operation": "update_sales_order",
                     "sales_order_id": sales_order_id,
                     "updated_by": updated_by
                 }
@@ -415,7 +448,16 @@ class SalesOrderService:
         except HTTPException:
             raise
         except Exception as e:
-            logger.error(f"Error updating sales order {sales_order_id}", exc_info=e)
+            logger.error(
+                f"Error updating sales order {sales_order_id}",
+                extra={
+                    "operation": "update_sales_order",
+                    "sales_order_id": sales_order_id,
+                    "error": str(e),
+                    "updated_by": updated_by
+                },
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail=f"Error updating sales order: {str(e)}"
@@ -464,6 +506,7 @@ class SalesOrderService:
             logger.info(
                 f"Generated invoice for sales order {sales_order_id}",
                 extra={
+                    "operation": "generate_invoice",
                     "sales_order_id": sales_order_id,
                     "invoice_id": invoice_id,
                     "invoice_number": invoice_number
@@ -478,7 +521,15 @@ class SalesOrderService:
             )
             
         except Exception as e:
-            logger.error(f"Error generating invoice", exc_info=e)
+            logger.error(
+                "Error generating invoice",
+                extra={
+                    "operation": "generate_invoice",
+                    "sales_order_id": sales_order_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail="Error generating invoice"
@@ -529,7 +580,15 @@ class SalesOrderService:
             )
             
         except Exception as e:
-            logger.error("Error getting sales widgets", exc_info=e)
+            logger.error(
+                "Error getting sales widgets",
+                extra={
+                    "operation": "get_sales_widgets",
+                    "error": str(e),
+                    "merchant_id": merchant_id
+                },
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail="Error fetching sales widgets"

app/sales/retail/controllers/router.py

@@ -1,7 +1,7 @@
 """
 Retail Sales API router.
 """
-import logging
+from app.core.logging import get_logger
 from uuid import UUID
 from fastapi import APIRouter, HTTPException, status, Depends
 
@@ -27,7 +27,7 @@ from app.sales.retail.services.service import (
     list_sales,
 )
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 router = APIRouter(
     prefix="/pos/sales",
@@ -53,20 +53,75 @@ async def create_sale_endpoint(
             payment_tenders=[t.model_dump() for t in req.payment_tenders] if req.payment_tenders else None,
         )
         sale = await get_sale(sid)
+        
+        logger.info(
+            "Sale created",
+            extra={
+                "operation": "create_sale",
+                "sale_id": str(sid),
+                "merchant_id": str(current_user.merchant_id),
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
+        
         return await _to_sale_response(sale)
+    except HTTPException:
+        raise
+    except ValueError as e:
+        logger.warning(
+            "Create sale validation failed",
+            extra={
+                "operation": "create_sale",
+                "error": str(e),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            }
+        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
     except Exception as e:
-        logger.error(f"Create sale failed: {e}")
-        raise HTTPException(status_code=400, detail=str(e))
+        logger.error(
+            "Create sale failed",
+            extra={
+                "operation": "create_sale",
+                "error": str(e),
+                "error_type": type(e).__name__,
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to create sale")
 
 @router.get("/{sale_id}", response_model=SaleResponse)
 async def get_sale_endpoint(
     sale_id: UUID,
     current_user: TokenUser = Depends(require_pos_permission("sales", "view"))
 ):
-    sale = await get_sale(sale_id)
-    if not sale:
-        raise HTTPException(status_code=404, detail="Sale not found")
-    return await _to_sale_response(sale)
+    try:
+        sale = await get_sale(sale_id)
+        if not sale:
+            logger.warning(
+                "Sale not found",
+                extra={
+                    "operation": "get_sale",
+                    "sale_id": str(sale_id),
+                    "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+                }
+            )
+            raise HTTPException(status_code=404, detail="Sale not found")
+        return await _to_sale_response(sale)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Get sale failed",
+            extra={
+                "operation": "get_sale",
+                "sale_id": str(sale_id),
+                "error": str(e),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to get sale")
 
 @router.post("/list", response_model=SaleListResponse, summary="List sales")
 async def list_sales_endpoint(
@@ -93,30 +148,54 @@ async def list_sales_endpoint(
     - skip: Records to skip (default: 0)
     - limit: Max records to return (default: 50, max: 500)
     """
-    # Extract filters and parameters from payload
-    filters = payload.filters or {}
-    skip = payload.skip or 0
-    limit = payload.limit or 50
-    projection_list = payload.projection_list
-    
-    # Always use merchant_id from token for security
-    if not current_user.merchant_id:
-        raise HTTPException(status_code=400, detail="merchant_id must be available in token")
-    
-    sales, total = await list_sales(
-        merchant_id=current_user.merchant_id,
-        filters=filters,
-        skip=skip,
-        limit=limit,
-        projection_list=projection_list
-    )
-    
-    return SaleListResponse(
-        sales=sales,  # Raw dicts when projection is used, full objects otherwise
-        total=total,
-        skip=skip,
-        limit=limit
-    )
+    try:
+        # Extract filters and parameters from payload
+        filters = payload.filters or {}
+        skip = payload.skip or 0
+        limit = payload.limit or 50
+        projection_list = payload.projection_list
+        
+        # Always use merchant_id from token for security
+        if not current_user.merchant_id:
+            raise HTTPException(status_code=400, detail="merchant_id must be available in token")
+        
+        sales, total = await list_sales(
+            merchant_id=current_user.merchant_id,
+            filters=filters,
+            skip=skip,
+            limit=limit,
+            projection_list=projection_list
+        )
+        
+        logger.info(
+            "Sales listed",
+            extra={
+                "operation": "list_sales",
+                "count": len(sales),
+                "total": total,
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            }
+        )
+        
+        return SaleListResponse(
+            sales=sales,  # Raw dicts when projection is used, full objects otherwise
+            total=total,
+            skip=skip,
+            limit=limit
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "List sales failed",
+            extra={
+                "operation": "list_sales",
+                "error": str(e),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to list sales")
 
 @router.put("/{sale_id}/items", response_model=SaleResponse)
 async def update_items_endpoint(
@@ -126,8 +205,40 @@ async def update_items_endpoint(
 ):
     try:
         sale = await replace_items(sale_id, [i.model_dump() for i in req.items])
+        
+        logger.info(
+            "Sale items updated",
+            extra={
+                "operation": "update_sale_items",
+                "sale_id": str(sale_id),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None,
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
+        
         return await _to_sale_response(sale)
+    except ValueError as e:
+        logger.warning(
+            "Update sale items validation failed",
+            extra={
+                "operation": "update_sale_items",
+                "sale_id": str(sale_id),
+                "error": str(e),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            }
+        )
+        raise HTTPException(status_code=400, detail=str(e))
     except Exception as e:
+        logger.error(
+            "Update sale items failed",
+            extra={
+                "operation": "update_sale_items",
+                "sale_id": str(sale_id),
+                "error": str(e),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            },
+            exc_info=True
+        )
         raise HTTPException(status_code=400, detail=str(e))
 
 @router.post("/{sale_id}/payments", response_model=SaleResponse)
@@ -146,8 +257,41 @@ async def capture_payment_endpoint(
             req.gst_amount,
             req.gst_rate
         )
+        
+        logger.info(
+            "Payment captured",
+            extra={
+                "operation": "capture_payment",
+                "sale_id": str(sale_id),
+                "amount": req.amount,
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None,
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
+        
         return await _to_sale_response(sale)
+    except ValueError as e:
+        logger.warning(
+            "Capture payment validation failed",
+            extra={
+                "operation": "capture_payment",
+                "sale_id": str(sale_id),
+                "error": str(e),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            }
+        )
+        raise HTTPException(status_code=400, detail=str(e))
     except Exception as e:
+        logger.error(
+            "Capture payment failed",
+            extra={
+                "operation": "capture_payment",
+                "sale_id": str(sale_id),
+                "error": str(e),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            },
+            exc_info=True
+        )
         raise HTTPException(status_code=400, detail=str(e))
 
 @router.post("/{sale_id}/cancel", response_model=SaleResponse)
@@ -157,8 +301,40 @@ async def cancel_sale_endpoint(
 ):
     try:
         sale = await cancel_sale(sale_id)
+        
+        logger.info(
+            "Sale cancelled",
+            extra={
+                "operation": "cancel_sale",
+                "sale_id": str(sale_id),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None,
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
+        
         return await _to_sale_response(sale)
+    except ValueError as e:
+        logger.warning(
+            "Cancel sale validation failed",
+            extra={
+                "operation": "cancel_sale",
+                "sale_id": str(sale_id),
+                "error": str(e),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            }
+        )
+        raise HTTPException(status_code=400, detail=str(e))
     except Exception as e:
+        logger.error(
+            "Cancel sale failed",
+            extra={
+                "operation": "cancel_sale",
+                "sale_id": str(sale_id),
+                "error": str(e),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            },
+            exc_info=True
+        )
         raise HTTPException(status_code=400, detail=str(e))
 
 @router.post("/{sale_id}/refund", response_model=SaleResponse)
@@ -169,8 +345,41 @@ async def refund_sale_endpoint(
 ):
     try:
         sale = await refund_sale(sale_id, req.amount, req.reason, req.refunded_by)
+        
+        logger.info(
+            "Sale refunded",
+            extra={
+                "operation": "refund_sale",
+                "sale_id": str(sale_id),
+                "amount": req.amount,
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None,
+                "user_id": str(current_user.id) if current_user.id else None
+            }
+        )
+        
         return await _to_sale_response(sale)
+    except ValueError as e:
+        logger.warning(
+            "Refund sale validation failed",
+            extra={
+                "operation": "refund_sale",
+                "sale_id": str(sale_id),
+                "error": str(e),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            }
+        )
+        raise HTTPException(status_code=400, detail=str(e))
     except Exception as e:
+        logger.error(
+            "Refund sale failed",
+            extra={
+                "operation": "refund_sale",
+                "sale_id": str(sale_id),
+                "error": str(e),
+                "merchant_id": str(current_user.merchant_id) if current_user.merchant_id else None
+            },
+            exc_info=True
+        )
         raise HTTPException(status_code=400, detail=str(e))
 
 async def _to_sale_response(sale: dict) -> SaleResponse:

app/sales/retail/services/service.py

@@ -1,14 +1,14 @@
 """
 Retail Sales service: business logic and Postgres operations.
 """
-import logging
+from app.core.logging import get_logger
 from uuid import uuid4, UUID
 from typing import Optional, List, Tuple
 from sqlalchemy import text
 
 from app.sql import get_postgres_session
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 # Helper to compute taxes (placeholder: 18% GST)
 TAX_RATE = 0.18
@@ -148,11 +148,27 @@ async def create_sale(
                 
                 await session.commit()
             
-            logger.info(f"Created sale {sale_id} with {len(enriched_items)} items")
+            logger.info(
+                f"Created sale {sale_id} with {len(enriched_items)} items",
+                extra={
+                    "operation": "create_sale",
+                    "sale_id": str(sale_id),
+                    "merchant_id": str(merchant_id),
+                    "items_count": len(enriched_items)
+                }
+            )
             return sale_id
         except Exception as e:
             await session.rollback()
-            logger.error(f"Failed to create sale: {e}")
+            logger.error(
+                f"Failed to create sale: {e}",
+                extra={
+                    "operation": "create_sale",
+                    "merchant_id": str(merchant_id),
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
 
 async def get_sale(sale_id: UUID) -> dict:
@@ -250,7 +266,15 @@ async def replace_items(sale_id: UUID, items: List[dict]) -> dict:
             await session.commit()
         except Exception as e:
             await session.rollback()
-            logger.error(f"Failed to update items: {e}")
+            logger.error(
+                f"Failed to update items: {e}",
+                extra={
+                    "operation": "replace_items",
+                    "sale_id": str(sale_id),
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     return await get_sale(sale_id)
 
@@ -295,7 +319,16 @@ async def capture_payment(sale_id: UUID, mode: str, amount: float, reference_no:
             await session.commit()
         except Exception as e:
             await session.rollback()
-            logger.error(f"Payment capture failed: {e}")
+            logger.error(
+                f"Payment capture failed: {e}",
+                extra={
+                    "operation": "capture_payment",
+                    "sale_id": str(sale_id),
+                    "amount": amount,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     return await get_sale(sale_id)
 
@@ -354,7 +387,16 @@ async def refund_sale(sale_id: UUID, amount: float, reason: Optional[str], refun
             await session.commit()
         except Exception as e:
             await session.rollback()
-            logger.error(f"Refund failed: {e}")
+            logger.error(
+                f"Refund failed: {e}",
+                extra={
+                    "operation": "refund_sale",
+                    "sale_id": str(sale_id),
+                    "amount": amount,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     return await get_sale(sale_id)
 
@@ -476,5 +518,5 @@ async def list_sales(
                     {"sid": str(sale_id)}
                 )
                 sale["refunds"] = [dict(r._mapping) for r in ref_rs.fetchall()]
-        
+                
         return sales, total

app/sales/returns/controllers/router.py

@@ -3,8 +3,7 @@ RMA (Return Merchandise Authorization) API router - FastAPI endpoints for RMA op
 """
 from typing import Optional, List
 from fastapi import APIRouter, HTTPException, Query, status
-# from insightfy_utils.logging import get_logger  # TODO: Uncomment when package is available
-import logging
+from app.core.logging import get_logger
 
 from app.sales.returns.schemas.schema import (
     RMACreate,
@@ -18,8 +17,7 @@ from app.sales.returns.schemas.schema import (
 )
 from app.sales.returns.services.service import RMAService
 
-# logger = get_logger(__name__)  # TODO: Uncomment when insightfy_utils is available
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 router = APIRouter(
     prefix="/rma",
@@ -47,8 +45,36 @@ async def create_rma(payload: RMACreate):
     - Order exists and items are valid
     - Return window is within policy
     """
-    rma = await RMAService.create_rma(payload)
-    return RMAResponse(**rma)
+    try:
+        rma = await RMAService.create_rma(payload)
+        
+        logger.info(
+            "RMA created",
+            extra={
+                "operation": "create_rma",
+                "rma_id": rma.get("rma_id"),
+                "merchant_id": payload.merchant_id,
+                "user_id": payload.created_by
+            }
+        )
+        
+        return RMAResponse(**rma)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Error creating RMA",
+            extra={
+                "operation": "create_rma",
+                "error": str(e),
+                "merchant_id": payload.merchant_id
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Error creating RMA"
+        )
 
 
 @router.get(
@@ -60,8 +86,25 @@ async def get_rma(rma_id: str):
     """
     Retrieve an RMA by ID.
     """
-    rma = await RMAService.get_rma(rma_id)
-    return RMAResponse(**rma)
+    try:
+        rma = await RMAService.get_rma(rma_id)
+        return RMAResponse(**rma)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            f"Error getting RMA {rma_id}",
+            extra={
+                "operation": "get_rma",
+                "rma_id": rma_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error getting RMA {rma_id}"
+        )
 
 
 @router.put(
@@ -74,8 +117,38 @@ async def update_rma(rma_id: str, payload: RMAUpdate):
     Update an RMA.
     Only allowed for requested or approved RMAs.
     """
-    rma = await RMAService.update_rma(rma_id, payload)
-    return RMAResponse(**rma)
+    try:
+        rma = await RMAService.update_rma(rma_id, payload)
+        
+        # Using merchant_id from result if available
+        merchant_id = rma.get("merchant_id")
+        
+        logger.info(
+            f"RMA {rma_id} updated",
+            extra={
+                "operation": "update_rma",
+                "rma_id": rma_id,
+                "merchant_id": merchant_id
+            }
+        )
+        
+        return RMAResponse(**rma)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            f"Error updating RMA {rma_id}",
+            extra={
+                "operation": "update_rma",
+                "rma_id": rma_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error updating RMA {rma_id}"
+        )
 
 
 @router.post(
@@ -92,8 +165,41 @@ async def approve_rma(rma_id: str, payload: RMAApproveRequest):
     - **approved_action**: Final approved action (may differ from requested)
     - **return_window_days**: Days allowed for return
     """
-    rma = await RMAService.approve_rma(rma_id, payload)
-    return RMAResponse(**rma)
+    try:
+        rma = await RMAService.approve_rma(rma_id, payload)
+        
+        action = "approved" if payload.approved else "rejected"
+        merchant_id = rma.get("merchant_id")
+        
+        logger.info(
+            f"RMA {rma_id} {action}",
+            extra={
+                "operation": "approve_rma",
+                "rma_id": rma_id,
+                "action": action,
+                "merchant_id": merchant_id,
+                "user_id": payload.approved_by
+            }
+        )
+        
+        return RMAResponse(**rma)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            f"Error approving RMA {rma_id}",
+            extra={
+                "operation": "approve_rma",
+                "rma_id": rma_id,
+                "error": str(e),
+                "user_id": payload.approved_by
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error approving RMA {rma_id}"
+        )
 
 
 @router.post(
@@ -110,8 +216,39 @@ async def schedule_pickup(rma_id: str, payload: RMAPickupRequest):
     - **pickup_address**: Address for pickup
     - **pickup_contact**: Contact person details
     """
-    rma = await RMAService.schedule_pickup(rma_id, payload)
-    return RMAResponse(**rma)
+    try:
+        rma = await RMAService.schedule_pickup(rma_id, payload)
+        
+        merchant_id = rma.get("merchant_id")
+        
+        logger.info(
+            f"Pickup scheduled for RMA {rma_id}",
+            extra={
+                "operation": "schedule_pickup",
+                "rma_id": rma_id,
+                "merchant_id": merchant_id,
+                "user_id": payload.scheduled_by
+            }
+        )
+        
+        return RMAResponse(**rma)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            f"Error scheduling pickup for RMA {rma_id}",
+            extra={
+                "operation": "schedule_pickup",
+                "rma_id": rma_id,
+                "error": str(e),
+                "user_id": payload.scheduled_by
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error scheduling pickup for RMA {rma_id}"
+        )
 
 
 @router.post(
@@ -134,8 +271,40 @@ async def inspect_rma(rma_id: str, payload: RMAInspectRequest):
     - Issue refund/credit note based on inspection
     - Close RMA if fully processed
     """
-    rma = await RMAService.inspect_rma(rma_id, payload)
-    return RMAResponse(**rma)
+    try:
+        rma = await RMAService.inspect_rma(rma_id, payload)
+        
+        merchant_id = rma.get("merchant_id")
+        
+        logger.info(
+            f"RMA {rma_id} inspected",
+            extra={
+                "operation": "inspect_rma",
+                "rma_id": rma_id,
+                "result": payload.inspection_result.value,
+                "merchant_id": merchant_id,
+                "user_id": payload.inspected_by
+            }
+        )
+        
+        return RMAResponse(**rma)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            f"Error inspecting RMA {rma_id}",
+            extra={
+                "operation": "inspect_rma",
+                "rma_id": rma_id,
+                "error": str(e),
+                "user_id": payload.inspected_by
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error inspecting RMA {rma_id}"
+        )
 
 
 @router.get(
@@ -153,14 +322,31 @@ async def list_rmas(
     """
     List RMAs with optional filters.
     """
-    rmas = await RMAService.list_rmas(
-        merchant_id=merchant_id,
-        requestor_id=requestor_id,
-        status=status.value if status else None,
-        skip=skip,
-        limit=limit
-    )
-    return [RMAListResponse(**rma) for rma in rmas]
+    try:
+        rmas = await RMAService.list_rmas(
+            merchant_id=merchant_id,
+            requestor_id=requestor_id,
+            status=status.value if status else None,
+            skip=skip,
+            limit=limit
+        )
+        return [RMAListResponse(**rma) for rma in rmas]
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Error listing RMAs",
+            extra={
+                "operation": "list_rmas",
+                "error": str(e),
+                "merchant_id": merchant_id
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Error listing RMAs"
+        )
 
 
 @router.delete(
@@ -176,5 +362,37 @@ async def cancel_rma(
     Cancel an RMA.
     Only allowed for requested or approved RMAs.
     """
-    result = await RMAService.cancel_rma(rma_id, cancelled_by, reason)
-    return {"message": f"RMA {rma_id} cancelled successfully"}
+    try:
+        result = await RMAService.cancel_rma(rma_id, cancelled_by, reason)
+        
+        merchant_id = result.get("merchant_id")
+        
+        logger.info(
+            f"RMA {rma_id} cancelled",
+            extra={
+                "operation": "cancel_rma",
+                "rma_id": rma_id,
+                "merchant_id": merchant_id,
+                "user_id": cancelled_by,
+                "reason": reason
+            }
+        )
+        
+        return {"message": f"RMA {rma_id} cancelled successfully"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            f"Error cancelling RMA {rma_id}",
+            extra={
+                "operation": "cancel_rma",
+                "rma_id": rma_id,
+                "error": str(e),
+                "user_id": cancelled_by
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error cancelling RMA {rma_id}"
+        )

app/sales/returns/services/service.py

@@ -5,8 +5,7 @@ from datetime import datetime
 from typing import Optional, List, Dict, Any
 from decimal import Decimal
 from fastapi import HTTPException, status
-# from insightfy_utils.logging import get_logger  # TODO: Uncomment when package is available
-import logging
+from app.core.logging import get_logger
 import secrets
 
 from app.nosql import get_database
@@ -26,7 +25,7 @@ from app.sales.returns.schemas.schema import (
 )
 
 # logger = get_logger(__name__)  # TODO: Uncomment when insightfy_utils is available
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 def generate_rma_number(merchant_code: str) -> str:
@@ -49,83 +48,101 @@ class RMAService:
         """Create a new RMA"""
         db = get_database()
         
-        # Validate related order exists
-        order = await db[SCM_SALES_ORDERS_COLLECTION].find_one({"sales_order_id": payload.related_order_id})
-        if not order:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"Order {payload.related_order_id} not found"
-            )
-        
-        # Validate items are in the order
-        order_skus = {item["sku"] for item in order.get("items", [])}
-        rma_skus = {item.sku for item in payload.items}
-        
-        if not rma_skus.issubset(order_skus):
-            invalid_skus = rma_skus - order_skus
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=f"Invalid SKUs not in order: {invalid_skus}"
-            )
-        
-        # Generate RMA ID and number
-        rma_id = generate_rma_id()
-        merchant_code = payload.merchant_id.split("_")[0] if "_" in payload.merchant_id else "MER"
-        rma_number = payload.rma_number or generate_rma_number(merchant_code)
-        
-        # Create RMA document
-        now = datetime.utcnow()
-        items_dict = [item.dict() for item in payload.items]
-        
-        rma_doc = {
-            "rma_id": rma_id,
-            "rma_number": rma_number,
-            "related_order_id": payload.related_order_id,
-            "related_order_type": payload.related_order_type,
-            "related_order_number": order.get("order_number"),
-            "requestor_id": payload.requestor_id,
-            "requestor_type": payload.requestor_type,
-            "requestor_name": None,  # TODO: Fetch from customer/merchant service
-            "merchant_id": payload.merchant_id,
-            "status": RMAStatus.REQUESTED.value,
-            "items": items_dict,
-            "requested_action": payload.requested_action.value,
-            "approved_action": None,
-            "return_reason": payload.return_reason,
-            "return_address": payload.return_address,
-            "pickup_required": payload.pickup_required,
-            "pickup_scheduled": False,
-            "pickup_details": None,
-            "shipment_id": None,
-            "tracking_number": None,
-            "inspection_result": None,
-            "inspection_notes": None,
-            "refund_amount": None,
-            "store_credit_amount": None,
-            "credit_note_id": None,
-            "replacement_order_id": None,
-            "notes": payload.notes,
-            "internal_notes": None,
-            "created_by": payload.created_by,
-            "created_at": now.isoformat(),
-            "updated_at": now.isoformat(),
-            "approved_at": None,
-            "approved_by": None,
-            "rejected_at": None,
-            "rejected_by": None,
-            "rejection_reason": None,
-            "inspected_at": None,
-            "inspected_by": None,
-            "closed_at": None,
-            "metadata": {}
-        }
-        
         try:
+            # Validate related order exists
+            order = await db[SCM_SALES_ORDERS_COLLECTION].find_one({"sales_order_id": payload.related_order_id})
+            if not order:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail=f"Order {payload.related_order_id} not found"
+                )
+            
+            # Validate items are in the order
+            order_skus = {item["sku"] for item in order.get("items", [])}
+            rma_skus = {item.sku for item in payload.items}
+            
+            if not rma_skus.issubset(order_skus):
+                invalid_skus = rma_skus - order_skus
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Invalid SKUs not in order: {invalid_skus}"
+                )
+            
+            # Generate RMA ID and number
+            rma_id = generate_rma_id()
+            merchant_code = payload.merchant_id.split("_")[0] if "_" in payload.merchant_id else "MER"
+            rma_number = payload.rma_number or generate_rma_number(merchant_code)
+            
+            # Create RMA document
+            now = datetime.utcnow()
+            items_dict = [item.dict() for item in payload.items]
+            
+            rma_doc = {
+                "rma_id": rma_id,
+                "rma_number": rma_number,
+                "related_order_id": payload.related_order_id,
+                "related_order_type": payload.related_order_type,
+                "related_order_number": order.get("order_number"),
+                "requestor_id": payload.requestor_id,
+                "requestor_type": payload.requestor_type,
+                "requestor_name": None,  # TODO: Fetch from customer/merchant service
+                "merchant_id": payload.merchant_id,
+                "status": RMAStatus.REQUESTED.value,
+                "items": items_dict,
+                "requested_action": payload.requested_action.value,
+                "approved_action": None,
+                "return_reason": payload.return_reason,
+                "return_address": payload.return_address,
+                "pickup_required": payload.pickup_required,
+                "pickup_scheduled": False,
+                "pickup_details": None,
+                "shipment_id": None,
+                "tracking_number": None,
+                "inspection_result": None,
+                "inspection_notes": None,
+                "refund_amount": None,
+                "store_credit_amount": None,
+                "credit_note_id": None,
+                "replacement_order_id": None,
+                "notes": payload.notes,
+                "internal_notes": None,
+                "created_by": payload.created_by,
+                "created_at": now.isoformat(),
+                "updated_at": now.isoformat(),
+                "approved_at": None,
+                "approved_by": None,
+                "rejected_at": None,
+                "rejected_by": None,
+                "rejection_reason": None,
+                "inspected_at": None,
+                "inspected_by": None,
+                "closed_at": None,
+                "metadata": {}
+            }
+        
             await db[SCM_RMA_COLLECTION].insert_one(rma_doc)
-            logger.info(f"Created RMA {rma_id}", extra={"rma_id": rma_id, "order_id": payload.related_order_id})
+            logger.info(
+                f"Created RMA {rma_id}", 
+                extra={
+                    "operation": "create_rma",
+                    "rma_id": rma_id, 
+                    "order_id": payload.related_order_id,
+                    "merchant_id": payload.merchant_id
+                }
+            )
             return rma_doc
+        except HTTPException:
+            raise
         except Exception as e:
-            logger.error(f"Error creating RMA", exc_info=e)
+            logger.error(
+                "Error creating RMA", 
+                extra={
+                    "operation": "create_rma",
+                    "error": str(e),
+                    "merchant_id": payload.merchant_id
+                }, 
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail="Error creating RMA"
@@ -134,152 +151,245 @@ class RMAService:
     @staticmethod
     async def get_rma(rma_id: str) -> Dict[str, Any]:
         """Get RMA by ID"""
-        db = get_database()
-        
-        rma = await db[SCM_RMA_COLLECTION].find_one({"rma_id": rma_id})
-        if not rma:
+        try:
+            db = get_database()
+            
+            rma = await db[SCM_RMA_COLLECTION].find_one({"rma_id": rma_id})
+            if not rma:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail=f"RMA {rma_id} not found"
+                )
+            
+            return rma
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(
+                f"Error getting RMA {rma_id}", 
+                extra={
+                    "operation": "get_rma",
+                    "rma_id": rma_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"RMA {rma_id} not found"
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Error getting RMA {rma_id}"
             )
-        
-        return rma
 
     @staticmethod
     async def approve_rma(rma_id: str, payload: RMAApproveRequest) -> Dict[str, Any]:
         """Approve or reject RMA"""
-        db = get_database()
-        
-        rma = await RMAService.get_rma(rma_id)
-        
-        if rma["status"] != RMAStatus.REQUESTED.value:
+        try:
+            db = get_database()
+            
+            rma = await RMAService.get_rma(rma_id)
+            
+            if rma["status"] != RMAStatus.REQUESTED.value:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Cannot approve RMA with status {rma['status']}"
+                )
+            
+            now = datetime.utcnow()
+            update_data = {
+                "updated_at": now.isoformat()
+            }
+            
+            if payload.approved:
+                update_data["status"] = RMAStatus.APPROVED.value
+                update_data["approved_at"] = now.isoformat()
+                update_data["approved_by"] = payload.approved_by
+                update_data["approved_action"] = payload.approved_action.value if payload.approved_action else rma["requested_action"]
+                
+                # Update items if partial approval
+                if payload.items:
+                    items_dict = [item.dict() for item in payload.items]
+                    update_data["items"] = items_dict
+            else:
+                update_data["status"] = RMAStatus.REJECTED.value
+                update_data["rejected_at"] = now.isoformat()
+                update_data["rejected_by"] = payload.approved_by
+                update_data["rejection_reason"] = payload.rejection_reason
+            
+            await db[SCM_RMA_COLLECTION].update_one(
+                {"rma_id": rma_id},
+                {"$set": update_data}
+            )
+            
+            action = "approve" if payload.approved else "reject"
+            logger.info(
+                f"{'Approved' if payload.approved else 'Rejected'} RMA {rma_id}", 
+                extra={
+                    "operation": "approve_rma",
+                    "rma_id": rma_id,
+                    "action": action,
+                    "user_id": payload.approved_by
+                }
+            )
+            
+            return await RMAService.get_rma(rma_id)
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(
+                f"Error approving RMA {rma_id}", 
+                extra={
+                    "operation": "approve_rma",
+                    "rma_id": rma_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=f"Cannot approve RMA with status {rma['status']}"
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Error approving RMA {rma_id}"
             )
-        
-        now = datetime.utcnow()
-        update_data = {
-            "updated_at": now.isoformat()
-        }
-        
-        if payload.approved:
-            update_data["status"] = RMAStatus.APPROVED.value
-            update_data["approved_at"] = now.isoformat()
-            update_data["approved_by"] = payload.approved_by
-            update_data["approved_action"] = payload.approved_action.value if payload.approved_action else rma["requested_action"]
-            
-            # Update items if partial approval
-            if payload.items:
-                items_dict = [item.dict() for item in payload.items]
-                update_data["items"] = items_dict
-        else:
-            update_data["status"] = RMAStatus.REJECTED.value
-            update_data["rejected_at"] = now.isoformat()
-            update_data["rejected_by"] = payload.approved_by
-            update_data["rejection_reason"] = payload.rejection_reason
-        
-        await db[SCM_RMA_COLLECTION].update_one(
-            {"rma_id": rma_id},
-            {"$set": update_data}
-        )
-        
-        logger.info(f"{'Approved' if payload.approved else 'Rejected'} RMA {rma_id}", extra={"rma_id": rma_id})
-        
-        return await RMAService.get_rma(rma_id)
 
     @staticmethod
     async def schedule_pickup(rma_id: str, payload: RMAPickupRequest) -> Dict[str, Any]:
         """Schedule pickup for RMA"""
-        db = get_database()
-        
-        rma = await RMAService.get_rma(rma_id)
-        
-        if rma["status"] != RMAStatus.APPROVED.value:
+        try:
+            db = get_database()
+            
+            rma = await RMAService.get_rma(rma_id)
+            
+            if rma["status"] != RMAStatus.APPROVED.value:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Cannot schedule pickup for RMA with status {rma['status']}"
+                )
+            
+            pickup_details = {
+                "carrier": payload.carrier,
+                "pickup_date": payload.pickup_date.isoformat(),
+                "pickup_address": payload.pickup_address,
+                "pickup_contact_name": payload.pickup_contact_name,
+                "pickup_contact_phone": payload.pickup_contact_phone,
+                "special_instructions": payload.special_instructions,
+                "scheduled_by": payload.scheduled_by,
+                "scheduled_at": datetime.utcnow().isoformat()
+            }
+            
+            update_data = {
+                "status": RMAStatus.PICKED.value,
+                "pickup_scheduled": True,
+                "pickup_details": pickup_details,
+                "updated_at": datetime.utcnow().isoformat()
+            }
+            
+            await db[SCM_RMA_COLLECTION].update_one(
+                {"rma_id": rma_id},
+                {"$set": update_data}
+            )
+            
+            logger.info(
+                f"Scheduled pickup for RMA {rma_id}", 
+                extra={
+                    "operation": "schedule_pickup",
+                    "rma_id": rma_id, 
+                    "carrier": payload.carrier,
+                    "user_id": payload.scheduled_by
+                }
+            )
+            
+            return await RMAService.get_rma(rma_id)
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(
+                f"Error scheduling pickup for RMA {rma_id}", 
+                extra={
+                    "operation": "schedule_pickup",
+                    "rma_id": rma_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=f"Cannot schedule pickup for RMA with status {rma['status']}"
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Error scheduling pickup for RMA {rma_id}"
             )
-        
-        pickup_details = {
-            "carrier": payload.carrier,
-            "pickup_date": payload.pickup_date.isoformat(),
-            "pickup_address": payload.pickup_address,
-            "pickup_contact_name": payload.pickup_contact_name,
-            "pickup_contact_phone": payload.pickup_contact_phone,
-            "special_instructions": payload.special_instructions,
-            "scheduled_by": payload.scheduled_by,
-            "scheduled_at": datetime.utcnow().isoformat()
-        }
-        
-        update_data = {
-            "status": RMAStatus.PICKED.value,
-            "pickup_scheduled": True,
-            "pickup_details": pickup_details,
-            "updated_at": datetime.utcnow().isoformat()
-        }
-        
-        await db[SCM_RMA_COLLECTION].update_one(
-            {"rma_id": rma_id},
-            {"$set": update_data}
-        )
-        
-        logger.info(f"Scheduled pickup for RMA {rma_id}", extra={"rma_id": rma_id, "carrier": payload.carrier})
-        
-        return await RMAService.get_rma(rma_id)
 
     @staticmethod
     async def inspect_rma(rma_id: str, payload: RMAInspectRequest) -> Dict[str, Any]:
         """Perform inspection on returned items"""
-        db = get_database()
-        
-        rma = await RMAService.get_rma(rma_id)
-        
-        if rma["status"] not in [RMAStatus.PICKED.value, RMAStatus.IN_TRANSIT.value, RMAStatus.RECEIVED.value]:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=f"Cannot inspect RMA with status {rma['status']}"
-            )
-        
-        now = datetime.utcnow()
-        update_data = {
-            "status": RMAStatus.INSPECTED.value,
-            "inspection_result": payload.inspection_result.value,
-            "inspection_notes": payload.inspection_notes,
-            "inspected_at": payload.inspected_at.isoformat(),
-            "inspected_by": payload.inspected_by,
-            "updated_at": now.isoformat()
-        }
-        
-        # Process based on inspection result
-        if payload.inspection_result.value in ["approved", "partial_approved"]:
-            if payload.refund_amount:
-                update_data["refund_amount"] = float(payload.refund_amount)
+        try:
+            db = get_database()
             
-            if payload.store_credit_amount:
-                update_data["store_credit_amount"] = float(payload.store_credit_amount)
+            rma = await RMAService.get_rma(rma_id)
             
-            if payload.credit_note_id:
-                update_data["credit_note_id"] = payload.credit_note_id
+            if rma["status"] not in [RMAStatus.PICKED.value, RMAStatus.IN_TRANSIT.value, RMAStatus.RECEIVED.value]:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Cannot inspect RMA with status {rma['status']}"
+                )
             
-            if payload.replacement_order_id:
-                update_data["replacement_order_id"] = payload.replacement_order_id
+            now = datetime.utcnow()
+            update_data = {
+                "status": RMAStatus.INSPECTED.value,
+                "inspection_result": payload.inspection_result.value,
+                "inspection_notes": payload.inspection_notes,
+                "inspected_at": payload.inspected_at.isoformat(),
+                "inspected_by": payload.inspected_by,
+                "updated_at": now.isoformat()
+            }
             
-            # Update inventory ledger for returned items
-            await RMAService._update_inventory_for_return(rma, payload.items)
+            # Process based on inspection result
+            if payload.inspection_result.value in ["approved", "partial_approved"]:
+                if payload.refund_amount:
+                    update_data["refund_amount"] = float(payload.refund_amount)
+                
+                if payload.store_credit_amount:
+                    update_data["store_credit_amount"] = float(payload.store_credit_amount)
+                
+                if payload.credit_note_id:
+                    update_data["credit_note_id"] = payload.credit_note_id
+                
+                if payload.replacement_order_id:
+                    update_data["replacement_order_id"] = payload.replacement_order_id
+                
+                # Update inventory ledger for returned items
+                await RMAService._update_inventory_for_return(rma, payload.items)
+                
+                # Close RMA if fully processed
+                update_data["status"] = RMAStatus.CLOSED.value
+                update_data["closed_at"] = now.isoformat()
             
-            # Close RMA if fully processed
-            update_data["status"] = RMAStatus.CLOSED.value
-            update_data["closed_at"] = now.isoformat()
-        
-        await db[SCM_RMA_COLLECTION].update_one(
-            {"rma_id": rma_id},
-            {"$set": update_data}
-        )
-        
-        logger.info(f"Inspected RMA {rma_id}", extra={"rma_id": rma_id, "result": payload.inspection_result.value})
-        
-        return await RMAService.get_rma(rma_id)
+            await db[SCM_RMA_COLLECTION].update_one(
+                {"rma_id": rma_id},
+                {"$set": update_data}
+            )
+            
+            logger.info(
+                f"Inspected RMA {rma_id}", 
+                extra={
+                    "operation": "inspect_rma",
+                    "rma_id": rma_id, 
+                    "result": payload.inspection_result.value,
+                    "user_id": payload.inspected_by
+                }
+            )
+            
+            return await RMAService.get_rma(rma_id)
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(
+                f"Error inspecting RMA {rma_id}", 
+                extra={
+                    "operation": "inspect_rma",
+                    "rma_id": rma_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Error inspecting RMA {rma_id}"
+            )
 
     @staticmethod
     async def _update_inventory_for_return(rma: Dict[str, Any], inspected_items: List[Dict[str, Any]]):
@@ -312,37 +422,60 @@ class RMAService:
     @staticmethod
     async def update_rma(rma_id: str, payload: RMAUpdate) -> Dict[str, Any]:
         """Update RMA"""
-        db = get_database()
-        
-        rma = await RMAService.get_rma(rma_id)
-        
-        if rma["status"] in [RMAStatus.CLOSED.value, RMAStatus.CANCELLED.value]:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=f"Cannot update RMA with status {rma['status']}"
+        try:
+            db = get_database()
+            
+            rma = await RMAService.get_rma(rma_id)
+            
+            if rma["status"] in [RMAStatus.CLOSED.value, RMAStatus.CANCELLED.value]:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Cannot update RMA with status {rma['status']}"
+                )
+            
+            update_data = payload.dict(exclude_unset=True)
+            if not update_data:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="No update data provided"
+                )
+            
+            if "items" in update_data:
+                items_dict = [item.dict() for item in update_data["items"]]
+                update_data["items"] = items_dict
+            
+            update_data["updated_at"] = datetime.utcnow().isoformat()
+            
+            await db[SCM_RMA_COLLECTION].update_one(
+                {"rma_id": rma_id},
+                {"$set": update_data}
+            )
+            
+            logger.info(
+                f"Updated RMA {rma_id}", 
+                extra={
+                    "operation": "update_rma",
+                    "rma_id": rma_id
+                }
+            )
+            
+            return await RMAService.get_rma(rma_id)
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(
+                f"Error updating RMA {rma_id}", 
+                extra={
+                    "operation": "update_rma",
+                    "rma_id": rma_id,
+                    "error": str(e)
+                },
+                exc_info=True
             )
-        
-        update_data = payload.dict(exclude_unset=True)
-        if not update_data:
             raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="No update data provided"
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Error updating RMA {rma_id}"
             )
-        
-        if "items" in update_data:
-            items_dict = [item.dict() for item in update_data["items"]]
-            update_data["items"] = items_dict
-        
-        update_data["updated_at"] = datetime.utcnow().isoformat()
-        
-        await db[SCM_RMA_COLLECTION].update_one(
-            {"rma_id": rma_id},
-            {"$set": update_data}
-        )
-        
-        logger.info(f"Updated RMA {rma_id}", extra={"rma_id": rma_id})
-        
-        return await RMAService.get_rma(rma_id)
 
     @staticmethod
     async def list_rmas(
@@ -368,7 +501,15 @@ class RMAService:
             rmas = await cursor.to_list(length=limit)
             return rmas
         except Exception as e:
-            logger.error("Error listing RMAs", exc_info=e)
+            logger.error(
+                "Error listing RMAs", 
+                extra={
+                    "operation": "list_rmas",
+                    "error": str(e),
+                    "merchant_id": merchant_id
+                },
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail="Error listing RMAs"
@@ -377,30 +518,55 @@ class RMAService:
     @staticmethod
     async def cancel_rma(rma_id: str, cancelled_by: str, reason: str) -> Dict[str, Any]:
         """Cancel RMA"""
-        db = get_database()
-        
-        rma = await RMAService.get_rma(rma_id)
-        
-        if rma["status"] in [RMAStatus.CLOSED.value, RMAStatus.CANCELLED.value]:
+        try:
+            db = get_database()
+            
+            rma = await RMAService.get_rma(rma_id)
+            
+            if rma["status"] in [RMAStatus.CLOSED.value, RMAStatus.CANCELLED.value]:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Cannot cancel RMA with status {rma['status']}"
+                )
+            
+            now = datetime.utcnow()
+            update_data = {
+                "status": RMAStatus.CANCELLED.value,
+                "rejection_reason": reason,
+                "rejected_by": cancelled_by,
+                "rejected_at": now.isoformat(),
+                "updated_at": now.isoformat()
+            }
+            
+            await db[SCM_RMA_COLLECTION].update_one(
+                {"rma_id": rma_id},
+                {"$set": update_data}
+            )
+            
+            logger.info(
+                f"Cancelled RMA {rma_id}", 
+                extra={
+                    "operation": "cancel_rma",
+                    "rma_id": rma_id,
+                    "user_id": cancelled_by,
+                    "reason": reason
+                }
+            )
+            
+            return await RMAService.get_rma(rma_id)
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(
+                f"Error cancelling RMA {rma_id}", 
+                extra={
+                    "operation": "cancel_rma",
+                    "rma_id": rma_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=f"Cannot cancel RMA with status {rma['status']}"
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Error cancelling RMA {rma_id}"
             )
-        
-        now = datetime.utcnow()
-        update_data = {
-            "status": RMAStatus.CANCELLED.value,
-            "rejection_reason": reason,
-            "rejected_by": cancelled_by,
-            "rejected_at": now.isoformat(),
-            "updated_at": now.isoformat()
-        }
-        
-        await db[SCM_RMA_COLLECTION].update_one(
-            {"rma_id": rma_id},
-            {"$set": update_data}
-        )
-        
-        logger.info(f"Cancelled RMA {rma_id}", extra={"rma_id": rma_id})
-        
-        return await RMAService.get_rma(rma_id)

app/staff/controllers/router.py

@@ -4,8 +4,8 @@ Simplified POS staff management.
 """
 from typing import Optional, List
 from fastapi import APIRouter, HTTPException, Query, status, Header
-import logging
 
+from app.core.logging import get_logger
 from app.constants.staff_types import Designation, stafftatus
 from app.staff.schemas.staff_schema import (
     StaffCreateSchema,
@@ -18,7 +18,7 @@ from app.staff.schemas.staff_schema import (
 )
 from app.staff.services.staff_service import StaffService
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 router = APIRouter(
     prefix="/staff",
@@ -50,7 +50,32 @@ async def create_staff(payload: StaffCreateSchema) -> StaffResponseSchema:
     - photo_url: Profile photo URL (HTTPS only)
     - notes: Additional information
     """
-    return await StaffService.create_staff(payload)
+    try:
+        result = await StaffService.create_staff(payload)
+        
+        logger.info(
+            "Staff member created",
+            extra={
+                "operation": "create_staff",
+                "merchant_id": str(payload.merchant_id),
+                "staff_name": payload.name
+            }
+        )
+        
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Create staff failed",
+            extra={
+                "operation": "create_staff",
+                "error": str(e),
+                "merchant_id": str(payload.merchant_id) if hasattr(payload, "merchant_id") else None
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to create staff member")
 
 
 
@@ -65,13 +90,43 @@ async def get_staff(staff_id: str) -> StaffResponseSchema:
     """
     Get detailed information about a specific staff member.
     """
-    staff = await StaffService.get_staff_by_id(staff_id)
-    if not staff:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Staff {staff_id} not found"
+    try:
+        staff = await StaffService.get_staff_by_id(staff_id)
+        if not staff:
+            logger.warning(
+                "Staff member not found",
+                extra={
+                    "operation": "get_staff",
+                    "staff_id": staff_id
+                }
+            )
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Staff {staff_id} not found"
+            )
+        
+        logger.info(
+            "Staff member retrieved",
+            extra={
+                "operation": "get_staff",
+                "staff_id": staff_id,
+                "merchant_id": str(staff.merchant_id) if hasattr(staff, "merchant_id") else None
+            }
         )
-    return staff
+        return staff
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Get staff failed",
+            extra={
+                "operation": "get_staff",
+                "staff_id": staff_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to get staff member")
 
 
 @router.put(
@@ -85,7 +140,32 @@ async def update_staff(staff_id: str, payload: StaffUpdateSchema) -> StaffRespon
     
     All fields are optional - only provided fields will be updated.
     """
-    return await StaffService.update_staff(staff_id, payload)
+    try:
+        result = await StaffService.update_staff(staff_id, payload)
+        
+        logger.info(
+            "Staff member updated",
+            extra={
+                "operation": "update_staff",
+                "staff_id": staff_id,
+                "merchant_id": str(result.merchant_id) if hasattr(result, "merchant_id") else None
+            }
+        )
+        
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Update staff failed",
+            extra={
+                "operation": "update_staff",
+                "staff_id": staff_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to update staff member")
 
 
 @router.delete(
@@ -96,7 +176,31 @@ async def delete_staff(staff_id: str):
     """
     Delete a staff member (soft delete - sets status to inactive).
     """
-    return await StaffService.delete_staff(staff_id)
+    try:
+        result = await StaffService.delete_staff(staff_id)
+        
+        logger.info(
+            "Staff member deleted",
+            extra={
+                "operation": "delete_staff",
+                "staff_id": staff_id
+            }
+        )
+        
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Delete staff failed",
+            extra={
+                "operation": "delete_staff",
+                "staff_id": staff_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to delete staff member")
 
 
 @router.get(
@@ -107,18 +211,48 @@ async def get_staff_schedule(staff_id: str):
     """
     Get working schedule for a staff member.
     """
-    staff = await StaffService.get_staff_by_id(staff_id)
-    if not staff:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Staff {staff_id} not found"
+    try:
+        staff = await StaffService.get_staff_by_id(staff_id)
+        if not staff:
+            logger.warning(
+                "Staff member not found for schedule",
+                extra={
+                    "operation": "get_staff_schedule",
+                    "staff_id": staff_id
+                }
+            )
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Staff {staff_id} not found"
+            )
+        
+        logger.info(
+            "Staff schedule retrieved",
+            extra={
+                "operation": "get_staff_schedule",
+                "staff_id": staff_id,
+                "merchant_id": str(staff.merchant_id) if hasattr(staff, "merchant_id") else None
+            }
         )
-    
-    return {
-        "staff_id": staff.staff_id,
-        "name": staff.name,
-        "working_hours": staff.working_hours
-    }
+        
+        return {
+            "staff_id": staff.staff_id,
+            "name": staff.name,
+            "working_hours": staff.working_hours
+        }
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Get staff schedule failed",
+            extra={
+                "operation": "get_staff_schedule",
+                "staff_id": staff_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to get staff schedule")
 
 
 @router.get(
@@ -140,7 +274,31 @@ async def get_employee(user_id: str) -> EmployeeResponse:
     Raises:
         404: Employee not found
     """
-    return await StaffService.get_employee(user_id)
+    try:
+        employee = await StaffService.get_employee(user_id)
+        
+        logger.info(
+            "Employee retrieved",
+            extra={
+                "operation": "get_employee",
+                "user_id": user_id,
+                "merchant_id": str(employee.merchant_id) if hasattr(employee, "merchant_id") else None
+            }
+        )
+        return employee
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Get employee failed",
+            extra={
+                "operation": "get_employee",
+                "user_id": user_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to get employee")
 
 
 @router.get(
@@ -162,7 +320,31 @@ async def get_employee_by_code(employee_code: str) -> EmployeeResponse:
     Raises:
         404: Employee not found
     """
-    return await StaffService.get_employee_by_code(employee_code)
+    try:
+        employee = await StaffService.get_employee_by_code(employee_code)
+        
+        logger.info(
+            "Employee retrieved by code",
+            extra={
+                "operation": "get_employee_by_code",
+                "employee_code": employee_code,
+                "merchant_id": str(employee.merchant_id) if hasattr(employee, "merchant_id") else None
+            }
+        )
+        return employee
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Get employee by code failed",
+            extra={
+                "operation": "get_employee_by_code",
+                "employee_code": employee_code,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to get employee by code")
 
 
 @router.put(
@@ -196,7 +378,34 @@ async def update_employee(
     - Phone uniqueness (if changing phone)
     - Manager validation (if changing manager)
     """
-    return await StaffService.update_employee(user_id, payload, x_user_id)
+    try:
+        result = await StaffService.update_employee(user_id, payload, x_user_id)
+        
+        logger.info(
+            "Employee updated",
+            extra={
+                "operation": "update_employee",
+                "user_id": user_id,
+                "merchant_id": str(result.merchant_id) if hasattr(result, "merchant_id") else None,
+                "updated_by": x_user_id
+            }
+        )
+        
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Update employee failed",
+            extra={
+                "operation": "update_employee",
+                "user_id": user_id,
+                "error": str(e),
+                "updated_by": x_user_id
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to update employee")
 
 
 @router.post(
@@ -227,22 +436,45 @@ async def list_staff(
     Returns:
         List of staff matching the filters and total count
     """
-    items, total = await StaffService.list_staff(
-        designation=payload.designation,
-        manager_id=payload.manager_id,
-        status_filter=payload.status,
-        region=payload.region,
-        skip=payload.skip,
-        limit=payload.limit,
-        projection_list=payload.projection_list
-    )
-    
-    return StaffListResponse(
-        items=items,
-        total=total,
-        skip=payload.skip,
-        limit=payload.limit
-    )
+    try:
+        items, total = await StaffService.list_staff(
+            designation=payload.designation,
+            manager_id=payload.manager_id,
+            status_filter=payload.status,
+            region=payload.region,
+            skip=payload.skip,
+            limit=payload.limit,
+            projection_list=payload.projection_list
+        )
+        
+        logger.info(
+            "Staff listed",
+            extra={
+                "operation": "list_staff",
+                "count": len(items),
+                "total": total,
+                "manager_id": payload.manager_id
+            }
+        )
+        
+        return StaffListResponse(
+            items=items,
+            total=total,
+            skip=payload.skip,
+            limit=payload.limit
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "List staff failed",
+            extra={
+                "operation": "list_staff",
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to list staff")
 
 
 @router.delete(
@@ -270,7 +502,33 @@ async def delete_employee(
         404: Employee not found
         400: Employee has active direct reports
     """
-    return await StaffService.delete_employee(user_id, x_user_id)
+    try:
+        result = await StaffService.delete_employee(user_id, x_user_id)
+        
+        logger.info(
+            "Employee deleted",
+            extra={
+                "operation": "delete_employee",
+                "user_id": user_id,
+                "deleted_by": x_user_id
+            }
+        )
+        
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Delete employee failed",
+            extra={
+                "operation": "delete_employee",
+                "user_id": user_id,
+                "error": str(e),
+                "deleted_by": x_user_id
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to delete employee")
 
 
 @router.get(
@@ -303,16 +561,39 @@ async def get_employee_reports(
     Returns:
         List of direct report staff
     """
-    # First verify employee exists
-    await StaffService.get_employee(user_id)
-    
-    items, _ = await StaffService.list_staff(
-        manager_id=user_id,
-        status_filter=status_filter,
-        skip=skip,
-        limit=limit
-    )
-    return items
+    try:
+        # First verify employee exists
+        await StaffService.get_employee(user_id)
+        
+        items, _ = await StaffService.list_staff(
+            manager_id=user_id,
+            status_filter=status_filter,
+            skip=skip,
+            limit=limit
+        )
+        
+        logger.info(
+            "Employee reports listed",
+            extra={
+                "operation": "get_employee_reports",
+                "user_id": user_id,
+                "count": len(items)
+            }
+        )
+        return items
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Get employee reports failed",
+            extra={
+                "operation": "get_employee_reports",
+                "user_id": user_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to get employee reports")
 
 
 @router.get(
@@ -332,22 +613,45 @@ async def get_employee_hierarchy(user_id: str):
     Returns:
         List of staff from top manager to current employee
     """
-    hierarchy = []
-    current_id = user_id
-    visited = set()  # Prevent infinite loops
-    
-    # Traverse up the hierarchy
-    while current_id and current_id not in visited:
-        visited.add(current_id)
-        employee_data = await StaffService.get_employee(current_id)
-        hierarchy.insert(0, employee_data)  # Insert at beginning to maintain order
-        current_id = employee_data.manager_id
-    
-    return {
-        "user_id": user_id,
-        "depth": len(hierarchy),
-        "hierarchy": hierarchy
-    }
+    try:
+        hierarchy = []
+        current_id = user_id
+        visited = set()  # Prevent infinite loops
+        
+        # Traverse up the hierarchy
+        while current_id and current_id not in visited:
+            visited.add(current_id)
+            employee_data = await StaffService.get_employee(current_id)
+            hierarchy.insert(0, employee_data)  # Insert at beginning to maintain order
+            current_id = employee_data.manager_id
+        
+        logger.info(
+            "Employee hierarchy retrieved",
+            extra={
+                "operation": "get_employee_hierarchy",
+                "user_id": user_id,
+                "depth": len(hierarchy)
+            }
+        )
+        
+        return {
+            "user_id": user_id,
+            "depth": len(hierarchy),
+            "hierarchy": hierarchy
+        }
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Get employee hierarchy failed",
+            extra={
+                "operation": "get_employee_hierarchy",
+                "user_id": user_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to get employee hierarchy")
 
 
 @router.patch(
@@ -380,8 +684,36 @@ async def update_employee_status(
     - active → suspended (disciplinary)
     - active/inactive/suspended → terminated (termination)
     """
-    update_payload = EmployeeUpdate(status=new_status)
-    return await StaffService.update_employee(user_id, update_payload, x_user_id)
+    try:
+        update_payload = EmployeeUpdate(status=new_status)
+        result = await StaffService.update_employee(user_id, update_payload, x_user_id)
+        
+        logger.info(
+            "Employee status updated",
+            extra={
+                "operation": "update_employee_status",
+                "user_id": user_id,
+                "new_status": new_status,
+                "updated_by": x_user_id
+            }
+        )
+        
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Update employee status failed",
+            extra={
+                "operation": "update_employee_status",
+                "user_id": user_id,
+                "new_status": new_status,
+                "error": str(e),
+                "updated_by": x_user_id
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to update employee status")
 
 
 @router.patch(
@@ -419,16 +751,43 @@ async def update_location_consent(
     - Background tracking requires location_tracking_consent=True
     - Consent timestamp is automatically recorded
     """
-    from datetime import datetime
-    from app.staff.schemas.staff_schema import LocationSettingsSchema
-    
-    location_settings = LocationSettingsSchema(
-        location_tracking_consent=location_tracking_consent,
-        consent_given_at=datetime.utcnow() if location_tracking_consent else None,
-        consent_ip=consent_ip,
-        consent_device=consent_device,
-        background_tracking_opt_in=background_tracking_opt_in
-    )
-    
-    update_payload = EmployeeUpdate(location_settings=location_settings)
-    return await StaffService.update_employee(user_id, update_payload, x_user_id)
+    try:
+        from datetime import datetime
+        from app.staff.schemas.staff_schema import LocationSettingsSchema
+        
+        location_settings = LocationSettingsSchema(
+            location_tracking_consent=location_tracking_consent,
+            consent_given_at=datetime.utcnow() if location_tracking_consent else None,
+            consent_ip=consent_ip,
+            consent_device=consent_device,
+            background_tracking_opt_in=background_tracking_opt_in
+        )
+        
+        update_payload = EmployeeUpdate(location_settings=location_settings)
+        result = await StaffService.update_employee(user_id, update_payload, x_user_id)
+        
+        logger.info(
+            "Location consent updated",
+            extra={
+                "operation": "update_location_consent",
+                "user_id": user_id,
+                "location_tracking_consent": location_tracking_consent,
+                "updated_by": x_user_id
+            }
+        )
+        
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Update location consent failed",
+            extra={
+                "operation": "update_location_consent",
+                "user_id": user_id,
+                "error": str(e),
+                "updated_by": x_user_id
+            },
+            exc_info=True
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to update location consent")

app/staff/services/staff_service.py

@@ -5,7 +5,7 @@ Syncs staff data to both MongoDB and PostgreSQL (trans.pos_staff_ref).
 from datetime import datetime
 from typing import Optional, List, Dict, Any, Union
 from fastapi import HTTPException, status
-import logging
+from app.core.logging import get_logger
 import secrets
 from sqlalchemy import text
 
@@ -22,7 +22,7 @@ from app.staff.schemas.staff_schema import (
 )
 from app.constants.staff_types import Designation, stafftatus
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 
@@ -39,7 +39,7 @@ async def sync_staff_to_postgres(staff_id: str, merchant_id: str, staff_name: st
     try:
         async with get_postgres_session() as session:
             if session is None:
-                logger.warning("PostgreSQL not available, skipping staff sync")
+                logger.warning("PostgreSQL not available, skipping staff sync", extra={"operation": "sync_staff_to_postgres"})
                 return
             
             query = text("""
@@ -57,10 +57,25 @@ async def sync_staff_to_postgres(staff_id: str, merchant_id: str, staff_name: st
                 "staff_name": staff_name
             })
             await session.commit()
-            logger.info(f"Synced staff {staff_id} to trans.pos_staff_ref")
+            logger.info(
+                f"Synced staff {staff_id} to trans.pos_staff_ref",
+                extra={
+                    "operation": "sync_staff_to_postgres",
+                    "staff_id": staff_id,
+                    "merchant_id": str(merchant_id)
+                }
+            )
             
     except Exception as e:
-        logger.error(f"Failed to sync staff {staff_id} to PostgreSQL: {e}")
+        logger.error(
+            f"Failed to sync staff {staff_id} to PostgreSQL",
+            extra={
+                "operation": "sync_staff_to_postgres",
+                "staff_id": staff_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
         # Don't raise - PostgreSQL sync is secondary to MongoDB
 def generate_staff_id() -> str:
     """Generate a unique staff ID."""
@@ -102,13 +117,28 @@ class StaffService:
                 staff_name=payload.name
             )
             
-            logger.info(f"Created staff {staff_id} for merchant {payload.merchant_id}")
+            logger.info(
+                f"Created staff {staff_id}",
+                extra={
+                    "operation": "create_staff",
+                    "staff_id": staff_id,
+                    "merchant_id": str(payload.merchant_id)
+                }
+            )
             
             # Return response
             return StaffResponseSchema(**staff_data)
             
         except Exception as e:
-            logger.error(f"Error creating staff: {e}")
+            logger.error(
+                "Error creating staff",
+                extra={
+                    "operation": "create_staff",
+                    "error": str(e),
+                    "merchant_id": str(payload.merchant_id) if hasattr(payload, "merchant_id") else None
+                },
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail=f"Error creating staff: {str(e)}"
@@ -123,7 +153,15 @@ class StaffService:
                 return None
             return StaffResponseSchema(**staff)
         except Exception as e:
-            logger.error(f"Error fetching staff {staff_id}: {e}")
+            logger.error(
+                f"Error fetching staff {staff_id}",
+                extra={
+                    "operation": "get_staff_by_id",
+                    "staff_id": staff_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail="Error retrieving staff"
@@ -177,14 +215,35 @@ class StaffService:
                 )
 
             if result.modified_count == 0:
-                logger.warning(f"No changes made to staff {staff_id}")
+                logger.warning(
+                    f"No changes made to staff {staff_id}",
+                    extra={
+                        "operation": "update_staff",
+                        "staff_id": staff_id
+                    }
+                )
 
-            logger.info(f"Updated staff {staff_id}")
+            logger.info(
+                f"Updated staff {staff_id}",
+                extra={
+                    "operation": "update_staff",
+                    "staff_id": staff_id,
+                    "merchant_id": str(updated_staff.merchant_id) if updated_staff else None
+                }
+            )
 
             return updated_staff
             
         except Exception as e:
-            logger.error(f"Error updating staff {staff_id}: {e}")
+            logger.error(
+                f"Error updating staff {staff_id}",
+                extra={
+                    "operation": "update_staff",
+                    "staff_id": staff_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail=f"Error updating staff: {str(e)}"
@@ -223,11 +282,25 @@ class StaffService:
                 }
             )
             
-            logger.info(f"Deleted staff {staff_id}")
+            logger.info(
+                f"Deleted staff {staff_id}",
+                extra={
+                    "operation": "delete_staff",
+                    "staff_id": staff_id
+                }
+            )
             return {"message": f"Staff {staff_id} deleted successfully"}
             
         except Exception as e:
-            logger.error(f"Error deleting staff {staff_id}: {e}")
+            logger.error(
+                f"Error deleting staff {staff_id}",
+                extra={
+                    "operation": "delete_staff",
+                    "staff_id": staff_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail="Error deleting staff"
@@ -247,7 +320,15 @@ class StaffService:
         except HTTPException:
             raise
         except Exception as e:
-            logger.error(f"Error fetching employee {user_id}: {e}")
+            logger.error(
+                f"Error fetching employee {user_id}",
+                extra={
+                    "operation": "get_employee",
+                    "user_id": user_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail="Error retrieving employee"
@@ -269,7 +350,15 @@ class StaffService:
         except HTTPException:
             raise
         except Exception as e:
-            logger.error(f"Error fetching employee by code {employee_code}: {e}")
+            logger.error(
+                f"Error fetching employee by code {employee_code}",
+                extra={
+                    "operation": "get_employee_by_code",
+                    "employee_code": employee_code,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail="Error retrieving employee"
@@ -412,7 +501,14 @@ class StaffService:
                 return [EmployeeResponse(**staff) for staff in staff_list], total
             
         except Exception as e:
-            logger.error(f"Error listing staff: {e}")
+            logger.error(
+                "Error listing staff",
+                extra={
+                    "operation": "list_staff",
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail="Error listing staff"

app/sync/catalogue_services/sync_service.py

@@ -5,12 +5,12 @@ Handles CRUD operations to keep PostgreSQL catalogue_service_ref table in sync w
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select, delete, text
 from typing import Optional, Dict, Any, List
-import logging
 from datetime import datetime
+from app.core.logging import get_logger
 
 from app.sync.models import CatalogueServiceRef
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class CatalogueServiceSyncService:
@@ -66,10 +66,13 @@ class CatalogueServiceSyncService:
                 """
                 await self.pg_session.execute(text(create_table_sql))
                 await self.pg_session.commit()
-                logger.info("✅ Created catalogue_service_ref table in trans schema")
+                logger.info("✅ Created catalogue_service_ref table in trans schema", extra={"operation": "ensure_schema"})
                 
         except Exception as e:
-            logger.warning(f"Schema/table creation failed (may already exist): {e}")
+            logger.warning(
+                f"Schema/table creation failed (may already exist): {e}",
+                extra={"operation": "ensure_schema", "error": str(e)}
+            )
 
     def _extract_sync_data(self, service_data: Dict[str, Any]) -> Dict[str, Any]:
         """Extract relevant data for PostgreSQL sync"""
@@ -116,12 +119,27 @@ class CatalogueServiceSyncService:
             await self.pg_session.commit()
             await self.pg_session.refresh(service_ref)
             
-            logger.info(f"Created catalogue service reference: {service_data.get('_id') or service_data.get('service_id')}")
+            logger.info(
+                f"Created catalogue service reference: {service_data.get('_id') or service_data.get('service_id')}",
+                extra={
+                    "operation": "create_catalogue_service_ref",
+                    "service_id": service_data.get('_id') or service_data.get('service_id'),
+                    "merchant_id": service_data.get('merchant_id')
+                }
+            )
             return service_ref
             
         except Exception as e:
             await self.pg_session.rollback()
-            logger.error(f"Error creating catalogue service reference: {e}")
+            logger.error(
+                f"Error creating catalogue service reference: {e}",
+                extra={
+                    "operation": "create_catalogue_service_ref",
+                    "service_id": service_data.get('_id') or service_data.get('service_id'),
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
 
     async def update_catalogue_service_ref(self, service_id: str, service_data: Dict[str, Any]) -> Optional[CatalogueServiceRef]:
@@ -135,7 +153,10 @@ class CatalogueServiceSyncService:
             service_ref = result.scalar_one_or_none()
             
             if not service_ref:
-                logger.warning(f"Catalogue service reference not found for update: {service_id}")
+                logger.warning(
+                    f"Catalogue service reference not found for update: {service_id}",
+                    extra={"operation": "update_catalogue_service_ref", "service_id": service_id}
+                )
                 return None
 
             # Update with new data
@@ -149,12 +170,19 @@ class CatalogueServiceSyncService:
             await self.pg_session.commit()
             await self.pg_session.refresh(service_ref)
             
-            logger.info(f"Updated catalogue service reference: {service_id}")
+            logger.info(
+                f"Updated catalogue service reference: {service_id}",
+                extra={"operation": "update_catalogue_service_ref", "service_id": service_id, "merchant_id": sync_data.get('merchant_id')}
+            )
             return service_ref
             
         except Exception as e:
             await self.pg_session.rollback()
-            logger.error(f"Error updating catalogue service reference: {e}")
+            logger.error(
+                f"Error updating catalogue service reference: {e}",
+                extra={"operation": "update_catalogue_service_ref", "service_id": service_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def delete_catalogue_service_ref(self, service_id: str) -> bool:
@@ -168,15 +196,25 @@ class CatalogueServiceSyncService:
             await self.pg_session.commit()
             
             if deleted_count > 0:
-                logger.info(f"Deleted catalogue service reference: {service_id}")
+                logger.info(
+                    f"Deleted catalogue service reference: {service_id}",
+                    extra={"operation": "delete_catalogue_service_ref", "service_id": service_id}
+                )
                 return True
             else:
-                logger.warning(f"Catalogue service reference not found for deletion: {service_id}")
+                logger.warning(
+                    f"Catalogue service reference not found for deletion: {service_id}",
+                    extra={"operation": "delete_catalogue_service_ref", "service_id": service_id}
+                )
                 return False
                 
         except Exception as e:
             await self.pg_session.rollback()
-            logger.error(f"Error deleting catalogue service reference: {e}")
+            logger.error(
+                f"Error deleting catalogue service reference: {e}",
+                extra={"operation": "delete_catalogue_service_ref", "service_id": service_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def get_catalogue_service_ref(self, service_id: str) -> Optional[CatalogueServiceRef]:
@@ -188,7 +226,11 @@ class CatalogueServiceSyncService:
             return result.scalar_one_or_none()
             
         except Exception as e:
-            logger.error(f"Error getting catalogue service reference: {e}")
+            logger.error(
+                f"Error getting catalogue service reference: {e}",
+                extra={"operation": "get_catalogue_service_ref", "service_id": service_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def sync_catalogue_service_status(self, service_id: str, status: str) -> bool:
@@ -203,15 +245,25 @@ class CatalogueServiceSyncService:
                 service_ref.status = status
                 service_ref.updated_at = datetime.utcnow()
                 await self.pg_session.commit()
-                logger.info(f"Updated catalogue service status: {service_id} -> {status}")
+                logger.info(
+                    f"Updated catalogue service status: {service_id} -> {status}",
+                    extra={"operation": "sync_catalogue_service_status", "service_id": service_id, "status": status}
+                )
                 return True
             else:
-                logger.warning(f"Catalogue service reference not found for status update: {service_id}")
+                logger.warning(
+                    f"Catalogue service reference not found for status update: {service_id}",
+                    extra={"operation": "sync_catalogue_service_status", "service_id": service_id}
+                )
                 return False
                 
         except Exception as e:
             await self.pg_session.rollback()
-            logger.error(f"Error updating catalogue service status: {e}")
+            logger.error(
+                f"Error updating catalogue service status: {e}",
+                extra={"operation": "sync_catalogue_service_status", "service_id": service_id, "status": status, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def list_catalogue_services_by_merchant(self, merchant_id: str, limit: int = 100, offset: int = 0) -> List[CatalogueServiceRef]:
@@ -227,7 +279,11 @@ class CatalogueServiceSyncService:
             return result.scalars().all()
             
         except Exception as e:
-            logger.error(f"Error listing catalogue services by merchant: {e}")
+            logger.error(
+                f"Error listing catalogue services by merchant: {e}",
+                extra={"operation": "list_catalogue_services_by_merchant", "merchant_id": merchant_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def search_catalogue_services(self, merchant_id: str, search_term: str, limit: int = 50) -> List[CatalogueServiceRef]:
@@ -249,7 +305,11 @@ class CatalogueServiceSyncService:
             return result.scalars().all()
             
         except Exception as e:
-            logger.error(f"Error searching catalogue services: {e}")
+            logger.error(
+                f"Error searching catalogue services: {e}",
+                extra={"operation": "search_catalogue_services", "merchant_id": merchant_id, "search_term": search_term, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def list_catalogue_services_by_category(self, merchant_id: str, category_id: str) -> List[CatalogueServiceRef]:
@@ -266,7 +326,11 @@ class CatalogueServiceSyncService:
             return result.scalars().all()
             
         except Exception as e:
-            logger.error(f"Error listing catalogue services by category: {e}")
+            logger.error(
+                f"Error listing catalogue services by category: {e}",
+                extra={"operation": "list_catalogue_services_by_category", "merchant_id": merchant_id, "category_id": category_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def list_catalogue_services_by_status(self, merchant_id: str, status: str) -> List[CatalogueServiceRef]:
@@ -283,7 +347,11 @@ class CatalogueServiceSyncService:
             return result.scalars().all()
             
         except Exception as e:
-            logger.error(f"Error listing catalogue services by status: {e}")
+            logger.error(
+                f"Error listing catalogue services by status: {e}",
+                extra={"operation": "list_catalogue_services_by_status", "merchant_id": merchant_id, "status": status, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def get_service_pricing_summary(self, merchant_id: str) -> Dict[str, Any]:
@@ -314,5 +382,9 @@ class CatalogueServiceSyncService:
             }
             
         except Exception as e:
-            logger.error(f"Error getting service pricing summary: {e}")
+            logger.error(
+                f"Error getting service pricing summary: {e}",
+                extra={"operation": "get_service_pricing_summary", "merchant_id": merchant_id, "error": str(e)},
+                exc_info=True
+            )
             raise

app/sync/customers/sync_service.py

@@ -5,13 +5,13 @@ Handles CRUD operations to keep PostgreSQL customer_ref table in sync with Mongo
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select, delete, text
 from typing import Optional, Dict, Any
-import logging
 from datetime import datetime
+from app.core.logging import get_logger
 
 from app.sync.models import CustomerRef
 from app.customers.models.model import CustomerModel
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class CustomerSyncService:
@@ -58,10 +58,13 @@ class CustomerSyncService:
                 """
                 await self.pg_session.execute(text(create_table_sql))
                 await self.pg_session.commit()
-                logger.info("✅ Created customer_ref table in trans schema")
+                logger.info("✅ Created customer_ref table in trans schema", extra={"operation": "ensure_schema"})
                 
         except Exception as e:
-            logger.warning(f"Schema/table creation failed (may already exist): {e}")
+            logger.warning(
+                f"Schema/table creation failed (may already exist): {e}",
+                extra={"operation": "ensure_schema", "error": str(e)}
+            )
             # Best-effort: if creation fails, proceed; operations may still succeed
 
     def _extract_sync_data(self, customer: CustomerModel) -> Dict[str, Any]:
@@ -89,12 +92,19 @@ class CustomerSyncService:
             await self.pg_session.commit()
             await self.pg_session.refresh(customer_ref)
             
-            logger.info(f"Created customer reference: {customer.customer_id}")
+            logger.info(
+                f"Created customer reference: {customer.customer_id}",
+                extra={"operation": "create_customer_ref", "customer_id": customer.customer_id, "merchant_id": customer.merchant_id}
+            )
             return customer_ref
             
         except Exception as e:
             await self.pg_session.rollback()
-            logger.error(f"Error creating customer reference: {e}")
+            logger.error(
+                f"Error creating customer reference: {e}",
+                extra={"operation": "create_customer_ref", "customer_id": customer.customer_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def update_customer_ref(self, customer_id: str, customer: CustomerModel) -> Optional[CustomerRef]:
@@ -108,7 +118,10 @@ class CustomerSyncService:
             customer_ref = result.scalar_one_or_none()
             
             if not customer_ref:
-                logger.warning(f"Customer reference not found for update: {customer_id}")
+                logger.warning(
+                    f"Customer reference not found for update: {customer_id}",
+                    extra={"operation": "update_customer_ref", "customer_id": customer_id}
+                )
                 return None
 
             # Update with new data
@@ -121,12 +134,19 @@ class CustomerSyncService:
             await self.pg_session.commit()
             await self.pg_session.refresh(customer_ref)
             
-            logger.info(f"Updated customer reference: {customer_id}")
+            logger.info(
+                f"Updated customer reference: {customer_id}",
+                extra={"operation": "update_customer_ref", "customer_id": customer_id, "merchant_id": customer.merchant_id}
+            )
             return customer_ref
             
         except Exception as e:
             await self.pg_session.rollback()
-            logger.error(f"Error updating customer reference: {e}")
+            logger.error(
+                f"Error updating customer reference: {e}",
+                extra={"operation": "update_customer_ref", "customer_id": customer_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def delete_customer_ref(self, customer_id: str) -> bool:
@@ -140,15 +160,25 @@ class CustomerSyncService:
             await self.pg_session.commit()
             
             if deleted_count > 0:
-                logger.info(f"Deleted customer reference: {customer_id}")
+                logger.info(
+                    f"Deleted customer reference: {customer_id}",
+                    extra={"operation": "delete_customer_ref", "customer_id": customer_id}
+                )
                 return True
             else:
-                logger.warning(f"Customer reference not found for deletion: {customer_id}")
+                logger.warning(
+                    f"Customer reference not found for deletion: {customer_id}",
+                    extra={"operation": "delete_customer_ref", "customer_id": customer_id}
+                )
                 return False
                 
         except Exception as e:
             await self.pg_session.rollback()
-            logger.error(f"Error deleting customer reference: {e}")
+            logger.error(
+                f"Error deleting customer reference: {e}",
+                extra={"operation": "delete_customer_ref", "customer_id": customer_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def get_customer_ref(self, customer_id: str) -> Optional[CustomerRef]:
@@ -160,7 +190,11 @@ class CustomerSyncService:
             return result.scalar_one_or_none()
             
         except Exception as e:
-            logger.error(f"Error getting customer reference: {e}")
+            logger.error(
+                f"Error getting customer reference: {e}",
+                extra={"operation": "get_customer_ref", "customer_id": customer_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def sync_customer_status(self, customer_id: str, status: str) -> bool:
@@ -175,15 +209,25 @@ class CustomerSyncService:
                 customer_ref.status = status
                 customer_ref.updated_at = datetime.utcnow()
                 await self.pg_session.commit()
-                logger.info(f"Updated customer status: {customer_id} -> {status}")
+                logger.info(
+                    f"Updated customer status: {customer_id} -> {status}",
+                    extra={"operation": "sync_customer_status", "customer_id": customer_id, "status": status}
+                )
                 return True
             else:
-                logger.warning(f"Customer reference not found for status update: {customer_id}")
+                logger.warning(
+                    f"Customer reference not found for status update: {customer_id}",
+                    extra={"operation": "sync_customer_status", "customer_id": customer_id}
+                )
                 return False
                 
         except Exception as e:
             await self.pg_session.rollback()
-            logger.error(f"Error updating customer status: {e}")
+            logger.error(
+                f"Error updating customer status: {e}",
+                extra={"operation": "sync_customer_status", "customer_id": customer_id, "status": status, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def list_customers_by_merchant(self, merchant_id: str, limit: int = 100, offset: int = 0) -> list:
@@ -199,7 +243,11 @@ class CustomerSyncService:
             return result.scalars().all()
             
         except Exception as e:
-            logger.error(f"Error listing customers by merchant: {e}")
+            logger.error(
+                f"Error listing customers by merchant: {e}",
+                extra={"operation": "list_customers_by_merchant", "merchant_id": merchant_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def search_customers(self, merchant_id: str, search_term: str, limit: int = 50) -> list:
@@ -222,5 +270,9 @@ class CustomerSyncService:
             return result.scalars().all()
             
         except Exception as e:
-            logger.error(f"Error searching customers: {e}")
+            logger.error(
+                f"Error searching customers: {e}",
+                extra={"operation": "search_customers", "merchant_id": merchant_id, "search_term": search_term, "error": str(e)},
+                exc_info=True
+            )
             raise

app/sync/staff/sync_service.py

@@ -5,12 +5,12 @@ Handles CRUD operations to keep PostgreSQL staff_ref table in sync with MongoDB.
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select, delete, text
 from typing import Optional, Dict, Any, List
-import logging
 from datetime import datetime
+from app.core.logging import get_logger
 
 from app.sync.models import StaffRef
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class StaffSyncService:
@@ -57,10 +57,13 @@ class StaffSyncService:
                 """
                 await self.pg_session.execute(text(create_table_sql))
                 await self.pg_session.commit()
-                logger.info("✅ Created pos_staff_ref table in trans schema")
+                logger.info("✅ Created pos_staff_ref table in trans schema", extra={"operation": "ensure_schema"})
                 
         except Exception as e:
-            logger.warning(f"Schema/table creation failed (may already exist): {e}")
+            logger.warning(
+                f"Schema/table creation failed (may already exist): {e}",
+                extra={"operation": "ensure_schema", "error": str(e)}
+            )
 
     def _extract_sync_data(self, staff_data: Dict[str, Any]) -> Dict[str, Any]:
         """Extract relevant data for PostgreSQL sync"""
@@ -88,12 +91,19 @@ class StaffSyncService:
             await self.pg_session.commit()
             await self.pg_session.refresh(staff_ref)
             
-            logger.info(f"Created staff reference: {staff_data.get('staff_id')}")
+            logger.info(
+                f"Created staff reference: {staff_data.get('staff_id')}",
+                extra={"operation": "create_staff_ref", "staff_id": staff_data.get('staff_id'), "merchant_id": staff_data.get('merchant_id')}
+            )
             return staff_ref
             
         except Exception as e:
             await self.pg_session.rollback()
-            logger.error(f"Error creating staff reference: {e}")
+            logger.error(
+                f"Error creating staff reference: {e}",
+                extra={"operation": "create_staff_ref", "staff_id": staff_data.get('staff_id'), "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def update_staff_ref(self, staff_id: str, staff_data: Dict[str, Any]) -> Optional[StaffRef]:
@@ -107,7 +117,10 @@ class StaffSyncService:
             staff_ref = result.scalar_one_or_none()
             
             if not staff_ref:
-                logger.warning(f"Staff reference not found for update: {staff_id}")
+                logger.warning(
+                    f"Staff reference not found for update: {staff_id}",
+                    extra={"operation": "update_staff_ref", "staff_id": staff_id}
+                )
                 return None
 
             # Update with new data
@@ -121,12 +134,19 @@ class StaffSyncService:
             await self.pg_session.commit()
             await self.pg_session.refresh(staff_ref)
             
-            logger.info(f"Updated staff reference: {staff_id}")
+            logger.info(
+                f"Updated staff reference: {staff_id}",
+                extra={"operation": "update_staff_ref", "staff_id": staff_id, "merchant_id": sync_data.get('merchant_id')}
+            )
             return staff_ref
             
         except Exception as e:
             await self.pg_session.rollback()
-            logger.error(f"Error updating staff reference: {e}")
+            logger.error(
+                f"Error updating staff reference: {e}",
+                extra={"operation": "update_staff_ref", "staff_id": staff_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def delete_staff_ref(self, staff_id: str) -> bool:
@@ -140,15 +160,25 @@ class StaffSyncService:
             await self.pg_session.commit()
             
             if deleted_count > 0:
-                logger.info(f"Deleted staff reference: {staff_id}")
+                logger.info(
+                    f"Deleted staff reference: {staff_id}",
+                    extra={"operation": "delete_staff_ref", "staff_id": staff_id}
+                )
                 return True
             else:
-                logger.warning(f"Staff reference not found for deletion: {staff_id}")
+                logger.warning(
+                    f"Staff reference not found for deletion: {staff_id}",
+                    extra={"operation": "delete_staff_ref", "staff_id": staff_id}
+                )
                 return False
                 
         except Exception as e:
             await self.pg_session.rollback()
-            logger.error(f"Error deleting staff reference: {e}")
+            logger.error(
+                f"Error deleting staff reference: {e}",
+                extra={"operation": "delete_staff_ref", "staff_id": staff_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def get_staff_ref(self, staff_id: str) -> Optional[StaffRef]:
@@ -160,7 +190,11 @@ class StaffSyncService:
             return result.scalar_one_or_none()
             
         except Exception as e:
-            logger.error(f"Error getting staff reference: {e}")
+            logger.error(
+                f"Error getting staff reference: {e}",
+                extra={"operation": "get_staff_ref", "staff_id": staff_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def sync_staff_status(self, staff_id: str, status: str) -> bool:
@@ -175,15 +209,25 @@ class StaffSyncService:
                 staff_ref.status = status
                 staff_ref.updated_at = datetime.utcnow()
                 await self.pg_session.commit()
-                logger.info(f"Updated staff status: {staff_id} -> {status}")
+                logger.info(
+                    f"Updated staff status: {staff_id} -> {status}",
+                    extra={"operation": "sync_staff_status", "staff_id": staff_id, "status": status}
+                )
                 return True
             else:
-                logger.warning(f"Staff reference not found for status update: {staff_id}")
+                logger.warning(
+                    f"Staff reference not found for status update: {staff_id}",
+                    extra={"operation": "sync_staff_status", "staff_id": staff_id}
+                )
                 return False
                 
         except Exception as e:
             await self.pg_session.rollback()
-            logger.error(f"Error updating staff status: {e}")
+            logger.error(
+                f"Error updating staff status: {e}",
+                extra={"operation": "sync_staff_status", "staff_id": staff_id, "status": status, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def list_staff_by_merchant(self, merchant_id: str, limit: int = 100, offset: int = 0) -> List[StaffRef]:
@@ -199,7 +243,11 @@ class StaffSyncService:
             return result.scalars().all()
             
         except Exception as e:
-            logger.error(f"Error listing staff by merchant: {e}")
+            logger.error(
+                f"Error listing staff by merchant: {e}",
+                extra={"operation": "list_staff_by_merchant", "merchant_id": merchant_id, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def search_staff(self, merchant_id: str, search_term: str, limit: int = 50) -> List[StaffRef]:
@@ -222,7 +270,11 @@ class StaffSyncService:
             return result.scalars().all()
             
         except Exception as e:
-            logger.error(f"Error searching staff: {e}")
+            logger.error(
+                f"Error searching staff: {e}",
+                extra={"operation": "search_staff", "merchant_id": merchant_id, "search_term": search_term, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def list_staff_by_role(self, merchant_id: str, role: str) -> List[StaffRef]:
@@ -239,7 +291,11 @@ class StaffSyncService:
             return result.scalars().all()
             
         except Exception as e:
-            logger.error(f"Error listing staff by role: {e}")
+            logger.error(
+                f"Error listing staff by role: {e}",
+                extra={"operation": "list_staff_by_role", "merchant_id": merchant_id, "role": role, "error": str(e)},
+                exc_info=True
+            )
             raise
 
     async def list_staff_by_specialization(self, merchant_id: str, specialization: str) -> List[StaffRef]:
@@ -256,5 +312,9 @@ class StaffSyncService:
             return result.scalars().all()
             
         except Exception as e:
-            logger.error(f"Error listing staff by specialization: {e}")
+            logger.error(
+                f"Error listing staff by specialization: {e}",
+                extra={"operation": "list_staff_by_specialization", "merchant_id": merchant_id, "specialization": specialization, "error": str(e)},
+                exc_info=True
+            )
             raise

app/sync/sync_service.py

@@ -4,14 +4,14 @@ Coordinates all sync operations across different entities.
 """
 from sqlalchemy.ext.asyncio import AsyncSession
 from typing import Dict, Any, Optional
-import logging
-
+from datetime import datetime
+from app.core.logging import get_logger
 from app.sync.customers.sync_service import CustomerSyncService
 from app.sync.staff.sync_service import StaffSyncService
 from app.sync.catalogue_services.sync_service import CatalogueServiceSyncService
 from app.customers.models.model import CustomerModel
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class POSSyncService:
@@ -29,7 +29,16 @@ class POSSyncService:
         try:
             return await self.customer_sync.create_customer_ref(customer)
         except Exception as e:
-            logger.error(f"Error syncing customer creation: {e}")
+            logger.error(
+                f"Error syncing customer creation: {e}",
+                extra={
+                    "operation": "sync_customer_create",
+                    "customer_id": customer.customer_id,
+                    "merchant_id": customer.merchant_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     
     async def sync_customer_update(self, customer_id: str, customer: CustomerModel):
@@ -37,7 +46,15 @@ class POSSyncService:
         try:
             return await self.customer_sync.update_customer_ref(customer_id, customer)
         except Exception as e:
-            logger.error(f"Error syncing customer update: {e}")
+            logger.error(
+                f"Error syncing customer update: {e}",
+                extra={
+                    "operation": "sync_customer_update",
+                    "customer_id": customer_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     
     async def sync_customer_delete(self, customer_id: str):
@@ -45,7 +62,15 @@ class POSSyncService:
         try:
             return await self.customer_sync.delete_customer_ref(customer_id)
         except Exception as e:
-            logger.error(f"Error syncing customer deletion: {e}")
+            logger.error(
+                f"Error syncing customer deletion: {e}",
+                extra={
+                    "operation": "sync_customer_delete",
+                    "customer_id": customer_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     
     async def sync_customer_status(self, customer_id: str, status: str):
@@ -53,7 +78,16 @@ class POSSyncService:
         try:
             return await self.customer_sync.sync_customer_status(customer_id, status)
         except Exception as e:
-            logger.error(f"Error syncing customer status: {e}")
+            logger.error(
+                f"Error syncing customer status: {e}",
+                extra={
+                    "operation": "sync_customer_status",
+                    "customer_id": customer_id,
+                    "status": status,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     
     # Staff sync operations
@@ -62,7 +96,16 @@ class POSSyncService:
         try:
             return await self.staff_sync.create_staff_ref(staff_data)
         except Exception as e:
-            logger.error(f"Error syncing staff creation: {e}")
+            logger.error(
+                f"Error syncing staff creation: {e}",
+                extra={
+                    "operation": "sync_staff_create",
+                    "staff_id": staff_data.get('staff_id'),
+                    "merchant_id": staff_data.get('merchant_id'),
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     
     async def sync_staff_update(self, staff_id: str, staff_data: Dict[str, Any]):
@@ -70,7 +113,15 @@ class POSSyncService:
         try:
             return await self.staff_sync.update_staff_ref(staff_id, staff_data)
         except Exception as e:
-            logger.error(f"Error syncing staff update: {e}")
+            logger.error(
+                f"Error syncing staff update: {e}",
+                extra={
+                    "operation": "sync_staff_update",
+                    "staff_id": staff_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     
     async def sync_staff_delete(self, staff_id: str):
@@ -78,7 +129,15 @@ class POSSyncService:
         try:
             return await self.staff_sync.delete_staff_ref(staff_id)
         except Exception as e:
-            logger.error(f"Error syncing staff deletion: {e}")
+            logger.error(
+                f"Error syncing staff deletion: {e}",
+                extra={
+                    "operation": "sync_staff_delete",
+                    "staff_id": staff_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     
     async def sync_staff_status(self, staff_id: str, status: str):
@@ -86,7 +145,16 @@ class POSSyncService:
         try:
             return await self.staff_sync.sync_staff_status(staff_id, status)
         except Exception as e:
-            logger.error(f"Error syncing staff status: {e}")
+            logger.error(
+                f"Error syncing staff status: {e}",
+                extra={
+                    "operation": "sync_staff_status",
+                    "staff_id": staff_id,
+                    "status": status,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     
     # Catalogue service sync operations
@@ -95,7 +163,16 @@ class POSSyncService:
         try:
             return await self.catalogue_service_sync.create_catalogue_service_ref(service_data)
         except Exception as e:
-            logger.error(f"Error syncing catalogue service creation: {e}")
+            logger.error(
+                f"Error syncing catalogue service creation: {e}",
+                extra={
+                    "operation": "sync_catalogue_service_create",
+                    "service_id": service_data.get('_id') or service_data.get('service_id'),
+                    "merchant_id": service_data.get('merchant_id'),
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     
     async def sync_catalogue_service_update(self, service_id: str, service_data: Dict[str, Any]):
@@ -103,7 +180,15 @@ class POSSyncService:
         try:
             return await self.catalogue_service_sync.update_catalogue_service_ref(service_id, service_data)
         except Exception as e:
-            logger.error(f"Error syncing catalogue service update: {e}")
+            logger.error(
+                f"Error syncing catalogue service update: {e}",
+                extra={
+                    "operation": "sync_catalogue_service_update",
+                    "service_id": service_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     
     async def sync_catalogue_service_delete(self, service_id: str):
@@ -111,7 +196,15 @@ class POSSyncService:
         try:
             return await self.catalogue_service_sync.delete_catalogue_service_ref(service_id)
         except Exception as e:
-            logger.error(f"Error syncing catalogue service deletion: {e}")
+            logger.error(
+                f"Error syncing catalogue service deletion: {e}",
+                extra={
+                    "operation": "sync_catalogue_service_delete",
+                    "service_id": service_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     
     async def sync_catalogue_service_status(self, service_id: str, status: str):
@@ -119,7 +212,16 @@ class POSSyncService:
         try:
             return await self.catalogue_service_sync.sync_catalogue_service_status(service_id, status)
         except Exception as e:
-            logger.error(f"Error syncing catalogue service status: {e}")
+            logger.error(
+                f"Error syncing catalogue service status: {e}",
+                extra={
+                    "operation": "sync_catalogue_service_status",
+                    "service_id": service_id,
+                    "status": status,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
             raise
     
     # Bulk sync operations
@@ -131,7 +233,16 @@ class POSSyncService:
                 result = await self.customer_sync.create_customer_ref(customer)
                 results.append({"customer_id": customer.customer_id, "status": "success", "result": result})
             except Exception as e:
-                logger.error(f"Error bulk syncing customer {customer.customer_id}: {e}")
+                logger.error(
+                    f"Error bulk syncing customer {customer.customer_id}: {e}",
+                    extra={
+                        "operation": "bulk_sync_customers",
+                        "customer_id": customer.customer_id,
+                        "merchant_id": customer.merchant_id,
+                        "error": str(e)
+                    },
+                    exc_info=True
+                )
                 results.append({"customer_id": customer.customer_id, "status": "error", "error": str(e)})
         return results
     
@@ -143,7 +254,16 @@ class POSSyncService:
                 result = await self.staff_sync.create_staff_ref(staff_data)
                 results.append({"staff_id": staff_data.get('staff_id'), "status": "success", "result": result})
             except Exception as e:
-                logger.error(f"Error bulk syncing staff {staff_data.get('staff_id')}: {e}")
+                logger.error(
+                    f"Error bulk syncing staff {staff_data.get('staff_id')}: {e}",
+                    extra={
+                        "operation": "bulk_sync_staff",
+                        "staff_id": staff_data.get('staff_id'),
+                        "merchant_id": staff_data.get('merchant_id'),
+                        "error": str(e)
+                    },
+                    exc_info=True
+                )
                 results.append({"staff_id": staff_data.get('staff_id'), "status": "error", "error": str(e)})
         return results
     
@@ -155,7 +275,16 @@ class POSSyncService:
                 result = await self.catalogue_service_sync.create_catalogue_service_ref(service_data)
                 results.append({"service_id": service_data.get('_id') or service_data.get('service_id'), "status": "success", "result": result})
             except Exception as e:
-                logger.error(f"Error bulk syncing catalogue service {service_data.get('_id') or service_data.get('service_id')}: {e}")
+                logger.error(
+                    f"Error bulk syncing catalogue service {service_data.get('_id') or service_data.get('service_id')}: {e}",
+                    extra={
+                        "operation": "bulk_sync_catalogue_services",
+                        "service_id": service_data.get('_id') or service_data.get('service_id'),
+                        "merchant_id": service_data.get('merchant_id'),
+                        "error": str(e)
+                    },
+                    exc_info=True
+                )
                 results.append({"service_id": service_data.get('_id') or service_data.get('service_id'), "status": "error", "error": str(e)})
         return results
     
@@ -169,7 +298,11 @@ class POSSyncService:
                 await self.customer_sync._ensure_customer_ref_schema()
             except Exception as e:
                 customer_health = False
-                logger.error(f"Customer sync health check failed: {e}")
+                logger.error(
+                    f"Customer sync health check failed: {e}",
+                    extra={"operation": "check_sync_health", "component": "customer_sync", "error": str(e)},
+                    exc_info=True
+                )
             
             # Test staff sync
             staff_health = True
@@ -177,7 +310,11 @@ class POSSyncService:
                 await self.staff_sync._ensure_staff_ref_schema()
             except Exception as e:
                 staff_health = False
-                logger.error(f"Staff sync health check failed: {e}")
+                logger.error(
+                    f"Staff sync health check failed: {e}",
+                    extra={"operation": "check_sync_health", "component": "staff_sync", "error": str(e)},
+                    exc_info=True
+                )
             
             # Test catalogue service sync
             catalogue_service_health = True
@@ -185,18 +322,27 @@ class POSSyncService:
                 await self.catalogue_service_sync._ensure_catalogue_service_ref_schema()
             except Exception as e:
                 catalogue_service_health = False
-                logger.error(f"Catalogue service sync health check failed: {e}")
+                logger.error(
+                    f"Catalogue service sync health check failed: {e}",
+                    extra={"operation": "check_sync_health", "component": "catalogue_service_sync", "error": str(e)},
+                    exc_info=True
+                )
             
+            logger.info("Sync health check completed", extra={"operation": "check_sync_health"})
             return {
                 "overall_health": customer_health and staff_health and catalogue_service_health,
                 "customer_sync": customer_health,
                 "staff_sync": staff_health,
                 "catalogue_service_sync": catalogue_service_health,
-                "timestamp": logger.info("Sync health check completed")
+                "timestamp": datetime.utcnow()
             }
             
         except Exception as e:
-            logger.error(f"Error checking sync health: {e}")
+            logger.error(
+                f"Error checking sync health: {e}",
+                extra={"operation": "check_sync_health", "error": str(e)},
+                exc_info=True
+            )
             return {
                 "overall_health": False,
                 "error": str(e)

logger_expection.md

@@ -0,0 +1,399 @@
+# Logger & Error Handling Implementation Summary
+
+## Quick Reference for New Modules
+
+### 1. Logger Setup (One line per module)
+```python
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+```
+
+---
+
+## Error Handling Patterns
+
+### Pattern 1: Simple Error with Context
+```python
+try:
+    result = await operation()
+except SpecificException as e:
+    logger.error(
+        "Operation failed",
+        extra={
+            "operation": "operation_name",
+            "error": str(e),
+            "error_type": type(e).__name__
+        },
+        exc_info=True
+    )
+    raise HTTPException(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        detail="Operation failed"
+    )
+```
+
+### Pattern 2: Validation Error with Details
+```python
+if not email or "@" not in email:
+    logger.warning(
+        "Validation failed",
+        extra={
+            "field": "email",
+            "value_provided": bool(email),
+            "validation": "email_format",
+            "user_id": user_id
+        }
+    )
+    raise HTTPException(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        detail="Invalid email format"
+    )
+```
+
+### Pattern 3: Authentication Error
+```python
+if not token:
+    logger.warning(
+        "Authentication failed",
+        extra={
+            "reason": "missing_token",
+            "endpoint": request.url.path,
+            "client_ip": request.client.host if request.client else None
+        }
+    )
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Missing authentication token"
+    )
+```
+
+### Pattern 4: Permission Denied
+```python
+if user.role not in required_roles:
+    logger.warning(
+        "Access denied",
+        extra={
+            "user_id": str(user.id),
+            "user_role": user.role,
+            "required_role": required_roles,
+            "resource": request.url.path
+        }
+    )
+    raise HTTPException(
+        status_code=status.HTTP_403_FORBIDDEN,
+        detail="Insufficient permissions"
+    )
+```
+
+### Pattern 5: Database Error
+```python
+try:
+    result = await collection.insert_one(data)
+except PyMongoError as e:
+    logger.error(
+        "Database operation failed",
+        extra={
+            "operation": "insert_one",
+            "collection": "collection_name",
+            "error": str(e),
+            "error_type": type(e).__name__
+        },
+        exc_info=True
+    )
+    raise HTTPException(
+        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+        detail="Database operation failed"
+    )
+```
+
+### Pattern 6: Success with Context
+```python
+logger.info(
+    "User login successful",
+    extra={
+        "user_id": user.id,
+        "username": user.username,
+        "method": "password",
+        "ip_address": request.client.host
+    }
+)
+```
+
+---
+
+## Global Exception Handlers (in main.py)
+
+```python
+from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError
+from pydantic import ValidationError
+from jose import JWTError
+from pymongo.errors import PyMongoError, ConnectionFailure, OperationFailure
+
+# 1. Request Validation Errors
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    errors = [
+        {
+            "field": " -> ".join(str(loc) for loc in error["loc"]),
+            "message": error["msg"],
+            "type": error["type"]
+        }
+        for error in exc.errors()
+    ]
+    
+    logger.warning(
+        "Validation error",
+        extra={
+            "path": request.url.path,
+            "method": request.method,
+            "error_count": len(errors),
+            "errors": errors
+        }
+    )
+    
+    return JSONResponse(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        content={
+            "success": False,
+            "error": "Validation Error",
+            "errors": errors
+        }
+    )
+
+# 2. JWT Errors
+@app.exception_handler(JWTError)
+async def jwt_exception_handler(request: Request, exc: JWTError):
+    logger.warning(
+        "JWT authentication failed",
+        extra={
+            "path": request.url.path,
+            "error": str(exc),
+            "client_ip": request.client.host if request.client else None
+        }
+    )
+    
+    return JSONResponse(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        content={
+            "success": False,
+            "error": "Unauthorized",
+            "detail": "Invalid or expired token"
+        }
+    )
+
+# 3. MongoDB Errors
+@app.exception_handler(PyMongoError)
+async def mongodb_exception_handler(request: Request, exc: PyMongoError):
+    logger.error(
+        "Database error",
+        extra={
+            "path": request.url.path,
+            "error": str(exc),
+            "error_type": type(exc).__name__
+        },
+        exc_info=True
+    )
+    
+    if isinstance(exc, ConnectionFailure):
+        status_code = status.HTTP_503_SERVICE_UNAVAILABLE
+        detail = "Database connection failed"
+    elif isinstance(exc, OperationFailure):
+        status_code = status.HTTP_500_INTERNAL_SERVER_ERROR
+        detail = "Database operation failed"
+    else:
+        status_code = status.HTTP_500_INTERNAL_SERVER_ERROR
+        detail = "Database error occurred"
+    
+    return JSONResponse(
+        status_code=status_code,
+        content={
+            "success": False,
+            "error": "Database Error",
+            "detail": detail
+        }
+    )
+
+# 4. General Exception Handler
+@app.exception_handler(Exception)
+async def general_exception_handler(request: Request, exc: Exception):
+    logger.error(
+        "Unhandled exception",
+        extra={
+            "method": request.method,
+            "path": request.url.path,
+            "error": str(exc),
+            "error_type": type(exc).__name__,
+            "client_ip": request.client.host if request.client else None
+        },
+        exc_info=True
+    )
+    
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content={
+            "success": False,
+            "error": "Internal Server Error",
+            "detail": "An unexpected error occurred"
+        }
+    )
+```
+
+---
+
+## Context Fields Reference
+
+| Field | Usage | Examples |
+|-------|-------|----------|
+| `user_id` | User identifier | "usr_123" |
+| `username` | Username | "john_doe" |
+| `email` | Email address | "john@example.com" |
+| `operation` | Action being performed | "insert_user", "delete_account" |
+| `error` | Error message | str(exception) |
+| `error_type` | Exception class | "ValidationError", "ConnectionFailure" |
+| `status_code` | HTTP status | 400, 401, 403, 500 |
+| `path` | Request path | "/api/users/login" |
+| `method` | HTTP method | "POST", "GET", "PUT" |
+| `client_ip` | Client IP | "192.168.1.1" |
+| `reason` | Why it failed | "invalid_password", "missing_token" |
+| `field` | Field name (validation) | "email", "password" |
+| `required_role` | Expected role | "admin", "super_admin" |
+| `user_role` | User's actual role | "user" |
+| `collection` | MongoDB collection | "system_users" |
+
+---
+
+## Response Format Template
+
+```python
+# Success Response
+{
+    "success": True,
+    "data": {...},
+    "message": "Operation completed"
+}
+
+# Error Response
+{
+    "success": False,
+    "error": "Error Type",
+    "detail": "Detailed message",
+    "errors": [...]  # For validation errors
+}
+```
+
+---
+
+## Implementation Checklist for New Module
+
+- [ ] Import logger: `from app.core.logging import get_logger`
+- [ ] Initialize: `logger = get_logger(__name__)`
+- [ ] Import exceptions: `from fastapi import HTTPException, status`
+- [ ] Wrap operations in try-except
+- [ ] Log warnings for user errors (401, 403, 422)
+- [ ] Log errors for server errors (500, 503)
+- [ ] Include error_type in extras
+- [ ] Use exc_info=True for exceptions
+- [ ] Include user_id for actions
+- [ ] Include operation name for tracking
+- [ ] Use consistent field names (see reference table)
+
+---
+
+## Common HTTP Status Codes
+
+| Code | Meaning | Logger Level | Use Case |
+|------|---------|--------------|----------|
+| 400 | Bad Request | `warning` | Invalid input data |
+| 401 | Unauthorized | `warning` | Missing/invalid token |
+| 403 | Forbidden | `warning` | Insufficient permissions |
+| 404 | Not Found | `info` | Resource doesn't exist |
+| 422 | Validation Error | `warning` | Invalid field values |
+| 500 | Server Error | `error` | Unexpected exception |
+| 503 | Service Unavailable | `error` | DB connection failed |
+
+---
+
+## Quick Copy-Paste Template
+
+```python
+"""
+Module description.
+"""
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.responses import JSONResponse
+
+from app.core.logging import get_logger
+from app.system_users.services.service import SystemUserService
+from app.dependencies.auth import get_system_user_service
+
+logger = get_logger(__name__)
+router = APIRouter(prefix="/api/path", tags=["Category"])
+
+
+@router.post("/endpoint")
+async def endpoint_function(
+    data: RequestModel,
+    service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Endpoint description.
+    
+    Raises:
+        HTTPException: 400 - Invalid input
+        HTTPException: 401 - Unauthorized
+        HTTPException: 500 - Server error
+    """
+    try:
+        # Validation
+        if not data.field:
+            logger.warning(
+                "Validation failed",
+                extra={
+                    "field": "field_name",
+                    "reason": "empty_value"
+                }
+            )
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail="Field is required"
+            )
+        
+        # Business logic
+        result = await service.operation(data)
+        
+        # Success logging
+        logger.info(
+            "Operation successful",
+            extra={
+                "operation": "operation_name",
+                "result_id": result.id
+            }
+        )
+        
+        return {
+            "success": True,
+            "data": result,
+            "message": "Operation completed"
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(
+            "Operation failed",
+            extra={
+                "operation": "operation_name",
+                "error": str(e),
+                "error_type": type(e).__name__
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Operation failed"
+        )
+```
+
+