# 🌐 Route Catalog & API Reference

All routes in the application use standard RESTful semantics powered by **Inertia.js** for full-page navigation and modal actions.

---

## 1. Authentication & Session Endpoints

| Method | URI | Name | Middleware | Description |
|---|---|---|---|---|
| `GET` | `/login` | `login` | `web, guest` | Render login credentials screen. |
| `POST` | `/login` | `login.store` | `web, guest` | Authenticate user credentials and establish session. |
| `POST` | `/logout` | `logout` | `web, auth` | Terminate session and invalidate cookies. |
| `GET` | `/two-factor-challenge` | `two-factor.login` | `web, guest` | Render 2FA verification challenge. |
| `POST` | `/two-factor-challenge` | `two-factor.login.store`| `web, guest` | Submit TOTP / recovery code for 2FA. |
| `GET` | `/forgot-password` | `password.request`| `web, guest` | Request password reset link. |
| `POST` | `/forgot-password` | `password.email` | `web, guest` | Send password reset notification. |

---

## 2. Dashboard & Territory Insights

| Method | URI | Name | Middleware | Controller & Description |
|---|---|---|---|---|
| `GET` | `/dashboard` | `dashboard` | `web, auth, verified` | `DashboardController@index`: Returns KPIs, visit summary cards, recent visits, and coverage progress. |

---

## 3. Medical & Pharmacy Field Visits (`/visits`)

| Method | URI | Name | Middleware | Action & Description |
|---|---|---|---|---|
| `GET` | `/visits` | `visits.index` | `auth, verified` | List visits with search, date filtering, rep filter, and target filter. |
| `GET` | `/visits/create` | `visits.create` | `auth, verified` | Render visit execution form with doctors, pharmacies, and product catalogs. |
| `POST` | `/visits` | `visits.store` | `auth, verified` | Submit a completed visit log via `StoreVisitRequest` & `VisitService`. |
| `GET` | `/visits/{visit}` | `visits.show` | `auth, verified` | View detailed audit of a visit (products detailed, samples left, pharmacy inventory). |
| `GET` | `/visits/{visit}/edit` | `visits.edit` | `auth, verified` | Edit a visit record (subject to role policies). |
| `PUT/PATCH` | `/visits/{visit}` | `visits.update` | `auth, verified` | Update visit details via `UpdateVisitRequest`. |
| `DELETE` | `/visits/{visit}` | `visits.destroy` | `auth, verified` | Soft delete visit record. |

### Payload Contract: `POST /visits`
```json
{
  "visit_type": "doctor",
  "doctor_id": "01J7ABCDEF...",
  "doctor_workplace_id": "01J7GHIJKL...",
  "visit_date": "2026-09-18",
  "visit_time": "11:30",
  "status": "completed",
  "latitude": 35.1318,
  "longitude": 36.7578,
  "notes": "Doctor expressed high interest in Crampan.",
  "products": [
    {
      "product_id": "01J7MNOPQR...",
      "feedback": "Positive response; requested more literature.",
      "samples_count": 2
    }
  ],
  "pharmacy_inventories": []
}
```

---

## 4. Doctors Directory & Workplaces (`/doctors`)

| Method | URI | Name | Middleware | Description |
|---|---|---|---|---|
| `GET` | `/doctors` | `doctors.index` | `auth` | Filterable list of 816+ doctors with classifications, specialties, and areas. |
| `GET` | `/doctors/create` | `doctors.create` | `auth` | Form to register a new doctor with primary clinic workplace. |
| `POST` | `/doctors` | `doctors.store` | `auth` | Store new doctor and create `doctor_workplace` record. |
| `GET` | `/doctors/{doctor}` | `doctors.show` | `auth` | Doctor profile, clinics, and visit history. |
| `GET` | `/doctors/{doctor}/edit` | `doctors.edit` | `auth` | Edit doctor information. |
| `PUT/PATCH` | `/doctors/{doctor}` | `doctors.update` | `auth` | Update doctor via `DoctorRequest`. |
| `DELETE` | `/doctors/{doctor}` | `doctors.destroy` | `auth` | Soft-delete doctor record. |
| `PATCH` | `/doctors/{doctor}/toggle-active` | `doctors.toggle-active` | `auth` | Activate or deactivate doctor. |

---

## 5. Medical Specialties Management (`/specialties`)

| Method | URI | Name | Middleware | Description |
|---|---|---|---|---|
| `POST` | `/specialties` | `specialties.store` | `auth, role:Super Admin|Admin` | Add a new canonical specialty. |
| `PUT/PATCH`| `/specialties/{specialty}` | `specialties.update` | `auth, role:Super Admin|Admin` | Update specialty name (`ar`/`en`) and icon. |
| `DELETE` | `/specialties/{specialty}` | `specialties.destroy` | `auth, role:Super Admin|Admin` | Delete specialty (if not referenced). |

---

## 6. Pharmacies Directory (`/pharmacies`)

