Estructura de Directorios y Repositorio

tags:

arquitectura
python
directorios
repo
ingelcoding created: 2026-04-11 type: referencia status: activo portal: id: salidas ejecutiva: | La carpeta donde aterrizan todos los reportes generados: Excel, CSV, bases SQLite y cachés. Es el “depósito de lo producido”: cualquier pipeline termina aquí antes de subir a Sheets o alimentar Power BI. tecnica: | Directorio SALIDAS/ con estructura estable: reportes_*.xlsx por pipeline (facturación, pedidos_HES, etc.), gantt_normalizado_powerbi.csv, subdirectorio cache_df/ con DataFrames .pkl para regeneración rápida sin reprocesar correos, y subdirectorio db/ con las 5 bases SQLite del data warehouse. Pendiente: limpieza automática de archivos obsoletos y rotación de caches.

Módulos Principales

Scripts de Entrada (main_*.py) — En raíz

Script	Descripción
`main_pedidos_HES.py`	Pipeline de pedidos HES
`main_pedidos_SAP.py`	Pipeline de pedidos SAP
`main_facturacion.py`	Pipeline de facturación
`main_valorizaciones.py`	Pipeline de valorizaciones
`main_gantt.py`	Pipeline de Gantt unificado

config/ — Configuración

Script	Descripción
`config.py`	Credenciales IMAP, rangos de fechas, Google Auth; constantes de persistencia: `INCREMENTAL_OVERLAP_DAYS`, `RAW_COMPRESSION`, `KNOWN_ABVS`
`paths.py`	Rutas centralizadas (PARAMS_DIR, OUTPUT_DIR)
`auth.py`	Autenticación

core/ — Captura de Datos

Script	Descripción
`imap_client.py`	Conexión y descarga de emails
`email_parser.py`	Parser de emails (extract_sender, decode_mime_words)
`raw_loaders.py`	Carga de archivos crudos
`raw_store.py`	Almacenamiento en JSON/Parquet
`build_cloud_dataframes.py`	Lectura desde Google Drive
`processed_store.py`	Almacenamiento durable de DataFrames procesados (parquet + manifest); expone `load_processed_or_pkl()`
`incremental.py`	Cálculo de fechas incrementales y hashes de trazabilidad
`sqlite_store.py`	Registro operacional SQLite (ingeldata.db, pipeline_runs)

domains/ — Procesamiento y Lógica de Negocio

Dominio	Procesamiento	Negocio	Excel Writer	Parsers
`facturacion/`	process_facturacion_from_raw	business_facturacion	excel_writer_facturacion	parse_pdf_facturas, parse_pdf_NCred
`pedidos_hes/`	process_pedidos_HES_from_raw	business_pedidos_HES	excel_writer_pedidos_HES	parse_pedidos_HES_tables, parse_pedidos_HES_mails
`pedidos_sap/`	process_pedidos_SAP_from_raw	—	excel_writer_pedidos_SAP	parse_pedidos_SAP
`valorizaciones/`	process_valorizaciones_from_raw	business_valorizaciones	excel_writer_valorizaciones	—
`gantt/`	process_gantt, process_gantt_chiloe	—	—	download_gantt

scripts/ — Scripts de Uso Manual

Carpeta / Script	Descripción
`scripts/debug/`	debug_.py, test_.py, check_processed_files.py
`scripts/reports/`	COSTOS.py, CONTROL OTs.py, CT_SAESA_vs_ING_*.py, Comparacion_Consolidado.py
`scripts/updates/`	ACTUALIZAR_.py, fetch_.py, normalize_brigadas.py
`scripts/migrate_raw_naming.py`	Migración one-shot de naming legacy a naming canónico `{dataset}_{ABV}.parquet`

static_data/ — Datos Base

Script	Descripción
`classifiers.py`	Clasificadores de zona, área, supervisor
`base_personas.py`	Base de personas
`base_nombres_apellidos.py`	Nombres y apellidos para normalización

utils/ — Utilidades

Módulo	Descripción
`utils_text.py`	Normalización de texto, strip_accents
`utils_date.py`	Fechas, duraciones
`utils_money.py`	Limpieza de montos
`utils_excel.py`	Escritura Excel
`utils_dataframe.py`	Manipulación de DataFrames
`utils_tables.py`	Extracción de tablas HTML
`utils_html_tables.py`	Utilidades para tablas HTML
`utils_drive_read.py` / `utils_drive_write.py`	Google Drive
`patterns.py`	Expresiones regulares (PAT_HES, PAT_OT, etc.)

