# Transferencia técnica · FUNDAE → Previnapp

Versión de laboratorio: **0.13.50**. Documento de referencia de implementación, no contrato público oficial de FUNDAE ni certificación de producción. **No contiene credenciales ni valores personales.**

## Objetivo y alcance

Reaprovechar en el ERP Previnapp la integración demostrada en el laboratorio FUNDAE: acceso autenticado con certificado; consultas de acciones y grupos; ficha de empresas, centros, participantes, tutores, horarios y costes; exportación de trabajadores por empresa; validación, preflight, envío y seguimiento de XML de acciones, inicio y finalización; notificación firmada de inicio y finalización; consulta del justificante PDF. No migrar sin revisión los controladores del laboratorio como API de producción.

## Mapa verificable: del frontend al backend

| Función | Acción `public/api.php` | Backend / observación |
|---|---|---|
| Buscar grupo por acción/grupo | `lab_groups_direct_search` | `FundaeBackend` / transporte HTTP autenticado |
| Empresas | `lab_group_companies_read` | `FundaeBackend::readGroupCompaniesLab` |
| Centros | `lab_group_centers_read` | `FundaeBackend::readGroupCentersLab` |
| Tutores | `lab_group_tutors_read` | `FundaeBackend::readGroupTutorsLab` |
| Participantes/trabajadores | `lab_group_participants_read` | `FundaeBackend::readGroupParticipantsLab`; remoto `cargarparticipantes_dt` |
| Horarios/calendario | `lab_groups_calendar_read` | `FundaeBackend::readGroupCalendarLab` |
| Costes | `lab_group_costs_read` | `FundaeBackend::readGroupCostsLab` |
| Preparación/notificación inicio | `lab_group_start_signature_contract`, `lab_group_start_signature_callback` | Contrato FIRe / firma / callback / readback; estudiar además acciones intermedias `open_form`, `prepare_fire`, `presign`, `pkcs1`, `postsign` |
| Finalización firmada | Examinar `lab_groups_finalization_signature_contract`, `lab_groups_finalization_signature_prepare`, `lab_groups_finalization_signature_return` y el controlador invocado por `finalizeGroupOneClick` | No considerar transacción completada sin lectura de estado |
| PDF finalización | `lab_groups_finalization_certificate_download` | Obtención autenticada sin escritura remota |
| Registro XML y validación XSD local | `submit_xml` | `XmlValidator`, `SchemaCatalog`, `OfficialContractStore` |
| Preflight XML inicio | `lab_xml_start_preflight` | Lectura remota sin envío |
| Preflight XML acciones | `lab_xml_actions_preflight` | Lectura remota sin envío |
| Preflight XML finalización | `lab_xml_finalization_preflight` | Lectura remota sin envío |
| Envío único XML | `lab_xml_remote_submit` | `FundaeBackend::uploadGroupXml` + `RemoteWriteGuard` |
| Estado de proceso XML | `lab_xml_status_check` | `FundaeBackend::readXmlUploadStatus` |
| Material de certificado de firma | `signing_material_status`, `signing_material_set`, `signing_material_clear` | Configuración de firma separada del certificado de acceso |

Los nombres son interfaces **internas del laboratorio**, no endpoints oficiales garantizados por FUNDAE. Consultar `public/api.php`, `src/Backend/FundaeBackend.php` y `src/Transport/NativeHttpTransport.php` antes de separar capas.

## Contratos remotos observados

- Consulta de participantes: `POST /{ejercicio}/gruposformativos/cargarparticipantes_dt` (payload del formulario: `Filtro.IdGrupoFormativo`, `Filtro.IdEstadoGrupo`, `Filtro.CifParticipante`, `Filtro.NifParticipante`, `Filtro.IdEstadoParticipante`). Respuesta JSON con `Data.data[]`; cada fila observada incluye `id`, `ID_EMPRESA`, `ID_CENTRO_EMPRESA`, `D_CIF`, `ID_GRUPO_FORMATIVO` y campos de ficha. `recordsTotal` y `recordsFiltered` permiten detectar paginación. No registrar datos personales en logs.
- Detalle individual: `POST /{ejercicio}/gruposformativos/participantedetalles` devuelve HTML. Confirmar el mapeo y el carácter exclusivamente de lectura antes de integrarlo para enriquecer el grid.
- Carga XML: `/{ejercicio}/CargaXML/NewEnvio`; seguimiento: `/{ejercicio}/CargaXML/NewListado`. Los endpoints, opciones, CSRF y formularios deben descubrirse y verificarse según ejercicio y perfil.
- Para lectura de detalle grupo y catálogo de acciones, seguir las rutas demostradas en la implementación, no fijar URLs sin validar.

## Esquemas, entradas y salidas

