# 🍇 MAPA INTEGRAL DE LA APLICACIÓN — AGRIGEST / MESAS (LEGACY)

> **Documento Maestro Canónico de Arquitectura, Funcionamiento y Flujos Operativos**  
> **Sistema**: Terminal Táctil Industrial de Pesaje y Control de Confección en Mesas de Uva de Mesa  
> **Versión**: 1.0 Legacy &bull; **Fecha de Auditoría**: 2026-10-10  
> **Stack Base**: Delphi XE3 / Delphi 11 Alexandria VCL &bull; ZeosLib 7.x (`TZConnection`, `TZReadOnlyQuery`, `TZTable`) &bull; MySQL Remoto (178.236.112.44) &bull; CPort (RS-232 Balanzas) &bull; Vcl.Touch.Keyboard  
> **Módulos**: 2 unidades (`principal.pas`, `desbloqueo.pas`) &bull; **Formularios UI**: 2 &bull; **Tablas BD**: 15 tablas detectadas en MySQL

---

## 📑 Tabla de Contenidos
1. [Visión General y Propósito del Sistema](#1-visión-general-y-propósito-del-sistema)
2. [Arquitectura Física y Dispositivos de Planta (Hardware)](#2-arquitectura-física-y-dispositivos-de-planta-hardware)
3. [Flujos Operativos y Ciclo de Pesaje (Diagramas Mermaid)](#3-flujos-operativos-y-ciclo-de-pesaje-diagramas-mermaid)
   - 3.1. Inicio de Jornada y Asignación de Puesto/Mesa
   - 3.2. Ciclo de Pesaje de Confección y Control de Estabilidad
   - 3.3. Detección de Desvío, Bloqueo de Báscula y Desbloqueo por Supervisor
   - 3.4. Pesaje de Limpiadoras y Rendimiento
4. [Componentes y Estructura de Datos](#4-componentes-y-estructura-de-datos)
   - 4.1. Conexión de Base de Datos y Replicación Antigua
   - 4.2. Datasets y Tablas Involucradas
   - 4.3. Parámetros de Configuración (`mesas.ini`)
5. [Catálogo de Unidades y Formularios](#5-catálogo-de-unidades-y-formularios)
6. [Debilidades Técnicas y Cuellos de Botella del Sistema Antiguo](#6-debilidades-técnicas-y-cuellos-de-botella-del-sistema-antiguo)

---

## 1. Visión General y Propósito del Sistema

El proyecto **MESAS (Legacy)** es una aplicación de terminal táctil industrial para almacenes y centrales hortofrutícolas de confección de uva de mesa (sector uva del Vinalopó / AGRIGEST).

Cada terminal está instalado físicamente en una mesa de selección y empaque de uva, conectado a una báscula industrial de precisión por puerto serie RS-232.

### Objetivos Clave de Negocio:
1. **Identificación y Registro de Operarios**: Control de operarias/envasadoras asignadas al puesto (`puesto`), registrando hora de entrada real, hora ajustada y cálculo de horas de jornada laboral.
2. **Pesaje en Tiempo Real de Cajas / Confección**: Captura automática del peso desde la balanza, validación frente al peso teórico del producto y su tara, e inserción automática de la pesada sin intervención manual.
3. **Control Metrológico y Antifraude (Bloqueo Automático)**: Si una caja supera el umbral de desvío permitido (`porcbloqueo` de la empresa), el terminal bloquea la báscula impidiendo seguir pesando hasta que un supervisor introduce la clave en pantalla (`desbloqueo.pas`).
4. **Rendimiento de Uva Limpiadora**: Pesaje de cajas de uva bruta destinadas a limpiadoras/desgranadoras para control de destrío y rendimiento individual por trabajadora.
5. **Replicación MySQL Directa**: Registro en línea de pesadas contra el servidor central MySQL de AGRIGEST.

---

## 2. Arquitectura Física y Dispositivos de Planta (Hardware)

```mermaid
graph LR
    subgraph "Mesa de Envasado / Planta"
        Bal["⚖️ Balanza / Báscula Industrial\n(Dibal / Gram / Baxtran)\nRS-232 / COM"] -->|Trama ASCII Continua| PC["💻 Terminal Táctil All-in-One\n(MESAS.exe)\nCPort + TouchKeyboard"]
        Operaria["👩‍🌾 Operaria / Envasadora"] -->|Interacción Táctil| PC
        Supervisor["👮 Supervisor Calidad"] -->|Clave Desbloqueo| PC
    end

    subgraph "Servidor Central"
        PC -->|TCP 3306 Directo\n(ZeosLib TZConnection)| MySQL[("🗄️ MySQL Server\n178.236.112.44:3306\nBase: agrigest")]
    end
```

- **Puerto Serie (`CPort`)**: Escucha tramas ASCII continuas de la báscula (`puerto1: TComPort`).
  - Utiliza `comdata1` y `comdata2` (`TComDataPacket`) para segmentar tramas por caracteres de inicio y fin (`StartString`, `StopString`) o el evento `puerto1RxChar`.
- **Teclado Virtual Táctil**: `TouchKeyboard1: TTouchKeyboard` embebido para evitar teclado físico en planta húmeda/polvorienta.

---

## 3. Flujos Operativos y Ciclo de Pesaje (Diagramas Mermaid)

### 3.1. Inicio de Jornada y Asignación de Puesto/Mesa

```mermaid
sequenceDiagram
    autonumber
    actor Op as Operaria
    participant UI as Formulario Principal (pprincipal)
    participant BD as MySQL (DBagrigest)

    Op->>UI: Introduce código de operaria / Selección en grid
    UI->>BD: SELECT * FROM trabajadores WHERE id = ...
    UI->>BD: INSERT INTO movimiento_mesas (mesa, idt, trabajador, entrada_real, puesto...)
    UI->>BD: INSERT INTO trabajo_diario (...)
    UI-->>Op: Muestra nombre de operaria en panel superior y activa báscula
```

### 3.2. Ciclo de Pesaje de Confección y Control de Estabilidad

```mermaid
flowchart TD
    Inicio([⚖️ Balanza envía peso continuo]) --> RX[Evento puerto1RxChar / ComDataPacket]
    RX --> Parse[Extraer valor numérico del peso]
    Parse --> CheckEstable{¿Peso estable?\npeso == peso_anterior}
    
    CheckEstable -- No --> ResetCont[Reiniciar contador estabilidad] --> Fin([Esperar siguiente trama])
    CheckEstable -- Sí --> CompTara{¿Peso > Tara + Mínimo?\npeso > tara_producto}
    
    CompTara -- No --> ResetCero[Marcar a_cero = True si peso < 0.100 kg] --> Fin
    CompTara -- Sí --> ValidaBloq{¿Supera umbral de bloqueo?\npeso > bloqueominimo}
    
    ValidaBloq -- Sí --> ActivaBloqueo[bloqueado = True\nMostrar pantalla fdesbloqueo]
    ValidaBloq -- No --> CheckPasoCero{¿Pasó previamente por cero?\na_cero == True}
    
    CheckPasoCero -- Sí --> RegPesada[Guardar Pesada en BD:\n- INSERT INTO produccion\n- INSERT INTO pesadas_sector]
    RegPesada --> MarcaCero[a_cero = False\nEmitir Beep acústico / Actualizar contador] --> Fin
    CheckPasoCero -- No --> Fin
```

### 3.3. Detección de Desvío, Bloqueo de Báscula y Desbloqueo por Supervisor

1. Cuando la caja tiene exceso de peso respecto a la fórmula:
   $$\text{bloqueominimo} = (\text{peso\_teórico} + \text{tara}) \times \frac{\text{porcbloqueo}}{100}$$
2. El sistema marca `bloqueado := true`. Al retirar la caja (`peso < 0.100`), la balanza se inhabilita.
3. Se instancia modalmente [`fdesbloqueo`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/MESAS/desbloqueo.pas):
   - El supervisor introduce la clave numérica en el teclado virtual táctil.
   - Si la clave es válida, se reactiva el timer de pesaje y se registra el evento en `qdesbloqueos`.

### 3.4. Pesaje de Limpiadoras y Rendimiento

- En mesas configuradas con limpiadora (`tpreguntarlimpiadora = 1`):
  - Botón `BPLIMPIADORA` abre panel de selección de limpiadora.
  - Se registra el peso bruto de la caja de uva sucia en `rendimiento`:
    $$\text{pesoneto} = \text{peso\_bruto} - \text{tara}$$
  - Permite liquidar el destrío o incentivos por kilo limpiado a destajo.

---

## 4. Componentes y Estructura de Datos

### 4.1. Conexión de Base de Datos y Replicación Antigua

En `MESAS.dpr`, todo el acceso se realiza a través de **ZeosLib 7.x**:
- `DBagrigest: TZConnection`: Conexión directa TCP al host MySQL remoto.
- `dbservidor: TZConnection`: Segunda conexión espejo hacia el servidor principal.
- `esclavo: TZQuery`: Ejecuta periódicamente `SHOW SLAVE STATUS` en el timer `tsincronizar`. Comprueba `Slave_IO_Running` y `Seconds_Behind_Master`.

### 4.2. Datasets y Tablas Involucradas

| Dataset Delphi | Clase Zeos | Tabla MySQL | Propósito de Negocio |
| :--- | :--- | :--- | :--- |
| `qmprimas` | `TZReadOnlyQuery` | `materias_primas` | Catálogo de variedades de uva de mesa |
| `qproductos` | `TZReadOnlyQuery` | `productos` | Confecciones (peso, tara, tolerancia, foto) |
| `qtrabajosalmacen` | `TZReadOnlyQuery` | `trabajos_almacen` | Puestos y labores del almacén |
| `qmovimientos_mesa` | `TZReadOnlyQuery` | `movimiento_mesas` | Registro de turnos y operarias activas |
| `qenvasadoras` | `TZReadOnlyQuery` | `movimiento_mesas` | Filtro de operarias asignadas a envasado |
| `lc_produccion` | `TZTable` | `produccion_local` | Histórico local de pesadas realizadas |
| `produccionx` | `TZTable` | `produccion` | Tabla maestra remota de pesadas |
| `lc_rendimiento` | `TZTable` | `rendimiento_local` | Pesadas de uva bruta de limpiadora |
| `rendimiento` | `TZTable` | `rendimiento` | Maestra remota de rendimiento |
| `lc_trabajo_diario` | `TZTable` | `trabajo_diario_local` | Jornada de operarios en mesa |
| `trabajo_diario` | `TZTable` | `trabajo_diario` | Maestra remota de horas trabajadas |
| `empresa` | `TZTable` | `empresa` | Tolerancias de bloqueo (`porcbloqueo`) |
| `tcalendario_laboral` | `TZTable` | `calendario_laboral` | Turnos, descansos, almuerzo y festivos |
| `qdesbloqueos` | `TZQuery` | `desbloqueos` | Auditoría de desbloqueos por supervisor |
| `qpesadassector` | `TZQuery` | `pesadas_sector` | Trazabilidad por sector de almacén |

### 4.3. Parámetros de Configuración (`mesas.ini`)

Archivo de texto plano de 10 líneas posicionales sin interfaz de edición:
1. `Host MySQL` (ej. `178.236.112.44`)
2. `Usuario MySQL` (ej. `mesa0`)
3. `Password MySQL`
4. `Número de Mesa` (ej. `0`)
5. `Número de Báscula` (ej. `1`)
6. `Puerto Serie COM` (ej. `6` para COM6)
7. `Modelo de Báscula` (ej. `1`)
8. `Preguntar Limpiadora` (`0` o `1`)
9. `Replicación Activa` (`0` o `1`)
10. `Nombre de Base de Datos` (ej. `agrigest`)

---

## 5. Catálogo de Unidades y Formularios

| Archivo | Formulario | Propósito y Responsabilidad |
| :--- | :--- | :--- |
| [`MESAS.dpr`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/MESAS/MESAS.dpr) | — | Punto de entrada del ejecutable. Inicializa y muestra `Tpprincipal`. |
| [`principal.pas`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/MESAS/principal.pas) | `Tpprincipal` | Formulario maestro monolítico. Maneja UI táctil, conexión Zeos, timers de pesaje y CPort. |
| [`principal.dfm`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/MESAS/principal.dfm) | `Tpprincipal` | Diseño visual VCL con 595 componentes (424 campos persistentes ZeosLib). |
| [`desbloqueo.pas`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/MESAS/desbloqueo.pas) | `Tfdesbloqueo` | Diálogo modal de desbloqueo con teclado numérico virtual. |
| [`desbloqueo.dfm`](file:///c:/fuentes/proyectos%20delphi/AGRIGEST/MESAS/desbloqueo.dfm) | `Tfdesbloqueo` | Pantalla táctil de autenticación de supervisor. |

---

## 6. Debilidades Técnicas y Cuellos de Botella del Sistema Antiguo

1. **Dependencia Total de la Red (Cero Tolerancia a Caídas)**: Al estar Zeos conectado en directo a MySQL por Internet, cualquier microcorte o saturación congela el hilo principal de Delphi, bloqueando la línea de empaque.
2. **Replicación Bloqueante en el Hilo UI**: El timer `tsincronizarTimer` ejecuta consultas síncronas contra el servidor remoto cada pocos segundos en el mismo hilo que lee la báscula, causando tirones e inestabilidad en la lectura de peso.
3. **Rigidez de Campos Persistentes (424 TFields en DFM)**: Cualquier cambio en tipos de datos de MySQL (ej. pasar un INT a BIGINT o cambiar longitud de VARCHAR) provocaba errores en tiempo de ejecución de tipo *Type Mismatch*.
4. **Modelos de Báscula Hardcodeados**: Protocolos y tamaños de buffer fijados en código fuente; cambiar de marca de balanza requería recompilar.
5. **Configuración Frágil**: Modificar la IP o el puerto requería editar `mesas.ini` con bloc de notas en el terminal industrial.
6. **Diseño Visual Antiguo y Rígido**: Coordenadas fijas en píxeles que no escalan en monitores panorámicos modernos o tablets.
