CUENTAS CLARAS · Portafolio

Integrantes

Matías Román QA & Coordinador — Pruebas funcionales y automatizadas. Tecnologías: Postman, GitHub Actions.
Patricio Quintanilla Desarrollador Frontend — Interfaz e integración. Tecnologías: React, TypeScript, Next.js.
Frank Vogt Desarrollador Backend — API y base de datos. Tecnologías: Node.js, MySQL, Redis.

Introducción

En esta presentación veremos los aspectos esenciales de Cuentas Claras: una aplicación web para gestionar cobros, cargos y conciliaciones en comunidades. Revisaremos arquitectura (frontend, backend y seguridad), autenticación segura, bases de datos relacionales y uso de Docker para entornos reproducibles.

Descripción del proyecto

Propuesta de solución

Plataforma web centralizada y segura para gestión de comunidades.
Automatiza registro de cargos, pagos y conciliaciones.
Autenticación segura (JWT, bcrypt, 2FA) y separación por comunidad.
Entorno reproducible con Docker e integración de pasarelas de pago.

Problema

Gestión manual de cobros y conciliaciones propensa a errores.
Falta de trazabilidad y herramientas no integradas.
Necesidad de un sistema centralizado que garantice seguridad y transparencia.

Objetivo del proyecto

General: Desarrollar una plataforma web segura y eficiente para emitir cargos, registrar pagos y realizar conciliaciones automáticas, optimizando procesos administrativos y garantizando transparencia financiera.

Específico: Implementar autenticación y control de acceso (JWT, bcrypt, 2FA) para proteger la información y mantener separación de datos entre comunidades.

Tecnologías usadas

React

Node.js

MySQL

Docker

GitHub

Metodología usada

Utilizamos metodología ágil Scrum: trabajo por sprints, tareas con objetivos claros y revisiones periódicas. Esto permitió organizar el equipo, adaptarse a cambios y mejorar continuamente mediante feedback.

Arquitectura

Si el diagrama no se renderiza: abre el archivo en un navegador moderno con internet y recarga. Guarda el archivo en UTF-8 si ves caracteres raros.

Modelo de datos (resumen)

MySQL en 3NF con desnormalizaciones puntuales para rendimiento. Tablas clave: comunidad, unidad, emision_gasto_comun, pago_aplicacion.

DIAGRAMA PRINCIPAL · Entidades y relaciones

Diagrama principal extraído del modelo y la base de datos SQL.

Resumen de Reglas de Negocio · Cuentas Claras

Flujo lógico: Usuario → Comunidad → Estructura → Operaciones → Administración

Grado 1 · Fundamentales

Multitenancy por Comunidad
Cada registro se asocia a comunidad_id; middleware filtra queries para evitar accesos cruzados.
Ej: SELECT * FROM gasto WHERE comunidad_id = ?

Roles y Permisos
Roles definidos en frontend; backend valida con JWT y checks de permiso.
Ej: if (!hasPermission('VIEW_FINANCES')) return 403;

Grado 2 · Estructurales

Estructura Jerárquica
Comunidades → edificios → torres → unidades; relaciones y FK en la BD.

Validaciones de Datos
Validaciones en frontend (regex) y backend (Joi) para formatos y seguridad.
Ej: validateRUT(rut) en validators.ts

Grado 3 · Operativas

Prorrateo Automático
Vistas o servicios calculan alícuotas y distribuciones; visibilidad por rol.
Ej: vista_prorrateo en SQL.

Aplicación de Multas
Solo perfiles autorizados (p. ej. presidente); registra en auditoría.
Ej: if (user.roles.includes('presidente')) createMulta();

Grado 4 · Administrativas

Aprobación de Gastos
Estados y workflow en BD/services hasta aprobación final.
Ej: UPDATE gasto SET estado = 'aprobado';

Conciliaciones y Reportes
Conciliación con bancos (aprobada por contador) y exportación segura filtrada por comunidad.

Estas reglas cubren ~80–90% de la lógica de negocio. Complementos técnicos (APIs, integraciones WebPay/email, middleware, migraciones, Docker) soportan la implementación pero no son reglas de negocio.

Sugerencia: mover este contenido a docs/reglas_negocio.md y enlazar desde la presentación.

Módulo 01 · Comunidades y parámetros

Gestión de comunidades, parámetros de cobranza, centros de costo y categorías. Reglas: unicidad de códigos y validación de alícuotas.

Detalle: ccbackend/base/DIAGRAMAS/SECCION_01_COMUNIDADES.md

Módulo 02 · Usuarios, roles y autenticación

Gestión de personas, usuarios, roles por comunidad, sesiones, 2FA (TOTP) y auditoría. Reglas: unicidad de username/RUT.

Detalle: ccbackend/base/DIAGRAMAS/SECCION_02_USUARIOS.md

Módulo 03 · Estructura organizacional

Edificios, torres, unidades y titulares. Reglas: jerarquía flexible y validaciones de tenencia y alícuotas. Para condominios (casas individuales), la relación directa Comunidad → Unidad permite estructuras sin edificios/torres.

Detalle: ccbackend/base/DIAGRAMAS/SECCION_03_ESTRUCTURA.md

Módulo 04 · Gestión financiera

Proveedores, documentos de compra, categorización contable y triggers de integridad para gastos y documentos.

Detalle: ccbackend/base/DIAGRAMAS/SECCION_04_FINACIERA.md

Módulo 05 · Cobros y pagos

Emisión, distribución (prorrateo), cuentas de cobro por unidad, medios de pago y conciliación bancaria.

Detalle: ccbackend/base/DIAGRAMAS/SECCION_05_COBROS.MD

Módulo 06 · Amenidades y reservas

Gestión de amenidades, políticas de reserva, tarifas y detección de solapamientos.

Detalle: ccbackend/base/DIAGRAMAS/SECCION_06_AMENIDADES.MD

Módulo 07 · Soporte y mantención

Tickets, historial, comentarios, mantenciones programadas y SLA. Flujos: ciclo de vida de ticket y automatizaciones.

Detalle: ccbackend/base/DIAGRAMAS/SECCION_07_SOPORTE.MD

Módulo 08 · Reportes y analytics

Dashboards, KPIs, reportes programados y exportación (PDF/Excel/CSV).

Detalle: ccbackend/base/DIAGRAMAS/SECCION_08_REPORTES.MD

Demostración y próximos pasos

Preparar endpoints demo, credenciales y walkthrough. Siguientes pasos: pruebas, despliegue y documentación final.

CUENTAS CLARAS · PORTAFOLIO DE TÍTULO