34. Caso práctico: documentación técnica completa de un sistema de gestión de turnos
34.1 Introducción
En este último tema integraremos los conceptos del curso mediante un caso práctico: la documentación técnica completa de un sistema de gestión de turnos. El objetivo no es escribir todos los documentos finales, sino mostrar cómo se organiza un conjunto documental coherente.
El sistema permitirá que pacientes consulten profesionales, reserven turnos, cancelen reservas y reciban notificaciones. También permitirá que administradores configuren agendas y que profesionales consulten sus horarios.
Usaremos este caso para relacionar requisitos, documentación funcional, arquitectura, API, base de datos, instalación, despliegue, operación, pruebas, seguridad y manuales de usuario.
34.2 Objetivo del caso práctico
El objetivo es construir una visión completa de la documentación necesaria para un sistema realista. No todos los proyectos requieren la misma formalidad, pero este ejemplo permite ver cómo se conectan los documentos entre sí.
La documentación debe servir a distintas audiencias: usuarios finales, desarrolladores, testers, operación, soporte, administradores, profesionales y responsables del producto.
34.3 Mapa documental del sistema
La imagen muestra el mapa documental de un sistema de gestión de turnos: requisitos, funcionalidad, arquitectura, API, base de datos, instalación, despliegue, operación, seguridad, pruebas, manual de usuario y mantenimiento.
34.4 Alcance del sistema
El sistema de turnos tendrá funcionalidades principales: registro e inicio de sesión, búsqueda de profesionales, consulta de disponibilidad, reserva de turnos, cancelación, administración de agendas, consulta de agenda profesional y envío de notificaciones.
El alcance documental debe reflejar estas funcionalidades, pero también sus aspectos técnicos: modelo de datos, API, seguridad, instalación, operación, pruebas y soporte.
34.5 Audiencias del caso
Las audiencias principales serán pacientes, profesionales, administradores, soporte, desarrollo, operación, testers y responsables del producto. Cada una necesita documentación distinta.
El paciente necesita guías de uso. El desarrollador necesita arquitectura, API, instalación local y reglas internas. Operación necesita despliegue, monitoreo y respaldos. Soporte necesita solución de problemas frecuentes. Producto necesita alcance, reglas y trazabilidad.
34.6 Documentación de requisitos
Los requisitos deben registrar necesidades y restricciones. Por ejemplo:
- RF-001: el paciente puede consultar profesionales por especialidad.
- RF-002: el paciente puede reservar un turno disponible.
- RF-003: el paciente puede cancelar un turno hasta 24 horas antes.
- RF-004: el administrador puede configurar la agenda de un profesional.
- RNF-001: las operaciones requieren autenticación.
- RNF-002: la reserva debe evitar doble asignación del mismo horario.
34.7 Documentación funcional
La documentación funcional debe describir procesos y reglas. Para reservar un turno, se documenta el flujo principal: buscar profesional, seleccionar horario, confirmar reserva y recibir confirmación.
También deben documentarse alternativas: no hay disponibilidad, el horario fue ocupado antes de confirmar, el usuario no tiene sesión activa o el profesional ya no atiende esa especialidad.
Las reglas deben ser precisas: un turno no puede reservarse dos veces, un paciente no puede cancelar fuera de plazo y un administrador puede cancelar por motivos operativos.
34.8 Casos de uso e historias
Los casos de uso principales pueden ser Reservar turno, Cancelar turno, Administrar agenda y Consultar agenda profesional. Cada uno debe incluir actor, objetivo, condiciones previas, flujo principal, alternativas y resultado final.
Una historia de usuario podría ser: "Como paciente, quiero reservar un turno en línea para elegir un horario sin comunicarme telefónicamente". Sus criterios de aceptación deben convertir esa necesidad en condiciones verificables.
34.9 Arquitectura
La documentación de arquitectura puede mostrar una aplicación web, una API backend, una base de datos, un servicio de notificaciones y un proveedor de autenticación. También debe indicar responsabilidades e interfaces.
La aplicación web permite interacción con usuarios. La API implementa reglas de negocio. La base de datos almacena pacientes, profesionales, agendas y turnos. El servicio de notificaciones envía confirmaciones y avisos.
34.10 Decisiones técnicas
El proyecto debe registrar decisiones relevantes. Por ejemplo, usar procesamiento asíncrono para notificaciones, aplicar bloqueo o transacción para evitar doble reserva, usar roles para autorización y mantener documentación técnica en el repositorio.
Cada decisión debe incluir contexto, alternativas, decisión y consecuencias. Esto permitirá entender por qué el sistema fue diseñado de esa forma.
34.11 API
La documentación de API debe incluir endpoints como:
GET /profesionales?especialidad=...para buscar profesionales.GET /profesionales/{id}/disponibilidadpara consultar horarios.POST /turnospara reservar un turno.DELETE /turnos/{id}para cancelar una reserva.
Para cada endpoint se documentan parámetros, autenticación, permisos, respuestas exitosas, errores y ejemplos.
34.12 Base de datos
La documentación de base de datos debe explicar entidades como Paciente, Profesional, Especialidad, Agenda, Disponibilidad, Turno y Notificación. También debe describir relaciones, claves y restricciones.
Una regla importante es evitar doble reserva. Esta regla puede estar protegida por restricciones, transacciones o bloqueos. La documentación debe indicar cómo se garantiza esa integridad.
34.13 Instalación y despliegue
La guía de instalación debe permitir ejecutar el sistema localmente: dependencias, variables de entorno, base de datos, migraciones, datos de prueba y comandos de inicio.
La guía de despliegue debe explicar ambientes, versión, artefactos, pipeline, configuración, migraciones, validaciones posteriores y rollback.
34.14 Operación y soporte
La documentación de operación debe incluir monitoreo, alertas, registros, respaldos y restauración. Debe indicar cómo verificar si la API funciona, si la cola de notificaciones está procesando y si la base de datos responde correctamente.
Soporte necesita guías para problemas frecuentes: el usuario no puede iniciar sesión, no ve horarios disponibles, no puede cancelar un turno o no recibe notificaciones.
34.15 Seguridad
La documentación de seguridad debe definir autenticación, roles, permisos y datos sensibles. Pacientes, profesionales y administradores tienen permisos distintos.
También debe identificar datos personales y, si corresponde, datos médicos. Debe indicar controles de acceso, auditoría de acciones críticas y manejo seguro de credenciales y tokens.
34.16 Pruebas
La documentación de pruebas debe incluir estrategia, casos, datos y resultados. Deben probarse reserva exitosa, horario ocupado, cancelación válida, cancelación fuera de plazo, permisos, sesión vencida y notificaciones.
También conviene probar concurrencia: dos pacientes intentando reservar el mismo horario. Esta prueba se relaciona con el requisito no funcional de evitar doble asignación.
34.17 Mapa de documentos recomendados
| Documento | Audiencia | Contenido principal |
|---|---|---|
| Visión general del sistema | Producto, soporte, nuevos integrantes | Objetivo, alcance, roles y funcionalidades. |
| Documentación funcional | Análisis, desarrollo, pruebas | Procesos, reglas, escenarios y estados. |
| Arquitectura | Desarrollo, operación, líderes técnicos | Componentes, responsabilidades e integraciones. |
| Referencia de API | Desarrolladores | Endpoints, parámetros, respuestas y errores. |
| Manual de usuario | Pacientes, profesionales, administradores | Guías paso a paso y problemas frecuentes. |
| Operación y soporte | Operación y soporte | Monitoreo, respaldos, alertas e incidentes comunes. |
34.18 Mantenimiento documental
El sistema de documentación debe mantenerse. Si cambia la regla de cancelación, se actualizan requisitos, documentación funcional, API, pruebas, manual de usuario y guías de soporte. Si cambia el despliegue, se actualizan instalación, operación y rollback.
También conviene definir responsables: producto para reglas, desarrollo para API y diseño, operación para runbooks, soporte para problemas frecuentes y calidad para pruebas.
34.19 Errores frecuentes en el caso
Al documentar un sistema completo suelen aparecer estos errores:
- Crear documentos aislados sin enlaces entre sí.
- Documentar la API sin reglas funcionales asociadas.
- Escribir manuales de usuario con lenguaje técnico.
- No documentar errores frecuentes de soporte.
- Omitir decisiones técnicas que afectan mantenimiento.
- No indicar responsables de actualización.
- Olvidar actualizar pruebas y documentación cuando cambia una regla.
34.20 Qué debes recordar de este tema
- Un sistema real necesita un conjunto de documentos relacionados.
- Cada documento debe tener audiencia, objetivo y responsable.
- Requisitos, funcionalidad, arquitectura, API, datos, pruebas y operación deben conectarse.
- La trazabilidad ayuda a revisar impactos cuando cambia una regla.
- La documentación de soporte y operación es esencial después del despliegue.
- La seguridad y los datos sensibles deben documentarse con cuidado.
- La documentación completa debe mantenerse junto con la evolución del sistema.
34.21 Conclusión del curso
La documentación técnica es una práctica central de la Ingeniería de Software. Permite conservar conocimiento, comunicar decisiones, reducir ambigüedad, facilitar mantenimiento y operar sistemas con mayor seguridad.
A lo largo del curso vimos cómo planificar, escribir, estructurar, revisar, publicar y mantener documentación para distintas audiencias y necesidades. El valor real aparece cuando la documentación se integra al trabajo cotidiano del equipo y evoluciona junto con el software.