Yasmany Ramos García yasmramos

📊 EconoNova FX - Sistema Contable Profesional

Sistema contable moderno y profesional desarrollado con JavaFX 17 y Ebean ORM 17, diseñado para cumplir con la normativa contable cubana (Resolución 340/2004).

📋 Tabla de Contenidos

Características
Tecnologías
Requisitos
Instalación
Módulos
Testing
Documentación
Desarrollo
Contribución
Licencia

✨ Características

Contabilidad General

✅ Plan de cuentas configurable (activo, pasivo, patrimonio, ingresos, gastos)
✅ Gestión de tipos de cuenta (detalle, titular, consolidación)
✅ Validación de partida doble automática
✅ Períodos contables con control de apertura/cierre
✅ Transacciones balanceadas con validación en tiempo real

Gestión de Transacciones

✅ Registro de comprobantes contables
✅ Asientos con múltiples entradas (debe/haber)
✅ Numeración automática de transacciones
✅ Estados: Borrador, Validado, Contabilizado, Anulado
✅ Auditoría completa (quién, cuándo, qué)

Control de Períodos

✅ Apertura y cierre de períodos mensuales/anuales
✅ Bloqueo de períodos cerrados
✅ Validación de fechas en transacciones
✅ Período actual activo por defecto

Usuarios y Seguridad

✅ Roles: Administrador, Contador, Auditor, Visualizador
✅ Permisos granulares por módulo
✅ Autenticación local (preparado para LDAP/AD)
✅ Bitácora de actividades

Terceros y Contactos

✅ Clientes, proveedores, empleados
✅ Clasificación por tipo de tercero
✅ Datos fiscales completos
✅ Historial de transacciones por tercero

Dashboard e Informes

✅ Panel principal con KPIs contables
✅ Balances de comprobación
✅ Estados financieros básicos
✅ Reportes exportables (PDF, Excel, CSV)

Tipos de Cambio

✅ Gestión de tasas de cambio activas
✅ Histórico de tipos de cambio
✅ Conversión automática en transacciones multicurrency

Arquitectura Multi-Tenant y Cumplimiento Normativo

✅ Arquitectura modular por paquetes (com.econovafx.modules.*)
✅ Diseño preparado para multi-tenant (empresas múltiples)
✅ Cumplimiento de la Resolución 340/2004 (normativa contable cubana)
✅ Exportación a formatos oficiales (PDF, Excel)
✅ Auditoría completa de todas las operaciones

🚀 Tecnologías Utilizadas

Tecnología	Versión	Descripción
Java	17 LTS	Lenguaje de programación
JavaFX	17	Interfaz gráfica de usuario moderna
Ebean ORM	17.11.0	Mapeo objeto-relacional de alto rendimiento
H2 Database	2.2.224	Base de datos embebida para desarrollo/testing
PostgreSQL	42.7.3	Base de datos de producción
Maven	3.9+	Gestión de dependencias y build
Logback	1.4.14	Framework de logging SLF4J
Avaje Inject	12.6	Inyección de dependencias ligera
JUnit 5	5.11.0	Testing framework
AssertJ	3.25.x	Assertions fluents para tests
Apache PDFBox	2.0.29	Exportación a PDF
Apache POI	5.2.5	Exportación a Excel
Ikonli	12.4.0	Iconos JavaFX (Material Design)
jBCrypt	0.4	Hashing de contraseñas

📋 Requisitos Previos

Java JDK 17 o superior (descargar)
Maven 3.9+ (instalar)
Git para clonar el repositorio

Verifica tu instalación:

java --version
mvn --version
git --version

🛠️ Instalación y Ejecución

1. Clonar el Repositorio

git clone https://github.com/yasmramos/EconovaFX.git
cd EconovaFX

2. Compilar el Proyecto

mvn clean compile

3. Ejecutar Tests (Opcional pero recomendado)

mvn test

4. Ejecutar la Aplicación

mvn javafx:run

5. Primer Inicio

Al iniciar por primera vez:

Se crea automáticamente la base de datos H2 en target/econovafx.db
Se genera un período contable para el año actual
Usuario por defecto: admin (sin contraseña en modo desarrollo)

📦 Módulos Implementados

Módulo	Estado	Descripción
Contabilidad (Accounting)	✅ Completado	Plan de cuentas, transacciones, períodos contables
Activos (Assets)	✅ Completado	Gestión de activos corrientes
Banco (Bank)	✅ Completado	Cuentas bancarias y conciliación bancaria
Facturación (Billing)	✅ Completado	Emisión y gestión de facturas
Caja (Cash)	✅ Completado	Gestión de efectivo y arqueo de caja
Core	✅ Completado	Configuración, empresa, utilidades
Activos Fijos (Fixed Assets)	✅ Completado	Depreciación y gestión de activos fijos
Inventario (Inventory)	✅ Completado	Almacenes, items y control de stock
Cuentas por Pagar (Payables)	✅ Completado	Gestión de obligaciones a proveedores
Nómina (Payroll)	✅ Completado	Gestión de salarios y empleados
Cuentas por Cobrar (Receivables)	✅ Completado	Gestión de créditos a clientes
Reportes (Reporting)	✅ Completado	Balances, estados financieros y consolidación
Seguridad (Security)	✅ Completado	Usuarios, roles y permisos
Presupuestos	⏳ Pendiente	Control presupuestario

