Initial commit: proyecto ContabilidadSaPolar completo

docs/planificacion/roadmap.md

@@ -0,0 +1,193 @@
+# 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
+
+- [x] Creación del proyecto Spring Boot multi-módulo
+- [x] Configuración de Spring Security con JWT
+- [x] Mapeo JPA de todas las entidades del dominio
+- [x] Script init.sql con DDL y datos semilla
+- [x] Configuración Docker con healthcheck de MySQL
+- [x] Corrección de tipos de columna (TINYINT UNSIGNED → INT)
+- [x] Corrección de palabra reservada `read` en MySQL
+- [x] Corrección de LazyInitializationException con @Transactional
+- [x] Generación correcta de hash BCrypt para admin
+- [x] 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
+
+- [x] Entidades ReceiptSeries y EmailLog
+- [x] Servicios ReceiptService, PdfReceiptService, EmailReceiptService, ReportService
+- [x] ReceiptScheduler con 3 tareas cron
+- [x] ReceiptController con 7 endpoints
+- [x] Configuración SMTP en application.yml
+- [x] Tablas receipt_series y email_log en init.sql
+- [x] Endpoints de reportes Excel
+- [x] Frontend React + Vite + TypeScript completo
+- [x] Páginas: Login, Dashboard, Properties, Tenants, Contracts, Incomes, Expenses, Incidents, Documents
+- [x] Capa API con Axios e interceptor JWT
+- [x] AuthContext con persistencia en localStorage
+- [x] Layout con sidebar y navegación
+- [x] Docker compose con servicio frontend (Nginx)
+- [x] Proxy reverso en Nginx para /api/*
+- [x] Compilación y build exitosos
+- [x] ID visible en todas las tablas, detalles y formularios
+- [x] Property Groups (Conjuntos) — entidad, CRUD backend, página frontend con propiedades asociadas
+- [x] Sistema de documentos con validación tipo-entidad (V5 migration)
+- [x] Componente DocumentUploader integrado en Contracts, Tenants, Properties, Incidents, Incomes, Expenses
+- [x] Endpoint getDocumentTypesForEntity para filtrar tipos permitidos por entidad
+- [x] CRUD completo de Inquilinos con validación de documentos (DNI/NIE/CIF)
+- [x] Gestión dinámica de múltiples inquilinos en Contratos con creación inline
+- [x] Acciones especiales: "Cobrar" en Ingresos, "Pagar" en Gastos, "Terminar contrato"
+- [x] Componentes reutilizables: Modal, ConfirmDialog, Pagination, SortableHeader, Toast, EntityLink
+- [x] Hook useSort para ordenación client-side con claves anidadas
+- [x] Hook useEntityNavigation para navegación programática entre entidades
+- [x] BankDataManager para gestión de datos bancarios de inquilinos (CRUD, validación IBAN)
+- [x] Previsualización de documentos (PDF en iframe, imágenes JPEG/PNG/GIF/WebP)
+- [x] Autocompletado de direcciones via datalist en formularios
+- [x] Badges de estado y prioridad con colores en todas las tablas
+- [x] Recepción de filtros desde Dashboard via location.state
+- [x] Flyway configurado con 6 migraciones (V1-V6)
+- [x] FlywayRepairConfig con estrategia por perfil (dev vs prod)
+- [x] Perfiles application-dev.yml y application-prod.yml
+- [x] 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.