# SPOTFIX Field Technician Performance & Tracking System

Mobile-first field operations system for SPOTFIX Technologies, Malindi.

## Quick Deploy

```bash
scp spotfix-field-v2.1.tar.gz root@YOUR_SERVER:/tmp/
ssh root@YOUR_SERVER
cd /tmp && tar xzf spotfix-field-v2.1.tar.gz && cd spotfix-field
chmod +x install.sh && ./install.sh
```

The installer prompts for all credentials — there are no default passwords.
The admin account is created during installation with the phone number and password you provide.

## Manual Install

### Prerequisites
Ubuntu 22.04+ or Debian 12+, Nginx, PHP 8.2+, MariaDB 10.6+

### Steps

```bash
# 1. Create database
mysql -u root -p -e "
  CREATE DATABASE spotfix_field CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  CREATE USER 'spotfix'@'localhost' IDENTIFIED BY 'YOUR_DB_PASSWORD';
  GRANT ALL ON spotfix_field.* TO 'spotfix'@'localhost';
"

# 2. Import schema
mysql -u root -p spotfix_field < database/schema.sql
mysql -u root -p spotfix_field < database/security_migration.sql

# 3. (Optional) Import demo data for testing
mysql -u root -p spotfix_field < database/seed.sql

# 4. Deploy files
cp -r backend frontend /var/www/spotfix-field/
mkdir -p /var/www/spotfix-field/{logs,backend/uploads}

# 5. Create .env from template (ALL secrets go here, not in PHP files)
cp .env.example /var/www/spotfix-field/.env
# Edit .env with your actual credentials:
nano /var/www/spotfix-field/.env

# 6. Set permissions
chown -R www-data:www-data /var/www/spotfix-field
chmod 640 /var/www/spotfix-field/.env
chown root:www-data /var/www/spotfix-field/.env
chmod 775 /var/www/spotfix-field/backend/uploads

# 7. Nginx
cp nginx.conf /etc/nginx/sites-available/spotfix-field
# Update server_name and PHP socket path in the file
ln -s /etc/nginx/sites-available/spotfix-field /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

# 8. SSL
certbot --nginx -d field.spotfix.co.ke

# 9. Create admin account via PHP (parameterized, no SQL injection risk)
php -r '
  require "/var/www/spotfix-field/backend/core.php";
  DB::insert("users", [
    "name" => "Your Name",
    "phone" => "+254712345678",
    "password" => password_hash("YourStr0ng!Pass", PASSWORD_BCRYPT, ["cost" => 12]),
    "role_id" => 1, "branch_id" => 1, "status" => "active", "must_change_password" => 0
  ]);
'

# 10. Cron jobs
crontab -e
# 0 2 * * * php /var/www/spotfix-field/cron-dormancy.php >> /var/www/spotfix-field/logs/dormancy.log
# 0 3 * * * /var/www/spotfix-field/backup.sh >> /var/www/spotfix-field/logs/backup.log
```

## Project Structure
```
spotfix-field/
├── install.sh              # Automated installer
├── nginx.conf              # Nginx config (HTTPS, security headers)
├── .env.example            # Environment template (secrets go here)
├── database/
│   ├── schema.sql          # 52 tables
│   ├── security_migration.sql  # Rate limits + must_change_password
│   └── seed.sql            # Demo data (optional)
├── backend/
│   ├── config.php          # Loads .env, zero hardcoded secrets
│   ├── core.php            # DB, Auth, AuthZ, Sanitize, RateLimiter
│   └── index.php           # 80+ API endpoints
└── frontend/
    ├── index.html          # PWA application
    ├── manifest.json       # PWA manifest
    └── sw.js               # Service worker
```

## Security Features
- Record-level authorization (technicians see only their own data)
- Input sanitization on all fields (XSS prevention)
- Hashed OTP storage (bcrypt)
- Rate limiting on login, OTP, SMS, API
- Account enumeration prevention
- File upload triple validation (extension + MIME + magic bytes)
- Credentials in .env only (640 perms, root:www-data)
- CORS explicit allowlist (no wildcard)
- Uploads served via auth-gated PHP endpoint
- CSP with per-request nonce, HSTS, X-Frame-Options DENY
- Password reset invalidates all sessions
- Password policy: 10+ chars, upper, lower, digit, special

## Password Policy
All passwords must meet:
- Minimum 10 characters
- At least one uppercase letter (A-Z)
- At least one lowercase letter (a-z)
- At least one digit (0-9)
- At least one special character (!@#$%^&* etc.)

## KPI Scoring
- 40% New Installations (actual/target × 40)
- 25% Dormant Reactivations (actual/target × 25)
- 20% New Hotspot Sites (actual/target × 20)
- 10% New Leads Registered (actual/target × 10)
- 5%  Job Quality (GPS + photo completeness from real data)

## Tech Stack
- **Backend:** PHP 8.2+ (zero framework dependencies)
- **Database:** MariaDB 10.6+
- **Frontend:** HTML5/CSS3/JS PWA
- **Maps:** Leaflet.js + OpenStreetMap
- **Auth:** bcrypt + SHA-256 tokens, CSP nonces
- **SMS:** Pate SMS API
- **Payments:** M-Pesa Paybill 4146327