feat(api): add dashboard endpoints for clinic, doctor, and secretary roles

- Implemented GET /api/v1/dashboard/clinic to return clinic stats and today's schedule for clinic owners. - Implemented GET /api/v1/dashboard/doctor to return doctor's stats and today's schedule for doctors. - Implemented GET /api/v1/dashboard/secretary to return stats and conditional appointments for secretaries. feat(migrations): create user_active_context and mobile_verification_otp tables - Added migration to create user_active_context table for tracking active user sessions. - Added migration to create mobile_verification_otp table for handling mobile number verification. feat(migrations): create site_config table for application settings - Added migration to create site_config table to store various site configuration settings. feat(appointments): create MyAppointmentsController for user-specific appointments - Added MyAppointmentsController to handle fetching user-specific appointments with pagination and filtering. feat(auth): implement NotificationMobileController for mobile number verification - Added NotificationMobileController to handle OTP requests and verification for mobile number changes. feat(auth): create MobileVerificationOtp entity for OTP management - Created MobileVerificationOtp entity to manage OTP records for mobile verification. feat(auth): create UserActiveContext entity for user session management - Created UserActiveContext entity to manage user active sessions. feat(config): implement SiteConfigController for managing site settings - Added SiteConfigController to handle fetching and updating site configuration settings. feat(config): create SiteConfig entity and repository for configuration management - Created SiteConfig entity and repository to manage site configuration data.
2026-06-11 12:20:12 +03:30
parent 54c491c734
commit e7b90a6399
32 changed files with 3780 additions and 354 deletions
@@ -0,0 +1,167 @@
+# Dashboard API
+
+Role-specific dashboard endpoints. Each endpoint requires the corresponding role JWT.
+
+---
+
+## GET /api/v1/dashboard/clinic
+
+Returns stats and today's schedule for the authenticated clinic owner.
+
+**Auth:** `ROLE_CLINIC` required
+
+### Response `200`
+
+```json
+{
+  "success": true,
+  "data": {
+    "clinic": {
+      "uuid": "string",
+      "name": "string",
+      "is_active": true,
+      "logo": "string | null"
+    },
+    "stats": {
+      "total_doctors": 5,
+      "today_appointments": 12,
+      "this_month_appointments": 87,
+      "pending_invitations": 2
+    },
+    "today_appointments": [
+      {
+        "uuid": "string",
+        "patient_name": "string | null",
+        "doctor_name": "string",
+        "slot_start": 1700000000,
+        "status": "reserved"
+      }
+    ],
+    "doctors": [
+      {
+        "uuid": "string",
+        "name": "string",
+        "today_count": 3
+      }
+    ]
+  }
+}
+```
+
+`today_appointments` — up to 5 records, ordered by `slot_start ASC`.  
+`doctors` — all doctors belonging to this clinic; each includes their appointment count for today.
+
+### Errors
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_NOT_FOUND_001` | 404 | Clinic not found for this user |
+
+---
+
+## GET /api/v1/dashboard/doctor
+
+Returns stats and today's schedule for the authenticated doctor.
+
+**Auth:** `ROLE_DOCTOR` required
+
+### Response `200`
+
+```json
+{
+  "success": true,
+  "data": {
+    "doctor": {
+      "uuid": "string",
+      "name": "string",
+      "degree": "string | null"
+    },
+    "stats": {
+      "today_appointments": 8,
+      "tomorrow_appointments": 5,
+      "this_month_appointments": 62,
+      "avg_rating": 4.6,
+      "total_ratings": 34
+    },
+    "today_appointments": [
+      {
+        "uuid": "string",
+        "patient_name": "string | null",
+        "patient_mobile": "string",
+        "slot_start": 1700000000,
+        "status": "reserved"
+      }
+    ],
+    "clinics": [
+      {
+        "uuid": "string",
+        "name": "string",
+        "logo": "string | null"
+      }
+    ]
+  }
+}
+```
+
+`today_appointments` — up to 10 records, ordered by `slot_start ASC`.  
+`avg_rating` — rounded to 1 decimal; `null` if no ratings yet.  
+`clinics` — all clinics the doctor belongs to.
+
+### Errors
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_NOT_FOUND_001` | 404 | Doctor profile not found for this user |
+
+---
+
+## GET /api/v1/dashboard/secretary
+
+Returns stats for the authenticated secretary and (conditionally) today's appointments.
+
+**Auth:** `ROLE_SECRETARY` required
+
+### Response `200`
+
+```json
+{
+  "success": true,
+  "data": {
+    "doctor": {
+      "uuid": "string",
+      "name": "string",
+      "degree": "string | null"
+    },
+    "permissions": {
+      "resources": {
+        "appointments": {
+          "view": true,
+          "edit": false
+        }
+      }
+    },
+    "stats": {
+      "today_appointments": 8,
+      "tomorrow_appointments": 5
+    },
+    "today_appointments": [
+      {
+        "uuid": "string",
+        "patient_name": "string | null",
+        "patient_mobile": "string",
+        "slot_start": 1700000000,
+        "status": "reserved"
+      }
+    ]
+  }
+}
+```
+
+`today_appointments` — only populated when `permissions.resources.appointments.view === true`; otherwise empty array.  
+`today_appointments` — up to 10 records when visible.
+
+### Errors
+
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_FORBIDDEN_001` | 403 | Secretary relation not configured or inactive |