Diccionario de datos para una base de datos prototipo que evita roturas

Por qué los prototipos rompen informes y facturación tan fácilmente

Las bases de datos de prototipo cambian rápido. Añades una columna para que algo funcione, renombras un campo para que la interfaz se lea mejor o cambias un tipo de dato para parchear un error. La app sigue funcionando, así que parece seguro.

Los informes, la facturación y las exportaciones son menos indulgentes. Se basan en suposiciones silenciosas: qué incluye un importe, qué timestamp define un mes, qué significa realmente un estado. Cuando esas suposiciones cambian sin que nadie lo note, los números se desvían y nada lanza un error.

Un fallo común se ve así: un informe suma amount, pero una solución rápida cambia amount de “precio antes de impuestos” a “precio después de descuentos”. Los totales siguen sumando, pero ahora significan otra cosa. La facturación sale mal, los gráficos de ingresos dejan de coincidir y pasan semanas hasta encontrar la causa porque la base de datos está haciendo exactamente lo que le pediste.

Los prototipos son frágiles porque el significado de las columnas suele ser poco claro. Nombres como status, type, value o total pueden esconder ideas distintas en distintos lugares. El status de una tabla puede significar “factura enviada”, en otra “pago recibido” y en una tercera “suscripción activa”. Añade código generado por IA y a menudo obtendrás nombres inconsistentes, campos duplicados y lógica repartida en múltiples tablas.

La mayoría de las roturas vienen de ediciones pequeñas y “obvias":

• renombrar columnas de las que dependen dashboards o exports
• reutilizar una columna para un nuevo propósito en vez de crear una nueva
• mezclar unidades (centavos vs dólares, UTC vs hora local)
• cambiar cómo se comportan nulos o valores por defecto
• rellenar datos históricos sin seguir las reglas originales

Un diccionario de datos es la salvaguarda más simple contra esto. Es una nota en lenguaje llano para cada tabla y columna: qué representa, de dónde viene y cómo debe usarse. La meta no es documentación perfecta. Es poder cambiar el esquema sin cambiar lo que significan tus números de negocio.

Qué es un diccionario de datos (y qué no es)

Un diccionario de datos es un mapa en lenguaje claro de tu base de datos. Se enfoca en significado y reglas, no solo en estructura.

El cambio importante es pasar de “qué almacena” a “qué significa”. Una columna llamada amount puede almacenar un número, pero su significado podría ser “subtotal en centavos, antes de impuestos, en la moneda de facturación del cliente, excluyendo reembolsos”. Sin ese significado escrito, dos personas usarán el mismo campo de forma distinta y los totales no coincidirán.

Qué debería incluir

Mantenlo pequeño, pero lo bastante completo para que una persona nueva pueda hacer un cambio seguro:

• una descripción para cada tabla y columna (significado de negocio, no solo tipo)
• reglas y restricciones (requerido vs opcional, valores permitidos, redondeo, zona horaria)
• ownership (quién decide qué significa y quién aprueba cambios)
• fuentes y destinos (de dónde viene el dato y dónde se usa)
• notas sobre datos sensibles (PII, tokens, expectativas de retención)

Qué no es

Un diccionario de datos no es un diagrama ER, una lista de queries SQL ni un volcado de comentarios autogenerados del esquema. Esos ayudan, pero normalmente explican la forma, no el significado.

Tampoco es una tarea única. Tiene que moverse con tu esquema.

Dónde debería vivir

Ponlo en un lugar que la gente realmente actualice: un documento, una hoja de cálculo compartida o una página wiki. La herramienta importa menos que la consistencia. Elige un lugar, un formato y un responsable.

Trátalo como parte del cambio. Si añades una columna, renombras una o cambias cómo se calcula un valor, actualiza el diccionario el mismo día.

Empieza por las salidas de las que depende la gente

Es más fácil documentar una base de datos prototipo de afuera hacia adentro: comienza con lo que el negocio necesita hoy. Las tablas pueden cambiar semanalmente, pero las facturas, dashboards, exportaciones y correos a clientes tienden a convertirse en la “verdad” en la cabeza de las personas.

Primero, identifica quién sale perjudicado cuando cambian los números:

• finanzas se preocupa por totales, impuestos y reembolsos
• operaciones se preocupa por cumplimiento y estado de entrega
• producto se preocupa por qué hace la app en casos límite
• analytics se preocupa por definiciones y ventanas temporales
• soporte se preocupa por lo que ven los clientes y lo que pueden explicar los agentes

Luego elige unas pocas salidas críticas del negocio y trátalas como contratos escritos en palabras sencillas. Ejemplos:

• “Invoice total = sum(line items) + tax - discounts.”
• “Monthly active users excludes internal accounts.”

Esas frases se convierten en anclas para tus definiciones de tablas y columnas.

