# Plataforma de donaciones CARF ## Memoria tecnica integrada y evolucion del proyecto Documento de cierre de fase valle Actualizacion documental: 02/09/2026 Sistemas incluidos: `donaciones` (legacy), `dona`, `donoradmin` y `shared-assets`. --- ## 1. Objeto y criterio documental Esta memoria presenta la plataforma como un unico sistema funcional que evoluciono desde la aplicacion legacy `donaciones` hasta tres proyectos especializados e intercomunicados. La primera parte explica el proceso, la arquitectura alcanzada y los puntos que condicionan su operacion. Los anexos conservan las memorias tecnicas originales y el detalle por jornadas para mantener trazabilidad. `donaciones` se utiliza solo como fuente historica. No forma parte de la linea activa de desarrollo ni debe sincronizarse con los proyectos actuales. ### Cobertura temporal de las fuentes | Proyecto | Condicion | Inicio verificable de la linea | Ultima actualizacion incluida | | --- | --- | --- | --- | | `donaciones` | Legacy y antecedente historico | Desarrollo anterior a la separacion; copia conservada en Git el 12/08/2026 | 12/08/2026 | | `dona` | Activo | 22/06/2026 | 01/09/2026 | | `donoradmin` | Activo, version `2.3.0` | 22/06/2026 | 02/09/2026 | | `shared-assets` | Activo y compartido | 22/06/2026 | 27/08/2026 | Las fechas distinguen el historial verificable de repositorio de la antiguedad funcional del sistema legacy. Que `donaciones` se incorporase a Git mas tarde no significa que su desarrollo comenzase en agosto. ## 2. Punto de partida: donaciones legacy El proyecto original concentraba en una misma aplicacion el formulario publico, el procesamiento de pagos, la persistencia de donantes y donaciones, la administracion, los documentos y las comunicaciones. Esta concentracion permitio construir y validar el circuito inicial, pero tambien acoplo responsabilidades con ritmos de cambio y riesgos diferentes. La documentacion y el historial disponibles acreditan una copia inicial de los nuevos repositorios el 22/06/2026. Esa fecha marca el comienzo verificable de la separacion tecnica. No se atribuye una fecha exacta de primera puesta en produccion porque las fuentes conservadas describen la evolucion funcional, pero no certifican por si solas el hito formal de despliegue productivo. ## 3. De un monolito a tres modulos activos La ruptura del sistema no fue una division aislada de codigo, sino una separacion por responsabilidades: - `dona`: experiencia publica, captura y validacion de datos, inicio y confirmacion de pagos, recurrencias, intentos y comunicaciones posteriores a la donacion. - `donoradmin`: operacion interna, donantes, donaciones, recurrencias, campañas, conciliacion SEPA, documentos, configuracion, auditoria, usuarios y seguimiento de incidencias. - `shared-assets`: recursos visuales y plantillas compartidas de email y PDF para evitar divergencias entre la pasarela y el panel. Los tres proyectos conservan una base funcional comun y contratos compartidos. La independencia de repositorios reduce el acoplamiento de despliegue, pero exige coordinar cambios de esquema, plantillas, rutas, estados y variables. ![Evolucion desde legacy](diagramas/evolucion.png) ## 4. Arquitectura funcional actual El navegador del donante entra por `dona`. La pasarela valida, registra el intento y dirige la operacion al metodo de pago correspondiente. Los webhooks y retornos actualizan el resultado. `donoradmin` explota los mismos datos para la gestion interna. Ambos consumen recursos de `shared-assets`, mientras procesos programados completan recuperaciones, cobros recurrentes, documentos y comunicaciones. ![Arquitectura de aplicaciones](diagramas/arquitectura.png) ## 5. Flujo principal de una donacion El circuito comienza con los datos personales o empresariales, consentimiento, campaña, importe y tipo de donacion. La eleccion del metodo determina el tratamiento posterior: Redsys o Bizum requieren confirmacion de pasarela; PayPal aplica su propio retorno; SEPA registra solicitud, mandato y estado bancario pendiente. Cada operacion debe ser idempotente: un retorno repetido no puede duplicar la donacion, el cobro, el certificado ni la comunicacion. Los fallos de correo o documento no deben convertir un pago valido en fallido. Los intentos no completados se recuperan con ventanas temporales y se omiten cuando la persona ya ha donado correctamente ese dia. ![Flujo de donacion](diagramas/flujo_donacion.png) ## 6. Modelo de datos funcional El nucleo relaciona contacto con sus datos personales o empresariales y sus canales. Las donaciones se asocian a contacto, campaña y metodo de pago; las recurrencias agrupan cuotas; los intentos registran el progreso previo a la confirmacion. Comunicaciones, documentos, auditoria y remesas aportan trazabilidad. El diagrama es conceptual y no sustituye el esquema SQL ni las migraciones. Resume las relaciones criticas para comprender la plataforma. ![Modelo de datos conceptual](diagramas/modelo_datos.png) ## 7. Estructura de servidor y despliegue Los repositorios activos se despliegan como aplicaciones hermanas. `shared-assets` debe publicarse en una ruta estable accesible por las otras dos. Los directorios de almacenamiento contienen sesiones, logs, temporales, certificados o medios generados y no deben tratarse como codigo versionado. Los secretos permanecen en `.env` y las migraciones se aplican de forma coordinada sobre la base compartida. ![Estructura del servidor](diagramas/servidor.png) ## 8. Alcance de dona `dona` es la frontera publica y de mayor exposicion. Su alcance incluye formulario responsive, normalizacion de identidad y contacto, pais y direccion, consentimientos, pagos puntuales y recurrentes, Redsys, Bizum, PayPal y SEPA, webhooks, certificados, emails e intentos recuperables. Sus puntos criticos son la validacion en servidor, la integridad del importe y la campaña, la idempotencia de pasarelas, el tratamiento seguro de datos personales y bancarios, la separacion entre pago y correo, y la compatibilidad de contratos con `donoradmin` y `shared-assets`. ## 9. Alcance de donoradmin `donoradmin`, actualmente en version `2.3.0`, concentra la gestion administrativa y tecnica: dashboard, donantes, donaciones, recurrencias, campañas, informes, certificados, medios, plantillas, usuarios, permisos, auditoria, configuracion, intentos y operativa SEPA. Sus puntos criticos son el control por perfil, CSRF y sesiones, la trazabilidad de acciones destructivas, el aislamiento de mandatos y metodos de pago, la conciliacion idempotente, la distincion entre devolucion y reembolso, la coherencia con Salesforce y la proteccion de datos historicos. ## 10. Alcance de shared-assets `shared-assets` centraliza identidad visual, hojas de estilo y scripts base, logotipos, plantillas fallback de email y plantillas PDF. Su valor principal es impedir que `dona` y `donoradmin` generen comunicaciones o documentos contradictorios. Los cambios en variables, nombres de plantilla, rutas o estructura HTML deben coordinarse con todos los consumidores. Un despliegue parcial puede provocar recursos ausentes o contenidos desalineados aunque el codigo de cada aplicacion sea correcto. ## 11. Seguridad, privacidad y trazabilidad - No se versionan secretos, claves privadas, sesiones, logs con datos reales, certificados generados ni volcados de produccion. - Las operaciones administrativas sensibles exigen sesion, perfil autorizado, CSRF y validacion repetida en servidor. - Los logs tecnicos evitan duplicar email, documento, telefono, direccion e IBAN cuando no son necesarios para diagnostico. - Los webhooks verifican el resultado de pasarela y aplican idempotencia antes de modificar estados. - Los procesos de email y PDF son posteriores al resultado economico y toleran fallos sin degradar una donacion confirmada. - Las migraciones deben conservar reversibilidad cuando sea posible y diagnosticar datos incompatibles antes de imponer nuevas restricciones. ## 12. Puntos criticos para mantenimiento 1. Tratar el esquema de base de datos como contrato compartido entre `dona` y `donoradmin`. 2. Desplegar conjuntamente los cambios que afecten variables o plantillas de `shared-assets`. 3. No reutilizar `donaciones` como espejo ni trasladar cambios automaticamente desde el legacy. 4. Probar retornos duplicados y asincronos de todas las pasarelas. 5. Mantener diferenciados `pagada`, `pendiente`, `denegada`, `error`, `devuelta` y `reembolsada`. 6. Revisar remesas, mandatos y secuencias `FRST`/`RCUR` antes de cualquier cambio SEPA. 7. Confirmar permisos tanto en interfaz como en backend. 8. Vigilar cron, SMTP, almacenamiento de certificados y logs tras cada despliegue. 9. Aplicar y registrar migraciones antes de activar codigo que dependa de ellas. 10. Actualizar memoria, version y manual cuando cambie una capacidad visible o un permiso. ## 13. Estado al cierre documental La plataforma ha pasado de una aplicacion concentrada a una arquitectura modular con responsabilidades claras. `donaciones` queda como testimonio del origen; `dona` y `donoradmin` son las lineas activas; `shared-assets` actua como contrato visual y documental. La fase valle es adecuada para consolidar pruebas de integracion, procedimientos de despliegue, inventario de tareas programadas y revisiones de recuperacion ante desastre. --- # Apendices documentales Los apartados siguientes incorporan las memorias originales. Conservan el orden y nivel de detalle de cada repositorio como evidencia del trabajo realizado por jornadas.