ContabilidadSaPolar/docs/planificacion/roadmap.md

Planificación del Proyecto - Sa Polar

Visión General

Sistema de gestión de alquileres desarrollado por fases incrementales. Cada fase añade funcionalidades completas y autónomas.

Fases Completadas

Fase 1 - MVP (Base del Sistema)

Estado: COMPLETADO

Objetivo: Sistema base funcional con operaciones CRUD esenciales y autenticación.

Módulos implementados

Módulo	Funcionalidades
Autenticación	Login con JWT, registro de usuarios, refresh token, roles (ADMIN, GERENTE, CONTABLE, VISUALIZADOR)
Usuarios	CRUD de usuarios, asignación de roles, activación/desactivación
Propiedades	CRUD con jerarquía (edificio → pisos), tipos y estados, historial de cambios de estado
Inquilinos	CRUD, búsqueda, personas físicas y jurídicas
Contratos	CRUD, asociación propiedad+inquilino, cambio automático de estado de propiedad al crear/terminar
Recibos de Ingresos	CRUD, categorías, registro de pagos, cálculo automático de retención IRPF, periodo
Plantillas de Gastos	CRUD, categorías, periodicidad, generación automática de recibos
Recibos de Gastos	CRUD, origen desde plantilla o manual, registro de pagos
Documentos	Subida/descarga polimórfica, validación de tipos por entidad, documentos obligatorios, componente reutilizable en todas las páginas
Dashboard	Resumen general con contadores y agregaciones financieras
Notificaciones	Sistema de notificaciones por usuario con marcado de lectura
Infraestructura	Docker compose (mysql + backend), Swagger/OpenAPI, script init.sql completo

Tareas técnicas realizadas

• Creación del proyecto Spring Boot multi-módulo
• Configuración de Spring Security con JWT
• Mapeo JPA de todas las entidades del dominio
• Script init.sql con DDL y datos semilla
• Configuración Docker con healthcheck de MySQL
• Corrección de tipos de columna (TINYINT UNSIGNED → INT)
• Corrección de palabra reservada read en MySQL
• Corrección de LazyInitializationException con @Transactional
• Generación correcta de hash BCrypt para admin
• Configuración CORS para frontend

Fase 2 - Recibos Automáticos e Incidencias

Estado: COMPLETADO

Objetivo: Automatizar la generación de recibos, gestión de incidencias y mantenimiento programado.

Módulos implementados

Módulo	Funcionalidades
Incidencias	CRUD completo, flujo de estados (SIN_REVISAR → TECNICO_AVISADO → REPARACION_PREVISTA → REPARADO), asignación de técnico, programación de reparación, prioridades
Mantenimiento Programado	CRUD, periodicidad configurable, cálculo de próxima ejecución, recordatorios
Recibos	Generación individual y masiva, numeración automática por serie fiscal, PDF con iText, envío por email con adjunto, log de envíos
Reportes	Informe mensual Excel (ingresos - gastos = balance) con Apache POI
Tareas Programadas	Generación mensual de recibos (día 1 a las 06:00), marcado de vencidos (diario 02:00), revisión de contratos próximos a vencer (día 1 a las 07:00)

Tareas técnicas realizadas

