# Datos y actualizacion

## Fuente

La fuente actual es football-data.org API v4.

Endpoint usado:

```text
GET https://api.football-data.org/v4/competitions/WC/matches?season=2026
X-Auth-Token: ...
```

`WC` es el codigo de competicion para World Cup.

## Archivos generados

```text
output/worldcup_2026_fixture.json
output/worldcup_2026_fixture.csv
fixture-data.js
match-metadata.js
```

`worldcup_2026_fixture.json` contiene la respuesta completa de football-data.org.

`worldcup_2026_fixture.csv` contiene una version tabular practica para revisar o importar.

`fixture-data.js` contiene el JSON embebido como `window.WORLD_CUP_FIXTURE`. Se usa para que `fixture.html` pueda abrirse directo como archivo local sin servidor.

`match-metadata.js` agrega sedes y timezones por partido para mostrar el horario local del estadio junto al horario UTC en el visor web.

## Token

Crear token:

```text
https://www.football-data.org/client/register
```

Guardar token en archivo:

```powershell
Set-Content .football-data-token "tu_token"
```

Tambien se puede usar variable de entorno:

```powershell
$env:FOOTBALL_DATA_TOKEN="tu_token"
```

Prioridad usada por el script:

```text
1. Archivo indicado por --token-file
2. Archivo .football-data-token
3. Variable FOOTBALL_DATA_TOKEN
```

## Descargar fixture

```powershell
python fetch_worldcup_fixture.py --season 2026
```

Opciones:

```text
--season              Temporada. Default: 2026
--competition         Codigo de competicion. Default: WC
--output-dir          Carpeta de salida. Default: output
--token-file          Archivo con token. Default: .football-data-token
--list-competitions   Lista competiciones visibles para el token
```

Ejemplos:

```powershell
python fetch_worldcup_fixture.py --list-competitions
python fetch_worldcup_fixture.py --season 2026 --output-dir output
python fetch_worldcup_fixture.py --token-file C:\secrets\football-data-token.txt --season 2026
```

## Regenerar fixture-data.js

Despues de actualizar `output/worldcup_2026_fixture.json`, regenerar:

```powershell
$json = Get-Content output\worldcup_2026_fixture.json -Raw
Set-Content -Path fixture-data.js -Encoding UTF8 -Value ("window.WORLD_CUP_FIXTURE = " + $json + ";")
```

## Publicar datos actualizados

El sitio de produccion en Netlify usa los mismos archivos generados:

```text
fixture-data.js                         visor web estatico
output/worldcup_2026_fixture.json       API serverless
output/worldcup_2026_fixture.csv        export tabular
```

Despues de actualizar el fixture y regenerar `fixture-data.js`, validar y publicar:

```powershell
npm run check
node --check netlify\functions\api.js
netlify deploy --prod
```

Verificar produccion:

```powershell
Invoke-RestMethod https://worldcupfixtureapi.com/api
Invoke-RestMethod "https://worldcupfixtureapi.com/api/matches?team=MEX"
Invoke-WebRequest "https://worldcupfixtureapi.com/api/calendar.ics?team=ARG" -UseBasicParsing
```

## Normalizacion aplicada por la API

El servidor transforma los datos fuente para exponer un modelo mas estable.

Ejemplos:

```text
match.id                 -> id: wc2026-{footballDataId}
match.id                 -> sourceIds.footballData
match.utcDate            -> kickoff.utc
match.status             -> status normalizado
match.status             -> sourceStatus original
match.stage              -> stage normalizado
match.stage              -> stageCode original
match.group              -> group normalizado
match.group              -> groupCode original
match.homeTeam/awayTeam  -> homeTeam/awayTeam normalizados
match.venue              -> venue normalizado o null
```

## Timezone y fechas locales

Los datos fuente vienen en UTC. La API calcula fecha y hora local por request usando `Intl.DateTimeFormat` de Node.

Esto afecta especialmente:

```text
GET /api/matches?date=YYYY-MM-DD&timezone=...
GET /api/matches?from=YYYY-MM-DD&to=YYYY-MM-DD&timezone=...
GET /api/matches/today?timezone=...
```

La agrupacion por dia se hace con el timezone pedido, no por el dia UTC.

## Limitaciones actuales

- Las sedes descargadas desde football-data.org aparecen vacias en el dataset actual. El visor web las enriquece con `match-metadata.js`, basado en el calendario publicado por FIFA.
- No hay datos live si el archivo local no se actualiza.
- Los standings se calculan con resultados disponibles; antes del torneo quedan en cero.
- El OpenAPI incluido es un contrato basico de descubrimiento, no un schema exhaustivo.
- Antes de publicar comercialmente, revisar terminos de uso del proveedor de datos.

## Recomendaciones para produccion

- Automatizar la descarga del fixture cada cierto intervalo durante el torneo.
- Guardar snapshots para auditar cambios.
- Agregar una fuente oficial o secundaria para enriquecer sedes.
- Incorporar cache HTTP con `ETag` o version de dataset.
- Agregar tests automatizados para filtros, timezones e ICS.