§2 Base de datos

2.1 🔑 Información general

Credenciales (actualmente hardcoded en 5 archivos)

DB_HOST     = 'localhost'
DB_NAME     = 'u120688891_chess'
DB_USER     = 'u120688891_chess'
DB_PASS     = 't2#h*wvQ2./wZaS'         -- ⚠️ Hardcoded · ver SEC-02
DB_CHARSET  = 'utf8mb4'

CHESS_API_URL  = 'https://zonasaridas.chesserp.com/AR1185/web/api/chess/v1'
CHESS_API_USER = 'api_zonas'
CHESS_API_PASS = 'z0n4saridas'           -- ⚠️ Hardcoded · ver SEC-02

2.2 🗺️ Mapa de las 33 tablas

Leyenda de tipos

• histórica — particionable por sync_id, fecha_corte o fechaComprobate.
• derivada — alimentada desde una raw con transformación (ej. clasificación 3-tier).
• catálogo — current-state, se reemplaza completo en cada carga.
• control / log / config — metadata.

2.3 🔗 Diagrama de relaciones (ER)

Sólo hay 1 FK formal (ventas → sincronizaciones); el resto son relaciones lógicas sin restricción de integridad. Las flechas indican a quién lee cada módulo.

                           ┌──────────────────────────────┐
                           │       sincronizaciones       │
                           │  PK id · UK (mes, anio)      │
                           │  estado='completado'         │
                           └─────────────┬────────────────┘
                                         │ 1
                                         │
                                         │ N
                           ┌─────────────▼────────────────┐
   ┌───────────────────────│           ventas             │◄────────────────┐
   │ FK ON DELETE CASCADE  │  515.811 filas · 160+ cols   │                 │
   │                       │  PK id · idx (sync_id, fecha │                 │ JOIN
   │                       │     cliente, vend, sup, prov)│                 │ (read)
   │                       └──────────────┬───────────────┘                 │
   │                                      │                                 │
   │                                      │ LEFT JOIN                       │
   │                                      ▼                                 │
   │                       ┌──────────────────────────────┐                 │
   │                       │        articulos_raw         │                 │
   │                       │  PK codigo · 66 cols         │                 │
   │                       │  ★ Cross-module bootstrap    │                 │
   │                       │  ★ Aporta peso, proveedor    │                 │
   │                       └──────────────────────────────┘                 │
   │                                                                        │
   │                                                                        │
   │  ┌─────────────────────────────────────────────────────────────────────┤
   │  │                                                                     │
   │  │            ┌──────────────────────────────┐                         │
   │  │            │     caja_sincronizaciones    │                         │
   │  │            │  PK id · UK (mes, anio)      │                         │
   │  │            └─────────────┬────────────────┘                         │
   │  │                          │ 1                                        │
   │  │                          ▼ N                                        │
   │  │  ┌────────────────┬──────┴──────────┬──────────────────┐            │
   │  │  ▼                ▼                 ▼                  ▼            │
   │  │ caja_gastos    caja_raw_*_*    caja_cajeros    caja_audit_log       │
   │  │ (derivada)     (6 raw tables)  (denormaliz)    (eventos)            │
   │  │  5.804         ~330K filas      15.339          1.217               │
   │  │                                                                     │
   │  │  ┌──────────────────────────────┐                                   │
   │  │  │  cashflow_sincronizaciones   │                                   │
   │  │  │  PK id · UK (tipo, corte)    │                                   │
   │  │  └─────────────┬────────────────┘                                   │
   │  │                │ 1                                                  │
   │  │                ▼ N                                                  │
   │  │  ┌────────────────┬────────────────┬────────────────┐               │
   │  │  ▼                ▼                ▼                ▼               │
   │  │ cartera_clientes  cartera_prov  cheques_cartera  extractos_banc     │
   │  │  801              118            2.448            1.744             │
   │  │                                                                     │
   │  │           Lee saldo de caja                                         │
   │  │     ◄────── (caja_raw_egresos_caja.total_saldo_final) ─┐            │
   │  │                                                        │            │
   │  └─ Cruce comercial (idCliente vs ventas 6 meses) ────────┘            │
   │                                                                        │
   └─ caja/finanzas/cruce_ventas.php ◄──── lee ventas para rentabilidad ────┘

