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

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.