Instruction file imported from chayand-wil/violencia-salud-guatemala-DB (.github/instructions/Instructions.instructions.md). Copyright stays with the author.

Instrucciones del proyecto para generacion, extraccion y carga de datos.

Contexto General

Tomar en cuenta el archivo enunciado_proyecto.txt.
Gestor de base de datos: Firebird.
Pais de referencia: Guatemala.

Reglas Generales de Carga

Si un campo no esta disponible, dejarlo en blanco.
Si falta un id de catalogo, usar el id correspondiente a desconocido.
Se puede usar Faker para crear datos sinteticos cuando aplique.
Si no se incluye municipio, elegir cualquiera del catalogo del departamento informado.

Flujo de Modelado por Tipo de Archivo

Este flujo es el patron oficial de la logica del proyecto para integrar fuentes con datos incompletos.
Cuando un archivo no traiga toda la informacion, no se debe omitir el evento: se deben crear las entidades minimas del flujo para preservar la trazabilidad.
En la mayoria de archivos no se cuenta con todos los datos, por lo que se debe seguir el flujo del modelo segun el tipo de archivo fuente.
Ejemplo denuncia: crear hecho, denuncia, persona e involucramiento segun corresponda, aunque algunos atributos queden en blanco o como desconocido.
Ejemplo sindicados: crear persona involucrada, asociarla al hecho y al hecho delictivo segun el flujo definido en el modelo.
Regla general: crear las entidades relacionadas necesarias para mantener trazabilidad del evento.

Criterio de Decision para Datos Incompletos

Prioridad 1: crear el hecho/evento y su contexto de ubicacion y fecha.
Prioridad 2: crear la persona involucrada aunque sus atributos vengan parciales.
Prioridad 3: registrar la relacion persona-hecho y el tipo de involucramiento.
Prioridad 4: asociar clasificaciones del evento (tipo de hecho, delito, estado) usando homologacion y valores desconocido cuando aplique.
Resultado esperado: cada registro de fuente debe quedar representado en el modelo, aun con atributos faltantes.

Reglas de Fechas

Cuando sea necesario inventar una fecha, debe quedar dentro de los limites temporales de los datos fuente utilizados.
Las fechas deben tener logica entre si, especialmente en pares de inicio y fin.
Evitar fechas contradictorias con la cronologia del evento.

Normalizacion y Homologacion de Catalogos

Normalizar catalogos que traen variantes como desconocido, ignorado u otros equivalentes.
Los delitos pueden venir clasificados distinto en PNC, MP y OJ.
Conservar el dato original de la fuente y homologarlo a una tabla o catalogo comun del modelo.

Regla Territorial desde Catalogo de Municipios

En catalogos/municipios/municipios- depto.txt, el prefijo numerico del codigo de municipio determina su departamento (ejemplo: 1601 pertenece al departamento 16).
Para fuentes con solo departamento, usar como municipio por defecto la primera cabecera disponible del departamento segun ese catalogo (generalmente xx01).

Reglas Especificas por Fuente: Denuncias MP (VCM)

Para archivos de Denuncias registradas del MP, seguir este flujo de carga: ubicacion -> persona -> hecho -> denuncia -> involucrado_hecho -> hecho_delictivo.
En este flujo, el tipo de hecho debe mapearse al valor correspondiente a hecho_delictivo del catalogo tipo_hecho.
En hecho_delictivo, mapear el delito al valor homologado de VCM en la tabla comun de delitos del modelo.
En involucrado_hecho, mapear el tipo de involucramiento al valor Denunciante.

Campos y Reglas Minimas para MP VCM

Fecha: usar fecha_hecho y fecha_denuncia con coherencia cronologica.
Municipio: priorizar municipio del hecho; si falta, usar municipio de origen de la persona; si aun falta, aplicar regla general de municipio por departamento.
Edad: derivar de fecha_nacimiento.
Escolaridad: mapear a nivel_escolaridad.
Pueblo de pertenencia: mapear a grupo_etnico homologado.
Orientacion sexual: mapear a orientacion_sexual.
Estado de caso: mapear a estado_denuncia.