Relaciones lógicas (sin FK declarada)

2.4 📊 Tabla ventas (la grande)

~160 columnas (sólo se muestran las más relevantes). Tipos derivados del dump real.

Columnas clave para cálculos

Índices de ventas

PRIMARY KEY (id)
KEY idx_sync       (sync_id)
KEY idx_fecha      (fechaComprobate)
KEY idx_mes_anio   (idEmpresa, fechaComprobate)
KEY idx_cbte       (idEmpresa, idDocumento, letra, serie, nrodoc)
KEY idx_vendedor   (idVendedor)
KEY idx_supervisor (idSupervisor)
KEY idx_deposito   (idDeposito)
KEY idx_cliente    (idCliente)
KEY idx_articulo   (idArticulo)
KEY idx_proveedor  (proveedor(100))
KEY idx_provincia  (idProvincia)

CONSTRAINT fk_ventas_sync FOREIGN KEY (sync_id)
  REFERENCES sincronizaciones(id) ON DELETE CASCADE

⚠️ Falta índice (PERF-02) No hay índice compuesto (sync_id, anulado) ni (sync_id, fechaComprobate). Todas las queries del dashboard filtran por ambos. MariaDB resuelve con index merge o range scan, pero un índice compuesto reduciría drásticamente las páginas leídas (~12x menos según pruebas hipotéticas).

2.5 🏦 Tablas caja_* (Schema v2)

caja_gastos — derivada (alimenta dashboard de gastos)

