ContabilidadSaPolar/docs/tecnicas/arquitectura.md

# Arquitectura del Sistema

## 1. Visión General

Sa Polar es un **monolito modular** con frontend separado. El backend Spring Boot expone una API RESTful que consume un frontend React. La base de datos MySQL se inicializa mediante un script SQL ejecutado en el arranque del contenedor.

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Cliente    │────▶│  Frontend    │────▶│   Backend    │────▶│   MySQL 8   │
│  (Browser)   │     │  (React 19)  │     │ (Spring Boot)│     │             │
│              │◀────│  (Vite 8)    │◀────│  (Java 21)   │◀────│             │
└──────────────┘     └──────────────┘     └──────────────┘
                            │                      │
                            │  /api/*               │  JPA/Hibernate
                            ▼                      ▼
                     Nginx (proxy)          JWT Security
```

## 2. Componentes

### 2.1 Backend (Spring Boot 3.4.1)

El backend se organiza en **paquetes verticales** por dominio de negocio:

| Paquete | Responsabilidad |
|---------|----------------|
| `auth` | Autenticación JWT, login, registro, refresh |
| `user` | CRUD de usuarios, roles, permisos |
| `property` | Gestión de inmuebles (jerárquica), tipos, estados y conjuntos (PropertyGroup) |
| `tenant` | Gestión de inquilinos (personas físicas/jurídicas) |
| `contract` | Contratos de alquiler, estados, periodos de pago |
| `finance.income` | Recibos de ingresos (IncomeReceipt), cobros, categorías |
| `finance.expense` | Plantillas de gastos (ExpenseTemplate), recibos de gastos (ExpenseReceipt), categorías |
| `finance.receipt` | Recibos, PDF, email, reportes Excel, scheduler |
| `incident` | Incidencias, prioridades, asignación técnica |
| `maintenance` | Mantenimiento programado recurrente |
| `notification` | Notificaciones por usuario |
| `document` | Gestión de documentos adjuntos (polimórfico) |
| `dashboard` | Agregaciones y resúmenes |
| `config` | Seguridad, CORS, OpenAPI, almacenamiento |
| `common` | DTOs genéricos, excepciones, utilidades |

### 2.2 Frontend (React 19 + TypeScript 6)

Aplicación SPA con las siguientes capas:

| Capa | Descripción |
|------|-------------|
| `api/client.ts` | Instancia Axios con interceptor JWT y redirección 401 |
| `api/auth.ts` | Funciones de login y refresh |
| `api/resources.ts` | Funciones CRUD para cada recurso |
| `contexts/AuthContext.tsx` | Estado global de autenticación |
| `components/Layout.tsx` | Sidebar de navegación + contenido principal |
| `pages/*.tsx` | Páginas individuales (Login, Dashboard, Properties, etc.) |
| `types/api.ts` | Interfaces TypeScript para los DTOs |

### 2.3 Base de datos (MySQL 8)

Esquema gestionado mediante script SQL de inicialización (`db/init.sql`). Hibernate opera en modo `validate` para verificar que el mapeo JPA coincida con el esquema existente.

## 3. Seguridad

### 3.1 Autenticación JWT

1. El usuario envía credenciales a `POST /api/auth/login`
2. El servidor valida contra la base de datos y devuelve:
   - `accessToken`: válido por 24 horas
   - `refreshToken`: válido por 30 días
3. El frontend almacena los tokens en `localStorage`
4. Cada petición incluye `Authorization: Bearer <token>`
5. El `JwtAuthenticationFilter` extrae y valida el token en cada request
6. Si el token expira, el frontend usa `POST /api/auth/refresh` para obtener uno nuevo

### 3.2 Roles y permisos

| Rol | Acceso |
|-----|--------|
| `ADMIN` | Todos los endpoints, incluyendo gestión de usuarios |
| `GERENTE` | Propiedades, inquilinos, contratos, incidencias, mantenimiento, recibos de ingresos, plantillas de gastos, recibos de gastos, dashboard |
| `CONTABLE` | Recibos de ingresos, plantillas de gastos, recibos de gastos, dashboard, reportes |
| `VISUALIZADOR` | Autenticado (acceso básico de solo lectura según configuración) |

### 3.3 Seguridad adicional

- CSRF deshabilitado (API stateless)
- Sesiones sin estado (`SessionCreationPolicy.STATELESS`)
- CORS configurable mediante `app.cors.allowed-origins`
- Contraseñas almacenadas con BCrypt

## 4. Flujo de Datos

### 4.1 Autenticación

```
Browser                  Frontend                 Backend                    MySQL
   │                        │                        │                        │
   │  login(user, pass)     │                        │                        │
   │──────────────────────▶│  POST /api/auth/login   │                        │
   │                        │───────────────────────▶│                        │
   │                        │                        │  SELECT user by email  │
   │                        │                        │───────────────────────▶│
   │                        │                        │◀───────────────────────│
   │                        │                        │  Verificar BCrypt hash │
   │                        │                        │  Generar JWT tokens    │
   │                        │◀───────────────────────│                        │
   │◀──────────────────────│  TokenResponse          │                        │
   │  Guardar en localStorage                       │                        │
```

### 4.2 Generación de recibos automáticos

```
Scheduler (cron: 0 0 6 1 * ?)
    │
    ▼
ReceiptService.generateMonthlyReceipts()
    │
    ├── Buscar contratos ACTIVOS con payment_day = mes actual
    ├── Para cada contrato:
    │   ├── Obtener siguiente número de serie (ReceiptSeries)
    │   ├── Crear registro IncomeReceipt con receipt_number
    │   ├── Generar PDF (PdfReceiptService)
    │   └── Enviar email si el inquilino tiene email (EmailReceiptService)
    └── Log de emails enviados (email_log)
```

## 5. Despliegue

### 5.1 Docker Compose

Tres servicios orquestados:

1. **mysql**: Imagen `mysql:8.0`, puerto `3307:3306`, volumen persistente, script init.sql
2. **backend**: Build multi-etapa (Maven + JRE), puerto `8080:8080`
3. **frontend**: Build multi-etapa (Node + Nginx), puerto `3000:3000`, proxy reverso `/api/` al backend

### 5.2 Entornos

| Entorno | Backend URL | Frontend URL | Propósito |
|---------|-------------|--------------|-----------|
| Desarrollo | `localhost:8080` | `localhost:5173` (Vite) | Desarrollo local |
| Producción | `localhost:8080` | `localhost:3000` (Nginx) | Docker compose |

## 6. Dependencias Externas

| Dependencia | Versión | Uso |
|-------------|---------|-----|
| Spring Boot | 3.4.1 | Framework principal |
| JJWT | 0.12.6 | Tokens JWT |
| SpringDoc OpenAPI | 2.7.0 | Documentación Swagger |
| iText | 8.0.5 | Generación de PDFs |
| Apache POI | 5.3.0 | Generación de Excel |
| MapStruct | 1.6.3 | Mapeo de DTOs (si se usa) |
| Lombok | 1.18.36 | Reducción de boilerplate |
| Flyway | - | Dependencia incluida pero deshabilitada |