SGCM — Sistema Web de Gestión de Citas Médicas

Plataforma web para automatizar y optimizar el proceso de gestión de citas médicas del Hospital Regional Traumatológico y Quirúrgico Prof. Juan Bosch (HTQPJB) en La Vega, República Dominicana.

Trabajo de grado para optar por el título de Licenciatura en Informática — Universidad Nacional Pedro Henríquez Ureña (UNPHU), Recinto La Vega.

---

Tabla de contenido

• Sobre el proyecto
• Características principales
• Arquitectura
• Stack tecnológico
• Evolución del stack tecnológico
• Inicio rápido
• Despliegue con TLS (HTTPS)
• Estructura del proyecto
• Casos de uso
• Roles y permisos
• Endpoints REST
• Variables de entorno
• Migraciones de base de datos
• Pruebas automatizadas
• Integración continua
• Comandos útiles
• Documentación
• Respaldos del sistema
• Operación sin internet (offline)
• Cumplimiento legal
• Autores
• Versión

---

Sobre el proyecto

El SGCM automatiza el proceso de gestión de citas que el HTQPJB realizaba previamente con registros físicos, libretas y comunicación verbal. La plataforma reemplaza esos soportes manuales por una solución digital centralizada que opera en la intranet del hospital.

Lo que el sistema NO es: una reingeniería del proceso institucional. La lógica operativa, los roles y las responsabilidades del personal se conservan.

Lo que el sistema SÍ es: la automatización de los puntos del flujo donde los soportes manuales generaban duplicaciones, demoras y descoordinación.

---

Características principales

• Autenticación JWT con hashing bcrypt y expiración configurable.
• Control de acceso basado en roles (RBAC) en dos capas: backend y frontend.
• Calendario interactivo con FullCalendar.js, vista mensual por defecto.
• Prevención física de duplicaciones mediante índice único parcial en PostgreSQL.
• Bloqueo temporal del registro de consulta: el médico no puede registrar diagnósticos antes de la fecha de la cita.
• Vinculación de usuarios con perfiles de médico desde la UI del administrador.
• Reset de contraseña por administrador (sin requerir la contraseña anterior; auditado).
• Reportes PDF generados con WeasyPrint, con fecha de emisión, numeración secuencial y trazabilidad del usuario que los genera.
• Reportes administrativos: resumen y PDF de usuarios por rol, detalle y PDF de médicos activos con estadísticas.
• Agenda extendida para secretaria/admin con filtros por médico, rango de fechas, estado y especialidad; exportación a PDF y Excel; impresión optimizada (@media print).
• Sistema de respaldos (CU-16) con tres modalidades: local, externo (USB/UNC) y andamiaje preparado para nube (Amazon S3, Google Cloud Storage, Azure Blob).
• Gestión de catálogos administrables (CU-17): el catálogo de especialidades vive en BD, se administra desde el panel admin y se valida en backend.
• Auditoría transaccional de todas las operaciones críticas (Ley 172-13).
• Suite de pruebas automatizadas con pytest.
• CI/CD con GitHub Actions ejecutando linter, tests y construcción de imagen Docker.
• Despliegue contenedorizado con Docker Compose.
• Máscaras visuales en cédula y teléfono para mejor experiencia de usuario.

---

Arquitectura