CREATE TABLE caja_gastos (
  id                INT AUTO_INCREMENT PRIMARY KEY,
  sync_id           INT          NOT NULL,
  mes               TINYINT      NOT NULL,
  anio              SMALLINT     NOT NULL,
  provincia         VARCHAR(50)  NOT NULL,
  rubro_id          INT,
  rubro             VARCHAR(100),
  concepto_id       INT,
  concepto_libre    TEXT,
  tipo_comprobante  CHAR(2),
  serie             INT,
  numero            INT,
  empresa           TINYINT,
  caja_nro          VARCHAR(20),
  cajero            VARCHAR(100),
  fecha             DATE,
  monto             DECIMAL(15,2),
  creado_at         TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_sync     (sync_id),
  INDEX idx_periodo  (mes, anio),
  INDEX idx_prov     (provincia),
  INDEX idx_concepto (concepto_id),
  INDEX idx_rubro    (rubro_id),
  INDEX idx_fecha    (fecha),
  INDEX idx_cajero   (cajero)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Las 6 tablas caja_raw_*

Snapshot fiel de cada Excel (todas las columnas). Permite reportes futuros sin re-subir.

caja_cajeros — denormalización (Mayo 2026)

Mapa empresa·caja_nro·cajero·provincia reconstruido automáticamente al finalizar cada sync con caja_rebuild_cajeros($pdo). Permite a Tesorería evitar sub-selects feos para resolver "qué provincia es este cajero".

CREATE TABLE caja_cajeros (
  id                  INT PK AI,
  empresa             VARCHAR(20)  NOT NULL,
  caja_nro            VARCHAR(20)  NOT NULL,
  cajero              VARCHAR(100) NOT NULL,
  provincia           VARCHAR(50),
  primer_visto        DATE,
  ultimo_visto        DATE,
  dias_operados       INT DEFAULT 0,
  total_lineas_gasto  INT DEFAULT 0,
  last_sync_id        INT,
  updated_at          TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uk_empresa_caja_cajero (empresa, caja_nro, cajero),
  INDEX idx_cajero    (cajero),
  INDEX idx_provincia (provincia)
);

caja_audit_log — auditoría

Registra cada evento del sync. Helper caja_audit_log($pdo, $syncId, $evento, $tabla, $filas, $msg).

CREATE TABLE caja_audit_log (
  id          INT PK AI,
  sync_id     INT,
  evento      VARCHAR(40),  -- sync_started · raw_batch · gastos_batch · sync_completed
  tabla       VARCHAR(50),
  filas       INT,
  mensaje     TEXT,
  creado_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_sync   (sync_id),
  INDEX idx_evento (evento),
  INDEX idx_fecha  (creado_at)
);

2.6 💸 Tablas cashflow_*

cashflow_cheques_cartera (la más rica)

Estados típicos: EN CARTERA · PAGO A TERCEROS (endosado) · PAGO SIN CONFIRMAR · RECHAZADO.

Cálculo crítico: dias_a_presentar = DATEDIFF(fecha_presentacion, fecha_corte). Si < 0 = vencido sin presentar (riesgo de prescripción 30 días post-vencimiento).

2.7 📦 Tablas articulos_*

El catálogo maestro tiene 66 columnas tipadas según los tipos sugeridos por el ERP en la fila 2 del Excel. PK = codigo (INT). Columnas con índices: proveedor_id, anulado, cod_tipo_mercaderia, cod_unidad_medida.

Columnas más usadas por otros módulos

• codigo — JOIN con ventas.idArticulo (cast a UNSIGNED).
• peso — enriquece cálculo de peso/toneladas en venta.
• proveedor_id + proveedor_razon_social — proveedor real (si en venta vino mal).
• cod_tipo_mercaderia + desc_tipo_mercaderia — segmentación.
• desc_unidad_medida, bultos_x_pallet, unidad_x_bulto — logística.
• anulado — filtro de SKUs vigentes.

Tablas auxiliares (catálogos)

-- Estructura común
CREATE TABLE articulos_raw_<aux> (
  codigo       INT PRIMARY KEY,    -- VARCHAR(50) para tipos_presentacion
  descripcion  VARCHAR(255),
  updated_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

2.8 📚 Otras tablas relevantes

articulos_precios — 22 columnas lista_N

Una fila por artículo, una columna por cada lista de precios habilitada en la empresa (Delivery, Lista 1, Costo Especial, Veterinaria, …). El schema declarado en el dump tiene lista_0 a lista_21 (todas DECIMAL(14,4)); el schema definido por listas/api/_schema.php omite las listas que no existen en el ERP de ZA (2, 6, 12, 20).

articulos_agrupaciones — N:N artículo × forma de agrupar

CREATE TABLE articulos_agrupaciones (
  id_articulo       INT NOT NULL,
  id_forma_agrupar  VARCHAR(50) NOT NULL,
  des_forma_agrupar VARCHAR(100),
  id_agrupacion     VARCHAR(50),
  des_agrupacion    VARCHAR(200),
  PRIMARY KEY (id_articulo, id_forma_agrupar),
  INDEX idx_forma      (id_forma_agrupar),
  INDEX idx_agrupacion (des_agrupacion(100))
);

Usado por listas/api/precios.php para filtrar por categoría comercial (marca, accesorio, fuerza de venta, etc.).

clientes_raw — catálogo completo de clientes

~3.000 clientes con 49 columnas tipadas + datos_raw LONGTEXT con JSON validado (CHECK json_valid(datos_raw)). Usado por el módulo separado /clientes, pero podría ser cruzado por reportes en el futuro (segmentación demográfica, actividad última visita, etc.).

2.9 ⚡ Inventario de índices

Total: ~80 índices repartidos en las 33 tablas. Más críticos:

Índices propuestos (PERF)

• PERF-02 ALTER TABLE ventas ADD INDEX idx_sync_anulado (sync_id, anulado, dsArticulo) — cubre la mayoría de queries del dashboard.
• PERF-03 ALTER TABLE ventas ADD INDEX idx_sync_supervisor (sync_id, dsSupervisor) — para drill-downs.
• PERF-04 ALTER TABLE caja_raw_gastos_tipificados ADD INDEX idx_anio_rubro (YEAR(fecha_comp), rubro_id) — Finanzas filtra por año constantemente. Requiere columna calculada o usar fecha_comp directo.
• PERF-05 FULLTEXT en nombreCliente y dsArticulo para búsquedas del cross-filter.

2.10 🔗 Foreign Keys actuales y propuestas

FK declarada (sólo 1)

ALTER TABLE ventas
  ADD CONSTRAINT fk_ventas_sync
  FOREIGN KEY (sync_id) REFERENCES sincronizaciones(id) ON DELETE CASCADE;

FKs propuestas (ver §11 propuesta ARQ-04)

-- 1) caja: hacer cascade limpio en sync_id
ALTER TABLE caja_gastos                   ADD CONSTRAINT fk_cg_sync   FOREIGN KEY (sync_id) REFERENCES caja_sincronizaciones(id) ON DELETE CASCADE;
ALTER TABLE caja_raw_egresos_caja         ADD CONSTRAINT fk_rec_sync  FOREIGN KEY (sync_id) REFERENCES caja_sincronizaciones(id) ON DELETE CASCADE;
ALTER TABLE caja_raw_egresos_detalle      ADD CONSTRAINT fk_red_sync  FOREIGN KEY (sync_id) REFERENCES caja_sincronizaciones(id) ON DELETE CASCADE;
ALTER TABLE caja_raw_gastos_tipificados   ADD CONSTRAINT fk_rgt_sync  FOREIGN KEY (sync_id) REFERENCES caja_sincronizaciones(id) ON DELETE CASCADE;
ALTER TABLE caja_raw_movimiento_detalle   ADD CONSTRAINT fk_rmd_sync  FOREIGN KEY (sync_id) REFERENCES caja_sincronizaciones(id) ON DELETE CASCADE;
ALTER TABLE caja_raw_movimiento_resumido  ADD CONSTRAINT fk_rmr_sync  FOREIGN KEY (sync_id) REFERENCES caja_sincronizaciones(id) ON DELETE CASCADE;

-- 2) cashflow: idem
ALTER TABLE cashflow_cartera_clientes    ADD CONSTRAINT fk_ccc_sync FOREIGN KEY (sync_id) REFERENCES cashflow_sincronizaciones(id) ON DELETE CASCADE;
ALTER TABLE cashflow_cartera_proveedores ADD CONSTRAINT fk_ccp_sync FOREIGN KEY (sync_id) REFERENCES cashflow_sincronizaciones(id) ON DELETE CASCADE;
ALTER TABLE cashflow_cheques_cartera     ADD CONSTRAINT fk_cch_sync FOREIGN KEY (sync_id) REFERENCES cashflow_sincronizaciones(id) ON DELETE CASCADE;

