Initial commit: proyecto ContabilidadSaPolar completo

2026-08-19 21:30:23 +00:00
commit 0d5c6f9512
232 changed files with 26730 additions and 0 deletions
@@ -0,0 +1,382 @@
+# 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.