Caso profesional extenso · Bloque 1
Auditoría previa de integración
Una organización quiere intercambiar expedientes con un proveedor, pero requisitos, tráfico y OpenAPI no describen el mismo comportamiento. Tu trabajo es convertir esa incertidumbre en un contrato revisable antes de que empiece la implementación.
Este caso sustituye deliberadamente al miniproyecto del bloque 1. No se pide código: el producto profesional es una auditoría técnica capaz de evitar que dos equipos implementen interpretaciones incompatibles.
Contexto profesional
El área de operaciones envía expedientes a un proveedor externo. El proveedor ha entregado una propuesta funcional, una captura de pruebas y un fragmento OpenAPI. El equipo consumidor debe decidir si el contrato está suficientemente definido para iniciar el desarrollo.
Tu destinatario es una revisión conjunta entre producto, el equipo consumidor y el proveedor. Por tanto, cada hallazgo debe distinguir hechos, inferencias, riesgos y preguntas abiertas.
Debes preservar
- Identidad estable de cada expediente.
- Posibilidad de reintentar tras una respuesta perdida.
- Errores que permitan actuar al consumidor.
- Una representación JSON documentada.
No debes asumir
- Qué framework utiliza el proveedor.
- Que una captura aislada define todo el contrato.
- Que 200 implica éxito de negocio.
- Que REST obliga a una única ruta posible.
Paquete de trabajo
- Requisitos recibidosObjetivos, restricciones y afirmaciones contradictorias de las partes.
- Mensajes HTTP de pruebaTres intercambios: creación, repetición tras timeout y consulta de estado.
- Fragmento OpenAPI propuestoContrato incompleto que debe contrastarse con requisitos y tráfico.
- Plantilla de entregaEstructura vacía para recursos, operaciones, estados, riesgos y preguntas.
Contradicciones iniciales
Estas observaciones sirven para comenzar la auditoría; no constituyen una lista exhaustiva ni adelantan cómo resolver cada diferencia.
| Área | Requisitos | Tráfico u OpenAPI | Pregunta de auditoría |
|---|---|---|---|
| Operación principal | Se denomina «enviar expediente» y debe ser REST. | Aparecen rutas orientadas a acción y a recurso. | ¿Qué recurso se crea o modifica realmente? |
| Resultado | Se solicita un código HTTP distinto según el resultado. | Una captura devuelve 200 con ok: false. | ¿Qué debe observar un cliente para distinguir éxito y error? |
| Identidad | La referencia externa evita duplicados. | El schema no la marca como requerida. | ¿Quién asigna cada identificador y cuál gobierna el reintento? |
| Documentos | Un expediente admite varios documentos. | Una representación utiliza un string singular. | ¿Cuál es la cardinalidad y forma pública? |
| Procesamiento | La validación puede continuar después de aceptar el envío. | La respuesta de creación declara un estado final. | ¿Qué significa aceptado frente a completado? |
Encargo
- Separa todas las afirmaciones del paquete en requisito, comportamiento observado, definición contractual o supuesto.
- Construye un inventario de recursos, representaciones, identificadores y relaciones.
- Reconstruye los tres intercambios HTTP y señala qué promete o contradice cada uno.
- Propón un contrato corregido a nivel de rutas, métodos, parámetros, bodies, respuestas y códigos de estado.
- Analiza seguridad e idempotencia de las operaciones y el comportamiento de una repetición tras timeout.
- Define una matriz de estados para éxito, aceptación pendiente, dato inválido, recurso ausente, duplicado o conflicto y fallo interno.
- Clasifica los cambios necesarios por compatibilidad e identifica a los consumidores afectados.
- Registra riesgos que no puedan cerrarse con la evidencia actual y formula preguntas concretas al cliente o proveedor.
Producto esperado
1. Inventario de contrato
Recursos, identidad, relaciones, representaciones y vocabulario compartido.
2. Contrato corregido
Tabla de operaciones con entradas, salidas, semántica y condiciones.
3. Matriz de estados
Situación, familia y código propuesto, cuerpo mínimo y acción esperada del cliente.
4. Registro de riesgos
Impacto, evidencia, supuesto, decisión pendiente y responsable de responder.
5. Compatibilidad
Cambios, consumidores afectados y transición proporcional.
6. Preguntas al cliente
Preguntas cerrables y priorizadas; no una lista genérica de dudas.
Criterios de aceptación
- Cada decisión importante puede rastrearse a una evidencia o a un supuesto declarado.
- El inventario diferencia expediente, documento, envío y estado cuando se tratan como conceptos distintos.
- Las rutas propuestas mantienen un vocabulario coherente y los métodos conservan su semántica.
- La matriz distingue errores del cliente, conflictos de estado y fallos internos.
- La propuesta define qué ocurre cuando se repite una petición cuya primera respuesta se perdió.
- Ausencia, null y campo opcional no se utilizan como sinónimos.
- El contrato corregido permite que un consumidor formule peticiones y casos de prueba.
- Los cambios incompatibles incluyen una transición y no solo una etiqueta de «breaking change».
- Las preguntas abiertas indican por qué la respuesta modifica el contrato o el riesgo.
- No se introduce implementación, base de datos, autenticación o despliegue para ocultar una decisión contractual.
Pistas graduadas
Pista 1 · Crea una tabla de procedencia
- Usa columnas para requisito, tráfico, OpenAPI e interpretación.
- Cuando dos columnas discrepen, no elijas todavía una ganadora: registra el conflicto.
Pista 2 · Separa recursos de procesos
- Pregunta qué cosas poseen identidad y qué verbos describen cambios sobre ellas.
- Un nombre de operación heredado no obliga a conservarlo como ruta pública.
Pista 3 · Simula una respuesta perdida
- Imagina que el servidor completó la primera petición pero el cliente no recibió la respuesta.
- Recorre tu contrato con una segunda petición idéntica y comprueba el estado observable.
Pista 4 · Prioriza preguntas
- Una buena pregunta desbloquea una decisión concreta de ruta, identidad, representación o estado.
- Coloca primero las respuestas que podrían obligar a rediseñar más partes del contrato.
Fuera de alcance
- Implementar endpoints o escribir código FastAPI.
- Elegir tablas, base de datos o estrategia de persistencia.
- Implementar autenticación, autorización o cifrado.
- Diseñar contenedores, infraestructura o despliegue.
- Completar un documento OpenAPI de producción con todos sus metadatos opcionales.
- Publicar una solución única: la revisión debe aceptar alternativas defendibles.