ContabilidadSaPolar/docs/usuario/manual.md

# Manual de Usuario - Sa Polar

## 1. Introducción

**Sa Polar** es un sistema de gestión de alquileres que permite administrar propiedades inmobiliarias, contratos de arrendamiento, inquilinos, ingresos, gastos, incidencias y mantenimiento programado. Está diseñado para propietarios, administradores de fincas y gestores de alquileres.

## 2. Acceso al Sistema

### 2.1 Inicio de sesión

1. Abrir el navegador y acceder a la URL del sistema:
   - **Entorno Docker:** `http://localhost:3000`
   - **Entorno desarrollo:** `http://localhost:5173`
2. Introducir credenciales:
   - **Usuario:** `admin`
   - **Contraseña:** `admin123`
3. Hacer clic en **Iniciar Sesión**

![Pantalla de login](images/login.png)

### 2.2 Roles de usuario

| Rol | Descripción |
|-----|-------------|
| **ADMIN** | Acceso completo a todas las funcionalidades del sistema |
| **GERENTE** | Gestión de propiedades, contratos, inquilinos, incidencias, mantenimiento, recibos y finanzas |
| **CONTABLE** | Gestión de ingresos, gastos, recibos y reportes |
| **VISUALIZADOR** | Acceso de solo lectura a la información |

## 3. Navegación

Una vez dentro del sistema, aparece un menú lateral con las siguientes secciones:

| Sección | Icono | Descripción |
|---------|-------|-------------|
| **Dashboard** | 📊 | Resumen general del sistema |
| **Propiedades** | 🏠 | Gestión de inmuebles |
| **Conjuntos** | 🏢 | Agrupación de propiedades (edificios, urbanizaciones) |
| **Inquilinos** | 👤 | Gestión de arrendatarios |
| **Contratos** | 📝 | Contratos de alquiler |
| **Recibos de Ingreso** | 💰 | Cobros y recibos (antes "Ingresos") |
| **Gastos** | 💸 | Pagos y facturas |
| **Incidencias** | 🔧 | Averías y reparaciones |

## 4. Dashboard

La pantalla principal muestra un resumen con:

- **Total de propiedades** registradas
- **Inquilinos** activos
- **Contratos activos** actualmente vigentes
- **Ingresos pendientes** de cobro

## 5. Gestión de Propiedades

### 5.1 Listado de propiedades

Muestra una tabla con todas las propiedades: ID, nombre, conjunto, ciudad, tipo, estado e importe de alquiler.

### 5.2 Jerarquía de propiedades

Las propiedades pueden organizarse jerárquicamente (ej: un edificio contiene varios pisos). La propiedad "padre" se selecciona al crear una nueva propiedad.

### 5.3 Tipos de propiedad

| Tipo | Descripción |
|------|-------------|
| EDIFICIO | Edificio completo con varias plantas |
| PISO | Vivienda en un edificio de pisos |
| LOCAL_COMERCIAL | Local comercial |
| BAR | Bar o restaurante |
| NAVE | Nave industrial o almacén |
| GARAJE | Plaza de garaje |
| TRASTERO | Trastero |
| OFICINA | Oficina o despacho |
| ADOSADO | Vivienda unifamiliar adosada |
| CHALET | Vivienda unifamiliar independiente |

### 5.4 Estados de propiedad

| Estado | Descripción |
|--------|-------------|
| DISPONIBLE | Disponible para alquilar |
| ALQUILADO | Actualmente alquilado |
| VACIO | Vacío, sin inquilino |
| ANUNCIADO | Anunciado para alquiler |
| MANTENIMIENTO | En obras o mantenimiento |

Los estados se actualizan automáticamente al crear o terminar contratos.

### 5.5 Historial de estados

Cada cambio de estado de una propiedad queda registrado con fecha, usuario y motivo.

### 5.6 Conjuntos (Agrupaciones)

Los conjuntos permiten agrupar propiedades que comparten una misma ubicación o promoción (edificios, urbanizaciones, residenciales).

#### 5.6.1 Listado de conjuntos

Muestra todos los conjuntos con ID, nombre y dirección.

#### 5.6.2 Crear un conjunto

1. Ir a **Conjuntos** en el menú lateral
2. Hacer clic en **+ Nuevo Conjunto**
3. Introducir nombre y dirección
4. Hacer clic en **Crear**

#### 5.6.3 Asignar propiedades a un conjunto

Al editar una propiedad, el campo **Conjunto** permite seleccionar el grupo al que pertenece. Una propiedad puede pertenecer a un solo conjunto o a ninguno.

#### 5.6.4 Detalle del conjunto

Al hacer clic en "Ver" sobre un conjunto, se muestran sus datos junto con una tabla de las propiedades que pertenecen a ese conjunto.

