# App de gestión de hermandades y cofradías — Especificación para desarrollo > Documento único para entregar a la IA/desarrollador. Contiene todo lo necesario para construir la aplicación. **Léelo entero antes de empezar. Trabaja por fases (sección 9). No añadas nada que no esté aquí sin preguntar.** --- ## 0. En una frase SaaS multi-hermandad, en PHP/Laravel, instalable como PWA en el móvil, donde cada hermandad gestiona hermanos, pasos, cuotas, papeletas de sitio, cuadrillas, banda, tesorería y calendario, con su propia imagen (logo, colores, nomenclatura) y un sistema de **avisos y asistencias** que funcione de verdad: si organizo un ensayo solo para los costaleros de un paso, se les notifica solo a ellos y luego se pasa lista desde el móvil. Debe ser sencillo, útil, bonito y rápido en móvil. --- ## 1. Stack (obligatorio, no cambiar) | Capa | Tecnología | |---|---| | Backend | PHP 8.2+, **Laravel 11** | | Base de datos | MySQL 8 / MariaDB 10.6+ | | Frontend | **Livewire 3 + Alpine.js + Tailwind CSS** (nada de React/Vue) | | Gráficas | Chart.js | | Auth | Laravel Breeze (stack Livewire) | | Roles/permisos | `spatie/laravel-permission` | | PDF | `barryvdh/laravel-dompdf` | | Excel | `maatwebsite/excel` | | QR | `simplesoftwareio/simple-qrcode` + `html5-qrcode` para escanear | | Backups | `spatie/laravel-backup` | | Colas | driver `database` | | Ficheros | disco `public` de Laravel (preparado para S3 por config) | | PWA | manifest dinámico + service worker + Web Push (VAPID) | | Multi-tenant | **Una sola base de datos**, columna `hermandad_id` en todas las tablas de negocio, **Global Scope** automático en los modelos. No usar paquetes de multi-BD. | | Idioma | Interfaz 100 % en español (España), textos en ficheros `lang/es`. | --- ## 2. Roles | Rol | Ámbito | Puede | |---|---|---| | **superadmin** | Plataforma | Crear/suspender hermandades, crear su primer admin, ver panel global, impersonar admin para soporte (con banner visible y auditoría). | | **admin** | Su hermandad | Todo: usuarios, configuración, personalización y todos los módulos. | | **secretaria** | Su hermandad | Hermanos, papeletas, calendario, comunicaciones, exportaciones. | | **tesoreria** | Su hermandad | Cuotas, remesas, tesorería, informes. Hermanos solo lectura. | | **capataz** | Su(s) paso(s) | Cuadrilla, tallaje, ensayos, asistencia. Hermanos solo lectura. | | **director_banda** | Su banda | Músicos, ensayos, actuaciones. | | **hermano** | Sus datos | Ver su ficha, cuotas, papeleta, calendario; solicitar papeleta; editar sus datos de contacto. | Permisos granulares (`hermanos.ver`, `hermanos.editar`, `tesoreria.editar`, `calendario.editar`…) agrupados en estos roles fijos. No hacer editor de roles personalizados. --- ## 3. Personalización de cada hermandad Es un requisito central. Cada hermandad se personaliza en dos niveles: ### 3.1 Imagen dentro de la app - Logo, color primario y secundario, nombre corto. - Se aplican a: cabecera, botones, gráficas (paleta derivada), PDFs (papeletas, informes) y al **manifest de la PWA** (nombre, iconos generados desde el logo, `theme_color`). - Nombres configurables de conceptos: cómo llaman a la cuota ("cuota", "limosna"), al hermano ("hermano", "cofrade"), a la papeleta ("papeleta de sitio", "túnica"). - Ejercicio: año natural o año cofrade (mes de inicio configurable). - Campos personalizados en la ficha de hermano (texto, número, fecha, sí/no, lista). - Categorías de tesorería y tipos de cuota propios. ### 3.2 Fuera de alcance No hay página web pública ni tienda. No construir nada de eso. --- ## 3b. Avisos y asistencias (requisito clave) Esto tiene que funcionar bien y ser lo más cómodo de usar de toda la app. ### Cómo se envía un aviso Cualquier evento (ensayo, culto, cabildo, reunión…) puede lanzar un aviso al crearlo o después. El **destinatario se elige por audiencia**, con estas opciones y combinables: - Todos los hermanos activos. - Junta de gobierno. - Un paso concreto (todas las personas con asignación en ese paso). - Una función en un paso: p. ej. **costaleros del paso de la Humildad**, nazarenos de la Virgen, acólitos de un paso. - Una cuadrilla concreta / una banda concreta. - Deudores de cuota. - Selección manual de personas. Ejemplo obligatorio: creo un ensayo el jueves 20:30 para la cuadrilla del Cristo de la Humildad → la app propone automáticamente como audiencia esa cuadrilla → envío → solo esas personas reciben push (si tienen la app instalada) y email (si tienen email). Nadie más ve ese evento en su calendario. ### Canales - **Push web (VAPID)**: prioritario. Al instalar la PWA se pide permiso; se guarda la suscripción por usuario. - **Email**: siempre como respaldo si la persona tiene email. - **Enlace WhatsApp**: botón que genera el texto del aviso para pegarlo en el grupo (no automatizar envío). - Cada aviso guarda a quién se envió y por qué canal; pantalla de "entregas" con quién tiene push, quién solo email y quién no tiene ninguno (para que secretaría sepa a quién avisar a mano). ### Confirmación de asistencia - Cada evento puede pedir confirmación: el receptor pulsa **Voy / No voy / Quizás** desde la notificación o desde su calendario. - El organizador ve en tiempo real cuántos han confirmado, listado con nombres y botón para reenviar aviso a quienes no han contestado. ### Recordatorios automáticos - Recordatorio push/email 24 h antes y 2 h antes (configurable por tipo de evento) a quien tenía el evento en su calendario y no ha dicho "No voy". ### Pase de lista (asistencia real) - En ensayos de cuadrilla y banda (y en cualquier evento marcado "pasar lista"), el capataz/director abre el evento en el móvil y ve la lista de su gente ordenada por puesto, con un toque por persona: presente / ausente / justificado. La confirmación previa se muestra al lado para agilizar. - Al terminar, resumen: presentes, ausentes, % asistencia. - Historial por persona (asistencia a los últimos N ensayos) visible en su ficha y en la cuadrilla, y gráfica de asistencia por ensayo y por persona. - Aviso opcional automático a quien acumule X faltas seguidas (config del capataz). ### Visibilidad - Cada persona con acceso solo ve en su calendario los eventos de su audiencia (o los generales). El admin ve todo. --- ## 4. Modelo de datos Todas las tablas de negocio llevan `hermandad_id`, timestamps y `deleted_at` salvo `hermandades`. Importes en `decimal(10,2)`. IBAN cifrado. ### Núcleo - **hermandades**: nombre, nombre_corto, slug (único), localidad, provincia, cif, email, telefono, direccion, logo_path, color_primario, color_secundario, estado_suscripcion (prueba/activa/suspendida), fecha_vencimiento, configuracion (JSON: nomenclatura, ejercicio, opciones). - **users**: hermandad_id (nullable solo superadmin), name, email, password, persona_id (nullable). - **pasos**: nombre, nombre_corto, tipo (cristo/virgen/misterio/otro), orden, imagen_path, color, activo. - **personas**: nombre, apellidos, dni, fecha_nacimiento, sexo, email, telefono, direccion, cp, localidad, provincia, foto_path, es_hermano, numero_hermano (único por hermandad), fecha_alta, fecha_baja, motivo_baja, estado (activo/baja/fallecido/pendiente), iban (encrypted), titular_cuenta, mandato_sepa_fecha, mandato_sepa_ref, persona_referente_id (familias/menores), observaciones, campos_extra (JSON). - **campos_personalizados**: nombre, tipo, opciones (JSON), obligatorio, orden. - **asignaciones**: persona_id, paso_id (nullable = general), funcion (nazareno/costalero/acolito/musico/mantilla/junta/otro), detalle, fecha_inicio, fecha_fin, activo. *Una persona puede tener varias: nazareno en un paso y costalero en otro.* ### Cuotas - **cuotas_tipos**: nombre, importe, periodicidad (anual/semestral/trimestral/mensual), activo. - **cuotas**: persona_id, cuota_tipo_id, ejercicio, periodo, importe, estado (pendiente/pagada/devuelta/exenta), fecha_pago, metodo_pago (efectivo/transferencia/domiciliacion/tarjeta/bizum), remesa_id, movimiento_id. - **remesas**: nombre, fecha_creacion, fecha_cobro, importe_total, numero_recibos, estado (borrador/generada/cerrada), fichero_path. ### Papeletas de sitio - **salidas**: nombre, fecha, ejercicio, estado (preparacion/reparto_abierto/reparto_cerrado/celebrada/cancelada), precio_base. - **tramos**: salida_id, paso_id, nombre, orden, plazas (nullable), precio (nullable), tipo (cirio/insignia/presidencia/cruz_guia/monaguillo/mantilla/otro). - **papeletas**: salida_id, persona_id, paso_id, tramo_id (nullable), estado (solicitada/lista_espera/asignada/pagada/entregada/anulada), importe, fecha_solicitud, fecha_pago, metodo_pago, movimiento_id, codigo_qr (uuid). ### Cuadrillas y banda - **cuadrillas**: paso_id, nombre, capataz_persona_id, ejercicio, activa. - **cuadrilla_miembros**: cuadrilla_id, persona_id, puesto, altura_cm, talla_costal, es_relevo, activo. - **bandas**: nombre, tipo, director_persona_id, activa. - **banda_miembros**: banda_id, persona_id, instrumento, voz, activo. - **banda_actuaciones**: banda_id, fecha_hora, lugar, contratante, importe, estado (pendiente/confirmada/realizada/cancelada), evento_id, movimiento_id. - **ensayos**: evento_id, cuadrilla_id (nullable), banda_id (nullable), tipo (ensayo/iguala/muda/otro). *Un ensayo es un evento con datos extra; al crearlo se crea el evento con la audiencia = esa cuadrilla/banda.* - **asistencias**: evento_id, persona_id, estado (presente/ausente/justificado), registrado_por. *La asistencia cuelga del evento (los ensayos son eventos), así sirve para ensayos y para cualquier acto.* ### Tesorería - **tesoreria_categorias**: nombre, tipo (ingreso/gasto), color, es_patrimonio, activa. Por defecto: *Ingresos:* Cuotas, Papeletas, Donativos, Lotería y rifas, Subvenciones, Actuaciones de banda, Otros. *Gastos:* Cera, Flores, Música, Enseres y patrimonio (patrimonio), Restauraciones (patrimonio), Cultos, Caridad, Suministros, Seguros, Local, Imprenta, Otros. - **movimientos**: tipo (ingreso/gasto), fecha, importe, concepto, categoria_id, paso_id (nullable = "General"), persona_id (nullable), proveedor, metodo_pago, ejercicio, origen (manual/cuota/papeleta/actuacion), origen_id, adjunto_path, observaciones. - **inventario**: nombre, descripcion, paso_id, categoria, fecha_adquisicion, valor, ubicacion, foto_path, movimiento_id, estado (bueno/regular/restauracion/baja). ### Calendario y comunicaciones - **eventos**: titulo, descripcion, fecha_inicio, fecha_fin, todo_el_dia, lugar, tipo (culto/ensayo/cabildo/salida/reunion/acto/otro), paso_id, paso_id, requiere_confirmacion, pasar_lista (bool), recordatorio_horas (JSON, ej. [24,2]), creado_por. - **evento_audiencias**: evento_id, tipo (todos/junta/paso/paso_funcion/cuadrilla/banda/deudores/personas), paso_id, funcion, cuadrilla_id, banda_id, persona_ids (JSON). *Un evento puede tener varias filas de audiencia. La audiencia se resuelve a personas concretas al enviar y se guarda en `evento_destinatarios`.* - **evento_destinatarios**: evento_id, persona_id, canal_push (bool), canal_email (bool), enviado_at, leido_at. - **evento_confirmaciones**: evento_id, persona_id, estado (asiste/no_asiste/quizas), respondido_at. - **comunicaciones**: titulo, cuerpo, canal (email/push/ambos), evento_id (nullable), enviado_por, fecha_envio, total. Usa las mismas tablas de audiencia (`comunicacion_audiencias`, `comunicacion_destinatarios`) con la misma estructura que las de eventos. - **push_subscriptions**: estándar Web Push. ### Auditoría - **auditoria**: user_id, accion, modelo, modelo_id, cambios (JSON). Se registra en personas, cuotas, movimientos y papeletas. --- ## 5. Módulos y pantallas Navegación: en móvil, barra inferior con 5 accesos (Inicio, Hermanos, Tesorería, Calendario, Más); en escritorio, menú lateral. Tablas → tarjetas apiladas en móvil, tabla en escritorio. Buscador rápido siempre visible. ### 5.1 Superadmin Listado de hermandades (estado, nº hermanos, vencimiento), crear hermandad + admin (email de bienvenida), suspender/reactivar (los usuarios ven "cuenta suspendida"), impersonar, panel con 2 gráficas (hermandades activas por mes, hermanos totales). ### 5.2 Inicio (dashboard) Tarjetas: hermanos activos, altas/bajas del año, % cuotas cobradas y deudores, próximos 5 eventos, balance del ejercicio. Gráficas: evolución de hermanos por año, pirámide de edades, ingresos vs gastos por mes, gasto por paso, gasto por categoría, estado de cuotas, asistencia media por cuadrilla (si hay). ### 5.3 Hermanos Listado con buscador y filtros (estado, paso, función, deudor, edad). Ficha con pestañas: Datos · Asignaciones · Cuotas · Papeletas · Cuadrilla/Banda · Notas · Historial. Alta rápida móvil. Nº hermano automático o manual. Baja/reactivación. Familias por referente. Importar/exportar Excel con plantilla. Botones llamar/WhatsApp/email. ### 5.4 Pasos CRUD (nombre, tipo, imagen, color, orden). Vista del paso: resumen de asignaciones, cuadrilla, tramos de la última salida, gasto del ejercicio. ### 5.5 Cuotas Tipos de cuota. Generar cuotas del ejercicio (tipo + destinatarios). Listado con filtros; pagar individual o en lote (método y fecha) → **crea el ingreso en tesorería automáticamente**. Deudores con recordatorio email/push. Remesas SEPA (XML pain.008 CORE) → al cerrar, marca cuotas pagadas por domiciliación; devoluciones individuales. ### 5.6 Papeletas de sitio Salida → tramos por paso (con "copiar de la salida anterior"). Fases: preparación → reparto abierto → cerrado → celebrada. Solicitud desde secretaría o desde el hermano (elige paso y tramo preferido; si no hay plaza, lista de espera). **Asignación automática por antigüedad** + ajuste manual. Cobro → ingreso en tesorería con el paso. PDF con logo y **QR**; pantalla de escaneo con cámara que marca entregada/presente. Listados por tramo. Estadísticas por paso/tramo/ingresos. ### 5.7 Cuadrillas Cuadrilla por paso y ejercicio: miembros, puesto, altura, talla, relevo, agrupados por trabajadera. Crear ensayo → evento con audiencia = la cuadrilla, aviso push/email al crearlo, confirmación Voy/No voy, pase de lista táctil el día del ensayo (ver 3b). Gráficas de asistencia por ensayo y por persona. ### 5.8 Banda Bandas, miembros por instrumento/voz, ensayos con aviso y asistencia (igual que cuadrillas), actuaciones con importe → al marcar realizada, ingreso en tesorería. Agenda en calendario. ### 5.9 Tesorería Movimientos con filtros y totales. Alta en móvil en segundos: tipo, importe, concepto, categoría, paso o General, fecha, foto del ticket. Si la categoría es de patrimonio → propone añadir al inventario con datos precargados. Ejemplo que debe funcionar: gasto 1.000 € "Ánforas personalizadas", Enseres, paso Humildad → ofrece inventario; gasto 20 € "Velas", Cera, paso Virgen. Los movimientos automáticos (cuota/papeleta/actuación) llevan etiqueta de origen y se editan desde su origen, no a mano. **Informes** por ejercicio y por paso: resumen, por categoría, por mes, comparativa con ejercicio anterior; **PDF para cabildo** con logo, tablas y gráficas. Exportar Excel. ### 5.10 Inventario Listado por paso y estado, alta manual o desde gasto, foto, valor, ubicación, exportar Excel/PDF. ### 5.11 Calendario Vista mes/lista, filtros por tipo y paso. Crear evento con: audiencia (ver 3b), enviar aviso ahora sí/no, pedir confirmación, pasar lista sí/no, recordatorios. Panel del evento: destinatarios, confirmaciones en vivo, botón reenviar a los que no contestan, pase de lista. Ensayos y actuaciones entran solos. Cada persona solo ve los eventos de su audiencia. ### 5.12 Comunicaciones Comunicados sueltos (sin evento) a cualquier audiencia de 3b, por email/push, con botón de texto para WhatsApp. Historial con entregas. 3 plantillas (recordatorio cuota, convocatoria cabildo, aviso reparto). ### 5.13 Acceso del hermano Pantalla propia: mis datos (editar contacto), mis cuotas, mis papeletas (solicitar y ver QR), mi calendario (solo mis eventos, con Voy/No voy), mis avisos, mi asistencia a ensayos. El admin activa el acceso desde la ficha (invitación por email). ### 5.14 Configuración Datos e imagen (logo, colores), nomenclatura, ejercicio, usuarios y roles, pasos, tipos de cuota, categorías, campos personalizados, datos SEPA, recordatorios por defecto por tipo de evento, opciones (varias papeletas por persona en distintos pasos sí/no; solicitud online sí/no), exportación completa de datos. --- ## 6. Reglas de negocio 1. Una persona = una ficha. Sus funciones por paso son asignaciones. Nunca duplicar. 2. Movimientos originados por cuotas, papeletas y actuaciones se crean, actualizan y anulan solos desde su origen. Nunca por duplicado. 3. Movimiento sin paso = "General". 4. Ejercicio calculado por fecha según configuración (natural/cofrade). 5. Nº de hermano único por hermandad; no se reutiliza salvo indicación del admin. 6. Antigüedad = fecha_alta, desempate por nº hermano. 7. Aislamiento total entre hermandades por Global Scope; escribir tests que lo demuestren. 8. Un evento solo lo ven y reciben las personas de su audiencia (más los admins). La audiencia se resuelve a personas concretas en el momento del envío y queda registrada. 9. Los envíos van por cola; nunca bloquear la interfaz. Reintentar push fallidos y borrar suscripciones caducadas. 10. Soft delete en personas, movimientos, papeletas y eventos. --- ## 7. Diseño Mobile-first. Paleta de la hermandad en cabecera, botones y acentos; fondo claro; tarjetas con sombra suave y esquinas redondeadas. Tipografía Inter. Toque mínimo 44 px. Iconos Heroicons. Estados vacíos con texto y botón de acción. Toasts de confirmación. Paginación y búsqueda con debounce. Imágenes redimensionadas al subir. Sin modo oscuro (no prioritario). --- ## 8. Seguridad, RGPD y operación HTTPS, bloqueo por intentos fallidos, IBAN cifrado y enmascarado, auditoría, política de privacidad y texto de encargado del tratamiento configurables por superadmin, botón "anonimizar persona", exportación de datos, backup diario programado, cron para colas y recordatorios. --- ## 9. Fases de desarrollo (seguir este orden) **Fase 1 — Base y personalización** Proyecto, auth, roles, multi-tenant con Global Scope, superadmin, layout móvil/escritorio, PWA, logo/colores/nomenclatura, pasos, personas con asignaciones y campos personalizados, importar/exportar Excel, **calendario con audiencias, avisos push/email, confirmaciones y pase de lista** (es el núcleo, va primero). **Fase 2 — Dinero** Tipos de cuota, generación, cobros, deudores, tesorería (categorías, movimientos, adjuntos, informes, PDF cabildo), enlace automático cuota → ingreso, inventario, dashboard con gráficas. **Fase 3 — Salida, equipos y calendario** Salidas, tramos, papeletas (asignación automática, cobro, PDF QR, escaneo), cuadrillas y banda (ensayos sobre el sistema de eventos de la fase 1), actuaciones, comunicaciones sueltas, acceso del hermano. **Fase 4 — Remate** Remesas SEPA, recordatorios automáticos y avisos por faltas, auditoría, backups, tests, seeder demo, README de instalación en VPS (Ubuntu + Nginx + PHP-FPM + MySQL, cron, colas, HTTPS). --- ## 10. Seeder de demostración Hermandad "Humildad y Esperanza" con 2 pasos (Cristo de la Humildad, Virgen de la Esperanza), 60 hermanos de edades variadas con asignaciones mixtas, una cuadrilla por paso, banda de 20 músicos, cuotas del ejercicio al 70 % pagadas, una salida con tramos y papeletas, ~80 movimientos por categorías y pasos (incluye 1.000 € ánforas Humildad y 20 € velas Virgen), 6 ensayos pasados con asistencias registradas y 2 futuros con confirmaciones. Usuarios: superadmin, admin, tesorero, capataz, hermano (contraseña `password`). --- ## 11. Instrucciones para la IA - Entrega cada fase completa y funcional; nada "pendiente de implementar". - Antes de cada fase, resume qué harás; al terminar, explica cómo probarlo. - Código y BD pueden ir en inglés si lo prefieres, pero la interfaz siempre en español. Correspondencia: hermandad=brotherhood, paso=float, persona=person, cuota=fee, papeleta=ticket, tramo=section, cuadrilla=crew, movimiento=transaction, salida=procession, evento=event, audiencia=audience, asistencia=attendance. - Livewire para todo; sin frontend aparte ni librerías innecesarias. - Si algo es ambiguo, elige lo más simple y anótalo.