# 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.