Valores por Defecto en MP VCM

Si no hay dato de estado civil o condicion alfabetica, usar desconocido.
Si no hay nombres u otros datos de identidad, se permite completar con Faker segun reglas generales.
Si no hay fecha de nacimiento, generar una fecha plausible dentro del rango de datos y consistente con la edad objetivo definida para la fuente.

Continuidad Entre Chats

Si el chat se corta, continuar desde el ultimo archivo del orden de insercion sin reiniciar cargas ya aplicadas.
Antes de cada nuevo lote, validar conteos por tabla para confirmar estado real de la DB.
Mantener idempotencia: todos los scripts de carga deben usar validaciones NOT EXISTS o reglas equivalentes para evitar duplicados.

Estado Operativo de Referencia

La tabla tipo_falta ya tiene carga de catalogo.
La tabla falta (transaccional) ya cuenta con carga inicial del archivo fuente 20240524231759eHmz6DmFKboNQ5Y3OlqNkbi9izmXULaP.xlsx (batch 101).
El involucramiento recomendado para faltas judiciales es Infractor (si la fuente no indica otro rol especifico).

Entregables Obligatorios

Entregar un archivo de insercion por cada catalogo o tabla destino.
Organizar catalogos en sql/inserts/catalogos y transaccionales en sql/inserts/transaccional.
Para lotes grandes, dividir en batches numerados por fuente (ejemplo: 100_, 101_, 102_).

Orden de Insercion para Retomar (Con Carpeta/Archivo)

ESTADO ACTUAL (17 de abril de 2026):

Batches completados: 41-54 (carga antigua hasta B54; B55 ya quedó generado con la nueva estrategia)
Estado actual de carga: B58 completado con merge visible por etapas; staging limpiada para run_id=58 [STG_ROWS=0]
Pendiente real: B59-B120 del tramo visible; el tramo amplio de Agraviados sigue con batches posteriores preparados
Batches ya preparados en disco con la nueva estrategia: 55-223
La corrida visible ya cerró B58 sin segundo plano; el siguiente paso es continuar con B59 en el mismo patrón
Estimado tiempo restante (batch 110): ~8-9 horas, dependiendo del throughput final de los loaders
Batches totales a ejecutar para batch 110: 223 batches (filas 1 a 444513)

Cambios de estrategia (últimas iteraciones):

✅ Eliminada generación sed/copy per-batch (ahora generador unificado parametrizable)
✅ Agregado pickle cache para lecturas Excel (0.71s vs 30s)
✅ Refactorizado a INSERTs directos (sin EXECUTE BLOCK per fila)
✅ Configurable CHUNK_SIZE (default 1000) para optimizar parsing SQL
✅ Todos los INSERTs con guards NOT EXISTS para idempotencia

Validaciones Minimas por Paso

Al terminar cada archivo, registrar conteos de tablas afectadas (antes/despues).
Confirmar si el archivo fue carga de catalogo o transaccional.
Si un archivo solo alimenta catalogos, marcarlo explicitamente como "solo catalogos".

Instructions

About

Contexto General

Reglas Generales de Carga

Flujo de Modelado por Tipo de Archivo

Criterio de Decision para Datos Incompletos

Reglas de Fechas

Normalizacion y Homologacion de Catalogos

Regla Territorial desde Catalogo de Municipios

Reglas Especificas por Fuente: Denuncias MP (VCM)

Campos y Reglas Minimas para MP VCM

Valores por Defecto en MP VCM

Continuidad Entre Chats

Estado Operativo de Referencia

Entregables Obligatorios

Orden de Insercion para Retomar (Con Carpeta/Archivo)

Validaciones Minimas por Paso

Use it

Manifest

Reviews