# South City Hospital — Backend API

Patient mobile app backend for OPD appointment booking, consultant scheduling, and hospital administration.

## Stack

| Layer | Technology |
|-------|-----------|
| Framework | Laravel 12 (PHP 8.4) |
| Database | MySQL 8.0 |
| Auth | Laravel Sanctum (Bearer token) |
| RBAC | Spatie Laravel Permission |
| Admin Panel | Filament v3 |
| API Docs | L5-Swagger / OpenAPI 3.0 |
| Reports | Maatwebsite Excel + DomPDF |

## Local Setup

```bash
# 1. Clone and install
composer install

# 2. Configure environment
cp .env.example .env
php artisan key:generate

# 3. Database
# Create MySQL database and user, then:
php artisan migrate --seed

# 4. Start server
php artisan serve
```

**Default admin accounts (seeded):**

| Email | Password | Role |
|-------|----------|------|
| admin@southcityhospital.pk | Admin@SCH2026! | super_admin |
| manager@southcityhospital.pk | Admin@SCH2026! | hospital_admin |
| reception@southcityhospital.pk | Admin@SCH2026! | reception |

## Endpoints

| URL | Description |
|-----|-------------|
| `GET /api/documentation` | Swagger UI (OpenAPI 3.0) |
| `POST /api/v1/auth/register` | Initiate registration (sends OTP) |
| `POST /api/v1/auth/register/verify` | Complete registration |
| `POST /api/v1/auth/login` | Password login → Bearer token |
| `POST /api/v1/auth/send-otp` | Send OTP (login/reset) |
| `POST /api/v1/auth/verify-otp` | OTP login → Bearer token |
| `GET /api/v1/auth/me` | Authenticated user profile |
| `POST /api/v1/auth/logout` | Revoke token |
| `GET /api/v1/departments` | List departments |
| `GET /api/v1/consultants` | List consultants (filterable) |
| `GET /api/v1/consultants/{id}/available-dates` | Dates with open slots |
| `GET /api/v1/consultants/{id}/slots?date=` | Slots for a date |
| `GET/POST /api/v1/appointments` | List / Book appointment |
| `POST /api/v1/appointments/{ref}/cancel` | Cancel appointment |
| `POST /api/v1/appointments/{ref}/reschedule` | Reschedule appointment |
| `POST /api/v1/appointments/{ref}/pay` | Initiate payment |
| `GET /api/v1/appointments/{ref}/payment-status` | Check payment |
| `GET/PUT /api/v1/patient/profile` | Patient profile |

## Admin Panel

Navigate to `/admin` — login with one of the seeded admin accounts.

**Navigation groups:**
- **Scheduling** — Consultant schedules, block dates / leaves
- **Appointments** — Appointment list with status management
- **Hospital Setup** — Departments, consultants, fees
- **Users & Access** — Staff accounts with role assignment
- **Reports** — Appointment, revenue, consultant performance reports with XLSX export

## Architecture Notes

- All API responses follow: `{status, data, message, error_code}`
- OTP codes logged to `storage/logs/laravel.log` in local env (`OTP_SMS_DRIVER=log`)
- Double-booking prevented via MySQL `GET_LOCK` + unique DB constraint
- Fees are immutable — each change inserts a new row, closing the previous
- Cancellation window is per-consultant (overrides global if `ALLOW_CONSULTANT_CANCELLATION_OVERRIDE=true`)
- Vendor integrations (HIMS, LIS) are stubs in Phase 1 — switch `VENDOR_MODE=live` in Phase 3
- Payment gateway switchable via `PAYMENT_GATEWAY=jazzcash|alfamall`

## Development

```bash
# Regenerate Swagger docs after annotation changes
php artisan l5-swagger:generate

# Clear compiled caches
php artisan config:clear && php artisan cache:clear

# Refresh database (dev only)
php artisan migrate:fresh --seed
```