## 6. Gestión de Inquilinos

### 6.1 Listado de inquilinos

Muestra todos los inquilinos con nombre, NIF/CIF, email, teléfono y tipo (persona física o jurídica).

### 6.2 Tipos de inquilino

- **PERSONA_FISICA:** Arrendatario individual (DNI)
- **PERSONA_JURIDICA:** Empresa o entidad (CIF)

### 6.3 Datos del inquilino

- Nombre completo (o razón social)
- NIF/CIF
- Dirección
- Teléfono y email
- IBAN para domiciliación de pagos

## 7. Gestión de Contratos

### 7.1 Listado de contratos

Muestra: número de contrato, propiedad, inquilino, importe, fechas de inicio/fin y estado.

### 7.2 Estados de contrato

| Estado | Descripción |
|--------|-------------|
| ACTIVO | Contrato vigente |
| VENCIDO | Fecha de fin superada |
| RENOVADO | Renovado a un nuevo contrato |
| RESCINDIDO | Cancelado antes del fin |
| ANULADO | Anulado sin efecto |

### 7.3 Creación de contrato

Al crear un contrato:
1. Seleccionar propiedad (debe estar en estado DISPONIBLE)
2. Seleccionar inquilino
3. Introducir importe de renta, fecha de inicio, período de pago
4. Opcional: fianza, fecha de fin, día de pago, IBAN domiciliación
5. **Automáticamente:** la propiedad pasa a estado ALQUILADO

### 7.4 Terminación de contrato

Al terminar un contrato:
1. Seleccionar causa de terminación
2. **Automáticamente:** la propiedad pasa a estado VACIO
3. El contrato se marca como RESCINDIDO

## 8. Gestión de Ingresos

### 8.1 Listado de ingresos

Muestra: número de recibo, propiedad, inquilino, importe bruto/neto, fechas de emisión/vencimiento/pago, estado.

### 8.2 Estados de ingreso

| Estado | Descripción |
|--------|-------------|
| PENDIENTE | Emitido pero no cobrado |
| PAGADO | Cobrado |
| VENCIDO | Fecha de vencimiento superada sin cobro |
| PARCIAL | Cobro parcial |
| ANULADO | Anulado |

### 8.3 Registrar pago

1. Localizar el ingreso en el listado
2. Hacer clic en "Registrar pago"
3. El sistema actualiza automáticamente:
   - Estado a PAGADO
   - Fecha de pago
   - Importe neto (después de retención IRPF)

### 8.4 Categorías de ingreso

| Categoría | Descripción |
|-----------|-------------|
| ALQUILER | Pago de renta mensual o periódica |
| FIANZA | Depósito de garantía |
| GASTOS_COMUNIDAD | Repercusión de gastos de comunidad |
| INTERESES_DEMORA | Intereses por pago fuera de plazo |
| INDEMNIZACION | Indemnización por daños o rescisión |
| OTROS_INGRESOS | Otros ingresos no clasificados |

## 9. Gestión de Gastos

### 9.1 Listado de gastos

Muestra: proveedor, factura, concepto, importe, fechas de emisión/pago y estado.

### 9.2 Categorías de gasto

| Categoría | Descripción |
|-----------|-------------|
| REPARACION | Reparaciones y arreglos |
| MANTENIMIENTO | Mantenimiento preventivo |
| COMUNIDAD | Gastos de comunidad de propietarios |
| IBI | Impuesto de Bienes Inmuebles |
| BASURA | Tasa de basura |
| SUMINISTROS_LUZ | Electricidad y suministro eléctrico |
| SUMINISTROS_GAS | Gas natural, butano, propano |
| SUMINISTROS_OTROS | Agua, internet, telefonía y otros suministros |
| SEGURO | Seguro del inmueble |
| REFORMA | Obras de reforma o mejora |
| GESTION | Gastos de gestión inmobiliaria |
| NOTARIA_REGISTRO | Gastos notariales y de registro |
| PUBLICIDAD | Anuncios y marketing |
| OTROS_GASTOS | Otros gastos no clasificados |

### 9.3 Gastos planificados

Se pueden crear gastos con fecha planificada futura para prever pagos periódicos (ej: IBI anual, seguro).

## 10. Gestión de Incidencias

### 10.1 Listado de incidencias

Muestra: título, propiedad, prioridad, técnico asignado, fecha y estado.

### 10.2 Estados de incidencia

```
SIN_REVISAR → TECNICO_AVISADO → REPARACION_PREVISTA → REPARADO
                                                      → IGNORADO
                                                      → ANULADO
```

### 10.3 Prioridades

| Prioridad | Descripción |
|-----------|-------------|
| BAJA | Puede esperar |
| MEDIA | Atención normal |
| ALTA | Urgencia relativa |
| URGENTE | Atención inmediata |