🧪 Testing

El proyecto cuenta con 385 tests automatizados que cubren:

✅ Tests unitarios de servicios y validadores
✅ Tests de integración con base de datos H2
✅ Tests de repositorios
✅ Validaciones de negocio (partida doble, períodos, etc.)

Ejecutar Tests

# Todos los tests
mvn test

# Tests específicos
mvn test -Dtest=AccountingValidatorTest
mvn test -Dtest=TransactionServiceTest

# Con reporte de cobertura (requiere plugin jacoco)
mvn test jacoco:report

Estado Actual

Tests ejecutados: 385
Pasados: 385 (100%)
Fallos: 0
Errores: 0

📚 Documentación

La documentación completa está indexada en docs/README.md:

Documentación Principal

Índice de Documentación - Vista general de toda la documentación
Guía de Usuario - Manual para usuarios finales
Arquitectura - Diseño técnico y estructura modular
Reportes Financieros - Consolidación multi-empresa y filtrado por fechas
Especificación Fase 1 - Especificación funcional
Análisis GAP Resolución 340/2004 - Análisis de cumplimiento
Análisis Detallado Resolución 340/2004 - Evidencia de implementación
Roadmap Resolución 340/2004 - Hoja de ruta de implementación
Docker - Guía de despliegue con Docker

Documentación del Proyecto

Changelog - Historial de cambios por versión
Commit Guidelines - Convenciones para mensajes de commit

👩‍💻 Guía de Desarrollo

Configurar IDE

IntelliJ IDEA

File → Open → Seleccionar pom.xml
Esperar a que Maven importe dependencias
Ejecutar: mvn javafx:run desde Maven panel

Eclipse

File → Import → Existing Maven Projects
Seleccionar directorio raíz
Ejecutar: Run As → Maven Build... → javafx:run

Comandos Maven Útiles

# Limpieza y compilación
mvn clean compile

# Ejecutar tests
mvn test

# Empaquetar JAR
mvn package

# Instalar en repositorio local
mvn install

# Ejecutar aplicación
mvn javafx:run

# Generar sitio de documentación
mvn site

# Ver árbol de dependencias
mvn dependency:tree

# Actualizar dependencias
mvn versions:display-dependency-updates

Convenciones de Código

Naming: CamelCase para clases, snake_case para BD
Entidades: Heredan de BaseEntity (id, createdAt, updatedAt)
Repositorios: Interfaz + implementación opcional
Servicios: Lógica de negocio, transaccionalidad
Controladores: Solo UI, delegan a servicios
Tests: Nombre descriptivo, Given-When-Then

Agregar Nueva Entidad

Crear clase modelo en src/main/java/com/econovafx/modules/<módulo>/model/ extendiendo BaseEntity
Anotar con @Entity, @Table(name = "tabla")
Definir campos con anotaciones JPA/Ebean
Crear repositorio en src/main/java/com/econovafx/modules/<módulo>/repository/
Crear servicio en src/main/java/com/econovafx/modules/<módulo>/service/
Crear validador en src/main/java/com/econovafx/modules/<módulo>/validation/ (si aplica)
Crear controlador UI en src/main/java/com/econovafx/modules/<módulo>/ui/controller/ (si aplica)
Agregar tests en src/test/java/com/econovafx/modules/<módulo>/

🤝 Contribución

¡Las contribuciones son bienvenidas! Sigue estos pasos:

Fork el repositorio
Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)
Commit tus cambios (git commit -m 'feat: agregar nueva funcionalidad')
Push a la rama (git push origin feature/nueva-funcionalidad)
Abre un Pull Request

Convenciones de Commits

Usamos Conventional Commits:

feat: Nueva funcionalidad
fix: Corrección de bug
docs: Cambios en documentación
style: Formato, faltantes, etc.
refactor: Refactorización
test: Agregar/modificar tests
chore: Mantenimiento, dependencias

Código de Conducta

Sé respetuoso y constructivo
Documenta tus cambios
Escribe tests para nuevas funcionalidades
Sigue las convenciones del proyecto

📄 Licencia

Este proyecto está bajo la licencia MIT. Ver LICENSE para más detalles.

Copyright (c) 2024 Yasmín Ramos

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

📞 Contacto

Autor: Yasmany Ramos García
Email: yasmramos95@gmail.com
GitHub: @yasmramos
Proyecto: EconoNova FX

🙏 Agradecimientos

Ebean ORM - Por su excelente framework ORM
OpenJFX - Por JavaFX moderno y potente
Comunidad Java Cuba - Por el apoyo continuo
Resolución 340/2004 - Normativa contable cubana

¿Te gusta este proyecto? ¡Dale una ⭐️ en GitHub!

Hecho con ❤️ para la comunidad contable cubana