# 💼 Core Business Workflows & Field Logic

This guide outlines the standard operating procedures and business workflows encoded in the Al-Hilal Medical Visits platform.

---

## 1. Medical Representative Field Routine

```mermaid
sequenceDiagram
    autonumber
    actor Rep as Medical Representative
    participant App as System / PWA
    participant Doctor as Healthcare Professional
    participant Pharmacy as Community / Hospital Pharmacy

    Rep->>App: Review assigned territory & daily plan
    Rep->>Doctor: Visit clinic during working hours
    Rep->>App: Open "New Visit" (Records Date & Time)
    Rep->>Doctor: Detail products (key selling points)
    Rep->>Doctor: Hand over samples / promotional gifts
    Rep->>App: Record products detailed, doctor feedback, samples given
    Rep->>App: Submit completed doctor visit

    Rep->>Pharmacy: Visit local pharmacy near clinic
    Rep->>Pharmacy: Inquire about prescription demand & stock levels
    Rep->>App: Log pharmacy stock audit & consumer availability
    Rep->>App: Submit pharmacy audit record
```

### Key Field Rules
1. **Target Identification**: A visit must specify either a `doctor` or a `pharmacy`.
2. **Workplace Binding**: For doctors with multiple clinics or hospital affiliations, the rep selects the specific `doctor_workplace_id` visited.
3. **Product Detailing & Samples**: Reps can attach multiple products to a single visit. Each product record includes:
   - Specific qualitative feedback from the physician.
   - Exact count of physical sample units handed over.
4. **Direct Field Execution**: Both Representatives and Supervisors can conduct and log field visits directly across their assigned zones.

---

## 2. Supervisor & Management Oversight

Supervisors govern assigned governorates and areas, monitoring field activity in real-time:

### 1. Coverage & Frequency Tracking
- **Coverage (%)**: Percentage of registered doctors in an area visited at least once during the monthly cycle:
  $$\text{Coverage Rate} = \left( \frac{\text{Unique Doctors Visited}}{\text{Total Registered Doctors in Territory}} \right) \times 100\%$$
- **Frequency**: Average number of repeat visits conducted per practitioner according to tier.

### 2. Tiered Doctor Visit Policy
Doctors are categorized into 4 tiers governing recommended monthly visit frequency:

| Classification | Priority Level | Recommended Monthly Visits | Typical Profile |
|---|---|---|---|
| **A+** | Top Key Opinion Leader | 3 – 4 Visits | High-volume prescriber, influential in medical societies and hospital departments. |
| **A** | Core Prescriber | 2 – 3 Visits | Consistent prescriber with steady patient flow across target specialties. |
| **B** | Standard Practitioner | 1 – 2 Visits | Moderate prescription volume with growth potential. |
| **C** | Occasional Prescriber | 1 Visit / As needed | Lower volume or peripheral clinic. |

---

## 3. Pharmacy Stock Auditing Workflow

Auditing pharmacies closes the commercial loop between doctor detailing and real pharmacy stock movement:

```mermaid
graph LR
    Rep["Medical Rep"] -->|"Surveys"| Ph["Pharmacy"]
    Ph -->|"Reports"| Stock["Current Stock Units"]
    Ph -->|"Reports"| Demand["Prescription Demand\n(High / Medium / Low / None)"]
    Stock --> Audit["Stored in visit_pharmacy_inventories"]
    Demand --> Audit
    Audit --> Report["Executive Stock Audit Report"]
```

### Pharmacy Visit Data Captured:
1. **Inventory Count**: Exact count of Al-Hilal products currently in stock on the shelves.
2. **Demand Level**: Qualitative indicator of prescription flow (High, Medium, Low, None) reported by the pharmacist.
3. **Availability Alerts**: Identifies out-of-stock items needing emergency wholesaler restocking.

---

## 4. Reports Hub & Analytics Navigation

The platform provides a consolidated entry point in the sidebar: **"التقارير والإحصائيات" / "Reports & Analytics"** (`/reports`). Inside, users switch between 4 specialized report views using a unified sub-navigation bar:

1. **Field Activity Reports (`/reports`)**:
   - Executive KPIs: Total visits, doctor/pharmacy splits, coverage rates, active reps.
   - Doctor coverage breakdown across medical specialties.
   - Pharmacy stock shortage alerts.
   - Representative performance leaderboard.
   - Governorate visit distribution.
   - Detailed paginated field visits log with mobile card streams, Excel export, and print view.

2. **Weekly Targets & Performance Alerts (`/reports/targets`)**:
   - Weekly doctor and pharmacy visit targets vs. actuals per representative.
   - Proactive warning banners highlighting lagging representatives.
   - Territory filtering by Governorate and Area.
   - Super Admin global weekly target management modal.
   - Dedicated printable report and Excel export.

3. **Product Availability Evolution (`/reports/product-evolution`)**:
   - Multi-week trend curves tracking product availability percentages in pharmacies over 4, 6, 8, or 12 weeks.
   - Territory-driven filtering (Governorate, Area, optional Rep).
   - High-distribution and depletion risk insight cards.
   - Interactive chart with toggleable product series.
   - Dedicated printable view and Excel export.

4. **Pharmacy Stock & Shortages (`/reports/pharmacy-stock`)**:
   - Product-level and pharmacy-level stock audit matrices.
   - Filterable by Governorate, Area, product, pharmacy, and stock status.
   - Dedicated printable view and Excel export.