Plataforma de operaciones de campo
Software de operaciones para una empresa de servicios de ingeniería en Colombia: equipos de los clientes y alarmas de mantenimiento, órdenes de trabajo que los técnicos ejecutan desde el celular y se firman en sitio, cotizaciones, cartera e informes de servicio en PDF, más un portal donde los clientes siguen sus equipos, solicitudes y saldos. En producción en Google Cloud.
Camino de una petición en producción
- app web o celularNext.js, JWT
- FastAPIcorrelation ID, DTOs validados
- auth y alcancerol, alcance de técnico y aliado
- servicio de dominiochequeo de organización, máquina de estados
- repositorioSQLAlchemy asíncrono, PostgreSQL
- efectos secundarioscorreos, notificaciones y PDFs en segundo plano
Tres apps, un backend
Back office
Personal
Clientes, equipos, proveedores y catálogos; operaciones, proyectos, cotizaciones, cartera, informes y un mapa en vivo de técnicos y clientes.
App de técnicos
Web móvil
Órdenes asignadas con check-in y check-out, fotos de evidencia, formularios dinámicos y dos firmas, y sigue funcionando sin señal.
Portal de clientes y aliados
Autoservicio
Equipos, solicitudes de servicio, PQRS, cotizaciones por aprobar y saldos de cartera.
API
FastAPI en Cloud Run
Un solo backend para las tres apps, con identidades separadas para el personal y los usuarios del portal.
Decisiones de arquitectura
- Órdenes de trabajo como máquina de estados
- Pendiente → asignada → en ejecución ⇄ pausada → ejecutada → terminada → cerrada. Un trabajo no se puede terminar sin fotos de inicio y fin, los campos obligatorios del formulario y dos firmas: la del técnico y la del cliente, con el nombre de quien firma.
- Terminado significa bloqueado
- Un trabajo terminado queda en solo lectura para el técnico, escribe una fila en el historial del equipo y le envía al cliente el informe en PDF por correo.
- Tickets con transiciones por actor
- El personal maneja casi toda la solicitud, los técnicos solo los pasos de ejecución y el cliente aprueba o rechaza la cotización.
- Datos acotados a la organización
- Cada registro lleva su organización; un desajuste se responde como no encontrado, y el aislamiento tiene sus propias pruebas.
- Dos sistemas de identidad
- Los tokens del personal y del portal se firman por separado, y un token de portal queda atado a exactamente un cliente o un aliado.
- Roles más excepciones
- Una matriz de permisos por rol con excepciones por usuario; los técnicos solo ven su propio trabajo y los aliados solo los clientes que tienen asignados.
- Efectos secundarios fuera de la petición
- Correos de auditoría, notificaciones del portal y PDFs adjuntos corren como tareas en segundo plano después de responder.
- Capas que siguen siendo capas
- api → domain → data, con un solo contrato de errores y un hook que bloquea el código que rompe las capas antes de escribirlo.
Hecho para el campo
- Funciona sin señal
- Los formularios guardan una copia local, un borrador y una cola de cambios pendientes que se sincronizan cuando el celular vuelve a tener conexión, con un estado visible.
- Firmas en el celular
- Técnico y cliente firman en pantalla; las firmas se guardan con el trabajo y salen impresas en el informe.
- Formularios dinámicos
- El personal diseña formularios de inspección con un constructor por tipo de trabajo, sin necesidad de un despliegue.
- Alarmas y mapa en vivo
- Las alarmas de mantenimiento llegan por server-sent events, y una señal de ubicación (con permiso) alimenta un mapa en vivo.
Documentos y dinero
- Cotizaciones y cartera juntas
- Aprobar una cotización crea su cuenta por cobrar en la misma transacción; luego vienen los pagos y las notas crédito y débito.
- Informes en PDF
- Cotizaciones, informes de servicio e informes financieros generados desde plantillas HTML.
- Excel de ida y vuelta
- Importación y exportación masiva, protegida contra inyección de fórmulas.
- Tareas programadas
- Una revisión diaria de alarmas de mantenimiento, marcado de cartera vencida y recordatorios únicos a los 30 y 90 días.
Corriendo en Google Cloud
- Cloud Run
- La API y la app web como servicios separados.
- Cloud SQL
- PostgreSQL 16, con las migraciones aplicadas por el proxy de Cloud SQL como un paso de cada despliegue.
- Cloud Storage
- Fotos, firmas y PDFs detrás de una interfaz de almacenamiento, servidos con URLs firmadas.
- Entrega
- Cloud Build en cada push a main: build, Artifact Registry, migraciones y despliegue. Los secretos viven en Secret Manager.
- Programador
- En la nube, un programador externo llama a un endpoint interno protegido con un secreto, en vez de correr las tareas dentro del proceso web.
- Correo
- Un proveedor intercambiable (API, SMTP o un modo local que guarda el HTML en disco para revisarlo).
Disciplina de ingeniería
- Probado
- 434 pruebas de backend pasando en la última ejecución, escritas con pruebas primero, más pruebas unitarias en la web.
- Esquema como código
- 32 migraciones de Alembic.
- Por escrito
- Roadmaps por fases, especificaciones de funcionalidades y post-mortems de bugs junto al código.
- Herramientas
- Ruff en Python y TypeScript estricto en la app web.