• Entidades ReceiptSeries y EmailLog
• Servicios ReceiptService, PdfReceiptService, EmailReceiptService, ReportService
• ReceiptScheduler con 3 tareas cron
• ReceiptController con 7 endpoints
• Configuración SMTP en application.yml
• Tablas receipt_series y email_log en init.sql
• Endpoints de reportes Excel
• Frontend React + Vite + TypeScript completo
• Páginas: Login, Dashboard, Properties, Tenants, Contracts, Incomes, Expenses, Incidents, Documents
• Capa API con Axios e interceptor JWT
• AuthContext con persistencia en localStorage
• Layout con sidebar y navegación
• Docker compose con servicio frontend (Nginx)
• Proxy reverso en Nginx para /api/*
• Compilación y build exitosos
• ID visible en todas las tablas, detalles y formularios
• Property Groups (Conjuntos) — entidad, CRUD backend, página frontend con propiedades asociadas
• Sistema de documentos con validación tipo-entidad (V5 migration)
• Componente DocumentUploader integrado en Contracts, Tenants, Properties, Incidents, Incomes, Expenses
• Endpoint getDocumentTypesForEntity para filtrar tipos permitidos por entidad
• CRUD completo de Inquilinos con validación de documentos (DNI/NIE/CIF)
• Gestión dinámica de múltiples inquilinos en Contratos con creación inline
• Acciones especiales: "Cobrar" en Ingresos, "Pagar" en Gastos, "Terminar contrato"
• Componentes reutilizables: Modal, ConfirmDialog, Pagination, SortableHeader, Toast, EntityLink
• Hook useSort para ordenación client-side con claves anidadas
• Hook useEntityNavigation para navegación programática entre entidades
• BankDataManager para gestión de datos bancarios de inquilinos (CRUD, validación IBAN)
• Previsualización de documentos (PDF en iframe, imágenes JPEG/PNG/GIF/WebP)
• Autocompletado de direcciones via datalist en formularios
• Badges de estado y prioridad con colores en todas las tablas
• Recepción de filtros desde Dashboard via location.state
• Flyway configurado con 6 migraciones (V1-V6)
• FlywayRepairConfig con estrategia por perfil (dev vs prod)
• Perfiles application-dev.yml y application-prod.yml
• TenantBankData: entidad, controller, repository, service, migración V6

Fase 3 - Funcionalidades Avanzadas

Estado: PARCIALMENTE COMPLETADA

Objetivo: Mejoras en la experiencia de usuario y funcionalidades complementarias.

Completado

Módulo	Funcionalidades
Frontend Avanzado	CRUD completo en 8 páginas (Properties, PropertyGroups, Tenants, Contracts, IncomeReceipts, ExpenseTemplates, ExpenseReceipts, Incidents, Documents) con patrón consistente ViewMode (list/detail/edit/create)
Filtros y búsqueda	Filtros desplegables + búsqueda por texto libre en todas las páginas de listado
Paginación	Paginación client-side con componente Pagination reutilizable (PAGE_SIZE = 20)
Ordenación	Cabeceras ordenables con hook useSort en todas las tablas
Formularios	Formularios de creación/edición completos con validación en todas las entidades
Navegación cruzada	Componente EntityLink para navegar entre entidades relacionadas
Documentos adjuntos	Componente DocumentUploader con drag & drop, previsualización (PDF/imágenes), descarga
Datos bancarios	Componente BankDataManager para gestión de IBAN de inquilinos con validación
Notificaciones UI	Sistema de Toast para feedback de acciones
Flyway	Configurado y funcionando con 6 migraciones (V1-V6), perfiles dev/prod
Repositorio Git	Inicializado con .gitignore completo, 5 commits

V11 — Refactor Financiero (COMPLETADO)

Módulo	Funcionalidades
IncomeReceipt	Nueva entidad con soporte de período, cuenta bancaria, domiciliación
ExpenseTemplate	Plantillas de gastos con periodicidad, importe fijo/variable
ExpenseReceipt	Recibos de gastos con origen desde plantilla o manual
ExpenseScheduler	Generación automática de recibos desde plantillas activas
Refactor recibos	PdfReceiptService, EmailReceiptService, ReceiptService, ReportService adaptados a nuevo modelo
Frontend	Páginas IncomeReceipts, ExpenseTemplates, ExpenseReceipts creadas
Seed data	Actualizado seed.sql con datos de demostración

Pendiente

Módulo	Funcionalidades	Prioridad
Página Mantenimiento	CRUD de mantenimiento programado ✅ COMPLETADO	Alta
Mejoras Mantenimiento	Reapertura de tareas, generación automática de gastos, diálogo de documentos al completar ✅ COMPLETADO	Alta
Página Reportes	Generación de informes Excel y gestión de recibos automáticos (backend existe, falta frontend)	Alta
Página Notificaciones	Gestión de notificaciones del usuario (backend existe, falta frontend)	Media
Página Usuarios	CRUD de usuarios y asignación de roles (backend existe, falta frontend)	Media
Exportación	Exportar listados a PDF/Excel desde el frontend	Media
Funcionalidad avanzada frontend	Terminar páginas IncomeReceipts, ExpenseTemplates, ExpenseReceipts con filtros y acciones completas	Alta
Inventario	Gestión de mobiliario y equipamiento por propiedad	Baja
Candidatos	Registro de interesados antes del contrato	Baja
Temporada	Alquileres por temporada con precios dinámicos	Baja

Fase 4 - Producción y Calidad

Estado: PARCIALMENTE COMPLETADA

Objetivo: Preparar el sistema para uso en producción con garantías de calidad.

Completado

Tarea	Descripción
Flyway	Configurado con 6 migraciones SQL, perfiles dev (clean+repair+migrate) y prod (solo repair+migrate), FlywayRepairConfig
Repositorio Git	Inicializado, .gitignore completo (raíz + frontend), 5 commits

Pendiente

Tarea	Descripción	Prioridad
Tests unitarios	Tests para AuthService, ReceiptService, PdfReceiptService, ContractService, etc.	Alta
Tests de integración	Tests con H2 (ya incluido en pom.xml) o Testcontainers	Alta
Pipeline CI/CD	GitHub Actions para build y tests automáticos	Media
Logs centralizados	Estructura de logging consistente (SLF4J + Logback)	Baja
Monitorización	Health checks, métricas con Actuator	Baja
SSL/TLS	Certificados HTTPS para producción	Media
Backups	Script de backup automático de BD	Media
Auditoría	Tabla de auditoría para cambios sensibles	Baja

Notas sobre la Planificación

Decisiones de arquitectura

• Se eligió monolito modular frente a microservicios por la simplicidad del dominio y para evitar complejidad operativa innecesaria.
• Se usa init.sql + ddl-auto: validate en lugar de Flyway para la fase inicial porque el esquema se define completamente desde el principio.
• El frontend se separó del backend desde el inicio para permitir desarrollo independiente y despliegue con Nginx.
• Los recibos de ingresos (tabla income_receipts) y recibos de gastos (tabla expense_receipts) se separan de las plantillas de gastos (tabla expense_templates) para mayor flexibilidad.
• Las plantillas de gastos permiten definir gastos recurrentes con periodicidad y generación automática mediante scheduler.
• Se usa BCrypt con Spring Security para contraseñas, con hash pre-generado para el usuario admin por defecto.

Convenciones de código

• Nombres de tablas en plural y snake_case.
• Nombres de columnas en snake_case.
• Entidades JPA con Lombok (@Getter, @Setter, @NoArgsConstructor).
• Servicios con inyección por constructor (no @Autowired directo).
• Controladores con inyección por constructor y @Valid en request bodies.
• Paquetes organizados por dominio de negocio (no por capa técnica).
• URLs RESTful con sustantivos en plural y verbs HTTP semánticos.