Estructura de Carpetas (2026-04-13)

IngelCoding/
├── main_*.py                   # Entry points en raíz
│
├── config/                     # Configuración
│   ├── __init__.py            # Re-exports públicos
│   ├── config.py              # MAILS, FECHA_DESDE, GOOGLE_AUTH
│   ├── paths.py               # load_list(), PARAMS_DIR
│   └── auth.py               # Autenticación
│
├── core/                       # Datos crudos
│   ├── __init__.py
│   ├── imap_client.py        # get_imap_ids()
│   ├── email_parser.py       # extract_sender(), decode_mime_words()
│   ├── raw_loaders.py        # Carga Excel/PDF
│   ├── raw_store.py          # persist_raw_emails()
│   ├── processed_store.py    # Parquet durable + manifest; load_processed_or_pkl()
│   ├── incremental.py        # Fechas incrementales, input_hash
│   ├── sqlite_store.py       # ingeldata.db, pipeline_runs
│   └── build_cloud_dataframes.py
│
├── domains/                    # Lógica por dominio
│   ├── __init__.py
│   ├── facturacion/
│   │   ├── __init__.py
│   │   ├── process_facturacion_from_raw.py
│   │   ├── business_facturacion.py
│   │   ├── excel_writer_facturacion.py
│   │   ├── parse_pdf_facturas.py
│   │   └── parse_pdf_NCred.py
│   ├── pedidos_hes/
│   │   ├── __init__.py
│   │   ├── process_pedidos_HES_from_raw.py
│   │   ├── business_pedidos_HES.py
│   │   ├── excel_writer_pedidos_HES.py
│   │   ├── parse_pedidos_HES_tables.py
│   │   ├── parse_pedidos_HES_tables_strats.py
│   │   ├── parse_pedidos_HES_mails.py
│   │   └── catastro_tablas_HES.py
│   ├── pedidos_sap/
│   │   ├── __init__.py
│   │   ├── process_pedidos_SAP_from_raw.py
│   │   ├── excel_writer_pedidos_SAP.py
│   │   └── parse_pedidos_SAP.py
│   ├── valorizaciones/
│   │   ├── __init__.py
│   │   ├── process_valorizaciones_from_raw.py
│   │   ├── business_valorizaciones.py
│   │   └── excel_writer_valorizaciones.py
│   └── gantt/
│       ├── __init__.py
│       ├── process_gantt.py
│       ├── process_gantt_chiloe.py
│       └── download_gantt.py
│
├── scripts/                    # Uso manual/esporádico
│   ├── __init__.py
│   ├── debug/
│   ├── reports/
│   ├── updates/
│   └── migrate_raw_naming.py  # Migración one-shot naming legacy → canónico
│
├── static_data/                # Catálogos
│   ├── __init__.py
│   ├── classifiers.py         # classify_zone(), find_area_and_sup()
│   ├── base_personas.py
│   └── base_nombres_apellidos.py
│
├── utils/                      # Utilidades genéricas
│   ├── utils_text.py
│   ├── utils_date.py
│   ├── utils_money.py
│   ├── utils_excel.py
│   ├── utils_dataframe.py
│   ├── utils_tables.py
│   ├── utils_html_tables.py
│   ├── utils_drive_read.py
│   ├── utils_drive_write.py
│   └── patterns.py
│
├── data_raw/                   # Raw acumulativo (canónico: {dataset}_{ABV}.parquet)
│   ├── emails_pedidos_HES_raw/
│   ├── emails_facturacion_raw/
│   └── ...
├── ENTRADAS/                   # No versionar
├── SALIDAS/                    # No versionar
│   ├── processed/              # Parquets curados por dominio + manifest JSON
│   │   ├── pedidos_HES/
│   │   ├── facturacion/
│   │   └── ...
│   ├── cache_df/               # Legacy: pkl (transición, será eliminado)
│   └── db/
│       ├── ingeldata.db        # BD operacional + pipeline_runs
│       └── data_warehouse.db
├── JSON/                       # No versionar
├── Parametros Base/           # Catálogos .txt/.xlsx
├── temp_*/                     # No versionar
│
├── .agent/                     # Config OpenCode
├── .github/                    # GitHub Actions
├── powerbi-calendar/          # Visual Power BI
└── BACKUPS/                   # No versionar

Proyectos Especiales

Power BI Calendar

powerbi-calendar/
├── src/
│   ├── components/       # React components
│   ├── utils/          # Helpers
│   ├── types.ts        # Tipos TypeScript
│   └── visual.ts       # Punto de entrada
└── style/              # Estilos Less