# Plan de Integración y Arquitectura del Módulo DECA en el ERP

> **Arquitectura**: Delphi 11 Alexandria + FireDAC + MariaDB/MySQL (InnoDB) + FastReport / Native PDF  
> **Área**: `c:\fuentes\proyectos delphi\DECA`  
> **Directrices**: Cumplimiento estricto de la Resolución de 5 de junio de 2026 y Ley 9/2025 (Movilidad Sostenible).

---

## 1. Visión General de la Integración

El objetivo es incorporar al ERP existente un módulo completo para la **emisión, control administrativo, trazabilidad y compartición de documentos DeCA** (tanto para transportes propios como para terceros/agencias contratadas), ofreciendo:
1. **Emisión directa desde Albaranes de Venta / Envíos**: Posibilidad de convertir un albarán o una expedición logística en un DeCA oficial con 1 clic.
2. **Generación independiente de DeCA**: Pantalla dedicada para crear DeCAs independientes (cargas complejas, grupajes, vehículos externos o retornos).
3. **Generación automática de PDF nativo con QR**: Mediante motor de reporte nativo con metadatos embebidos de fecha/hora de creación.
4. **Servicio Web / Endpoint de Descarga Pública Segura (HTTPS)**: Para que los códigos QR permitan a la Guardia Civil / Inspectores de Transporte descargar directamente el PDF oficial sin barreras de autenticación.
5. **Envío instantáneo al conductor**: Vía WhatsApp / Web Share o enlace directo SMS/Email antes de que el camión inicie la marcha.

```mermaid
flowchart TD
    subgraph ERP["ERP Delphi 11 (VCL)"]
        ALB["Albarán / Expedición"] --> GEN["Generador DeCA"]
        DIR["Alta Manual DeCA"] --> GEN
        GEN --> DB[("MariaDB InnoDB\n(Tablas deca_*)")]
        GEN --> PDF["Generador PDF Nativo + Metadatos\n+ Código QR Embebido"]
    end

    subgraph CLOUD["Servidor Web / API REST (HTTPS)"]
        PDF -->|Upload Seguro Stream| REPO["Repositorio DeCA\n(Tokens Criptográficos)"]
        REPO --> HTTP["Endpoint Público\nGET /deca/doc/:token"]
    end

    subgraph CONDUCTOR["Dispositivo Móvil Conductor"]
        GEN -.->|WhatsApp / Enlace| WAPP["PDF en Smartphone\n(Modo Offline/Cache)"]
    end

    subgraph INSPECCION["Inspección DGT / Tráfico / Guardia Civil"]
        INSP["Agente de Tráfico"] -->|Escanea QR en Carretera| HTTP
        HTTP -->|Descarga Directa PDF < 5MB| INSP
    end
```

---

## 2. Componentes y Módulos Técnicos

### A. Capa de Base de Datos (`database/schema_deca.sql`)
- Motor **InnoDB** con transacciones ACID, integridad referencial y `ON DELETE RESTRICT` para evitar pérdidas documentales.
- Estructura normalizada:
  1. `deca_cabecera`: Datos identificativos, token público hash SHA-256 para el QR, cargador contractual, transportista efectivo, origen, destino, fechas, matrículas (tractora y remolque), peso total, tipo de mercancía, estado (`BORRADOR`, `EMITIDO`, `RECTIFICADO`, `ANULADO`).
  2. `deca_paradas`: Hasta 10 paradas intermedias con orden secuencial, NIF, tipo de operación (`paso`, `carga`, `descarga`, `carga_descarga`), kg netos y detalles.
  3. `deca_adr_lineas`: Información completa de mercancías peligrosas ligadas a paradas u origen/destino.
  4. `deca_rectificaciones`: Registro histórico inmutable de cualquier corrección efectuada sobre un DeCA emitido (fecha exacta, motivo, usuario y datos previos).

### B. Capa de Datos Delphi 11 (`src/uDecaDataModule.pas` & `src/uDecaTypes.pas`)
- Conexión vía **FireDAC** con parámetros fuertemente tipados (`ftWideString` para UTF-8 limpio con tildes).
- Mapeo desacoplado de entidades de dominio.
- Enlace opcional a las tablas de clientes, proveedores y flotas del ERP para auto-rellenado de datos fiscales (Cargador / Transportista).

### C. Generación de PDF Nativo y Código QR
- **Generación de Código QR**: Utilización de componentes de código de barras bidimensional (como `DelphiZXingQRCode` o componentes nativos de FastReport) sin librerías externas que requieran instalación de software de terceros.
- **Incrustación de Metadatos**: El PDF generado debe contener en el diccionario `Info` las marcas `/CreationDate` y `/ModDate` con fecha UTC estricta.
- **Formato Visual Oficial**: Cabecera con "DOCUMENTO ELECTRÓNICO DE CONTROL ADMINISTRATIVO (DECA) - ORDEN FOM/2861/2012 Y RESOLUCIÓN DGT/DGTCF", recuadros diferenciados para Cargador y Transportista, bloque de ruta con paradas, bloque de vehículo con matrículas y bloque QR con texto legal explicativo para inspección.

### D. Servicio de Alojamiento y Endpoint de Tráfico
- Al emitir el DeCA, el sistema sube el archivo PDF generado a un servidor seguro propio bajo HTTPS o ejecuta un microservicio REST (ej. en el servidor del portal web o API Node/Delphi).
- La URL generada adopta el formato:
  `https://documentos.[dominio].com/deca/[token_seguro]`
- El servidor responde directamente con:
  - `Content-Type: application/pdf`
  - `Content-Disposition: inline; filename="DECA_[Matricula]_[Fecha].pdf"`
  - `Cache-Control: public, max-age=86400`
- No se solicita usuario, contraseña ni captcha en dicha ruta.

---

## 3. Plan de Fases de Ejecución

1. **Fase 1: Esquema de Base de Datos y Tipos Delphi**:
   - Crear el script DDL `schema_deca.sql` para MariaDB/MySQL.
   - Crear la unidad `uDecaTypes.pas` con los tipos, enums y registros de validación.
2. **Fase 2: Motor de Negocio y Lógica de Emisión**:
   - Validación estricta de campos obligatorios según Orden FOM/2861/2012.
   - Generación de token criptográfico único para la URL.
   - Generación del PDF nativo con QR incrustado.
3. **Fase 3: Pantalla VCL Delphi 11 de Gestión de DeCA**:
   - Diseño responsivo adaptado según `vcl-responsive-ui-designer`.
   - Soporte de paradas dinámicas y bloque ADR.
   - Botón de envío directo a WhatsApp / Portapapeles para el conductor.
4. **Fase 4: Auditoría de Calidad y Rendimiento**:
   - Validación estricta de gestión de memoria (`try..finally`), `Tag=999` en controles de filtro y ausencia de memory leaks con FastMM.