No adivines. Recoge algunos artefactos reales que tu equipo ya confíe:

• una factura o recibo pagado reciente
• un CSV export que un cliente o compañero realmente usa
• una captura de dashboard que la gente trata como “fuente de verdad”
• una plantilla de correo de soporte que incluye números (fin de prueba, importe adeudado)
• una respuesta de API de ejemplo que usa otro sistema

Elige un alcance inicial pequeño: las 5–10 tablas que alimentan dinero y métricas centrales. Si puedes trazar “Subtotal”, “Tax” y “Total” de una factura hasta la query exacta que los calcula, ya encontraste el conjunto inicial.

Qué documentar por cada tabla y columna

Empieza con lo que tu base de datos ya sabe y luego añade el significado humano que evita que arreglos “pequeños” rompan informes, facturación o exportaciones.

Para cada tabla

Escribe una frase propósito que elimine ambigüedad.

Ejemplo: invoices almacena una fila por factura de cliente, no por intento de pago.

Esa línea ahorra horas cuando alguien une la tabla equivocada o asume la granularidad incorrecta.

Para cada columna

Captura dos capas:

• Hechos de esquema: tipo, nullable, default y si es único o indexado.
• Significado en lenguaje llano: qué representa, más 2-3 valores de ejemplo.

Luego añade las reglas que mantienen los números estables:

• Reglas de dato: valores permitidos, unidades, redondeo y supuestos de zona horaria.
• Linaje: de dónde viene, quién lo escribe y cuándo se actualiza.
• Notas de privacidad: si contiene PII y qué no debe exportarse nunca.

Las reglas de dato son donde los prototipos esconden las peores minas:

• Si tienes amount, di dólares o centavos, moneda y redondeo.
• Si tienes created_at, especifica la zona horaria y si la establece la app o la BD.
• Si tienes status, lista valores permitidos y qué significa cada uno.

El linaje importa aún más en prototipos desordenados. Una columna puede ser escrita por un job en segundo plano, un webhook o un formulario del cliente. Si nadie puede responder “qué crea este valor”, los informes derivarán.

Finalmente, marca la privacidad claramente. Señala email, dirección, IP y cualquier token o secreto, y anota qué no debe aparecer en exportaciones.

Una plantilla simple de diccionario de datos que puedes reutilizar

Elige un formato que realmente mantendrás. Para prototipos pequeños, una hoja de cálculo es suficiente: una pestaña por tabla o una sola pestaña donde las filas se agrupan por nombre de tabla.

Un diccionario útil te ayuda a responder dos preguntas rápido:

• ¿Qué significa este campo?
• ¿Qué se romperá si cambia?

Plantilla (copiar/pegar)

Usa el mismo conjunto de columnas para cada tabla, incluso si algunas celdas quedan vacías al principio:

Table:

| Column | Type | Null? | Description | Example | Key/Relation | Used by (report/billing/export) | Owner | Notes / Warnings |
|--------|------|-------|-------------|---------|--------------|----------------------------------|-------|------------------|
| id     | uuid | no    | Primary identifier for this row | 8f... | PK | internal joins | Eng | DO NOT CHANGE format |

En “Key/Relation”, escribe pistas simples de join, no ensayos. Ejemplo: “FK -> users.id (many invoices belong to one user).”

Si una relación solo está implícita en código (común en prototipos generados por IA), documéntala como “logical FK” para que la próxima persona no la pase por alto.

Añade advertencias solo donde importen. Si una columna alimenta totales de factura, impuestos, reportes de ingresos o una exportación hacia el cliente, márcala claramente (por ejemplo, “alimenta totales de facturas - no cambies nombre/tipo sin actualizar exportaciones”).

Reglas de nomenclatura que evitan confusión

No necesitas una guía enorme de estilo. Unas pocas convenciones consistentes evitan la mayor parte de la deriva del esquema:

• elige nombres de tabla singulares o plurales y apégate a ello
• escoge un formato de clave primaria (id o <table>_id) y mantenlo consistente
• nombra claves foráneas referenced_table_id (ejemplo: customer_id)
• almacena dinero en centavos enteros cuando sea posible (ejemplo: amount_cents) y documenta el redondeo
• estandariza timestamps (created_at, updated_at) y documenta la zona horaria

Crea la primera versión en una tarde

No necesitas un doc perfecto. Necesitas algo que impida romper dinero y métricas.

1) Exporta el esquema que ya tienes

Lista cada tabla y columna tal como existen hoy. La mayoría de bases de datos y ORMs pueden producir esto rápido (UI de admin, archivo de esquema, volcado SQL). Pégalo en una hoja o doc, una fila por columna.

Haz un triage rápido y marca las tablas que tocan:

• invoices, payments, subscriptions, discounts, refunds
• dashboards de métricas e informes semanales
• cualquier export CSV o integración que salga de tu sistema

