feat: Implement check-out API with total working time calculation

- Add CheckOutRequest and CheckOutResponse schemas
- Implement create_checkout service method with edge case handling
- Add POST /attendance/check-out endpoint
- Calculate total working minutes automatically
- Handle edge cases: no check-in found, already checked out, GPS disabled
- Validate check-out time is after check-in time
- Update attendance record with check-out details

app/tracker/attendance/constants.py

@@ -11,6 +11,9 @@ ERROR_GPS_DISABLED = "GPS tracking is disabled for this employee"
 ERROR_LOCATION_REQUIRED = "Location coordinates are required"
 ERROR_EMPLOYEE_NOT_FOUND = "Employee not found"
 ERROR_INVALID_COORDINATES = "Invalid GPS coordinates"
+ERROR_NO_CHECKIN_FOUND = "No check-in found for today"
+ERROR_ALREADY_CHECKED_OUT = "Already checked out for today"
 
 # Success messages
 SUCCESS_CHECKIN = "Check-in successful"
+SUCCESS_CHECKOUT = "Check-out successful"

app/tracker/attendance/router.py

@@ -6,7 +6,7 @@ from app.core.logging import get_logger
 from app.dependencies.auth import get_current_user, TokenUser
 from app.nosql import get_database
 from app.tracker.attendance.service import AttendanceService, get_attendance_service
-from app.tracker.attendance.schemas import CheckInRequest, CheckInResponse, ErrorResponse
+from app.tracker.attendance.schemas import CheckInRequest, CheckInResponse, CheckOutRequest, CheckOutResponse, ErrorResponse
 
 logger = get_logger(__name__)
 
@@ -136,3 +136,116 @@ async def attendance_health():
         "module": "attendance",
         "version": "1.0.0"
     }
+
+
+@router.post(
+    "/check-out",
+    response_model=CheckOutResponse,
+    status_code=status.HTTP_200_OK,
+    responses={
+        200: {"description": "Check-out successful"},
+        400: {"model": ErrorResponse, "description": "Bad request - no check-in found or already checked out"},
+        401: {"description": "Unauthorized"},
+        422: {"description": "Validation error"},
+        500: {"model": ErrorResponse, "description": "Internal server error"}
+    },
+    summary="Employee Check-Out",
+    description="""
+    Mark the end of an employee's working day and calculate total working time.
+    
+    **Rules:**
+    - Allowed only after successful check-in
+    - Location coordinates are mandatory
+    - Auto-calculates total working hours in minutes
+    - GPS tracking must be enabled for the employee
+    
+    **Edge Cases:**
+    - No check-in found → 400 error
+    - Already checked out → 400 error
+    - GPS disabled → 400 error
+    - Check-out time before check-in time → 400 error
+    
+    **Data Storage:**
+    - Updates the attendance record with check-out timestamp, coordinates, and total working minutes
+    - Table: trans.scm_attendance
+    """
+)
+async def check_out(
+    payload: CheckOutRequest,
+    current_user: TokenUser = Depends(get_current_user)
+) -> CheckOutResponse:
+    """
+    Create a check-out record for the authenticated employee.
+    
+    Args:
+        payload: Check-out request with timestamp, latitude, and longitude
+        current_user: Authenticated user from JWT token
+        
+    Returns:
+        CheckOutResponse with success status and total working minutes
+        
+    Raises:
+        HTTPException 400: If no check-in found, already checked out, or GPS disabled
+        HTTPException 500: If internal error occurs
+    """
+    try:
+        # Get MongoDB database
+        mongo_db = get_database()
+        
+        # Create service instance
+        service = get_attendance_service(mongo_db)
+        
+        # Create check-out
+        result = await service.create_checkout(
+            employee_id=current_user.user_id,
+            merchant_id=current_user.merchant_id,
+            payload=payload
+        )
+        
+        logger.info(
+            "Check-out successful",
+            extra={
+                "employee_id": current_user.user_id,
+                "merchant_id": current_user.merchant_id,
+                "total_minutes": result.total_minutes
+            }
+        )
+        
+        return result
+        
+    except ValueError as e:
+        # Business logic errors (no check-in, already checked out, GPS disabled)
+        error_message = str(e)
+        logger.warning(
+            f"Check-out validation failed: {error_message}",
+            extra={
+                "employee_id": current_user.user_id,
+                "error": error_message
+            }
+        )
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={
+                "success": False,
+                "error": error_message,
+                "detail": error_message
+            }
+        )
+    except Exception as e:
+        # Unexpected errors
+        logger.error(
+            "Check-out failed with unexpected error",
+            extra={
+                "employee_id": current_user.user_id,
+                "error": str(e)
+            },
+            exc_info=e
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={
+                "success": False,
+                "error": "Internal server error",
+                "detail": "An unexpected error occurred during check-out"
+            }
+        )

