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)

# 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

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

Frontend

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/:

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.

5.6 KiB Raw Blame History