Docs

Documentación
técnica pública.

Las guías con las que trabajamos en AULAS LATAM: convenciones, diseño de APIs, seguridad, frontend, datos e IA. Úsalas, cítalas o propón mejoras.

9
Guías
v1.0
Versión

Introducción

Esta documentación describe cómo construimos software en el ecosistema AULAS LATAM. Está organizada según el marco Diátaxis: tutoriales para aprender, guías para resolver tareas, referencia para consultar y explicaciones para entender el porqué.

Las guías son normativas para los proyectos de AULAS LATAM y de libre consulta para cualquier persona. Cuando una regla tiene excepción, la excepción se documenta en un ADR.

Palabras clave. “Debe” indica una regla obligatoria; “debería”, una recomendación fuerte que admite excepciones justificadas; “puede”, una opción.

Convenciones de código

El objetivo es que cualquier persona del equipo pueda leer, revisar y modificar cualquier repositorio sin fricción.

  • Cada repositorio debe incluir .editorconfig, formateador y linter configurados y ejecutados en integración continua.
  • Los nombres deben describir intención: calcularDigitoVerificacion, no calc2.
  • El código y sus identificadores pueden estar en inglés o español, pero no mezclados dentro del mismo módulo.
  • Los mensajes de commit siguen Conventional Commits.

Mensajes de commit

feat(api): agrega paginación por cursor en /eventos
fix(auth): corrige expiración de sesión en Safari
docs(readme): documenta variables de entorno
refactor(pagos): separa conciliación del webhook
chore(deps): actualiza dependencias de desarrollo

# Cambio incompatible:
feat(api)!: elimina el parámetro "page" en favor de "cursor"

Flujo de Git y revisión

Trabajamos con ramas de vida corta sobre main. Todo cambio llega por pull request y main siempre debe poder desplegarse.

  • Ramas: feat/…, fix/…, docs/…. Idealmente viven menos de tres días.
  • Pull requests pequeños: si la revisión toma más de 30 minutos, probablemente debe dividirse.
  • Al menos una aprobación de otra persona; dos para cambios en autenticación, pagos o datos personales.
  • La integración continua debe pasar antes de fusionar: pruebas, lint, análisis estático y auditoría de dependencias.

Lista de verificación del pull request

- [ ] Describe el problema y la solución
- [ ] Incluye pruebas o explica por qué no aplican
- [ ] Actualiza la documentación afectada
- [ ] No introduce secretos ni datos personales
- [ ] Considera accesibilidad y rendimiento (si hay interfaz)

Diseño de APIs

Diseñamos contract-first: el contrato OpenAPI 3.1 se revisa antes de escribir la implementación y es la fuente de verdad para clientes y pruebas.

  • Recursos en plural y en minúsculas: /v1/eventos, /v1/eventos/{id}.
  • Versión mayor en la ruta (/v1). Los cambios compatibles no cambian la versión.
  • Paginación por cursor para colecciones que crecen; nunca devolver colecciones sin límite.
  • Fechas en ISO 8601 con zona horaria; montos como enteros en la unidad mínima de la moneda.
  • Errores en formato Problem Details (RFC 9457), con Content-Type: application/problem+json.

Ejemplo de error

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://aulas.dev/docs/errores/validacion",
  "title": "Datos inválidos",
  "status": 422,
  "detail": "El campo fecha_inicio debe ser anterior a fecha_fin.",
  "instance": "/v1/eventos/8f2c",
  "errors": [{ "pointer": "/fecha_inicio", "code": "rango_invalido" }]
}

Seguridad

La seguridad es un requisito, no una fase. Tomamos OWASP ASVS como referencia de controles y el OWASP Top 10 for LLM Applications para sistemas con IA.

Estándar de entrega

ControlQué se exige
threat_modelModelado de amenazas (STRIDE) para cada épica o cambio de arquitectura.
sast_scanAnálisis estático sin hallazgos críticos ni altos abiertos.
dependency_auditDependencias sin vulnerabilidades conocidas críticas; excepciones documentadas con fecha de revisión.
sbom_generatedSBOM en formato CycloneDX o SPDX adjunto a cada versión.
tests_passedPruebas automatizadas en verde, incluidas las de autorización.
docs_publishedDocumentación de uso, operación y cambios actualizada.
peer_reviewRevisión por al menos otra persona; dos en áreas sensibles.

Reglas básicas

  • Los secretos nunca van en el repositorio: se usan variables de entorno o un gestor de secretos.
  • Mínimo privilegio para personas, servicios y agentes de IA; los agentes no ejecutan acciones irreversibles sin confirmación humana.
  • HTTPS en todo (los dominios .dev lo exigen por estar en la lista HSTS preload).
¿Encontraste una vulnerabilidad? Escríbenos de forma privada a [email protected] antes de divulgarla. Responderemos y coordinaremos la corrección.

PWA y frontend

Construimos para teléfonos de gama media y conexiones irregulares, que es la realidad de buena parte de América Latina.

  • Accesibilidad WCAG 2.2 nivel AA: contraste, foco visible, navegación por teclado y textos alternativos.
  • Core Web Vitals en el percentil 75: LCP ≤ 2,5 s, INP ≤ 200 ms, CLS ≤ 0,1.
  • Respeto a prefers-reduced-motion: las animaciones son opcionales, el contenido no.
  • Service worker con estrategia explícita: red primero para páginas, caché primero para recursos versionados, página offline.
  • Fuentes y recursos alojados en el propio dominio, sin rastreadores de terceros por defecto.

Datos e IA responsable

El tratamiento de datos personales en Colombia se rige por la Ley 1581 de 2012. Además, aplicamos estas reglas a cualquier sistema con IA:

  • Minimización: solo se recolectan los datos necesarios para la finalidad informada.
  • Prototipos y retos usan datos sintéticos o anonimizados, nunca datos reales de clientes.
  • Toda funcionalidad con IA tiene evaluación documentada: métricas, conjunto de prueba y limitaciones conocidas.
  • Revisión humana en decisiones que afectan derechos, dinero o reputación de las personas.
  • Las personas usuarias deben saber cuándo interactúan con un sistema automatizado.

Registros de decisión (ADR)

Cada decisión de arquitectura relevante se registra en docs/adr/ con numeración consecutiva. Un ADR no se edita: si la decisión cambia, se escribe uno nuevo que lo reemplaza.

# ADR-0000: Título corto de la decisión

Estado: Propuesto | Aceptado | Reemplazado por ADR-XXXX
Fecha: AAAA-MM-DD

## Contexto
¿Qué problema o fuerza obliga a decidir?

## Opciones consideradas
1. Opción A — ventajas / desventajas
2. Opción B — ventajas / desventajas

## Decisión
Elegimos ... porque ...

## Consecuencias
Qué se vuelve más fácil, qué se vuelve más difícil, qué riesgos aceptamos.

Despliegue y operación

  • Tres entornos: desarrollo, staging y producción. Staging replica producción con datos de prueba.
  • Cada despliegue tiene plan de reversión probado y se anuncia con su versión y CHANGELOG.
  • Copias de seguridad automáticas con restauración verificada periódicamente.
  • Incidentes: detectar, contener, comunicar y aprender con un postmortem sin culpables.
¿Ves algo que mejorar? Estas guías evolucionan con la comunidad. Propón cambios desde Comunidad.

Documentado
es terminado.

Si trabajas con estos estándares, ya hablas el mismo idioma que nuestros equipos.