app/tracker/attendance/schemas.py

@@ -71,6 +71,69 @@ class CheckInResponse(BaseModel):
     }
 
 
+class CheckOutRequest(BaseModel):
+    """Request schema for check-out"""
+    timestamp: int = Field(..., description="Unix timestamp in milliseconds")
+    latitude: float = Field(..., description="GPS latitude", ge=-90, le=90)
+    longitude: float = Field(..., description="GPS longitude", ge=-180, le=180)
+    
+    @field_validator('timestamp')
+    @classmethod
+    def validate_timestamp(cls, v):
+        """Validate timestamp is reasonable"""
+        if v <= 0:
+            raise ValueError("Timestamp must be positive")
+        # Check if timestamp is not too far in the past or future (within 24 hours)
+        now_ms = int(datetime.now().timestamp() * 1000)
+        diff_hours = abs(now_ms - v) / (1000 * 60 * 60)
+        if diff_hours > 24:
+            raise ValueError("Timestamp is too far from current time")
+        return v
+    
+    @field_validator('latitude')
+    @classmethod
+    def validate_latitude(cls, v):
+        """Validate latitude range"""
+        if not -90 <= v <= 90:
+            raise ValueError("Latitude must be between -90 and 90")
+        return v
+    
+    @field_validator('longitude')
+    @classmethod
+    def validate_longitude(cls, v):
+        """Validate longitude range"""
+        if not -180 <= v <= 180:
+            raise ValueError("Longitude must be between -180 and 180")
+        return v
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "timestamp": 1708186800000,
+                "latitude": 19.0760,
+                "longitude": 72.8777
+            }
+        }
+    }
+
+
+class CheckOutResponse(BaseModel):
+    """Response schema for check-out"""
+    success: bool = Field(..., description="Whether check-out was successful")
+    total_minutes: int = Field(..., description="Total working time in minutes")
+    message: Optional[str] = Field(None, description="Success or error message")
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "success": True,
+                "total_minutes": 480,
+                "message": "Check-out successful"
+            }
+        }
+    }
+
+
 class ErrorResponse(BaseModel):
     """Error response schema"""
     success: bool = Field(False, description="Always false for errors")

app/tracker/attendance/service.py

@@ -9,13 +9,16 @@ from motor.motor_asyncio import AsyncIOMotorDatabase
 
 from app.core.logging import get_logger
 from app.postgres import get_postgres_connection, release_postgres_connection
-from app.tracker.attendance.schemas import CheckInRequest, CheckInResponse
+from app.tracker.attendance.schemas import CheckInRequest, CheckInResponse, CheckOutRequest, CheckOutResponse
 from app.tracker.attendance.constants import (
     EMPLOYEES_COLLECTION,
     ERROR_DUPLICATE_CHECKIN,
     ERROR_GPS_DISABLED,
     ERROR_EMPLOYEE_NOT_FOUND,
-    SUCCESS_CHECKIN
+    ERROR_NO_CHECKIN_FOUND,
+    ERROR_ALREADY_CHECKED_OUT,
+    SUCCESS_CHECKIN,
+    SUCCESS_CHECKOUT
 )
 
 logger = get_logger(__name__)
