# 🍇 MAPA INTEGRAL DE LA APLICACIÓN — AGRIGEST / MESAS_V2 (MODERNIZADO)

> **Documento Maestro Canónico de Arquitectura, Funcionamiento y Despliegue Portable**  
> **Sistema**: Terminal Táctil Industrial Offline-First de Pesaje y Control de Mesas de Uva de Mesa  
> **Versión**: 2.0 (Modernización Completada) &bull; **Fecha de Actualización**: 2026-10-10  
> **Stack Base**: Delphi 11 Alexandria VCL &bull; FireDAC (`SQLite` Local + `MySQL` Remoto) &bull; Hilo Asíncrono `TSyncThread` &bull; CPort con Parser Heurístico `uCapturaBascula` &bull; Despliegue Portable Standalone  
> **Módulos**: 6 unidades (`principal.pas`, `desbloqueo.pas`, `configuracion.pas`, `local_db.pas`, `sync_thread.pas`, `uCapturaBascula.pas`)  
> **Estado de Compilación**: Compila con éxito (0 Errores en Release y Debug, Delphi 11 Alexandria)

---

## 📑 Tabla de Contenidos
1. [Visión General y Filosofía Portable ("Copy & Run")](#1-visión-general-y-filosofía-portable-copy--run)
2. [Comparativa Arquitectónica: Legacy MESAS / REPLICANDO vs. MESAS_V2](#2-comparativa-arquitectónica-legacy-mesas--replicando-vs-mesas_v2)
3. [Arquitectura Técnica de Capas y Componentes](#3-arquitectura-técnica-de-capas-y-componentes)
   - 3.1. Esquema de Doble Motor FireDAC (SQLite Offline + MySQL Central)
   - 3.2. Motor de Replicación Asíncrona en Background (`TSyncThread`)
   - 3.3. Diálogo Táctil de Configuración Avanzado (`fconfiguracion`)
   - 3.4. Test en Vivo de Báscula Serie (Puerto COM, Peso, Estabilidad y Trama)
   - 3.5. Soporte Multi-Monitor y Multi-Instancia en Planta
4. [Ciclos de Vida y Diagramas de Flujo (Mermaid)](#4-ciclos-de-vida-y-diagramas-de-flujo-mermaid)
   - 4.1. Arranque del Sistema, Puesta en Marcha y Selección de Monitor
   - 4.2. Flujo de Pesaje Desconectado (Offline-First)
   - 4.3. Motor de Sincronización Push / Pull y Monitor de Pesadas
   - 4.4. Cierre y Purga Remota de Sesión de Operarias
5. [Catálogo Maestro de Módulos y Unidades](#5-catálogo-maestro-de-módulos-y-unidades)
6. [Guía de Puesta en Marcha en Nuevos Equipos de Planta](#6-guía-de-puesta-en-marcha-en-nuevos-equipos-de-planta)

---

## 1. Visión General y Filosofía Portable ("Copy & Run")

El proyecto **`mesas_v2`** sustituye y unifica en un solo ejecutable ligero el sistema anterior de dos procesos (`MESAS.exe` + `REPLICANDO.exe`), eliminando por completo la necesidad de instalar o mantener un servidor MySQL local en los terminales de planta.

### Claves del Despliegue:
1. **Portabilidad Absoluta**: Para instalar la aplicación en un equipo nuevo de planta, basta con copiar la carpeta compilada (`mesas_v2.exe` junto con `libmysql.dll`).
2. **Cero Instalación de Base de Datos Local**: SQLite se compila embebido directamente dentro del binario. La base de datos local `<nombre_ini>_local.db` se auto-inicializa en el primer arranque.
3. **Asistente de Puesta en Marcha**: Si no existe archivo de configuración (o si se arranca con `/config`), se abre automáticamente el formulario visual de configuración para validar la conexión al servidor MySQL central y probar la báscula.
4. **Soporte Multi-Monitor y Multi-Instancia**: Admite la ejecución de dos o más terminales simultáneos en el mismo PC (ej. Monitor 1 con Báscula 1 por COM1 y Monitor 2 con Báscula 2 por COM2) sin interferencias.

---

## 2. Comparativa Arquitectónica: Legacy MESAS / REPLICANDO vs. MESAS_V2

| Característica | MESAS + REPLICANDO (Legacy) | MESAS_V2 (Modernizado) | Beneficio Operativo |
| :--- | :--- | :--- | :--- |
| **Procesos en Windows** | 2 ejecutables (`MESAS.exe` + `REPLICANDO.exe`) | **1 único ejecutable (`mesas_v2.exe`)** | Cero problemas de sincronización entre procesos. |
| **Entorno Delphi** | Delphi XE3 (v14.3) | **Delphi 11 Alexandria (v19.3)** | Soporte moderno, rápido y compatible 64-bit. |
| **Capa de Datos** | ZeosLib 7.x (`TZConnection`) | **FireDAC (`TFDConnection`)** | Mayor velocidad nativa y pool de conexiones. |
| **Base de Datos Local** | Requiere MySQL Server local (`mysqld.exe`) | **SQLite 3 embebido (`<ini>_local.db`)** | Cero configuración ni servicios que se cuelguen. |
| **Tolerancia a Caídas de Red** | Fragilidad por servicios dependientes | **100% Offline-First con colas locales** | La balanza nunca se detiene aunque caiga Internet. |
| **Test de Báscula en Pantalla** | No existía (a ciegas con blocs de notas) | **Panel interactivo con peso, trama y estado** | El técnico valida la báscula en 5 segundos. |
| **Test de Conexión a Servidor** | No existía en la UI | **Botón "Probar Conexión" con latencia ms** | Diagnóstico instantáneo de red y credenciales. |
| **Multi-Monitor / Multi-Báscula** | Manual arrastrando ventanas | **Selector de monitor y `/puesto:X`** | Ventanas fijadas automáticamente en su monitor. |
| **Purga Remota de Operarias** | En `REPLICANDO.exe` mediante borrado | **Integrado en `TSyncThread` con notificación** | Puesto liberado si la operaria ficha en otra mesa. |
| **Contador de Pesadas** | Botón aislado en `REPLICANDO.exe` | **Monitor en tiempo real en la barra de estado** | Visibilidad de cajas pesadas y cola pendiente. |

---

## 3. Arquitectura Técnica de Capas y Componentes

```mermaid
graph TD
    subgraph "Terminal Táctil Standalone (mesas_v2.exe)"
        UI["🎨 Capa Visual UI\n(principal.pas / Tpprincipal)\nMonitorización en Tiempo Real"]
        Cfg["⚙️ fconfiguracion (configuracion.pas)\nTest de COM y Servidor Central"]
        Desb["🔒 fdesbloqueo (desbloqueo.pas)\nDesbloqueo supervisor"]
        Cap["🔬 Parser Metrológico\n(uCapturaBascula.pas)\nFiltrado heurístico de tramas"]
        
        UI --> Cfg
        UI --> Desb
        Cfg --> Cap

        subgraph "Persistencia Local Offline (local_db.pas)"
            FDLoc["💾 FireDAC SQLite (<ini>_local.db)"]
            Colas[("🗂️ Colas de Subida:\nmovimiento_mesas_local\nproduccion_local\nrendimiento_local\ndesbloqueos_local")]
            Espejos[("📚 Caché Espejo de Maestros:\nproductos, materias_primas,\ntrabajos_almacen, calendario")]
            FDLoc --> Colas
            FDLoc --> Espejos
        end

        subgraph "Hilo de Replicación Asíncrono"
            Sync["🔄 TSyncThread (sync_thread.pas)\nPush Transaccional / Pull con Transacciones ACID"]
        end

        UI --> FDLoc
        Sync --> FDLoc
    end

    subgraph "Servidor Central AGRIGEST"
        MySQL[("🗄️ MySQL Remoto Central\n(178.236.112.44)")]
        Sync -.->|TCP 3306 (Al inicio y cada 30s)\nPush / Pull / Expulsión Operarias| MySQL
    end

    subgraph "Balanza de Mesa"
        Bascula["⚖️ Balanza Serie RS-232"] -->|Trama Continua / CPort| UI
    end
```

### 3.1. Esquema de Doble Motor FireDAC (SQLite Offline + MySQL Central)

- **`local_db.pas`**:
  Crea dinámicamente en tiempo de ejecución las tablas necesarias en SQLite:
  1. **Colas de transacciones locales** con columna de control `estado`:
     - `estado = 1`: Pendiente de inserción en MySQL central.
     - `estado = 2`: Pendiente de actualización en MySQL central (ej. salida de operario).
     - `estado = 0`: Ya sincronizado.
  2. **Espejos de datos maestros** de sólo lectura para que la aplicación funcione aislada:
     - `productos`, `materias_primas`, `trabajos_almacen`, `almacen_sector`, `empresa`, `sectores_mesas`, `calendario_laboral`.
  3. **Control Automático y Auto-reparación del Driver MySQL (`libmysql.dll`)**:
     - Registra `TFDPhysMySQLDriverLink` global al iniciar la aplicación (`initialization`).
     - Resuelve la ruta canónica de `libmysql.dll` (directorio del ejecutable, `C:\MESAS\libmysql.dll`, rutas relativas y ubicaciones estándar corporativas).
     - Si falta junto al ejecutable pero existe en otra ruta corporativa, la copia automáticamente al directorio local ("Self-Healing").
     - Asigna el parámetro `VendorLib` explícito a todas las conexiones remotas FireDAC evitando el error 314.

### 3.2. Motor de Replicación Asíncrona en Background (`TSyncThread`)

- Implementado como un `TThread` independiente con ciclo de reposo configurable (se ejecuta inmediatamente al inicio y luego cada 30 segundos).
- **Flujo PUSH (Subida)**:
  - Revisa `movimiento_mesas_local` (`estado = 1` y `estado = 2`) con reintento atómico de concurrencia.
  - Revisa `produccion_local` (`estado = 1`).
  - Revisa `rendimiento_local` (`estado = 1`).
  - Revisa `desbloqueos_local` (`estado = 1`).
  - Revisa `trabajo_diario_local` (`estado = 1`).
- **Flujo PULL Transaccional (Bajada de maestros)**:
  - Descarga cambios en lotes atómicos envueltos en `LLocalConn.StartTransaction` y `Commit` para máxima velocidad en SQLite (más de 50x más rápido).
- **Cierre y Purga Remota de Operarias**:
  - Escanea todas las operarias locales con `salida_real IS NULL`. Si en el servidor central tienen salida, las purga de local y avisa a la UI.
- **Monitorización de Estadísticas**:
  - Emite el evento `OnStatsUpdate(Sender, TotalHoy, PendientesSubida)` actualizando la barra de estado en vivo.

### 3.3. Diálogo Táctil de Configuración Avanzado (`fconfiguracion`)

- Acceso por primer arranque, doble clic en la barra de estado o parámetro `/config`.
- **Aislamiento Total de Comunicaciones (`DetenerComunicaciones`)**:
  - Al abrirse la configuración (por primer inicio, línea de comandos o doble clic), se **detienen automáticamente todos los temporizadores en segundo plano** (`tcomprobar`, `tsincronizar`, `Timer4`, `tpesar`, `Ta_cero`, `Tboton`).
  - Se **cierra el puerto serie** (`puerto1.Connected := False`) para garantizar acceso 100% exclusivo al puerto COM durante los tests metrológicos.
  - Se **detiene y destruye el hilo de sincronización** `TSyncThread` para evitar colisiones de red o bloqueos de base de datos.
  - Una vez guardada la configuración, `ReanudarComunicaciones` conecta ordenadamente `DBagrigest` al archivo SQLite local, reabre `puerto1`, reinicia `TSyncThread` y activa los temporizadores.
- **Grupo Servidor Central**:
  - Parámetros de Host, DB, Usuario y Contraseña.
  - Botón **"🔌 Probar Conexión"** que valida inmediatamente la accesibilidad del servidor y reporta el tiempo de respuesta en milisegundos.
- **Grupo Puesto e Instancia**:
  - Número de mesa y nombre de báscula.
  - Selector de monitor (`cbMonitor`) que lista las pantallas detectadas por Windows (`Screen.Monitors`).
  - Botón **"📍 Fijar Posición Actual de Ventana"** para recordar coordenadas exactas.
  - Checkbox para maximizar automáticamente en el monitor asignado.
- **Grupo Comunicaciones y Báscula**:
  - Selector desplegable de puertos COM cargado con detección automática (`EnumComPorts`) y botón de refresco `🔄`.
  - Selector de velocidad (BaudRate: 1200 a 115200 bps).
  - Selector de modelo de báscula dinámico (`modelos_basculas` o catálogo estándar).

### 3.4. Test en Vivo de Báscula Serie (Puerto COM, Peso, Estabilidad y Trama)

- Incorpora la unidad [`uCapturaBascula.pas`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/mesas_v2/uCapturaBascula.pas) adaptada de `AGRIGEST\BASCULAS`.
- Al pulsar **"▶ Iniciar Test Báscula"**:
  - Abre el puerto serie seleccionado en modo escucha.
  - Decodifica el peso en tiempo real y lo muestra en texto gigante (`lblTestPeso`).
  - Muestra el estado metrológico: verde si es **Peso ESTABLE**, naranja si es **Peso EN MOVIMIENTO**.
  - Muestra la **última trama ASCII en crudo** recibida de la balanza (`lblTestTrama`).
  - Posee temporizador de seguridad de 20 segundos que detiene el test si se deja desatendido.

### 3.5. Soporte Multi-Monitor y Multi-Instancia en Planta

Para trabajar en un equipo con dos monitores conectados a dos balanzas distintas:
- **Instancia 1**:
  Acceso directo: `mesas_v2.exe /puesto:1`
  Genera: `mesas_puesto1.ini` y `mesas_puesto1_local.db` (en Monitor 1 por COM1).
- **Instancia 2**:
  Acceso directo: `mesas_v2.exe /puesto:2`
  Genera: `mesas_puesto2.ini` y `mesas_puesto2_local.db` (en Monitor 2 por COM2).
- Cada instancia tiene su propia base de datos SQLite, garantizando **cero conflictos de bloqueo de archivos**.

---

## 4. Ciclos de Vida y Diagramas de Flujo (Mermaid)

### 4.1. Arranque del Sistema, Puesta en Marcha y Selección de Monitor

```mermaid
sequenceDiagram
    autonumber
    actor Tech as Técnico de Planta
    participant Main as mesas_v2.exe
    participant Frm as Tpprincipal
    participant Cfg as fconfiguracion

    Tech->>Main: Ejecuta mesas_v2.exe [/puesto:1 o /config]
    Main->>Frm: FormShow
    alt ¿No existe INI o viene con /config?
        Frm->>Cfg: ShowModal (Asistente de Configuración)
        Tech->>Cfg: Configura MySQL y pulsa "Probar Conexión"
        Tech->>Cfg: Selecciona COM y pulsa "Iniciar Test Báscula"
        Cfg-->>Tech: Valida peso en vivo y tramas ASCII
        Tech->>Cfg: Selecciona Monitor 1 y pulsa "Guardar"
        Cfg-->>Frm: Guarda INI con monitor y puertos
    end
    Frm->>Frm: Inicializa SQLite local (<ini>_local.db)
    Frm->>Frm: Posiciona ventana en el Monitor configurado
    Frm->>Frm: Conecta báscula y arranca TSyncThread en segundo plano
```

### 4.2. Flujo de Pesaje Desconectado (Offline-First)

```mermaid
flowchart TD
    PesoIn([⚖️ Trama de peso recibida por CPort]) --> Valida[Verificar estabilidad y paso por cero]
    Valida --> CalcTol[Comparar con peso teórico + tara de productos local]
    CalcTol --> OkPeso{¿Peso correcto?}
    
    OkPeso -- Exceso / Desvío --> Bloq[Activar bloqueo y mostrar fdesbloqueo]
    OkPeso -- Correcto --> GrabaLocal[Insertar en produccion_local\nestado = 1\n(SQLite Local Instantáneo)]
    
    GrabaLocal --> UIAct[Actualizar UI:\n- Beep acústico\n- Incrementar contador de cajas\n- Refrescar rejilla]
    UIAct --> Fin([Listo para siguiente pesada])
    
    subgraph "Segundo Plano (Asíncrono)"
        GrabaLocal -.->|En cola| Cola[produccion_local WHERE estado = 1]
        Cola -.->|TSyncThread| PushSrv[INSERT INTO produccion en MySQL Central\nUPDATE produccion_local estado = 0]
    end
```

---

## 5. Catálogo Maestro de Módulos y Unidades

| Archivo | Formulario / Clase | Capa | Responsabilidad Principal |
| :--- | :--- | :---: | :--- |
| [`mesas_v2.dpr`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/mesas_v2/mesas_v2.dpr) | — | Entry | Punto de entrada del ejecutable. Inicializa la aplicación. |
| [`principal.pas`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/mesas_v2/principal.pas) | `Tpprincipal` | UI / Pesaje | Formulario principal táctil. Posicionamiento en monitores, captura de peso y monitor de sincronización. |
| [`principal.dfm`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/mesas_v2/principal.dfm) | `Tpprincipal` | UI / Layout | Formulario VCL optimizado sin campos persistentes rígidos. |
| [`configuracion.pas`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/mesas_v2/configuracion.pas) | `Tfconfiguracion` | Config | Pantalla gráfica táctil de configuración. Incluye test en vivo de báscula, test de BD y asignación de monitor. |
| [`configuracion.dfm`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/mesas_v2/configuracion.dfm) | `Tfconfiguracion` | Config UI | Layout visual con panel de test metrológico y grupos funcionales. |
| [`uCapturaBascula.pas`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/mesas_v2/uCapturaBascula.pas) | `TCapturaBascula` | Hardware | Parser metrológico heurístico que decodifica tramas ASCII de múltiples marcas de báscula. |
| [`desbloqueo.pas`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/mesas_v2/desbloqueo.pas) | `Tfdesbloqueo` | Seguridad | Diálogo modal táctil para desbloqueo de pesada mediante supervisor. |
| [`desbloqueo.dfm`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/mesas_v2/desbloqueo.dfm) | `Tfdesbloqueo` | Seguridad UI | Teclado virtual `TouchKeyboard` de supervisión. |
| [`local_db.pas`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/mesas_v2/local_db.pas) | `InicializarBaseDatosLocal` | Data / SQLite | DDL automático de tablas SQLite para colas offline y espejos de maestros. |
| [`sync_thread.pas`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/mesas_v2/sync_thread.pas) | `TSyncThread` | Logic / Replicación | Hilo en segundo plano que gestiona Push transaccional, Pull con transacciones ACID, purga remota de operarias y estadísticas. |

---

## 6. Guía de Puesta en Marcha en Nuevos Equipos de Planta

Para instalar y arrancar la aplicación en cualquier máquina nueva:

1. **Copiar Carpeta**:
   Copiar los archivos generados en [`Win32\Release`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/mesas_v2/Win32/Release) a cualquier carpeta del nuevo equipo (ej. `C:\AGRIGEST_MESAS\`):
   - `mesas_v2.exe`
   - `libmysql.dll`
2. **Crear Accesos Directos**:
   - Para un puesto con una sola báscula:
     `C:\AGRIGEST_MESAS\mesas_v2.exe`
   - Para un puesto de doble báscula / multimonitor:
     - Acceso directo 1: `C:\AGRIGEST_MESAS\mesas_v2.exe /puesto:1` (ej. Monitor Izquierdo)
     - Acceso directo 2: `C:\AGRIGEST_MESAS\mesas_v2.exe /puesto:2` (ej. Monitor Derecho)
3. **Configuración en el Primer Arranque**:
   - Al abrirse por primera vez, la aplicación muestra la ventana de configuración:
     - Indicar Host del servidor MySQL (ej. `178.236.112.44`), Base de Datos, Usuario y Clave.
     - Pulsar **"Probar Conexión"** para verificar acceso.
     - Seleccionar el puerto COM de la báscula y pulsar **"Iniciar Test Báscula"** para ver el peso en vivo.
     - Seleccionar el monitor donde debe abrirse la ventana.
     - Pulsar **"Guardar"**.
4. ¡Listo! La aplicación queda 100% operativa pesando en local y replicando en segundo plano.
