feat: enhance appointment scheduling with session management and availability checks

docs/api/appointment.md

@@ -6,7 +6,7 @@
 
 ## GET `/api/v1/appointment-slots`
 
-Get available appointment slots for a doctor on a specific date.
+Get all appointment slots (available and booked) for a doctor on a specific date.
 
 **Permission:** `PUBLIC`
 
@@ -23,23 +23,40 @@ Get available appointment slots for a doctor on a specific date.
   "data": {
     "doctor_uuid": "550e8400-...",
     "date": "2024-06-15",
-    "slots": [
+    "sessions": [
       {
-        "start": 1718438400,
-        "end": 1718439600,
-        "available": true
+        "start_time": "09:00",
+        "end_time": "13:00",
+        "slots": [
+          {
+            "start": 1718438400,
+            "end": 1718439600,
+            "start_time": "09:00",
+            "end_time": "09:20",
+            "location_id": null,
+            "is_available": true
+          },
+          {
+            "start": 1718439600,
+            "end": 1718440800,
+            "start_time": "09:20",
+            "end_time": "09:40",
+            "location_id": null,
+            "is_available": false
+          }
+        ]
       },
       {
-        "start": 1718439600,
-        "end": 1718440800,
-        "available": false
+        "start_time": "15:00",
+        "end_time": "17:00",
+        "slots": [...]
       }
     ]
   }
 }
 ```
 
-> All times are **Unix timestamps**. Slots are calculated from `WeeklySchedule` minus booked appointments, date overrides, and holidays.
+> Returns **all** slots grouped by work shift. `is_available: false` means the slot has an active (pending/confirmed) appointment. Session boundaries match the doctor's `WeeklySchedule` or date override config.
 
 ### Errors
 | Code | HTTP | Description |