| Method | URI | Name | Middleware | Description |
|---|---|---|---|---|
| `GET` | `/pharmacies` | `pharmacies.index` | `auth` | Paginated registry of 897+ pharmacies. |
| `GET` | `/pharmacies/create`| `pharmacies.create` | `auth` | Form to register a pharmacy. |
| `POST` | `/pharmacies` | `pharmacies.store` | `auth` | Store new pharmacy via `PharmacyRequest`. |
| `GET` | `/pharmacies/{pharmacy}` | `pharmacies.show` | `auth` | Pharmacy details and stock audit history. |
| `PUT/PATCH`| `/pharmacies/{pharmacy}` | `pharmacies.update` | `auth` | Update pharmacy profile. |
| `DELETE` | `/pharmacies/{pharmacy}` | `pharmacies.destroy`| `auth` | Soft delete pharmacy. |
| `GET` | `/pharmacies/{pharmacy}/latest-stock` | `pharmacies.latest-stock` | `auth` | Fetch last recorded inventory levels. |
| `PATCH` | `/pharmacies/{pharmacy}/toggle-active` | `pharmacies.toggle-active` | `auth` | Toggle active status. |

---

## 7. Products & Product Categories (`/products`)

| Method | URI | Name | Middleware | Description |
|---|---|---|---|---|
| `GET` | `/products` | `products.index` | `auth` | Catalog of Al-Hilal pharmaceutical products. |
| `POST` | `/products` | `products.store` | `auth, role:Super Admin|Admin` | Add a new pharmaceutical preparation. |
| `PUT/PATCH`| `/products/{product}` | `products.update` | `auth, role:Super Admin|Admin` | Update product details and leaflet/image. |
| `DELETE` | `/products/{product}` | `products.destroy` | `auth, role:Super Admin|Admin` | Soft delete product. |
| `PATCH` | `/products/{product}/toggle-active` | `products.toggle-active` | `auth` | Toggle active promotion status. |
| `POST` | `/product-categories` | `product-categories.store` | `auth, role:Super Admin|Admin` | Add product category. |
| `PUT/PATCH`| `/product-categories/{category}` | `product-categories.update` | `auth, role:Super Admin|Admin` | Update category. |
| `DELETE` | `/product-categories/{category}` | `product-categories.destroy`| `auth, role:Super Admin|Admin` | Delete category. |

---

## 8. Administrative Areas & Governorates (`/admin/areas`)

| Method | URI | Name | Middleware | Description |
|---|---|---|---|---|
| `GET` | `/admin/areas` | `admin.areas.index` | `auth, role:Super Admin|Admin` | Browse 202 areas across Syrian governorates. |
| `POST` | `/admin/areas` | `admin.areas.store` | `auth, role:Super Admin|Admin` | Create new area under a governorate. |
| `PUT/PATCH`| `/admin/areas/{area}` | `admin.areas.update` | `auth, role:Super Admin|Admin` | Update area names (`ar`/`en`). |
| `DELETE` | `/admin/areas/{area}` | `admin.areas.destroy` | `auth, role:Super Admin|Admin` | Soft delete area. |
| `PATCH` | `/admin/areas/{area}/toggle-active` | `admin.areas.toggle-active` | `auth` | Toggle area operational status. |

---

## 9. Reports & Document Exports (`/reports`)

| Method | URI | Name | Middleware | Description |
|---|---|---|---|---|
| `GET` | `/reports` | `reports.index` | `auth` | Analytics dashboard: Coverage, frequency, product detailing metrics. |
| `GET` | `/reports/export/excel` | `reports.export.excel` | `auth` | Download full visit audit spreadsheet (`.xlsx`). |
| `GET` | `/reports/export/pdf` | `reports.export.pdf` | `auth` | Stream formal PDF executive summary report. |
| `GET` | `/reports/print` | `reports.print` | `auth` | Printable HTML optimized view for direct browser printing. |
| `GET` | `/reports/pharmacy-stock` | `reports.pharmacy-stock` | `auth` | Comprehensive pharmacy stock audit matrix. |
| `GET` | `/reports/pharmacy-stock/export` | `reports.pharmacy-stock.export` | `auth` | Export pharmacy stock report to Excel. |
| `GET` | `/reports/pharmacy-stock/print` | `reports.pharmacy-stock.print` | `auth` | Printable pharmacy stock distribution sheet. |

---

## 10. Data Quality & Deduplication Hub (/admin/data-quality)

| Method | URI | Name | Middleware | Description |
|---|---|---|---|---|
| GET | /admin/data-quality | dmin.data-quality.index | uth, role:Super Admin\|Admin | Interactive audit center: duplicates, honorific titles, and double clinics. |
| POST | /admin/data-quality/merge-doctors | dmin.data-quality.merge-doctors | uth, role:Super Admin\|Admin | Atomically merge duplicate doctors and reassign visits/clinics. |
| POST | /admin/data-quality/merge-pharmacies | dmin.data-quality.merge-pharmacies | uth, role:Super Admin\|Admin | Atomically merge duplicate pharmacies and reassign inventory surveys. |
| POST | /admin/data-quality/standardize-doctor-names | dmin.data-quality.standardize-doctor-names | uth, role:Super Admin\|Admin | Standardize doctor names, strip titles, merge collisions, and update clinics. |
| POST | /admin/data-quality/clean-double-clinics | dmin.data-quality.clean-double-clinics | uth, role:Super Admin\|Admin | Clean redundant nested clinic prefixes with Dal-letter protection. |