# Entity Glossary & Truth Model

## Entities

| Entity | Description |
|--------|-------------|
| **MR** | Medical Representative. Field user with assigned territory(ies). |
| **Doctor** | Target healthcare professional (name, specialty, clinic, priority, location). |
| **Area / Territory** | Geographic polygon(s) (primary or secondary) assigned to MRs. |
| **Visit** | Single field activity record: MR, date, location, mapped doctor, area resolved, confidence. |
| **Assignment** | MR–Area link: primary (must cover) or secondary (allowed overlap). |
| **Target** | Expected coverage (e.g. doctors to visit in an area). |
| **Exception** | Allowed deviation: meeting, training, leave, or approved outside-territory. |

## Area Rules

- **Primary assigned:** Areas the MR must cover.
- **Secondary / allowed overlap:** Optional areas that may overlap with other MRs.
- **Outside territory:** Visits here count as deviation unless marked as exception.

## Confidence Model (0–100)

- **Source confidence:** Excel completeness (required columns present, valid formats).
- **Mapping confidence:** Doctor match score (name similarity, area, distance, history).
- **Geo confidence:** GPS present vs inferred from doctor vs manual/unknown.

**KPI inclusion:** Visits below configurable confidence thresholds are excluded from territory/compliance KPIs (or shown as “low confidence”).

## KPI Definitions

| KPI | Description |
|-----|-------------|
| **Territory compliance score** | How much activity stays within assigned (primary/secondary) areas. |
| **Coverage score** | Visited target doctors / expected target doctors in period. |
| **Doctor neglect risk** | Days since last visit, weighted by doctor priority. |
| **Travel inefficiency score** | Route/distance vs optimal. |
| **Drift score** | Directional or repeated deviation (outside primary/secondary). |

## Assignment Status (per visit)

- `in_primary` — Visit point inside a primary assigned area.
- `in_secondary` — Visit point inside a secondary assigned area only.
- `outside` — Visit point outside any assigned area.
- `border_ambiguous` — Visit near polygon border (small buffer); may be excluded from harsh penalties.
