# Romania UAT Content Pipeline

Acest proiect pregateste si publica continut derivat din `https://github.com/geospatialorg/geospatialorg.github.io` pentru aplicatii web care afiseaza limite administrative si informatii contextuale pe harti interactive.

Scopul pipeline-ului este furnizarea de fisiere si contracte de consum pentru alte proiecte. Nu face in mod implicit logica aplicativa, adnotare de trasee sau analiza spatiala pentru clienti.

Continutul publicat este destinat pentru:

- afisarea limitelor administrative pe harta
- marcarea punctelor de trecere intre judete, UAT-uri sau alte unitati administrative
- atasarea de notite pe trasee GPX
- expunerea unui contract stabil de fisiere pentru aplicatii consumatoare

## Sursa si publicare

- sursa upstream: `https://github.com/geospatialorg/geospatialorg.github.io`
- root proiect local: `/home/romania-uat/project`
- spatiu de publicare: `/var/www/romania-uat`
- checkout local upstream: `/home/romania-uat/project/runtime/source/geospatialorg.github.io`
- build local intermediar: `/home/romania-uat/project/runtime/build`

Scriptul principal sincronizeaza upstream-ul, pregateste directoarele de iesire si publica metadate despre versiunea curenta. Generarea efectiva a dataseturilor trebuie extinsa in `scripts/generate-datasets.sh`, pe masura ce clarificam structura finala a datelor sursa.

In versiunea actuala, generatorul extrage catalogul administrativ din `descarcare/listaLimiteAdministrative.jsx` din upstream si poate oglindi local fisierele `GeoJSON` expuse de `services.geo-spatial.org`.

## Contract de continut

Aplicatiile trebuie sa considere urmatoarea structura publica in `/var/www/romania-uat`:

- `index.html`: pagina simpla de health/info pentru publicarea statica
- `README.md`: documentatia dataseturilor publicate
- `docs/index.html`: documentatie HTML generata pentru consumatori
- `docs/usage.html`: ghid de integrare
- `examples/overlay-alignment.html`: exemplu interactiv de overlay/aliniere in stil Leaflet
- `datasets/geojson/`: limite administrative in format GeoJSON
- `datasets/gpx/`: trasee si puncte auxiliare in format GPX, daca sunt furnizate de un proces extern
- `datasets/notes/`: notite structurale in format JSON
- `manifests/catalog.json`: catalogul tuturor dataseturilor publicate
- `metadata/last-sync.json`: metadate despre ultimul import upstream
- `metadata/administrative-boundaries.inventory.json`: inventarul complet extras din catalogul upstream
- `schemas/course-points.schema.json`: schema JSON pentru punctele de trecere
- `schemas/route-notes.schema.json`: schema JSON pentru notitele atasate rutelor

### Formate recomandate

#### Limite administrative

Fiecare fisier GeoJSON din `datasets/geojson/` ar trebui sa contina un tip omogen de entitati:

- `ro_admin_county_polygon.geojson`: limite de judet
- `ro_admin_lau_polygon.geojson`: limite UAT
- `ro_admin_country_simplified_polygon.geojson`: contur simplificat pentru afisare rapida
- alte fisiere `ro_admin_*` rezultate prin oglindirea catalogului geo-spatial.org

Proprietati minime recomandate per feature:

- `id`: identificator intern stabil
- `level`: nivel administrativ, de exemplu `county`, `uat`, `locality`
- `name`: nume afisat
- `code`: cod administrativ daca exista in sursa
- `parent_id`: id-ul unitatii parinte
- `source_updated_at`: data ultimei modificari upstream, daca poate fi determinata

#### Puncte de trecere intre unitati

Aplicatiile care vor marca treceri pe traseu pot consuma:

- `datasets/notes/course-points.json`

Structura recomandata pentru fiecare obiect:

```json
{
  "id": "county-transition-b-ct",
  "type": "boundary-crossing",
  "boundary_level": "county",
  "from_id": "b",
  "to_id": "ct",
  "label": "Intrare din Bucuresti in Constanta",
  "geometry": {
    "type": "Point",
    "coordinates": [28.1234, 44.5678]
  },
  "route_refs": ["dobrogea-tour-2026"]
}
```

