Fix
This commit is contained in:
devRaGonSa
263
docs/frontend-backend-contract.md
Normal file
263
docs/frontend-backend-contract.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# Frontend Backend Contract
|
||||
|
||||
## Objetivo
|
||||
|
||||
Definir un contrato inicial y pequeno entre la landing actual y el futuro backend Python sin implementar todavia integraciones reales ni comprometer detalles de infraestructura antes de tiempo.
|
||||
|
||||
## Estado actual
|
||||
|
||||
- Frontend: landing estatica sin consumo de API
|
||||
- Backend: bootstrap Python con `GET /health`
|
||||
- Integraciones reales: no implementadas
|
||||
|
||||
## Convenciones generales
|
||||
|
||||
- Todas las respuestas usan JSON.
|
||||
- Los nombres de campos usan `snake_case`.
|
||||
- `status` es obligatorio en todas las respuestas.
|
||||
- Las respuestas exitosas usan `status: "ok"`.
|
||||
- Las respuestas de error usan `status: "error"` y un campo `message`.
|
||||
- Cuando un endpoint sea solo placeholder o aun no tenga datos reales, puede responder datos controlados o quedar documentado como previsto hasta una task posterior.
|
||||
|
||||
## Estructura base de respuesta
|
||||
|
||||
Respuesta correcta:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
Respuesta de error minima:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"message": "Route not found"
|
||||
}
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
|
||||
### `GET /health`
|
||||
|
||||
- Proposito: comprobar que el backend bootstrap esta levantado.
|
||||
- Metodo HTTP: `GET`
|
||||
- Ruta: `/health`
|
||||
- Estado actual: implementado
|
||||
|
||||
Ejemplo JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"service": "hll-vietnam-backend",
|
||||
"phase": "bootstrap"
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/community`
|
||||
|
||||
- Proposito: devolver contenido resumido de presentacion de la comunidad para bloques de texto o estadisticas futuras.
|
||||
- Metodo HTTP: `GET`
|
||||
- Ruta: `/api/community`
|
||||
- Estado actual: previsto
|
||||
|
||||
Ejemplo JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"title": "Comunidad Hispana HLL Vietnam",
|
||||
"summary": "Punto de encuentro para jugadores, escuadras y comunidad.",
|
||||
"discord_invite_url": "https://discord.com/invite/PedEqZ2Xsa"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/trailer`
|
||||
|
||||
- Proposito: exponer la informacion del trailer que hoy esta fija en la landing.
|
||||
- Metodo HTTP: `GET`
|
||||
- Ruta: `/api/trailer`
|
||||
- Estado actual: previsto
|
||||
|
||||
Ejemplo JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"video_url": "https://www.youtube.com/embed/JzYzYNVWZ_A",
|
||||
"title": "Trailer HLL Vietnam",
|
||||
"provider": "youtube"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/discord`
|
||||
|
||||
- Proposito: centralizar la informacion publica del acceso a Discord sin integrar todavia datos reales del servidor.
|
||||
- Metodo HTTP: `GET`
|
||||
- Ruta: `/api/discord`
|
||||
- Estado actual: placeholder
|
||||
|
||||
Ejemplo JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"invite_url": "https://discord.com/invite/PedEqZ2Xsa",
|
||||
"label": "Unirse al Discord",
|
||||
"availability": "manual"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/servers`
|
||||
|
||||
- Proposito: exponer el estado actual de los 2 servidores reales de la comunidad desde backend, usando el ultimo snapshot valido y forzando refresco real cuando el cache local supere el objetivo de 120 segundos.
|
||||
- Metodo HTTP: `GET`
|
||||
- Ruta: `/api/servers`
|
||||
- Estado actual: implementado con refresco A2S bajo demanda y fallback a snapshot persistido stale
|
||||
|
||||
Ejemplo JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"title": "Estado actual de servidores",
|
||||
"context": "current-hll-status",
|
||||
"source": "real-time-a2s-refresh",
|
||||
"last_snapshot_at": "2026-03-20T18:37:58.628122Z",
|
||||
"snapshot_age_seconds": 0,
|
||||
"snapshot_age_minutes": 0,
|
||||
"max_snapshot_age_seconds": 120,
|
||||
"is_stale": false,
|
||||
"freshness": "fresh",
|
||||
"refresh_attempted": true,
|
||||
"refresh_status": "success",
|
||||
"refresh_errors": [],
|
||||
"items": [
|
||||
{
|
||||
"external_server_id": "comunidad-hispana-01",
|
||||
"server_name": "Comunidad Hispana #01",
|
||||
"status": "online",
|
||||
"players": 74,
|
||||
"max_players": 100,
|
||||
"current_map": "Sainte-Marie-du-Mont",
|
||||
"region": "ES",
|
||||
"snapshot_origin": "real-a2s",
|
||||
"captured_at": "2026-03-20T18:37:58.628122Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notas del comportamiento actual:
|
||||
|
||||
- Si el snapshot persistido tiene `120` segundos o menos, puede reutilizarse sin refresco inmediato.
|
||||
- Si el snapshot supera ese umbral, backend intenta una consulta A2S real antes de responder.
|
||||
- Si la consulta real falla, backend devuelve el ultimo snapshot valido con `is_stale: true`.
|
||||
- Si no existe ningun snapshot valido, backend responde `items: []` y no inventa servidores de referencia.
|
||||
|
||||
### `GET /api/servers/latest`
|
||||
|
||||
- Proposito: devolver el ultimo snapshot conocido por servidor desde la persistencia local.
|
||||
- Metodo HTTP: `GET`
|
||||
- Ruta: `/api/servers/latest`
|
||||
- Estado actual: implementado para validacion tecnica
|
||||
|
||||
Ejemplo JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"title": "Ultimo estado conocido de servidores",
|
||||
"context": "current-hll-history",
|
||||
"source": "local-snapshot-storage",
|
||||
"items": [
|
||||
{
|
||||
"server_id": 1,
|
||||
"external_server_id": "hll-esp-tactical-rotation",
|
||||
"server_name": "HLL ESP Tactical Rotation",
|
||||
"region": "EU",
|
||||
"captured_at": "2026-03-20T08:45:20.802006Z",
|
||||
"status": "online",
|
||||
"players": 74,
|
||||
"max_players": 100,
|
||||
"current_map": "Sainte-Marie-du-Mont"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/servers/history`
|
||||
|
||||
- Proposito: devolver una ventana simple de snapshots recientes desde la persistencia local.
|
||||
- Metodo HTTP: `GET`
|
||||
- Ruta: `/api/servers/history`
|
||||
- Parametros opcionales: `limit` entre `1` y `100`
|
||||
- Estado actual: implementado para validacion tecnica
|
||||
|
||||
Ejemplo JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"title": "Historial reciente de servidores",
|
||||
"context": "current-hll-history",
|
||||
"source": "local-snapshot-storage",
|
||||
"limit": 20,
|
||||
"items": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /api/servers/{id}/history`
|
||||
|
||||
- Proposito: devolver una historia basica de snapshots para un servidor concreto.
|
||||
- Metodo HTTP: `GET`
|
||||
- Ruta: `/api/servers/{id}/history`
|
||||
- Parametros opcionales: `limit` entre `1` y `100`
|
||||
- Identificadores aceptados: `server_id` numerico interno o `external_server_id`
|
||||
- Estado actual: implementado para validacion tecnica
|
||||
|
||||
Ejemplo JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"data": {
|
||||
"title": "Historial por servidor",
|
||||
"context": "current-hll-history",
|
||||
"source": "local-snapshot-storage",
|
||||
"server_id": "hll-esp-tactical-rotation",
|
||||
"limit": 20,
|
||||
"items": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Consumo previsto desde frontend
|
||||
|
||||
- El frontend deberia llamar primero a `GET /health` solo para comprobaciones tecnicas o entornos de desarrollo, no para condicionar el render basico de la landing.
|
||||
- Los endpoints de contenido (`/api/community`, `/api/trailer`, `/api/discord`, `/api/servers`) deberian consumirse con `fetch`.
|
||||
- Si una llamada falla, la landing debe conservar un fallback estatico mientras exista contenido fijo en `index.html`.
|
||||
- La futura migracion debe reemplazar valores hardcoded de forma incremental, endpoint por endpoint.
|
||||
|
||||
## Notas de alcance
|
||||
|
||||
- Este contrato no introduce autenticacion.
|
||||
- Este contrato no define base de datos.
|
||||
- Este contrato no integra Discord ni servidores reales.
|
||||
- La implementacion de estos endpoints queda para tasks posteriores.
|
||||
Reference in New Issue
Block a user