# Location Data Seeder Design

## Goal
Populate the application's `countries`, `cities`, and `regions` tables from a ready-made public dataset, filtered to a configurable list of countries, without manual data entry.

## Context
The project already contains:
- `Country`, `City`, and `Region` Eloquent models with standard relationships.
- Migrations for `countries`, `cities`, and `regions`.
- A `LocationService` / `Location` facade that currently auto-creates locations when a building is stored.
- Form requests (`CountryRequest`, `CityRequest`, `RegionRequest`) and controllers for CRUD operations.

The user intends to remove the auto-creation behavior later and instead rely on a seeded/imported location dataset.

## Out of Scope
- Removing the existing auto-creation logic in `LocationService` is **not** part of this work; it will be handled separately.
- Changing the overall admin UI for locations is out of scope.

## Design

### 1. Schema Fix: Add `is_active` Columns
The `cities` and `regions` tables currently lack an `is_active` column, but the code references it. We will add it.

- If the original migrations have not yet run in production/shared environments, edit:
  - `database/migrations/2026_06_08_100706_create_cities_table.php`
  - `database/migrations/2026_06_08_100914_create_regions_table.php`
- If the migrations have already run, create a new migration instead.

Add:
```php
$table->boolean('is_active')->default(true);
```

### 2. Configuration
Create `config/locations.php`:

```php
<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Countries to Seed
    |--------------------------------------------------------------------------
    |
    | Comma-separated list of country names to import from the public dataset.
    | Example: "Syria,United Arab Emirates,Saudi Arabia"
    |
    */
    'seed_countries' => array_filter(
        explode(',', env('SEED_COUNTRIES', 'Syria'))
    ),
];
```

### 3. Download & Filter Command
Create `app/Console/Commands/DownloadLocations.php`.

Responsibilities:
- Download the full JSON dataset from `https://raw.githubusercontent.com/dr5hn/countries-states-cities-database/master/countries%2Bstates%2Bcities.json`.
- Filter the dataset to only the countries listed in `config('locations.seed_countries')`.
- Save the filtered JSON to `database/data/locations.json`.
- Output counts of imported countries, cities, and regions.
- Fail gracefully if the download fails or no countries match.

Command:
```bash
php artisan locations:download
```

### 4. Database Seeder
Create `database/seeders/LocationSeeder.php`.

Responsibilities:
- Read `database/data/locations.json`.
- Import data in dependency order:
  1. Countries (link to existing `currencies` by code when available).
  2. Cities (linked to countries).
  3. Regions (linked to cities).
- Use `firstOrCreate` so the seeder is idempotent.
- Set `is_active` to `true` by default.

### 5. Fix Validation Bugs
Update form requests to match the intended string-based lookup flow:
- `CityRequest`: `country_name` should be a string (not integer).
- `RegionRequest`: `city_name` and `country_name` should be strings.

### 6. Wiring
Call `LocationSeeder` from `DatabaseSeeder` after `RolesAndPermissionsSeeder` so `php artisan db:seed` seeds locations automatically.

## Usage

1. Configure target countries in `.env`:
   ```env
   SEED_COUNTRIES=Syria,United Arab Emirates,Saudi Arabia
   ```

2. Download the dataset:
   ```bash
   php artisan locations:download
   ```

3. Seed the database:
   ```bash
   php artisan db:seed --class=LocationSeeder
   ```

Or, if wired into `DatabaseSeeder`:
```bash
php artisan db:seed
```

## Trade-offs
- **Pros:** Uses a comprehensive public dataset; filter keeps the dataset small; filtered snapshot is reusable offline; idempotent seeding.
- **Cons:** Requires an external download on first run; dataset structure depends on the upstream repository.

## Testing
- Unit test the filter logic of the download command.
- Feature test the seeder to ensure it creates countries, cities, and regions in the correct hierarchy.
- Verify the `is_active` column is present and defaults to `true`.