@@ -241,6 +244,121 @@ class AttendanceService:
         finally:
             if conn:
                 await release_postgres_connection(conn)
+    
+    async def create_checkout(
+        self,
+        employee_id: str,
+        merchant_id: str,
+        payload: CheckOutRequest
+    ) -> CheckOutResponse:
+        """
+        Create a check-out record and calculate total working time.
+        
+        Args:
+            employee_id: Employee ID
+            merchant_id: Merchant ID
+            payload: Check-out request data
+            
+        Returns:
+            CheckOutResponse with total working minutes
+            
+        Raises:
+            ValueError: If validation fails or no check-in found
+        """
+        # Convert timestamp to date
+        work_date = datetime.fromtimestamp(payload.timestamp / 1000).date()
+        
+        # 1. Check if employee exists and has location tracking consent
+        has_consent = await self.check_location_tracking_consent(employee_id)
+        if not has_consent:
+            logger.warning(f"GPS disabled for employee {employee_id}")
+            raise ValueError(ERROR_GPS_DISABLED)
+        
+        # 2. Get today's attendance record
+        conn = None
+        try:
+            conn = await get_postgres_connection()
+            
+            # Find today's attendance record
+            query = """
+                SELECT 
+                    id,
+                    check_in_time,
+                    check_out_time
+                FROM trans.scm_attendance
+                WHERE employee_id = $1::uuid 
+                AND work_date = $2
+            """
+            
+            record = await conn.fetchrow(query, employee_id, work_date)
+            
+            if not record:
+                logger.warning(f"No check-in found for employee {employee_id} on {work_date}")
+                raise ValueError(ERROR_NO_CHECKIN_FOUND)
+            
+            # Check if already checked out
+            if record['check_out_time'] is not None:
+                logger.warning(f"Employee {employee_id} already checked out on {work_date}")
+                raise ValueError(ERROR_ALREADY_CHECKED_OUT)
+            
+            # Calculate total working time in minutes
+            check_in_time_ms = record['check_in_time']
+            check_out_time_ms = payload.timestamp
+            total_minutes = int((check_out_time_ms - check_in_time_ms) / (1000 * 60))
+            
+            # Ensure total_minutes is not negative
+            if total_minutes < 0:
+                logger.error(f"Negative working time calculated: {total_minutes} minutes")
+                raise ValueError("Check-out time cannot be before check-in time")
+            
+            # Update attendance record with check-out details
+            update_query = """
+                UPDATE trans.scm_attendance
+                SET 
+                    check_out_time = $1,
+                    check_out_lat = $2,
+                    check_out_lon = $3,
+                    total_minutes = $4,
+                    updated_at = NOW()
+                WHERE id = $5
+                RETURNING id
+            """
+            
+            result = await conn.fetchval(
+                update_query,
+                payload.timestamp,
+                payload.latitude,
+                payload.longitude,
+                total_minutes,
+                record['id']
+            )
+            
+            logger.info(
+                f"Check-out created successfully",
+                extra={
+                    "attendance_id": str(result),
+                    "employee_id": employee_id,
+                    "merchant_id": merchant_id,
+                    "work_date": str(work_date),
+                    "total_minutes": total_minutes
+                }
+            )
+            
+            return CheckOutResponse(
+                success=True,
+                total_minutes=total_minutes,
+                message=SUCCESS_CHECKOUT
+            )
+            
+        except ValueError:
+            # Re-raise ValueError (business logic errors)
+            raise
+        except Exception as e:
+            logger.error(f"Error creating check-out: {e}", exc_info=e)
+            raise
+        finally:
+            if conn:
+                await release_postgres_connection(conn)
 
 
 def get_attendance_service(mongo_db: AsyncIOMotorDatabase) -> AttendanceService: