Arquitectura y Diseño Técnico del Sistema de Mantenimiento

1. Stack Tecnológico Recomendado

Backend

• Lenguaje: PHP 8.2+ con Laravel 11 o Python 3.11+ con Django 5.0.


• Razón: desarrollo rápido, ecosistema maduro, orquestación de tareas y colas (Laravel Queues, Django Celery) para notificaciones y preventivos.


• Alternativa minimalista: FastAPI (Python) o Slim (PHP), pero perderíamos algunas ventajas de scaffolding.

Base de datos

• PostgreSQL 15+ (preferida) o MySQL 8.0.


• Ventajas: soporte de JSON, transacciones, fiabilidad. PostgreSQL es más robusto para datos geo/referencias si en el futuro se añaden ubicaciones precisas.

Frontend

• Admin/Residente/Técnico: React + Vite (SPA) o Livewire (si usamos Laravel) para menor complejidad.


• Responsive: Tailwind CSS.


• PWA opcional: para que técnicos instalen la app en móvil.

Autenticación

• JWT (JSON Web Tokens) con refresh rotation.


• Guardias por rol (residente, admin, técnico, supervisor).

Notificaciones

• Email: SMTP (configurable por cliente) o servicio como SendGrid/Mailgun.


• WhatsApp (opcional): Twilio API o proveedor local (ej. MessageBird).

Almacenamiento de archivos

• Local ( storage/app/public ) con backups diarios.


• O S3-compatible (MinIO, AWS S3) para escalar.

Colas y tareas programadas

• Laravel Queues (Redis o database) o Celery (Redis/RabbitMQ).


• Para: envío de emails, generación de preventivos, alertas de stock.

Infraestructura y despliegue

• Docker + Docker Compose para desarrollo y producción.


• Nginx como reverse proxy.


• Certbot para Let’s Encrypt.


• Backup automatizado de BD y archivos.

2. Modelo de Datos (Entidades principales)

Usuario (id, nombre, email, password_hash, rol, edificio_id? )

Edificio (id, nombre, dirección, contacto_admin)

Equipo (id, código_qr, marca, modelo, n_serie, fecha_instalacion, ubicación (edificio_id, piso, zona), notas)

OrdenTrabajo (id, numero_ot, edificio_id, equipo_id, residente_id? , técnico_id, estado, prioridad, descripción, fecha_creacion, fecha_asignacion, fecha_inicio, fecha_cierre, observaciones, foto_cierre? )

Repuesto (id, sku, nombre, proveedor, costo_unitario, stock_minimo, stock_actual)

MovimientoInventario (id, repuesto_id, orden_trabajo_id, cantidad, tipo (salida/entrada/ajuste), fecha, usuario_id)

MantenimientoPreventivo (id, equipo_id, tipo_tarea, frecuencia_meses, ultima_fecha, proxima_fecha, orden_trabajo_id? )

Relaciones clave

• OrdenTrabajo pertenece a un Equipo y puede estar asignada a un Técnico.


• OrdenTrabajo puede estar asociada a un Residente que la reportó (opcional, pues a veces el admin crea la OT).


• MovimientoInventario vincula un Repuesto con una OrdenTrabajo (salida por uso).


• Equipo tiene historial completo a través de OrdenTrabajo.


• MantenimientoPreventivo genera OrdenTrabajo when到达 fecha.

3. API REST (Endpoints principales)

Autenticación

• `POST /api/auth/login` → { token, usuario }


• `POST /api/auth/refresh` → nuevo token


• `POST /api/auth/logout`

Residentes

• `GET /api/residentes` (admin) – lista residentes del edificio.


• `POST /api/residentes` (admin) – crear residente.


• `GET /api/residentes/{id}` – ver perfil.


• `GET /api/residentes/{id}/reportes` – listado de OT reportadas por ese residente.

Equipos

• `GET /api/equipos` (admin/supervisor) – lista equipos por edificio.


• `POST /api/equipos` (admin) – crear equipo.


• `GET /api/equipos/{id}` – detalle con historial.


• `PUT /api/equipos/{id}` – actualizar datos.


• `GET /api/equipos/qr/{codigo}` – escaneo QR para ver equipo y reportar (público autenticado como residente).

Órdenes de Trabajo

• `POST /api/ordenes` – crear OT (residente o admin). Body: { equipo_id, descripción, foto? }


• `GET /api/ordenes` – lista con filtros (estado, técnico, fecha). Permisos según rol.


• `GET /api/ordenes/{id}` – detalle.


• `PUT /api/ordenes/{id}` – actualizar estado, asignar técnico, etc. (solo admin/técnico según corresponda).


• `POST /api/ordenes/{id}/cerrar` – cambiar estado a Completado y registrar repuestos/tiempo.


• `GET /api/ordenes/export` – exportar a CSV/Excel (admin).

Repuestos

• `GET /api/repuestos` – lista con stock.


• `POST /api/repuestos` – crear repuesto (admin).


• `PUT /api/repuestos/{id}` – ajustar stock manual (admin).


• `GET /api/repuestos/bajo-stock` – lista de repuestos con stock ≤ mínimo (admin).

Mantenimiento Preventivo

• `GET /api/preventivos` – lista programada.


• `POST /api/preventivos/generar` – forzar generación de órdenes (admin).


• `PUT /api/preventivos/{id}/completar` – marcar como hecho, crear OT si no existe.

Dashboard (admin)

• `GET /api/dashboard/resumen` – métricas aggregate (pendientes, completadas hoy, costo mes, top equipos fallones).


• `GET /api/dashboard/cumplimiento-preventivo` – % cumplido.

4. Interfaz de Usuario (Wireframes conceptuales)

Portal Residente (web móvil)

• Home: botón grande “Reportar falla”. Lista de mis reportes con estados.


• Formulario de reporte: elegir equipo (select con búsqueda), descripción, foto (upload), enviar.


• Detalle de reporte: historial de la máquina, comentarios, fotos de reparación.

Panel Técnico (web + PWA)

• Dashboard personal: órdenes asignadas, pendientes, en progreso.


• Lista de órdenes con filtros. Cada orden se expande para ver detalles.


• Formulario de actualización: cambiar estado, agregar repuestos (buscador de catálogo), tiempo trabajado, observaciones, foto.


• Posibilidad de escanear código QR en el equipo para confirmar ubicación.

Panel Administrador (desktop)

• Dashboard con gráficos y tablas resumidas.


• Gestión de usuarios (crear, desactivar).


• Gestión de equipos (CRUD).


• Inventario: lista de repuestos, ajustes, historial de movimientos.


• Configuración: edificios, notificaciones, límites de costo.


• Reportes: exportar datos.

5. Seguridad

• HTTPS obligatorio.


• JWT con expiración corta (1h) y refresh token długoterminowy almacenado en httpOnly cookie (o local storage con precauciones).


• Middleware de autenticación y autorización por rol.


• Validación de entradas (Laravel Validation o Django Forms).


• Logging de acciones críticas (cambios de estado, modificaciones de inventario).


• Backup cifrado de la base de datos.

6. Escalabilidad y Rendimiento

• Uso de índices en BD: en `ordenes` por `estado`, `fecha_creacion`, `tecnico_id`; en `equipos` por `edificio_id`.


• Caché de configuraciones (ej. lista de repuestos) en Redis.


• Colas para envío de emails y generación de preventivos (evitan bloqueos en solicitudes HTTP).


• Paginación en todas las listas.


• Compresión de imágenes subidas (Intervention Image o Pillow).

7. Despliegue y Operaciones

• Entornos: desarrollo, staging, producción.


• Configuración por variables de entorno (`.env`).


• Dockerfile para backend, Nginx como proxy.


• Scripts de migración de BD (php artisan migrate o Django migrations).


• Supervisor (o systemd) para manejar colas y workers.


• Monitoreo: logs centralizados (Laravel Telescope? o Sentry), salud del servicio (`/health` endpoint).

8. Próximos Pasos

• Validar el modelo de datos con posibles clientes (administradores de edificios).


• Elegir framework (Laravel vs Django) basado en habilidades del equipo de desarrollo.


• Implementar MVP en sprints de 1-2 semanas.


• Realizar pruebas de concepto con un edificio piloto.