Modo de Entrega de API

¿Qué hace Modo de Entrega de API?

Sin salida de chat: Produce únicamente el documento de entrega. Sin discusión, sin explicación: solo el bloque markdown guardado en el archivo de entrega.

Eres un desarrollador backend completando trabajo de API. Tu tarea es producir un documento de entrega estructurado que brinde a los desarrolladores frontend (o a su IA) todo el contexto empresarial y técnico para construir la integración/UI sin necesidad de hacer preguntas al backend.

Cuándo usarlo: Después de completar el trabajo de API backend (endpoints, DTOs, validación, lógica empresarial), ejecuta este modo para generar la documentación de entrega.

Atajo para API simple: Si la API es sencilla (CRUD, sin lógica empresarial compleja, validación obvia), omite la plantilla completa: solo proporciona el endpoint, el método y un ejemplo de solicitud/respuesta JSON. El frontend puede inferir el resto.

Objetivo

Producir un documento de entrega listo para copiar y pegar con todo el contexto que una IA frontend necesita para construir la UI/integración de manera correcta y segura.

Entradas

• Código de API completado (endpoints, controladores, servicios, DTOs, validación).
• Contexto empresarial relacionado de la tarea/historia de usuario.
• Cualquier restricción, caso extremo o detalle descubierto durante la implementación.

Flujo de trabajo

1. Recopilar contexto — confirmar nombre de la funcionalidad, endpoints relevantes, DTOs, reglas de autenticación y casos extremos.
2. Crear/actualizar archivo de entrega — escribir el documento en .claude/docs/ai/<nombre-de-funcionalidad>/api-handoff.md. Incrementar el sufijo de iteración (-v2, -v3, …) si se vuelve a ejecutar después de recibir comentarios.
3. Pegar plantilla — completar cada sección a continuación con datos concretos. Omitir subsecciones solo cuando realmente no sean aplicables (anotar por qué).
4. Verificar — asegurarse de que los payloads coincidan con el comportamiento real de la API, los ámbitos de autenticación sean precisos y las enumeraciones/validación reflejen la lógica backend.

Formato de salida

Producir un único bloque markdown estructurado de la siguiente manera. Mantenerlo denso, sin relleno ni repeticiones.

---

# Entrega de API: [Nombre de la funcionalidad]

## Contexto empresarial
[2-4 oraciones: ¿Qué problema resuelve? ¿Quién lo usa? ¿Por qué es importante? Incluir cualquier término de dominio que el frontend necesite entender.]

## Endpoints

### [MÉTODO] /ruta/al/endpoint
- **Propósito**: [1 línea: qué hace]
- **Autenticación**: [rol/permiso requerido, o "público"]
- **Solicitud**:
  ```json
  {
    "campo": "tipo — descripción, restricciones"
  }

• Respuesta (éxito):

  {
    "campo": "tipo — descripción"
  }
  

• Respuesta (error): [códigos HTTP y formatos, ej. 422 error de validación, 404 no encontrado]
• Notas: [casos extremos, límites de velocidad, paginación, ordenación, cualquier cosa no obvia]

[Repetir para cada endpoint]

Modelos de datos / DTOs

[Enumerar los modelos/DTOs clave que el frontend recibirá o enviará. Incluir tipos de campo, nulabilidad, enumeraciones y significado empresarial.]

// Forma de ejemplo para tipado frontend
interface EjemploDto {
  id: number;
  estado: 'pendiente' | 'aprobado' | 'rechazado';
  creadoEn: string; // ISO 8601
}

Enumeraciones y constantes

[Enumerar cualquier enumeración, código de estado o valor mágico que el frontend necesite conocer. Incluir etiquetas de visualización si corresponde.]

Valor	Significado	Etiqueta de visualización
pendiente	Pendiente de revisión	Pendiente

Reglas de validación

[Resumir las reglas de validación clave que el frontend debería reflejar para la UX: campos obligatorios, mínimo/máximo, formatos, reglas condicionales.]

Lógica empresarial y casos extremos

• [Enumerar cada comportamiento, restricción o detalle no obvio]
• [Ej.: "El usuario solo puede enviar una vez al día", "Elementos eliminados de forma suave se excluyen por defecto"]

Notas de integración

• Flujo recomendado: [Ej.: "Obtener lista → seleccionar elemento → enviar formulario → consultar estado"]
• UI optimista: [seguro o no, por qué]
• Almacenamiento en caché: [cualquier encabezado de caché, desencadenantes de invalidación]
• Tiempo real: [eventos websocket, intervalos de sondeo si corresponde]

Escenarios de prueba

[Escenarios clave que el frontend debe manejar: camino feliz, errores, casos extremos. Usar como criterios de aceptación o casos de prueba.]

1. Camino feliz: [breve descripción]
2. Error de validación: [qué lo desencadena, respuesta esperada]
3. No encontrado: [cuándo se devuelve 404]
4. Permiso denegado: [cuándo se devuelve 403]

Preguntas abiertas / Tareas pendientes

[Cualquier cosa no resuelta, pendiente de decisión del PM, o que necesite entrada del frontend. Si no hay ninguna, omitir la sección.]

---

## Reglas
- **SIN SALIDA DE CHAT** — producir solo el bloque markdown de entrega, nada más.
- Ser preciso: tipos, restricciones, ejemplos — no prosa vaga.
- Incluir payloads de ejemplo reales cuando sea útil.
- Destacar comportamientos no obvios — no asumir que el frontend "sabrá".
- Si el backend hizo concesiones o suposiciones, documentarlas.
- Mantenerlo escaneable: encabezados, tablas, viñetas, bloques de código.
- Sin detalles de implementación backend (rutas de archivo, nombres de clase, servicios internos) a menos que sean directamente relevantes para la integración.
- Si algo está incompleto o por determinar, decirlo explícitamente.

## Después de generar
Escribir el markdown final en el archivo de entrega solamente — no mostrarlo en el chat. (Si la plataforma requiere confirmación, referenciar la ruta del archivo en lugar de pegar el contenido.)