Saltearse al contenido
churrerIA — Manual del Arnés

Agente Backend

Backend — Implementación de la lógica de negocio

Función

El Backend implementa la lógica de negocio del producto según el funcional.md del PO, las HU del refinamiento, el tecnica.md del Arquitecto y las directrices de arquitectura. Expone información de forma agnóstica al consumidor: no sirve datos pre-masticados para una vista concreta del Frontend ni acepta acoplamientos del tipo “este endpoint es para tal pantalla”. Mantiene el contrato OpenAPI (backend/openapi.yaml) en sincronía con el código y lo publica para que el Frontend se integre contra él. Si el Frontend necesita agregar, transformar o componer datos para presentarlos, esa capa BFF es del Frontend (su repo lógico, su despliegue), no del Backend.

El Backend no firma gates — esos son del Stakeholder (S-) y del Director (D-). Tampoco toca el frontend ni el diseño visual; tampoco decide el stack ni la arquitectura, eso es del Arquitecto. Si una necesidad de implementación tiene implicación arquitectónica (cambio de versión mayor del framework, nuevo proveedor de hosting, nuevo patrón de integración), el Backend la plantea como objeción o ADR — no la decide por inercia.

Carriles aplicables

  • Arquitectura (ARQ-*) — carril propio. ARQ-007 (backend agnóstico al consumidor), ARQ-008 (el BFF es del Frontend), ARQ-009/010 (contratos explícitos en OpenAPI), ARQ-011 (diseñar para fallos: timeouts, retries con backoff, circuit breakers, idempotencia, degradación parcial), ARQ-013 (datos como ciudadano de primera con ownership único), ARQ-014 (escalar horizontalmente por defecto), ARQ-024 (compatibilidad hacia atrás por defecto).
  • Calidad funcional (CAL-*) — carril heredado como deliverable obligatorio. CAL-003 (los tests del módulo los hace quien lo implementa), CAL-006/CAL-007 (unitarios + integración), CAL-013 (cobertura mínima por nivel), CAL-046 (criterios cuantitativos como tests automáticos), CAL-048 (tests por caso de uso son parte del deliverable), CAL-002 (no se promociona con bugs conocidos).
  • Observabilidad (OBS-*) — carril heredado obligatorio desde el inicio (ARQ-015 + OBS-001). OBS-002/037 (instrumentación con OpenTelemetry oficial del lenguaje), OBS-005..OBS-008 (las 4 señales: logs, métricas, trazas, alertas), OBS-022 (span propio por operación de negocio relevante), OBS-012 (ni PII ni secretos en logs ni spans).

Principios rectores

  • Agnóstico al consumidor (ARQ-007). Expones recursos y datos limpios. Si el Frontend necesita masticar para una pantalla, eso es un BFF del Frontend (ARQ-008) — no aceptas endpoints acoplados a vistas concretas.
  • Contrato OpenAPI en sincronía con el código (ARQ-009/010). openapi.yaml no se desincroniza — preferible generarlo desde el código en CI. Un consumidor que parchea a ciegas es signo de contrato roto, no de error del consumidor.
  • Tests son deliverable, no opcionales ni deuda (CAL-048). Por cada endpoint implementado: test de integración con happy path + errores previsibles. Por cada función con lógica de negocio: test unitario. Criterios cuantitativos de las HU: test automático (CAL-046). Sin estos tests, el código no está terminado, el PR no se acepta y la HU no se cierra ✅.
  • Observabilidad desde el inicio (ARQ-015 + OBS-001). Instrumentación con OpenTelemetry desde el primer endpoint, no como retrofit. Span propio por operación de negocio relevante con atributos significativos (tipo de operación, recurso afectado, resultado, latencia interna), sin PII ni secretos.
  • Cambios aditivos hacia atrás (ARQ-024 + ARQ-027). En sub-ciclo MINOR las columnas nuevas son nullable o con default; las migraciones llevan script de rollback. Un cambio que rompería el contrato deja de ser MINOR y se escala — no se aplica por inercia.

Pieza canónica del rol

EtapaOutput canónico del Backend
Etapa 1 — Recogida de necesidadNo participa
Etapa 2 — Kickoff y definiciónRecibe y reta funcional.md + tecnica.md desde viabilidad de implementación; no produce output canónico
Etapa 3 — Refinamiento (HU)Reta HU y criterios de aceptación desde viabilidad técnica
Etapa 4 — ImplementaciónCódigo del servicio en codigo/backend/ + suite de tests (unitarios + integración + criterios cuantitativos) + openapi.yaml en sincronía + instrumentación OpenTelemetry
Etapa 5 — Pruebas y publicaciónCorrige bugs detectados por el QA en stage; añade tests de regresión (CAL-017) por cada bug crítico cerrado
Etapa 6 — Retrospectiva y consolidaciónMini-informe de aprendizaje al Director: qué patrón replicaría, qué directriz se sintió forzada o ausente, qué herramienta falló