Si no estás seguro, busca en el código “invoice”, “total”, “export”, “report” y “balance” y anota qué tablas tocan esas queries.

2) Rellena significado y reglas, empezando por el dinero

Escribe definiciones para los campos que impulsan totales y cambios de estado. Comienza por moneda y tiempo porque los malentendidos pequeños crean problemas grandes.

Concéntrate primero en:

• campos de importe (moneda, si el impuesto está incluido, centavos vs decimales)
• campos de estado (valores permitidos y significado exacto)
• timestamps (qué evento representan y la zona horaria)
• claves foráneas (qué significa la relación en la vida real)
• identificadores (qué es visible para el usuario y qué es interno)

Pon la regla junto a la columna, no en una sección separada de “reglas”.

Ejemplos:

• “invoice.status = paid solo después de que el pago esté capturado, no cuando se intentó.”
• “line_item.amount_cents excluye descuentos; discount_cents es separado.”

Luego valídalo con una persona no técnica que dependa de los números (finanzas u operaciones). Recorre un escenario real: “Si un cliente recibe un reembolso, qué columnas cambian y qué informe debe seguir coincidiendo?” Ajusta la redacción hasta que estén de acuerdo.

Mantén un pequeño registro de cambios (fecha, qué cambió, por qué) y asigna un responsable de revisión.

Vincula columnas a métricas, facturas y exportaciones

Un diccionario es más valioso cuando protege las salidas de las que depende la gente. Cada métrica clave, línea de factura y columna de exportación debe apuntar a los campos exactos que la producen.

Para cada salida “que no puede fallar” (MRR, facturas pagadas, saldo pendiente, suscriptores activos, exportaciones a clientes), captura:

• qué significa (una frase que un compañero no técnico entienda)
• la regla temporal (fecha de factura vs fecha de pago, y qué zona horaria)
• los filtros (valores de status incluidos, cuentas de prueba excluidas)
• dependencias (lista table.column, incluyendo claves de join)
• la “fuente de verdad” cuando los valores discrepen

Sé explícito cuando el esquema ofrece dos fuentes en competencia. Si reporting puede usar payments.amount o invoices.paid_amount, decide cuál gana y escribe si la otra es derivada (se puede recalcular) o autoritativa (no debe sobrescribirse).

Documenta casos límite que suelen causar desajustes:

• reembolsos como pagos negativos vs filas separadas de refund
• pagos parciales y múltiples pagos por factura
• suscripciones canceladas que aún facturan hasta el fin de periodo
• facturas con fechas retroactivas o datos históricos migrados
• clientes duplicados creados por flujos mágicos de registro

No necesitas pegar SQL por todas partes. Registrar la lógica en palabras suele ser suficiente:

• “Suma payments donde status es succeeded, agrupado por mes de factura, excluyendo refunds, usando paid_at.”

Errores comunes que llevan a sorpresas costosas

Las bases de datos prototipo “funcionan” porque la app es indulgente. La sorpresa llega después, cuando un cambio pequeño rompe un informe, un total de factura o un CSV que un cliente usa.

Renombrar sin comprobar usos downstream

La app puede seguir ejecutándose, pero hojas de finanzas, dashboards de BI y scripts de exportación pueden seguir buscando el nombre antiguo.

Campos de dinero vagos

Una columna llamada amount puede significar centavos o dólares, neto o bruto, antes o después de impuestos, con o sin reembolsos. Si nadie lo escribe, acabarás discutiendo por qué no coinciden los totales.

Timestamps mezclados

Los prototipos suelen mezclar created_at, paid_at, fulfilled_at y “cuando terminó el job” en el mismo gráfico. Si un informe agrupa por tiempo de creación y otro por tiempo de pago, los números de fin de mes pueden oscilar.

Tipos de ID inconsistentes

Si customer_id es string en una tabla y entero en otra, los joins fallan, aparecen duplicados y las exportaciones pierden filas.

“Status” convirtiéndose en cajón de sastre

Se añaden valores nuevos en horas críticas y nadie documenta qué significan. Luego alguien filtra el conjunto equivocado de status y cambia una métrica en silencio.

Si quieres un conjunto rápido de “olores” para marcar antes de desplegar un cambio:

• cambió el nombre de una columna pero no se verificaron informes/exports
• los campos de dinero no especifican moneda ni si incluyen impuestos
• existen varios timestamps pero solo se usa uno “porque estaba ahí”
• los IDs no comparten el mismo tipo entre tablas
• los valores de status no están listados con significado en lenguaje llano

Lista rápida antes de cambiar la base de datos

Antes de renombrar una columna o “añadir solo un campo más”, para y verifica las partes que mantienen correctos el dinero y los informes.

