# 🚀 Quick Start - Fibre Coverage System

## Setup (5 minutes)

### 1. Configure API Key
```bash
# Edit .env file
GOOGLE_MAPS_API_KEY=your_api_key_here
```

### 2. Run Setup
```bash
# Windows
setup-coverage.bat

# Linux/Mac
chmod +x setup-coverage.sh
./setup-coverage.sh
```

### 3. Test
```bash
php artisan coverage:test -- -17.824858 31.053028
```

## Common Commands

### Test Coverage
```bash
# Harare CBD (High feasibility)
php artisan coverage:test -- -17.824858 31.053028

# Harare suburbs (Medium feasibility)
php artisan coverage:test -- -17.790000 31.120000

# Rural area (Low feasibility)
php artisan coverage:test -- -17.500000 31.500000
```

### Database Operations
```bash
# Re-seed nodes
php artisan db:seed --class=FibreNodeSeeder

# Check node count
php artisan tinker
>>> FibreNode::count()

# View all nodes
>>> FibreNode::all()

# Find nodes in Harare
>>> FibreNode::where('name', 'like', 'Harare%')->get()
```

### Cache Management
```bash
# Clear all cache
php artisan cache:clear

# Clear specific cache
php artisan tinker
>>> Cache::forget('road_distance_-17.824858_31.053028_-17.786222_31.117483')
```

## Feasibility Tiers

| Status | Distance | Cost | Time |
|--------|----------|------|------|
| 🟢 High | 0-500m | $0 | 7-14 days |
| 🟡 Medium | 500m-2km | $150 + $0.50/m | 14-30 days |
| 🔴 Low | 2km+ | Custom | TBD |

## API Endpoints

### Public Coverage Check
```bash
POST /api/website/check-feasibility
{
  "address": "123 Main St, Harare",
  "email": "customer@example.com",
  "latitude": -17.824858,
  "longitude": 31.053028
}
```

### Authenticated Coverage Check
```bash
POST /api/feasibility/check
Authorization: Bearer {token}
{
  "address": "123 Main St, Harare",
  "latitude": -17.824858,
  "longitude": 31.053028
}
```

### Get Coverage History
```bash
GET /api/feasibility/history
Authorization: Bearer {token}
```

## Major Cities Coverage

### Harare (15 nodes)
- CBD Central, CBD East
- Borrowdale, Avondale, Mount Pleasant
- Newlands, Highlands, Eastlea
- Mbare, Mabelreign, Belvedere
- Glen Lorne, Greendale, Waterfalls, Msasa

### Bulawayo (6 nodes)
- CBD, North, Hillside
- Suburbs, Pumula, Nkulumane

### Mutare (4 nodes)
- CBD, North, Greenside, Sakubva

### Other Cities
- Gweru (3), Kwekwe (2), Masvingo (2)
- Chinhoyi, Kadoma, Marondera, Norton
- Victoria Falls, Hwange, Kariba

## Troubleshooting

### No nodes found
```bash
php artisan db:seed --class=FibreNodeSeeder
```

### Google Maps not working
1. Check API key in `.env`
2. Enable Distance Matrix API in Google Cloud
3. Check browser console for errors

### High API costs
1. Verify caching is enabled
2. Check cache driver: `CACHE_DRIVER=file` in `.env`
3. Review logs for excessive calls

### Wrong distances
1. Check if using fallback (logs)
2. Test with known locations
3. Compare road vs straight-line

## Monitoring

### Check Logs
```bash
# Real-time logs
php artisan pail

# Filter coverage logs
php artisan pail --filter=coverage

# View log file
type storage\logs\laravel.log
```

### Database Queries
```sql
-- All active nodes
SELECT * FROM fibre_nodes WHERE status = 'active';

-- Nodes by city
SELECT * FROM fibre_nodes WHERE name LIKE 'Harare%';

-- Recent coverage checks
SELECT * FROM feasibility_checks 
ORDER BY created_at DESC 
LIMIT 10;

-- Coverage by status
SELECT feasibility_status, COUNT(*) 
FROM feasibility_checks 
GROUP BY feasibility_status;
```

## Adding New Nodes

### Via Tinker
```bash
php artisan tinker
>>> FibreNode::create([
...   'name' => 'New Location',
...   'code' => 'NEW-LOC-01',
...   'latitude' => -17.123456,
...   'longitude' => 31.123456,
...   'type' => 'distribution',
...   'capacity' => 2000,
...   'status' => 'active',
... ])
```

### Via Seeder
Edit `database/seeders/FibreNodeSeeder.php` and add to the `$nodes` array.

## Cost Calculation

### Extension Cost Formula
```
Base Cost: $150 (site survey + planning)
Per Meter: $0.50 (cable, conduit, labor)
Free Distance: First 500m

Example: 1.2km distance
Additional: 1200m - 500m = 700m
Cost: $150 + (700 × $0.50) = $500
```

## Performance Tips

1. **Pre-filtering**: System checks only nodes within 50km
2. **Caching**: 30-day cache for distance calculations
3. **Batch queries**: Use `getRoadDistancesToMultiple()` for multiple destinations
4. **Indexes**: Database has optimized indexes for location queries

## Support Resources

- 📚 Full Documentation: `COVERAGE_SYSTEM.md`
- 📋 Upgrade Summary: `COVERAGE_UPGRADE_SUMMARY.md`
- 🔧 This Guide: `QUICK_START.md`
- 📝 Laravel Logs: `storage/logs/laravel.log`

## Quick Reference

```bash
# Setup
setup-coverage.bat

# Test (use -- before negative coordinates)
php artisan coverage:test -- -17.824858 31.053028

# Seed
php artisan db:seed --class=FibreNodeSeeder

# Clear cache
php artisan cache:clear

# View logs
php artisan pail

# Start server
php artisan serve
```

---

**Need Help?** Check `COVERAGE_SYSTEM.md` for detailed documentation.