#### Notite pentru trasee GPX

Aplicatiile pot corela fisierele GPX cu un fisier JSON de notite:

- `datasets/gpx/*.gpx`
- `datasets/notes/route-notes.json`

Structura recomandata:

```json
{
  "route_id": "dobrogea-tour-2026",
  "notes": [
    {
      "id": "note-001",
      "type": "boundary-crossing",
      "title": "Schimbare de judet",
      "description": "Traseul intra in judetul Constanta.",
      "lat": 44.5678,
      "lon": 28.1234,
      "feature_refs": ["county:ct"]
    }
  ]
}
```
 
Aceste fisiere sunt publicate ca format-contract pentru proiectele consumatoare. Logica prin care ele sunt populate ramane responsabilitatea proiectului care le produce.

## Catalog public

`manifests/catalog.json` trebuie mentinut ca index pentru clienti:

```json
{
  "generated_at": "2026-03-15T10:00:00Z",
  "source": {
    "repo": "https://github.com/geospatialorg/geospatialorg.github.io",
    "commit": "abcdef1234567890"
  },
  "datasets": [
    {
      "id": "counties",
      "path": "datasets/geojson/counties.geojson",
      "format": "geojson",
      "feature_count": 42,
      "level": "county"
    }
  ]
}
```

## Actualizare periodica

Scriptul `scripts/update-content.sh`:

1. sincronizeaza repository-ul upstream
2. pregateste directoarele publice
3. extrage catalogul administrativ din `listaLimiteAdministrative.jsx`
4. oglindeste local fisierele GeoJSON selectate explicit pentru publicare web
5. scrie `metadata/last-sync.json`
6. publica schemele JSON pentru fisierele auxiliare
7. publica documentatia HTML si exemplul de overlay/aliniere
8. lasa in urma `manifests/catalog.json`

Unitatile `systemd` din `systemd/` ruleaza automat acest proces.

## Instalare systemd

Copiere manuala fisiere:

```bash
sudo cp /home/romania-uat/project/systemd/romania-uat-sync.service /etc/systemd/system/
sudo cp /home/romania-uat/project/systemd/romania-uat-sync.timer /etc/systemd/system/
sudo cp /home/romania-uat/project/systemd/romania-uat-sync.env.example /etc/default/romania-uat-sync
```

Activare:

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now romania-uat-sync.timer
```

Verificare:

```bash
systemctl list-timers romania-uat-sync.timer
journalctl -u romania-uat-sync.service -n 100 --no-pager
```

Alternativ, se poate folosi scriptul:

```bash
sudo bash /home/romania-uat/project/scripts/install-systemd.sh
```

## Rulare manuala

```bash
bash /home/romania-uat/project/scripts/update-content.sh
```

## Variabile utile

`/etc/default/romania-uat-sync` poate controla rollout-ul:

- `MIRROR_GEOJSON=1`: activeaza descarcarea fisierelor GeoJSON in public root
- `MIRROR_GEOJSON=0`: ruleaza doar extractia catalogului fara download
- `DATASET_LIMIT=5`: limiteaza numarul de dataseturi oglindite
- `DATASET_INCLUDE_PATTERN=county|lau`: selecteaza doar anumite coduri de strat
- `MIRROR_SELECTION_PATTERN=lau_simplified|county_simplified|country_simplified`: controleaza care seturi sunt oglindite local

Fara `MIRROR_SELECTION_PATTERN`, generatorul oglindeste implicit doar seturile simplificate sau cele de nivel mai mare decat UAT. Este o protectie utila pentru ca unele fisiere complete sunt foarte mari pentru uz web.

## Urmatorii pasi recomandati

- maparea exacta a fisierelor relevante din upstream
- definirea exacta a fisierelor GPX si a fluxului prin care alte proiecte populeaza `course-points` si `route-notes`
- definirea regulilor de denumire stabile pentru `id`, `code` si `parent_id`
- adaugarea de validari GeoJSON/GPX in pipeline