### 10.4 Flujo de trabajo

1. **Crear incidencia:** Seleccionar propiedad, título, descripción y prioridad
2. **Asignar técnico:** El gestor asigna un técnico responsable
3. **Programar reparación:** Establecer fecha prevista de intervención
4. **Resolver:** Marcar como reparado, ignorado o anulado, con notas de resolución

## 11. Recibos Automáticos

### 11.1 Generación de recibos

El sistema puede generar recibos de dos formas:

- **Individual:** Generar un recibo para un contrato específico indicando fecha de emisión y vencimiento.
- **Mensual (automático):** El día 1 de cada mes a las 06:00, el sistema genera recibos para todos los contratos activos.

### 11.2 Numeración

Cada recibo recibe un número único secuencial por año fiscal con formato: `R-2026-00001`, `R-2026-00002`, etc.

### 11.3 PDF

Cada recibo puede descargarse en formato PDF con:
- Datos del arrendador
- Datos del inquilino
- Datos de la propiedad
- Importe, retención IRPF e importe neto
- Número de recibo y fechas

### 11.4 Envío por email

Los recibos pueden enviarse por email al inquilino con el PDF adjunto. El sistema registra un log de cada envío (destinatario, fecha, éxito/error).

### 11.5 Vencimiento automático

El sistema revisa diariamente los ingresos pendientes cuya fecha de vencimiento ha pasado y los marca como VENCIDOS automáticamente.

## 12. Reportes

### 12.1 Informe mensual Excel

Se puede descargar un informe mensual en formato Excel (.xlsx) que incluye:

- **Ingresos del mes:** listado de cobros
- **Gastos del mes:** listado de pagos
- **Balance:** ingresos - gastos = resultado del mes

### 12.2 Dashboard

El dashboard muestra resúmenes visuales con datos agregados del año en curso.

## 13. Gestión de Documentos

El sistema permite adjuntar documentos a cualquier entidad:

- **Propiedades:** fotos, planos, certificados
- **Contratos:** contratos firmados, anexos
- **Inquilinos:** DNI, CIF
- **Incidencias:** fotos de la avería
- **Ingresos:** justificantes de pago
- **Gastos:** facturas escaneadas

**Formatos soportados:** PDF, imágenes (JPG, PNG), documentos (DOC, DOCX, XLS, XLSX)

## 14. Notificaciones

El sistema genera notificaciones automáticas para:

- Incidencias abiertas y asignadas
- Mantenimiento programado próximo a vencer
- Recibos vencidos
- Contratos próximos a vencer
- Contratos vencidos

Las notificaciones pueden marcarse como leídas individualmente o todas a la vez.

## 15. Consejos y Buenas Prácticas

### 15.1 Organización de propiedades

- Usar la jerarquía para agrupar: Edificio (padre) → Pisos (hijos)
- Asignar referencias únicas y descriptivas
- Mantener actualizado el estado de cada propiedad

### 15.2 Gestión de contratos

- Registrar siempre la fecha de fin, aunque sea estimada
- Usar el IBAN de domiciliación para facilitar cobros recurrentes
- Revisar contratos próximos a vencer con antelación

### 15.3 Control financiero

- Registrar los gastos a medida que se generan, no solo cuando se pagan
- Usar la funcionalidad de gastos planificados para prever pagos periódicos
- Generar recibos mensualmente para mantener la tesorería controlada
- Descargar informes mensuales para llevar un control contable externo

### 15.4 Incidencias

- Incluir fotos y descripciones detalladas al crear incidencias
- Establecer prioridades realistas
- Registrar el coste final de cada reparación para control presupuestario

## 16. Preguntas Frecuentes

**¿Puedo recuperar una propiedad eliminada?**
No, la eliminación es lógica (soft-delete). Un administrador puede reactivarla desde la base de datos.

**¿Cómo se calcula el importe neto de un ingreso?**
`net_amount = amount - tax_withheld`. La retención de IRPF se aplica sobre el importe bruto.

**¿Puedo modificar un recibo ya generado?**
Sí, modificando el ingreso correspondiente desde la sección Ingresos.

**¿Qué ocurre si falla el envío de un email?**
El sistema registra el error en el log de emails. Puede reintentarse manualmente.

**¿Los recibos se generan automáticamente todos los meses?**
Sí, el día 1 de cada mes a las 06:00. Un administrador también puede generar todos los recibos manualmente desde la API.

**¿Puedo tener varias series de numeración de recibos?**
Sí, la tabla `receipt_series` permite múltiples series. Por defecto se crea una serie "RECIBOS" para el año actual.

## 17. Soporte

Para incidencias técnicas o consultas, contactar con el administrador del sistema.