87 lines
3.7 KiB
Markdown
87 lines
3.7 KiB
Markdown
# TASK-005-frontend-backend-contract
|
|
|
|
## Goal
|
|
Definir el contrato inicial entre frontend y backend para el proyecto HLL Vietnam, estableciendo endpoints, formatos de respuesta y convenciones mínimas sin implementar todavía integraciones reales con Discord, servidores de juego o base de datos.
|
|
|
|
## Context
|
|
El proyecto ya dispone de una landing mínima funcional y de un backend Python bootstrap con verificación básica de estado. Antes de añadir lógica real, es importante fijar un contrato claro entre frontend y backend para evitar improvisación posterior y permitir que futuras tasks implementen endpoints y consumo de datos de forma consistente.
|
|
|
|
## Steps
|
|
1. Revisar la estructura actual del frontend y del backend.
|
|
2. Revisar el estado actual del backend bootstrap y el endpoint de salud existente.
|
|
3. Definir el conjunto mínimo de endpoints previstos a corto plazo, aunque algunos queden documentados como futuros. Incluir al menos:
|
|
- `GET /health`
|
|
- `GET /api/community`
|
|
- `GET /api/trailer`
|
|
- `GET /api/discord`
|
|
- `GET /api/servers`
|
|
4. Para cada endpoint, documentar:
|
|
- propósito
|
|
- método HTTP
|
|
- ruta
|
|
- formato de respuesta
|
|
- ejemplo JSON
|
|
- estado actual: implementado, previsto o placeholder
|
|
5. Definir convenciones básicas de respuesta:
|
|
- nombres de campos
|
|
- estructura JSON
|
|
- uso de `status`
|
|
- tratamiento mínimo de errores
|
|
6. Documentar cómo debería consumir el frontend estos endpoints más adelante, sin implementarlo todavía.
|
|
7. Añadir o actualizar documentación técnica para que el contrato quede claro dentro del repositorio.
|
|
8. Si detectas incoherencias pequeñas entre documentación y bootstrap actual, corrígelas sin salirte del alcance.
|
|
|
|
## Files to Read First
|
|
- README.md
|
|
- AGENTS.md
|
|
- docs/project-overview.md
|
|
- docs/roadmap.md
|
|
- docs/decisions.md
|
|
- ai/repo-context.md
|
|
- ai/architecture-index.md
|
|
- backend/README.md
|
|
- backend/app/__init__.py
|
|
- backend/app/main.py
|
|
- frontend/index.html
|
|
- frontend/assets/js/main.js
|
|
|
|
## Expected Files to Modify
|
|
- docs/project-overview.md
|
|
- docs/decisions.md
|
|
- backend/README.md
|
|
- ai/architecture-index.md
|
|
- opcionalmente un nuevo documento técnico si encaja mejor, por ejemplo:
|
|
- `docs/frontend-backend-contract.md`
|
|
|
|
## Constraints
|
|
- No implementar todavía endpoints reales adicionales.
|
|
- No integrar Discord real.
|
|
- No integrar servidores de juego reales.
|
|
- No introducir base de datos.
|
|
- No cambiar el comportamiento visible del frontend.
|
|
- No añadir frameworks ni dependencias nuevas.
|
|
- No hacer cambios destructivos.
|
|
- Mantener la solución clara, pequeña y útil para futuras tasks.
|
|
|
|
## Validation
|
|
- Existe documentación clara del contrato inicial frontend-backend.
|
|
- `GET /health` queda reflejado correctamente como endpoint actual.
|
|
- Los endpoints futuros quedan documentados con ejemplos coherentes.
|
|
- El contrato usa convenciones consistentes de respuesta JSON.
|
|
- El repositorio queda preparado para que siguientes tasks implementen endpoints reales de forma ordenada.
|
|
|
|
## Change Budget
|
|
- Preferir menos de 5 archivos modificados o creados.
|
|
- Preferir menos de 220 líneas cambiadas.
|
|
## Outcome
|
|
|
|
- Se añadió `docs/frontend-backend-contract.md` como referencia central del contrato inicial frontend-backend.
|
|
- Se actualizaron `docs/project-overview.md`, `docs/decisions.md` y `backend/README.md` para reflejar el contrato y el estado actual de `GET /health`.
|
|
- No se implementaron endpoints nuevos ni se cambió el comportamiento visible del frontend.
|
|
|
|
## Validation Result
|
|
|
|
- Verificado con `python -c "from app.main import build_health_payload; print(build_health_payload())"` en `backend/`.
|
|
- Resultado comprobado: `{'status': 'ok', 'service': 'hll-vietnam-backend', 'phase': 'bootstrap'}`.
|
|
- No aplican integration tests para este alcance documental.
|