# Gap Finder Analytics

Geo-intelligent MR–Doctor tracking and territory compliance analytics.

## Setup

1. **Prerequisites**: PHP 8.2+, Composer, MySQL 8+ (or MariaDB 10.2+), XAMPP (or equivalent)

2. **Create database**:
   ```sql
   CREATE DATABASE gap_finder_analytics CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   ```

3. **Configure `.env`** (MySQL connection is pre-configured):
   - `DB_DATABASE=gap_finder_analytics`
   - `DB_USERNAME=root`
   - `DB_PASSWORD=` (adjust if needed)

4. **Run migrations**:
   ```bash
   php artisan migrate --force
   ```

5. **Start server** (XAMPP Apache or artisan):
   ```bash
   php artisan serve
   ```
   Or use: `http://localhost/gap-finder-analytics/public`

## Features (MVP in progress)

- **Excel import**: Upload field activity Excel → staging → validation → preview
- **Entity glossary**: MR, Doctor, Area, Visit, Assignment (see `docs/ENTITY_GLOSSARY.md`)
- **MySQL spatial**: POINT/MULTIPOLYGON for doctors, areas, visits
- **Planned**: Matching engine, manual mapping UI, territory compliance, Leaflet map

## Imports

### 1. Visit / field activity sheet

- MR: `mr`, `mr_name`, `medical_representative`
- Date: `date`, `visit_date`
- Doctor: `doctor`, `doctor_name`, `dr`
- Clinic: `clinic`, `clinic_name`, `location`
- GPS: `lat`/`lng`, `latitude`/`longitude`

### 2. Ground team / location sheet (Map location.xlsx)

Import areas, MRs, doctors, and MR–area assignments. Expected columns:

- Territory code, Employee, Designation, Base town name, Team name
- Doctor codes, Doctor name, Doctor grade, Doctor specialty
- Location, p-lat, p-long (doctor coordinates)

**Upload via UI** (Imports page) or **CLI**:
```bash
php artisan import:location
# or
php artisan import:location path/to/Map location.xlsx
```