flowchart TB
    Browser[Navegador del usuario]
    subgraph Server["Servidor en intranet del hospital"]
        Nginx[Nginx<br/>puertos 80 redirige a 443<br/>TLS + proxy + estaticos]
        API[FastAPI<br/>puerto 8000<br/>backend]
        DB[(PostgreSQL<br/>puerto 5432<br/>base de datos)]
    end

    Browser -->|HTTPS 443| Nginx
    Nginx -->|/api/v1/*| API
    Nginx -->|archivos HTML/JS/CSS| Browser
    API <-->|SQL| DB

---

Stack tecnológico

Backend

• Python 3.11+ — Lenguaje principal.
• FastAPI — Framework web asíncrono con OpenAPI automático.
• SQLModel — ORM combinado con validación Pydantic.
• Alembic — Migraciones versionadas del esquema.
• python-jose — Generación y validación de JWT.
• passlib + bcrypt — Hashing seguro de contraseñas.
• WeasyPrint — Generación de PDFs desde HTML/CSS.
• pytest + httpx — Pruebas automatizadas.

Base de datos

• PostgreSQL 15 — Con índices únicos parciales para prevenir duplicaciones.

Frontend

• HTML5 + JavaScript ES6 — Vanilla, sin framework.
• Tailwind CSS — Servido localmente desde static/vendor/tailwind/.
• FullCalendar.js 6.1.15 — Calendario interactivo (también local).
• Lucide Icons — Iconografía servida desde static/vendor/lucide/.
• Fuente Inter — Archivos .woff2 locales (static/fonts/inter/).

Sin internet: todas las dependencias del frontend viajan en el repositorio. El sistema funciona completo dentro de la intranet del HTQPJB aunque el servidor no tenga salida a internet. Ver docs/OFFLINE.md.

Infraestructura

• Docker + Docker Compose — Orquestación de contenedores.
• Nginx — Proxy inverso, servidor de archivos estáticos y terminación TLS (puerto 80 redirige a 443).
• openssl — Generación de certificados TLS autofirmados para la intranet (scripts/gen-cert.sh y scripts/gen-cert.ps1).
• GitHub Actions — Integración continua.

---

Evolución del stack tecnológico

El stack actual no fue el original. Durante las fases de análisis y diseño, y a lo largo de las primeras iteraciones de desarrollo, el proyecto evolucionó significativamente conforme fui descubriendo limitaciones de las herramientas iniciales y conociendo alternativas más apropiadas para los requisitos del sistema. Esta sección documenta esa evolución, porque entender por qué algo cambió es tan importante como saber qué se está usando hoy.

Comparativa: idea inicial vs implementación final

Componente	Idea inicial	Stack actual	Razón del cambio
Base de datos	SQLite	PostgreSQL 15	SQLite no soporta índices únicos parciales con cláusula WHERE, característica clave del diseño para resolver el conflicto entre cancelación y reagendamiento de citas. Tampoco está pensado para concurrencia real con múltiples secretarias agendando al mismo tiempo.
Framework backend	Flask	FastAPI	Flask es minimalista pero requiere construir manualmente validación de datos, documentación OpenAPI y manejo asíncrono. FastAPI lo trae todo de fábrica con Pydantic, genera Swagger automáticamente y ofrece un rendimiento muy superior gracias a Starlette y al soporte nativo de async/await.
ORM	SQLAlchemy puro	SQLModel sobre SQLAlchemy y Pydantic	SQLModel unifica los modelos de base de datos con los esquemas de validación en una sola capa. Reduce código duplicado y mantiene la potencia de SQLAlchemy por debajo.
Frontend	HTML, JavaScript y Tailwind CSS	Igual, más FullCalendar.js	Se mantuvo el enfoque vanilla por su simplicidad y por evitar la complejidad de un framework para un sistema de este alcance. Se incorporó FullCalendar.js como pieza clave para la visualización del calendario interactivo.
Entorno de operación	Servidor local con Docker	Igual	Decisión validada y mantenida. La contenedorización facilita despliegue, reproducibilidad y portabilidad.
Control de versiones	Git	Git más GitHub Actions	Se añadió integración continua: cada commit ejecuta tests automatizados y construye la imagen Docker, garantizando que el código en el repositorio siempre sea desplegable.
Diseño visual	Draw.io	Draw.io	Se mantiene como herramienta de planificación de diagramas (DFD, casos de uso, MER).

Componentes incorporados durante la evolución

Algunos componentes no estaban en la planificación inicial pero se sumaron al darme cuenta de su importancia:

• Alembic para migraciones versionadas del esquema de base de datos. Sin él, cualquier cambio de modelo implicaba intervenciones manuales propensas a errores.
• WeasyPrint para generación de reportes PDF a partir de HTML y CSS, lo que permite reutilizar templates del frontend para reportes profesionales.
• python-jose y passlib (bcrypt) para JWT y hashing de contraseñas. La autenticación inicial se pensó simple, pero al estudiar la Ley 172-13 quedó claro que se requería hashing fuerte y tokens firmados.
• Nginx como proxy inverso. Originalmente se contemplaba que FastAPI sirviera todo (API y archivos estáticos), pero al separar responsabilidades se obtuvo mejor rendimiento, terminación SSL más limpia y un punto de entrada único.
• pytest y httpx para una suite de pruebas automatizadas. Esto no estaba en el plan original; surgió de la necesidad de evitar regresiones al iterar el sistema.
• GitHub Actions para CI/CD. Práctica que adopté tras enfrentar el primer fallo en pruebas que un test automatizado habría evitado.
• ruff como linter para análisis estático del código.

Por qué documentar esta evolución

Porque demuestra dos cosas que considero importantes en cualquier proyecto técnico serio:

1. El stack no se eligió por moda, sino por requisitos. Cada cambio respondió a una limitación concreta encontrada durante el desarrollo o a una característica específica que el sistema necesitaba (por ejemplo, los índices únicos parciales de PostgreSQL que SQLite no soporta).

2. El proyecto evolucionó con disciplina. Cambiar de Flask a FastAPI o de SQLite a PostgreSQL en mitad del desarrollo no es trivial: implicó reescribir partes considerables del código. Fueron decisiones tomadas tempranamente, antes de que el costo del cambio fuera prohibitivo, lo cual es una habilidad fundamental en ingeniería de software.

El stack actual no es perfecto ni final. Hay áreas donde reconozco oportunidades de mejora futura (tests end-to-end con Playwright, observabilidad con Prometheus, despliegue con Kubernetes para múltiples instancias), pero corresponden a un alcance mayor al de un trabajo de grado y quedan documentadas como recomendaciones de evolución.

---

Inicio rápido

Requisitos previos

• Docker Engine 24+ y Docker Compose v2.
• Git 2.30+.

Instalación en cuatro pasos

# 1. Clonar el repositorio
git clone https://github.com/je7remy/HTQ_Citas.git sgcm
cd sgcm

# 2. Configurar variables de entorno
cp .env.example .env
# Editar .env y configurar JWT_SECRET_KEY (mínimo 32 caracteres)

# 3. Generar el certificado TLS autofirmado (requerido por Nginx)
# Linux / macOS:
./scripts/gen-cert.sh                  # CN=sgcm.intranet
# o con la IP/hostname real del servidor: ./scripts/gen-cert.sh 10.0.0.15
# Windows PowerShell (requiere openssl en el PATH):
# .\scripts\gen-cert.ps1

# 4. Arrancar el sistema
docker compose up -d --build

# 5. Verificar
docker compose ps

Acceder a https://localhost/ en el navegador. El puerto 80 redirige automáticamente a 443. La primera vez el navegador mostrará un