• Las tablas de facturación tienen responsable. Si una tabla afecta facturas, pagos, suscripciones, descuentos o reembolsos, alguien responde por su significado y por cuándo debe cambiar.
• Cada columna de dinero es inequívoca. Documenta moneda, precisión (¿centavos?), y si es neto o bruto. Anota si incluye impuestos, tasas o créditos.
• Cada campo temporal declara el evento y la zona horaria. “created_at” puede significar cuando se insertó la fila, cuando el usuario clicó “Pagar” o cuando el dinero se liquidó. Elige un significado y documéntalo.
• Se señalan los joins principales. Lista los joins “camino dorado” usados en reporting (por ejemplo: invoices -> invoice_items -> customers).
• Las exportaciones detallan contratos. Si una exportación espera fechas ISO, centavos enteros o nombres de columnas específicos, anótalo para que un refactor no rompa herramientas downstream.

Mantén un registro simple de cambios que responda:

• qué cambió (esquema y definición)
• quién lo cambió y cuándo
• por qué cambió y qué salidas re-verificar

Un ejemplo pequeño: renombrar paid_at a paid_on puede parecer inofensivo, pero puede romper una exportación contable o cambiar métricas de “pagado hoy” si el nuevo campo empieza a almacenar otro evento.

Ejemplo: arreglar un esquema de facturación desordenado sin romper totales

Un problema común en prototipos: una app creada por IA tiene invoices y una tabla transactions, pero nadie sabe qué significa cada campo. Ves columnas como amount, total, fee, status, type, notes y meta. Los informes parecen bien hasta que “limpias” el esquema y los totales de facturas, impuestos o reembolsos dejan de coincidir con lo que pagaron los clientes.

Empieza pequeño: céntrate solo en facturación. Elige una factura que sepas que es correcta (el importe que pagó el cliente coincide con tu procesador de pagos). Rastrea cómo se calculó el total en la UI y luego escribe el significado de cada columna implicada.

Aclara qué impulsa realmente los totales

Sé explícito sobre la fuente de verdad y las convenciones de signo:

• transactions.gross_amount_cents: cargo completo antes de descuentos y reembolsos (documenta moneda y redondeo).
• transactions.tax_cents: porción de impuesto, y si está incluida en gross o se añade aparte.
• transactions.discount_cents: descuentos aplicados en el momento del cargo, no después.
• transactions.refund_cents: reembolsos registrados como centavos positivos (o filas negativas). Elige una regla y documéntala.
• invoices.total_cents: define la fórmula (gross - discount - refunds + tax) y las filas exactas que suma.

Una vez escritos esos significados, un “pequeño refactor” como renombrar amount a total ya no podrá hacerse a la ligera. Si alguien cambia tipos (centavos a dólares), invierte signos o filtra por otro status, verás inmediatamente qué informes y facturas cambiarán.

Documenta una exportación de extremo a extremo

Elige un CSV que finanzas o una agencia realmente use. Escribe columnas esperadas, formatos y supuestos. Ejemplo:

• invoice_number (string)
• issued_at (fecha ISO)
• subtotal_cents (entero)
• tax_cents (entero)
• total_cents (entero)
• si los reembolsos aparecen como filas separadas

Aquí salen a la luz roturas ocultas. Herramientas downstream suelen esperar centavos, nombres de columna estables y manejo consistente de reembolsos. Un diccionario te fuerza a mantener esos contratos.

Si el esquema es desordenado o inseguro para tocar (joins poco claros, monedas inconsistentes, datos sensibles en lugares equivocados), pausa el refactor y haz un plan antes de cambiar nada.

Siguientes pasos: mantenlo actualizado y pide ayuda cuando el prototipo se resista

Un diccionario de datos solo te protege si se mantiene vigente. La regla más simple funciona bien: ningún cambio de esquema se despliega hasta que la entrada del diccionario esté actualizada.

Mantén definiciones accesibles para compañeros no técnicos. Apunta a una frase, un significado. Si una columna significa dos cosas según la pantalla o el flujo, asume que reporting o facturación ya son inconsistentes.

Añade una revisión ligera para cambios de alto riesgo

No necesitas un proceso enorme, pero sí un botón de pausa para todo lo que toque dinero o métricas clave.

Antes de mergear un cambio que afecte facturación o reporting, confirma:

• la entrada del diccionario fue actualizada (tabla, columna, significado, ejemplo)
• se identificaron informes/exports/cálculos de factura dependientes
• los valores viejos se manejan (plan de migración o comportamiento por defecto)
• alguien es responsable de la definición (un nombre, no solo “engineering”)

Si heredaste un prototipo generado por IA y no estás seguro de qué es seguro cambiar, una auditoría breve puede ahorrar días de ida y vuelta. FixMyMess (fixmymess.ai) realiza diagnóstico y reparaciones de codebases creadas por IA, y ofrece una auditoría de código gratuita para mapear problemas en facturación, reporting y lógica de base de datos antes de tocar datos de producción.