-- 3) articulos: precio referencia catálogo
ALTER TABLE articulos_precios     ADD CONSTRAINT fk_ap_articulo FOREIGN KEY (id_articulo) REFERENCES articulos_raw(codigo) ON DELETE CASCADE;
ALTER TABLE articulos_agrupaciones ADD CONSTRAINT fk_ag_articulo FOREIGN KEY (id_articulo) REFERENCES articulos_raw(codigo) ON DELETE CASCADE;

2.11 ⚠️ Observaciones generales sobre la BD

Bien hecho

• ✅ InnoDB en 100% — soporta transacciones y FKs.
• ✅ utf8mb4 universal — soporta emojis y caracteres extendidos.
• ✅ Tipos nativos (DECIMAL/INT/DATE) en vez de JSON o VARCHAR — JOINs eficientes.
• ✅ AUTO_INCREMENT con UNSIGNED donde corresponde.
• ✅ Schemas con ALTER TABLE defensivos en try/catch → migraciones idempotentes sin downtime.
• ✅ ON UPDATE CURRENT_TIMESTAMP en catálogos para detectar staleness.
• ✅ UNIQUE KEY uk_mes_anio en sincronizaciones — previene duplicados.
• ✅ JSON validado (CHECK json_valid(datos_raw)) en clientes_raw.

Pendientes / mejoras

• ⚠️ Sólo 1 FK declarada (ver §2.10).
• ⚠️ Falta índice compuesto (sync_id, anulado) en ventas.
• ⚠️ CAST(idArticulo AS UNSIGNED) en JOIN inhibe uso del índice → considerar ALTER TABLE ventas MODIFY idArticulo INT.
• ⚠️ Catálogos articulos_raw_tipos_mercaderia / unidades_medida vacíos — el ERP no los exporta o no se subieron.
• ⚠️ Sin particionado (MariaDB PARTITION BY RANGE (sync_id) sería útil cuando ventas supere 10M filas).
• ⚠️ Sin vistas materializadas — todos los agregados se recalculan en cada hit.
• ⚠️ Sin CHECK constraints a nivel BD (ej. monto >= 0 en gastos no aplicaría, hay devoluciones).

Tamaño en disco estimado

Sin acceso al filesystem real del servidor, estimando por filas × longitud promedio:

El dump SQL (765 MB) está cerca del tamaño en disco — coherente.