- XSD locales de referencia: `schemas/2026/AAFF_Inicio.xsd`, `InicioGrupos_Organizadora.xsd`, `FinalizacionGrupo_Organizadora.xsd`.
- XML de ejemplo de estructura: `examples/2026/` (**no** reutilizar como cargas reales).
- Identidad de carga: ID local de submission, SHA-256 del contenido, tipo semántico, ejercicio y estado remoto verificable.
- Salidas propuestas en ERP: DTOs tipados para Acción, Grupo, Empresa, Centro, Participante, Horario, Coste, Operación XML, Firma y Evidencia. Normalizar estado separado de solicitud/transporte/negocio/confirmación readback.
- Exportaciones CSV/XML/JSON: aplicar filtro de empresa confirmado por `ID_EMPRESA`/CIF; evitar equiparar un ID interno a un CIF o a un ID de centro. Exportar todas las propiedades retornadas por el origen elegido; marcar si hay enriquecimiento individual pendiente.

## Arquitectura para Previnapp

1. **FundaeAdapter** aislado para endpoints remotos, encabezados, cookies y CSRF, con TLS verificado y descubrimiento de contratos por ejercicio/perfil.
2. **CredentialProvider** para certificados de acceso y firma diferenciados; secretos fuera de base de datos y logs, permisos mínimos y rotación.
3. **Servicios de aplicación**: consulta, acciones/grupos, participantes, importación XML, notificación de inicio/finalización, justificantes y exportación.
4. **Estado transaccional e idempotencia**: cada mutación vinculada a consentimiento explícito, submission y SHA-256; no repetir POST por timeout o error ambiguo sin readback.
5. **Cola/worker opcional** para consultas y seguimiento; nunca automatizar firmas o escrituras sin política de autorización y control del actor.
6. **Contrato de integración**: exponer al ERP contratos propios versionados y DTOs, no rutas de páginas FUNDAE ni JSON diagnóstico del laboratorio.
7. **Observabilidad segura**: operación, duración, código HTTP, estado, conteos, hashes y correlation ID; exclusión de datos personales, cookies, CSRF, material criptográfico y XML crudo.

## Comportamiento obligatorio de escritura

`validación local → preflight remoto sin envío → revisión amigable → autorización explícita → envío una sola vez → consulta de estado/readback`. Mantener `RemoteWriteGuard` o mecanismo de producción equivalente; no exponer interruptores inseguros al usuario final. Una aceptación HTTP o de FIRe no equivale siempre a una operación de negocio confirmada.

## Calidad y validaciones antes de migrar

- Ejecutar pruebas existentes en `tests/` y añadir contratos simulados por ejercicio; validar comportamiento sin conexión real.
- Confirmar fin a fin cada endpoint de escritura solo con casos reales autorizados; separar **observado**, **probado**, **pendiente**.
- Probar varios grupos y varias empresas; paginación, filtros, duplicados y errores de pertenencia.
- Validar expiración de sesión, renovación CSRF, certificados caducados, caídas de red, rate limits, reintentos e idempotencia.
- Ensayar el ciclo de firma FIRe/PKCS#1 y notificación de inicio y finalización, y actualizar UI solamente después de readback.
- Revisar RGPD y permisos: los archivos CSV/XML/JSON con datos de trabajadores son personales; control de acceso, retención y descarga.
- Validar y versionar los XSD de cada ejercicio; evitar constantes hardcodeadas para 2026.

## Ubicación del código original

- `public/index.php`: interfaz.
- `public/assets/workspace.js`: llamadas y flujos de UI.
- `public/api.php`: endpoints y orquestación, **no** API estable de ERP.
- `src/Backend/FundaeBackend.php`: fachada backend.
- `src/Transport/NativeHttpTransport.php`: transporte remoto autenticado.
- `src/Safety/RemoteWriteGuard.php`: salvaguarda de escritura.
- `src/Signature/`: sondas y componentes de firma.
- `src/Xml/`: validación y contratos XML.
- `src/Certificate/`, `src/Tls/`: certificados y confianza TLS.
- `tests/`: pruebas existentes.

## Estado de entrega

**Confirmado en código del laboratorio:** los componentes, interfaces y rutas PHP enumerados; consultas autónomas de grupos/participantes; barreras de escritura y preflights. **Evidencia de conversación previa:** se han realizado operaciones auténticas de inicio/finalización y una importación XML de fin aceptada, pero no debe elevarse a garantía global de fiabilidad del ERP. **Pendiente:** extraer librería, crear DTOs y contratos públicos, cobertura de regresión y pruebas completas end-to-end por cada ejercicio/perfil. Esta pantalla es una guía de traspaso; no sustituye revisión del código fuente completo.