ContabilidadSaPolar/README.md

# Sa Polar - Sistema de Gestión de Alquileres

Sistema integral para la administración y contabilidad de alquileres de inmuebles. Permite gestionar propiedades, conjuntos, contratos, inquilinos, ingresos, gastos, incidencias, mantenimiento programado y recibos automáticos.

## Stack Tecnológico

| Componente | Tecnología |
|------------|------------|
| Backend | Java 21, Spring Boot 3.4.1, Maven |
| Frontend | React 19, TypeScript 6, Vite 8 |
| Base de datos | MySQL 8 |
| Autenticación | JWT (jjwt 0.12.6) |
| Seguridad | Spring Security con roles (ADMIN, GERENTE, CONTABLE, VISUALIZADOR) |
| PDF | iText 8.0.5 |
| Excel | Apache POI 5.3.0 |
| Documentación API | SpringDoc OpenAPI 2.7.0 |
| Contenedores | Docker + docker-compose |

## Arquitectura

Monolito modular con frontend separado:

```
cliente (browser)
    │
    ├── http://localhost:3000 (Nginx - producción)
    └── http://localhost:5173 (Vite - desarrollo)
            │
            └── /api/* ────→ backend:8080 (Spring Boot)
                                    │
                                    └── mysql:3306 (MySQL 8)
```

## Requisitos

- Docker y docker-compose
- O en su defecto: Java 21 + Node 22 + MySQL 8

## Inicio Rápido (Docker)

```bash
# 1. Clonar repositorio
git clone <repo-url> sa-polar
cd sa-polar

# 2. Copiar configuración de entorno
cp .env.example .env

# 3. Iniciar todos los servicios
docker compose up -d

# 4. Acceder a la aplicación
# Frontend: http://localhost:3000
# Backend API: http://localhost:8080
# Swagger UI: http://localhost:8080/swagger-ui.html
```

## Credenciales por Defecto

| Usuario | Contraseña | Rol |
|---------|-----------|-----|
| admin | admin123 | ADMIN |

## Desarrollo Local (sin Docker)

### Backend

```bash
# Requiere MySQL 8 corriendo en localhost:3306 con base de datos "sa_polar"
cd backend
mvn spring-boot:run -DskipTests
```

### Frontend

```bash
cd frontend
npm install
npm run dev
# Acceder en http://localhost:5173
```

## Estructura del Proyecto

```
sa-polar/
├── backend/                    # Backend Spring Boot
│   └── src/main/java/com/sapolar/
│       ├── auth/               # Autenticación JWT
│       ├── common/             # DTOs, excepciones, utilidades
│       ├── config/             # Configuraciones (seguridad, CORS, OpenAPI)
│       ├── contract/           # Gestión de contratos
│       ├── dashboard/          # Dashboard y resúmenes
│       ├── document/           # Gestión de documentos adjuntos
│       ├── finance/            # Módulo financiero
│       │   ├── expense/        # Gastos
│       │   ├── income/         # Ingresos
│       │   └── receipt/        # Recibos, PDF, email, reportes
│       ├── incident/           # Incidencias
│       ├── maintenance/        # Mantenimiento programado
│       ├── notification/       # Notificaciones
│       ├── property/           # Propiedades, inmuebles y conjuntos
│       ├── tenant/             # Inquilinos/arrendatarios
│       └── user/               # Usuarios y roles
├── db/
│   └── init.sql                # DDL + datos semilla
├── frontend/                   # Frontend React
│   └── src/
│       ├── api/                # Cliente Axios, funciones API
│       ├── components/         # Componentes (Layout)
│       ├── contexts/           # AuthContext
│       ├── pages/              # Páginas (Login, Dashboard, etc.)
│       └── types/              # Tipos TypeScript
├── docs/                       # Documentación
├── docker-compose.yml          # Orquestación de servicios
├── Dockerfile.backend          # Build multi-etapa backend
└── Dockerfile.frontend         # Build multi-etapa frontend
```

## Documentación

La documentación completa está disponible en el directorio `docs/`:

- [Índice de documentación](docs/INDEX.md)
- [Arquitectura del sistema](docs/tecnicas/arquitectura.md)
- [Referencia de API](docs/tecnicas/api.md)
- [Esquema de base de datos](docs/tecnicas/base-de-datos.md)
- [Planificación y roadmap](docs/planificacion/roadmap.md)
- [Manual de usuario](docs/usuario/manual.md)

## API Endpoints Principales

| Grupo | Base Path | Métodos |
|-------|-----------|---------|
| Autenticación | `/api/auth` | login, register, refresh |
| Usuarios | `/api/users` | CRUD (solo ADMIN) |
| Propiedades | `/api/properties` | CRUD + árbol + historial |
| Conjuntos | `/api/property-groups` | CRUD + propiedades asociadas |
| Inquilinos | `/api/tenants` | CRUD + búsqueda |
| Contratos | `/api/contracts` | CRUD + terminación |
| Ingresos | `/api/incomes` | CRUD + registro de pago |
| Gastos | `/api/expenses` | CRUD |
| Incidencias | `/api/incidents` | CRUD + asignación + programación |
| Mantenimiento | `/api/maintenance` | CRUD + programado |
| Recibos | `/api/receipts` | Generación, PDF, email, reportes |
| Notificaciones | `/api/notifications` | Listado, marcar leídas |
| Dashboard | `/api/dashboard` | Resúmenes y gráficos |
| Documentos | `/api/documents` | Subida, descarga |

## Variables de Entorno

| Variable | Defecto | Descripción |
|----------|---------|-------------|
| `DB_NAME` | `sa_polar` | Nombre de la base de datos |
| `DB_USER` | `root` | Usuario MySQL |
| `DB_PASSWORD` | `root` | Contraseña MySQL |
| `JWT_SECRET` | (por defecto) | Secreto para firmar JWT (base64) |
| `CORS_ORIGINS` | `http://localhost:3000,http://localhost:5173` | Orígenes CORS permitidos |
| `UPLOAD_PATH` | `./uploads` | Ruta de almacenamiento de archivos |

## Licencia

Uso interno.