~/diego-viscarra
$ man construmarket.md
~/proyectos/construmarket/case-study.md
Enterprise Financial ERP / B2B Web Platform
Lead Fullstack Engineer & Software Architect

Sistema de Control Presupuestario de Obras

Gobernanza financiera, auditoría con precisión de 6 decimales y prevención de sobrecostos en tiempo real.

CLIENTEGrupo ConstruMarket
TIEMPO2026 — En Producción
ESTADOSistema en producción activa
// Métricas & Invariantes Clave
1,730+
Pruebas automatizadas
Pytest + Vitest + AST Linter para garantizar cero regresiones matemáticas
DECIMAL(18,6)
Precisión unitaria
Cálculo de tasas sin redondeo para evitar fugas silenciosas de miles de dólares
7 estados
Máquina de estados finita
Ciclo de vida inmutable con trazabilidad estricta de aprobaciones
0
Aritmética en cliente
Invariante I-14: todo cálculo financiero se ejecuta en el núcleo de dominio
$cat pantallas_clave.preview
[5 PANTALLAS DOCUMENTADAS]
construmarket ~ GET /proyectos/:id
Pantalla InsigniaGET /proyectos/:id
Espacio de Proyecto (Project Command Center)
Clic para pantalla completa ⤢

Centro de mando unificado con semáforos de desviación de margen en tiempo real, KPIs ejecutivos e historial de eventos sin pestañas fragmentadas.

⚠Aviso: Los datos, cifras y registros mostrados son ficticios y corresponden a pruebas simuladas (mock data); no pertenecen a la empresa ni exponen información real.
// Contexto de Negocio & El Reto Real

ConstruMarket diseña, suministra e instala obras arquitectónicas monumentales (centros comerciales, pérgolas bioclimáticas, cancelería). En proyectos de 2 a 12 meses con cientos de insumos, el sistema legacy en hojas de cálculo sufría de 4 dolores críticos:

⚠Fugas silenciosas por redondeo

El sistema legacy trataba el costo unitario como dinero con 2 decimales en vez de una tasa. En 14,800m de cable, redondear $0.1534 a $0.15 causaba pérdidas inmediatas de $50 por línea.

⚠Gasto a ciegas y sobrecostos tardíos

Compras emitía pedidos sin saber el saldo remanente real del rubro; los sobregiros se detectaban semanas después cuando la factura del proveedor llegaba a contabilidad.

⚠Mutabilidad de presupuestos aprobados

Cualquier ajuste sobreescribía la base de datos, destruyendo la foto histórica original ('papel de lo aprobado') aprobada por el comité de gerencia.

⚠ERP corporativo intocable

El ERP corporativo (SAMI, 500+ tablas) prohibía modificaciones en su esquema. Toda la solución debía convivir en un esquema satélite sin bloqueos transaccionales.

// Decisiones de Arquitectura e Ingeniería

Arquitectura Hexagonal Pura (Ports & Adapters)

Dominio Puro

El núcleo de dominio no tiene ninguna dependencia externa (ni Flask, ni SQL Server, ni bibliotecas externas).

  • ›Reglas de negocio y cálculos financieros encapsulados en entidades puras de Python.
  • ›Puertos abstractos (Interfaces ABC) para repositorios de datos y servicios externos.
  • ›Adaptadores HTTP e infraestructura desacoplados y fácilmente testeables.

Gobernanza Financiera: Invariante I-14

Rigor Matemático

Prohibición total de cálculos de dinero en el frontend.

  • ›El cliente web solo renderiza valores exactos devueltos por el backend.
  • ›Validación en milisegundos de disponibilidad de rubro antes de admitir cualquier solicitud de gasto.
  • ›Instantáneas inmutables mes a mes para el cierre financiero de proyectos.
// Desglose del Catálogo de Pantallas
01.Espacio de Proyecto (Project Command Center)

Centro de mando unificado con semáforos de desviación de margen en tiempo real, KPIs ejecutivos e historial de eventos sin pestañas fragmentadas.

GET /proyectos/:id[01-command-center.png]
02.Panorama Ejecutivo vs. Tablero Operativo

Tablero consolidado de obras activas, presupuestos globales, alertas tempranas de riesgo y estado de salud de cada proyecto.

GET /dashboard[02-dashboard.png]
03.Libro de Rubros y Presupuesto de Costeo

Árbol jerárquico WBS y desglose de costos unitarios con aritmética exacta de 6 decimales para evitar pérdidas silenciosas de margen.

GET /costeos[03-presupuesto-costeos.png]
04.Cierre Mensual de Proyectos (Financial Closing Grid)

Reemplazo de hojas de cálculo de más de 25 columnas por una matriz transpuesta ultralegible con instantáneas inmutables de presupuestos.

GET /reportes/cierre-mensual[04-cierre-mensual.png]
05.Superficie Única de Captura de Gasto

Interfaz transaccional rápida con bloqueo en milisegundos contra sobrecostos no presupuestados y balanceo automático de partidas.

POST /salidas/nueva[05-captura-gastos.png]
// Ficha Técnica Completa
BACKEND
• Python 3.13
• Flask 3.0
• pyodbc 5.2
• ReportLab 5.0
• OpenPyXL
FRONTEND
• React 19
• TypeScript
• Vite
• TanStack Query v5
• Tailwind CSS
BASE DE DATOS
• Microsoft SQL Server
• Esquema aislado proyectos.*
• Transacciones atómicas