Convención de esquemas y nombres — warehouse Postgres

Regla de diseño para cuando una misma entidad de negocio existe en más de una fuente (ej. comprobantes vía MPRO vs. vía XMLs parseados directo del SAT): nunca se mezclan fuentes en el mismo schema ni en la misma tabla de raw, aunque representen “lo mismo” a nivel negocio — la fusión, si aplica, ocurre explícitamente en una capa posterior.

Convención por capa

• raw — un schema por fuente de origen: raw_<origen>.<entidad> (ej. raw_mpro.comprobante_digital, raw_xmlfiles.comprobante). Espejo fiel, sin transformar, columnas completas.
• staging (stg_<origen>__<entidad>, dentro de un schema dbt/staging) — limpieza mínima 1:1, filtro de estado activo, sin columnas de auditoría. El origen sigue siendo visible en el nombre del modelo.
• intermediate/marts (int_*, fct_*, dim_*) — aquí sí se fusionan fuentes, con lógica de conciliación explícita. Ya no expone el origen en el nombre (puede llevar una columna source_system como trazabilidad).

Reglas de conciliación al fusionar fuentes

Cada decisión de conciliación no obvia se documenta en un ADR (docs/decisions/2026-0X-conciliacion-<entidad>.md), respondiendo:

1. Prioridad de fuente — si el mismo registro existe en ambas, ¿cuál gana?
2. Registros exclusivos de una fuente — ¿se incluyen? ¿con qué bandera de origen?
3. Duplicados entre fuentes — ¿cómo se detecta que es “el mismo” registro?

Regla práctica para decidir dónde va algo

• Tal cual está en el sistema origen, sin decisiones → raw.
• Ya tiene filtro o limpieza básica pero sigue siendo de una sola fuente → staging.
• Ya se fusionó con otra fuente o tiene lógica de negocio aplicada → intermediate/marts.

Estado real vs. convención de diseño

El warehouse implementado hoy usa raw a secas (no raw_mpro) porque hasta ahora solo hay una fuente MPRO real en esa capa — el prefijo por origen se reserva para el día en que exista una segunda fuente que compita por el mismo espacio de nombres. raw_sat (XMLs CFDI parseados directo, sin pasar por MPRO) ya seguía este mismo principio en la práctica antes de que esta convención se formalizara por escrito: se separó a propósito de raw en vez de mezclarse, aunque el nombre no lleve el prefijo raw_ + origen explícito. Ningún modelo staging/intermediate/marts existe todavía — todo el trabajo de BI hoy vive en raw + lógica Python/SQL ad-hoc dentro de cada exploracion/<proyecto>, no en dbt.

Véase también

• Warehouse Postgres — inventario real de schemas y tablas al que aplica esta convención.