Datenwörterbuch für eine Prototyp-Datenbank, das Ausfälle verhindert

Warum Prototypen Reporting und Abrechnung so leicht kaputt machen

Prototyp-Datenbanken ändern sich schnell. Sie fügen eine Spalte hinzu, damit etwas funktioniert, benennen ein Feld um, damit die UI besser lesbar ist, oder wechseln den Datentyp, um einen Fehler zu beheben. Die App läuft weiter, deshalb wirkt alles sicher.

Reporting, Abrechnung und Exporte sind weniger nachsichtig. Sie beruhen auf stillen Annahmen: was ein Betrag einschließt, welcher Zeitstempel einen Monat definiert, was ein Status wirklich bedeutet. Wenn diese Annahmen sich ändern, ohne dass es jemand merkt, driftet die Zahl und es gibt keinen Fehler.

Ein typischer Fehler sieht so aus: Ein Report summiert amount, aber ein schneller Fix ändert amount von „Preis vor Steuern“ zu „Preis nach Rabatten“. Die Summen stimmen weiterhin, aber die Bedeutung ist eine andere. Rechnungen sind falsch, Umsatzdiagramme passen nicht mehr zusammen, und es dauert Wochen, die Ursache zu finden — weil die Datenbank genau das tut, was sie soll.

Prototypen sind fragil, weil die Bedeutung von Spalten oft unklar ist. Namen wie status, type, value oder total können an verschiedenen Stellen unterschiedliche Dinge verbergen. In einer Tabelle bedeutet status „Rechnung gesendet“, in einer anderen „Zahlung empfangen“ und in einer dritten „Abo aktiv“. Mit KI-generiertem Code kommen oft inkonsistente Benennungen, doppelte Felder und Logik, die über mehrere Tabellen verteilt ist.

Die meisten Ausfälle entstehen durch kleine, „offensichtliche“ Änderungen:

• Spalten umbenennen, auf die Dashboards oder Exporte angewiesen sind
• eine Spalte für einen neuen Zweck wiederverwenden statt eine neue zu erstellen
• Einheiten mischen (Cents vs Dollar, UTC vs lokale Zeit)
• ändern, wie Nullwerte oder Defaults behandelt werden
• Daten backfillen ohne die ursprünglichen Regeln zu beachten

Ein Datenwörterbuch ist die einfachste Leitplanke dagegen. Es ist eine Notiz in Alltagssprache für jede Tabelle und Spalte: was sie repräsentiert, woher sie kommt und wie sie verwendet werden sollte. Das Ziel ist nicht perfekte Dokumentation, sondern die Möglichkeit, das Schema zu ändern, ohne die Bedeutung Ihrer Geschäftszahlen zu ändern.

Was ein Datenwörterbuch ist (und was nicht)

Ein Datenwörterbuch ist eine Karte Ihrer Datenbank in einfacher Sprache. Es konzentriert sich auf Bedeutung und Regeln, nicht nur auf Struktur.

Die wichtige Verschiebung ist, von „was es speichert“ zu „was es bedeutet“ zu wechseln. Eine Spalte namens amount speichert vielleicht eine Zahl, ihre Bedeutung könnte aber „Zwischensumme in Cents, vor Steuern, in der Rechnungswährung des Kunden, ohne Rückerstattungen“ sein. Ohne diese Bedeutung schriftlich hat dieselbe Spalte zwei Nutzer, die sie unterschiedlich verwenden, und Summen passen nicht zusammen.

Was es enthalten sollte

Halten Sie es klein, aber vollständig genug, damit eine neue Person eine sichere Änderung vornehmen kann:

• eine Beschreibung für jede Tabelle und Spalte (geschäftliche Bedeutung, nicht nur Typ)
• Regeln und Einschränkungen (Pflicht vs optional, erlaubte Werte, Rundung, Zeitzone)
• Besitz (wer entscheidet, was es bedeutet und wer Änderungen genehmigt)
• Quellen und Ziele (woher die Daten kommen und wo sie benutzt werden)
• Hinweise zu sensiblen Daten (PII, Tokens, Aufbewahrungserwartungen)

Was es nicht ist

Ein Datenwörterbuch ist kein ER-Diagramm, keine Liste von SQL-Abfragen und kein Dump automatisch generierter Schema-Kommentare. Diese können helfen, erklären aber meist die Form, nicht die Bedeutung.

Es ist auch keine einmalige Aufgabe. Es muss mit Ihrem Schema mitgehen.

Wo es liegen sollte

Legen Sie es dorthin, wo Leute es auch tatsächlich aktualisieren: ein Doc, ein geteiltes Spreadsheet oder eine Wiki-Seite. Das Tool ist weniger wichtig als Konsistenz. Wählen Sie einen Ort, ein Format und einen Owner.

Behandeln Sie es als Teil der Änderung. Wenn Sie eine Spalte hinzufügen, umbenennen oder ändern, wie ein Wert berechnet wird, aktualisieren Sie das Wörterbuch am selben Tag.

Von den Outputs ausgehen, auf die Leute angewiesen sind

Eine Prototyp-Datenbank dokumentiert man am einfachsten von außen nach innen: beginnen Sie mit dem, worauf das Geschäft heute angewiesen ist. Tabellen können wöchentlich wechseln, aber Rechnungen, Dashboards, Exporte und Kunden-E-Mails werden in den Köpfen der Leute schnell zur „Wahrheit“.

Identifizieren Sie zuerst, wer betroffen ist, wenn Zahlen sich ändern:

• Finance kümmert sich um Summen, Steuern und Rückerstattungen
• Ops kümmert sich um Fulfillment und Lieferstatus
• Produkt kümmert sich darum, was die App in Edge-Cases macht
• Analytics kümmert sich um Definitionen und Zeitfenster
• Support kümmert sich darum, was Kunden sehen und was Agenten erklären können

Wählen Sie dann einige geschäftskritische Outputs und behandeln Sie jeden wie einen Vertrag, in einfachen Worten formuliert. Beispiele:

• „Invoice total = sum(line items) + tax - discounts.“
• „Monthly active users schließt interne Accounts aus.“

Diese Sätze werden zu Ankern für Ihre Tabellen- und Spaltendefinitionen.

Raten Sie nicht. Sammeln Sie ein paar reale Artefakte, denen Ihr Team vertraut:

• eine kürzlich bezahlte Rechnung oder Quittung
• eine CSV-Exportdatei, die ein Kunde oder Kollege tatsächlich nutzt
• einen Dashboard-Screenshot, den Leute als „Quelle der Wahrheit“ betrachten
• eine Support-E-Mail-Vorlage, die Zahlen enthält (Probe endet, fälliger Betrag)
• eine Beispiel-API-Antwort, die von einem anderen System genutzt wird

Wählen Sie einen kleinen ersten Umfang: die 5–10 Tabellen, die Geld und Kernmetriken speisen. Wenn Sie „Subtotal“, „Tax“ und „Total“ auf einer Rechnung bis zur exakten Abfrage zurückverfolgen können, die sie berechnet, haben Sie Ihren Startpunkt gefunden.

Was für jede Tabelle und Spalte dokumentiert werden sollte

Beginnen Sie mit dem, was Ihre Datenbank bereits weiß, und fügen Sie dann die menschliche Bedeutung hinzu, die verhindert, dass „kleine“ Fixes Reporting, Abrechnung oder Exporte brechen.

Für jede Tabelle

Schreiben Sie einen Ein-Satz-Zweck, der Mehrdeutigkeiten beseitigt.

Beispiel: invoices speichert eine Zeile pro Kundenrechnung, nicht pro Zahlungsversuch.

Diese eine Zeile spart später Stunden, wenn jemand die falsche Tabelle verbindet oder die falsche Granularität annimmt.

Für jede Spalte

Erfassen Sie zwei Ebenen:

• Schema-Fakten: Typ, nullable, Default und ob sie einzigartig oder indexiert ist.
• Einfache Bedeutung: was sie repräsentiert, plus 2–3 Beispielwerte.

Dann fügen Sie die Regeln hinzu, die Zahlen stabil halten:

• Datenregeln: erlaubte Werte, Einheiten, Rundung und Zeitzonenannahmen.
• Lineage: woher es kommt, wer es schreibt und wann es aktualisiert wird.
• Privacy-Hinweise: ob es PII enthält und was niemals exportiert werden darf.

Datenregeln sind dort, wo Prototypen die schlimmsten Landminen verbergen:

• Wenn Sie amount haben, sagen Sie Dollar oder Cents, Währung und Rundung.
• Wenn Sie created_at haben, geben Sie die Zeitzone an und ob die App oder die DB sie setzt.
• Wenn Sie status haben, listen Sie erlaubte Werte und erklären Sie, was jeder Wert bedeutet.

Lineage ist in unordentlichen Prototypen noch wichtiger. Eine Spalte könnte von einem Hintergrundjob, einem Webhook oder einem clientseitigen Formular geschrieben werden. Wenn niemand beantworten kann “was erzeugt diesen Wert?”, driften Reports.

Markieren Sie schließlich Datenschutz klar. Kennzeichnen Sie Email, Adresse, IP und jegliche Tokens oder Secrets und notieren Sie, was niemals in Exporte darf.

Eine einfache Datenwörterbuch-Vorlage, die Sie wiederverwenden können

Wählen Sie ein Format, das Sie tatsächlich pflegen werden. Für kleine Prototypen reicht ein Spreadsheet: entweder ein Tab pro Tabelle oder ein einzelnes Tab, in dem Zeilen nach Tabellen gruppiert sind.

Ein nützliches Datenwörterbuch hilft schnell zwei Fragen zu beantworten:

• Was bedeutet dieses Feld?
• Was bricht, wenn es sich ändert?

Vorlage (kopieren/einfügen)

Verwenden Sie für jede Tabelle dasselbe Set an Spalten, auch wenn manche Zellen zunächst leer sind:

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 |

In “Key/Relation” schreiben Sie einfache Join-Hinweise, keine Essays. Beispiel: “FK -> users.id (many invoices belong to one user).”

Wenn eine Beziehung nur implizit im Code ist (häufig in KI-generierten Prototypen), dokumentieren Sie sie trotzdem als “logical FK”, damit die nächste Person sie nicht übersieht.

Fügen Sie Warnhinweise nur dort hinzu, wo sie relevant sind. Wenn eine Spalte Rechnungs-Totale, Steuern, Revenue-Reports oder einen kundenorientierten Export speist, kennzeichnen Sie sie deutlich (z. B. “speist Rechnungssummen – Name/Typ nicht ändern ohne Exporte zu aktualisieren”).

Namensregeln, die Verwirrung verhindern

Sie brauchen keinen riesigen Style-Guide. Einige konsistente Konventionen verhindern den Großteil der Schema-Drift:

• wählen Sie singuläre oder plurale Tabellennamen und halten Sie sich daran
• wählen Sie ein Primary-Key-Format (id oder <table>_id) und bleiben Sie konsistent
• benennen Sie Foreign Keys als <referenced_table>_id (z. B. customer_id)
• speichern Sie Geld als ganze Cents, wenn möglich (z. B. amount_cents) und dokumentieren Sie Rundung
• standardisieren Sie Timestamps (created_at, updated_at) und dokumentieren Sie die Zeitzone

Erstellen Sie die erste Version an einem Nachmittag

Sie brauchen kein perfektes Dokument. Sie brauchen etwas, das Sie davor bewahrt, Geld und Metriken zu zerschießen.

1) Exportieren Sie das Schema, das Sie bereits haben

Listen Sie jede Tabelle und Spalte so auf, wie sie heute existiert. Die meisten Datenbanken und ORMs können das schnell erzeugen (Admin-UI, Schema-Datei, SQL-Dump). Fügen Sie es in ein Spreadsheet oder Doc ein, eine Zeile pro Spalte.

Führen Sie ein schnelles Triage durch und markieren Sie die Tabellen, die betreffen:

• invoices, payments, subscriptions, discounts, refunds
• Metrik-Dashboards und wöchentliche Reports
• jeder CSV-Export oder jede Integration, die Ihr System verlässt

Wenn Sie unsicher sind, suchen Sie im Code nach “invoice”, “total”, “export”, “report” und “balance” und notieren Sie, welche Tabellen diese Abfragen treffen.

2) Füllen Sie Bedeutung und Regeln aus, beginnend mit Geld

Schreiben Sie Definitionen für Felder, die Totale und Statusänderungen antreiben. Beginnen Sie mit Währung und Zeit, denn kleine Missverständnisse erzeugen große Probleme.

Konzentrieren Sie sich zuerst auf:

• Betragsfelder (Währung, ob Steuer enthalten, Cents vs Dezimal)
• Statusfelder (erlaubte Werte und genaue Bedeutung)
• Timestamps (welches Ereignis sie repräsentieren und die Zeitzone)
• Fremdschlüssel (was die Beziehung im realen Leben bedeutet)
• Identifikatoren (öffentlich sichtbar vs intern)

Setzen Sie die Regel direkt neben die Spalte, nicht in einen separaten “Regeln”-Abschnitt.

Beispiele:

• “invoice.status = paid erst nachdem die Zahlung erfasst wurde, nicht bei Zahlungsversuch.”
• “line_item.amount_cents schließt Rabatte aus; discount_cents ist separat.”

Validieren Sie das dann mit einer nicht-technischen Person, die von den Zahlen abhängt (Finance oder Ops). Gehen Sie ein reales Szenario durch: “Wenn ein Kunde eine Rückerstattung erhält, welche Spalten ändern sich und welcher Report muss immer noch übereinstimmen?” Formulieren Sie so lange, bis sie zustimmen.

Führen Sie ein kleines Changelog (Datum, was geändert wurde, warum) und benennen Sie einen Reviewer.

Verknüpfen Sie Spalten mit Metriken, Rechnungen und Exporten

Ein Wörterbuch ist am wertvollsten, wenn es die Outputs schützt, auf die sich Menschen verlassen. Jede wichtige Metrik, Rechnungszeile und Export-Spalte sollte auf die exakten Felder verweisen, die sie erzeugen.

Für jeden “darf nicht falsch sein”-Output (MRR, bezahlte Rechnungen, ausstehender Saldo, aktive Abonnenten, Kunden-Exporte) erfassen Sie:

• was es bedeutet (ein Satz, dem eine nicht-technische Kollegin zustimmen würde)
• die Zeitregel (Rechnungsdatum vs Zahlungsdatum und welche Zeitzone)
• die Filter (inkludierte Statuswerte, Testkonten ausgeschlossen)
• Abhängigkeiten (Tabelle.Spalte Liste, inklusive Join-Keys)
• die “Quelle der Wahrheit”, wenn Werte widersprüchlich sind

Seien Sie explizit, wenn das Schema zwei konkurrierende Quellen bietet. Wenn Reporting entweder payments.amount oder invoices.paid_amount verwenden könnte, entscheiden Sie, welche Quelle gewinnt, und schreiben Sie dazu, ob die andere abgeleitet (neu berechnet) oder autoritativ (darf nicht überschrieben werden) ist.

Dokumentieren Sie Edge-Cases, die oft Abweichungen verursachen:

• Rückerstattungen als negative Zahlungen vs separate Refund-Zeilen
• Teilzahlungen und mehrere Zahlungen pro Rechnung
• stornierte Abos, die bis zum Periodenende noch abrechnen
• rückdatierte Rechnungen oder migrierte historische Daten
• doppelte Kunden, erzeugt durch „magische“ Sign-up-Flows

Sie müssen nicht überall SQL einfügen. Logik in Worten reicht meist aus:

• “Summiere Zahlungen, bei denen status succeeded ist, gruppiert nach Rechnungsmonat, exklusive Rückerstattungen, using paid_at.”

Häufige Fehler, die teuer werden können

Prototyp-Datenbanken “funktionieren”, weil die App nachsichtig ist. Die Überraschung kommt später, wenn eine kleine Änderung einen Report, eine Rechnungssumme oder einen CSV-Export bricht, den ein Kunde erwartet.

Umbenennen ohne Downstream-Checks

Die App läuft vielleicht weiter, aber Finance-Sheets, BI-Dashboards und Export-Skripte suchen noch nach dem alten Namen.

Vage Geldfelder

Eine Spalte namens amount kann Cents oder Dollar bedeuten, netto oder brutto, vor oder nach Steuern, Rückerstattungen enthalten oder nicht. Wenn niemand das notiert, streiten Sie später über “warum die Summen nicht zusammenpassen”.

Gemischte Zeitstempel

Prototypen mischen oft created_at, paid_at, fulfilled_at und “wann der Job fertig war” in demselben Chart. Wenn ein Report nach Erstellungszeit gruppiert und ein anderer nach Zahlungszeit, schwanken Monatszahlen.

Inkonsistente ID-Typen

Wenn customer_id in einer Tabelle ein String und in einer anderen ein Integer ist, schlagen Joins fehl, Duplikate erscheinen und Exporte fehlen Zeilen.

„Status“ wird zur Müllhalde

Neue Werte werden in hektischen Momenten hinzugefügt und niemand dokumentiert die Bedeutung. Später filtert jemand nach dem falschen Status-Set und ändert stillschweigend eine Metrik.

Wenn Sie schnell nach Gerüchen suchen wollen, bevor Sie eine Änderung ausliefern:

• ein Spaltenname wurde geändert, aber Reports/Exporte wurden nicht geprüft
• Geldfelder geben keine Währung oder Auskunft, ob Steuer enthalten ist
• mehrere Timestamps existieren, aber nur einer wird „weil er da war“ benutzt
• IDs haben in verschiedenen Tabellen unterschiedliche Typen
• Statuswerte sind nicht mit einfacher Bedeutungsliste dokumentiert

Schnelle Checkliste, bevor Sie die Datenbank ändern

Bevor Sie eine Spalte umbenennen oder “nur noch ein Feld hinzufügen”, pausieren Sie und verifizieren Sie die Teile, die Geld und Reporting schützen.

• Abrechnungstabellen haben Owner. Wenn eine Tabelle Rechnungen, Zahlungen, Abos, Rabatte oder Rückerstattungen beeinflusst, ist jemand verantwortlich für die Bedeutung und den Zeitpunkt von Änderungen.
• Jedes Geldfeld ist eindeutig. Dokumentieren Sie Währung, Genauigkeit (Cents?), und ob es netto oder brutto ist. Notieren Sie, ob Steuern, Gebühren oder Gutschriften enthalten sind.
• Jedes Zeitfeld benennt Ereignis und Zeitzone. “created_at” kann den Moment des Einfügens, den Klick auf “Pay” oder den Abschluss einer Buchung meinen. Wählen und dokumentieren Sie eine Bedeutung.
• Wichtige Joins sind genannt. Listen Sie die “goldene Pfad”-Joins, die im Reporting verwendet werden (z. B. invoices -> invoice_items -> customers).
• Exporte legen Verträge fest. Wenn ein Export ISO-Daten, Integer-Cents oder bestimmte Spaltennamen erwartet, schreiben Sie das auf, damit ein Refactor downstream-Tools nicht bricht.

Führen Sie ein einfaches Changelog, das beantwortet:

• was sich geändert hat (Schema und Definition)
• wer es wann geändert hat
• warum es geändert wurde und welche Outputs nachgeprüft werden müssen

Ein kleines Beispiel: paid_at in paid_on umzubenennen wirkt harmlos, kann aber einen Accounting-Export brechen oder “heute bezahlt”-Metriken verschieben, wenn das neue Feld ein anderes Ereignis speichert.

Beispiel: ein unordentliches Abrechnungsschema reparieren, ohne Summen zu brechen

Ein häufiges Prototyp-Problem: Eine KI-erstellte App hat invoices und eine transactions-Tabelle, aber niemand kann sagen, was jedes Feld bedeutet. Sie sehen Spalten wie amount, total, fee, status, type, notes und meta. Reporting sieht zunächst korrekt aus, bis Sie das Schema “aufräumen” und Rechnungs-Totale, Steuern oder Rückerstattungen nicht mehr mit dem übereinstimmen, was Kunden bezahlt haben.

Fangen Sie klein an: Konzentrieren Sie sich nur auf Abrechnung. Wählen Sie eine Rechnung, von der Sie wissen, dass sie korrekt ist (der vom Kunden gezahlte Betrag stimmt mit Ihrem Zahlungsanbieter überein). Verfolgen Sie, wie die UI-Summe berechnet wurde, und schreiben Sie dann die Bedeutung jeder beteiligten Spalte auf.

Klären Sie, was wirklich Totale antreibt

Seien Sie explizit über die Quelle der Wahrheit und Vorzeichen:

• transactions.gross_amount_cents: voller Charge vor Rabatten und Rückerstattungen (Währung und Rundung dokumentieren).
• transactions.tax_cents: Steueranteil und ob er im Brutto enthalten ist oder ob er oben drauf gerechnet wird.
• transactions.discount_cents: zum Zeitpunkt der Belastung angewendete Rabatte, nicht nachträglich.
• transactions.refund_cents: Rückerstattungen als positive Cents (oder als negative Zeilen). Wählen Sie eine Konvention und dokumentieren Sie sie.
• invoices.total_cents: definieren Sie die Formel (gross - discount - refunds + tax) und welche Zeilen genau summiert werden.

Wenn diese Bedeutungen aufgeschrieben sind, kann ein “kleiner Refactor” wie amount in total umzubenennen nicht mehr beiläufig passieren. Ändert jemand Typen (Cents zu Dollar), Vorzeichen oder filtert nach anderem status, sehen Sie sofort, welche Reports und Rechnungen betroffen sind.

Dokumentieren Sie einen Export Ende-zu-Ende

Wählen Sie einen CSV-Export, den Finance oder eine Agentur tatsächlich nutzt. Schreiben Sie erwartete Spalten, Formate und Annahmen auf. Beispiel:

• invoice_number (string)
• issued_at (ISO date)
• subtotal_cents (integer)
• tax_cents (integer)
• total_cents (integer)
• ob Rückerstattungen als separate Zeilen erscheinen

Hier zeigen sich versteckte Brüche. Downstream-Tools erwarten oft Cents, stabile Spaltennamen und konsistente Behandlung von Rückerstattungen. Ein Wörterbuch zwingt Sie, diese Verträge einzuhalten.

Wenn das Schema unordentlich oder unsicher zu ändern ist (unklare Joins, inkonsistente Währungen, sensible Werte an falschen Stellen), pausieren Sie den Refactor und erstellen Sie einen Plan, bevor Sie etwas ändern.

Nächste Schritte: aktuell halten und Hilfe holen, wenn der Prototyp sich wehrt

Ein Datenwörterbuch schützt nur, wenn es aktuell bleibt. Die simpelste Regel funktioniert gut: Keine Schema-Änderung wird deployed, bevor der Wörterbuch-Eintrag aktualisiert ist.

Halten Sie Definitionen verständlich für nicht-technische Kollegen. Streben Sie einen Satz, eine Bedeutung an. Wenn eine Spalte in verschiedenen Screens zwei Dinge bedeutet, gehen Sie davon aus, dass Reporting oder Abrechnung bereits inkonsistent sind.

Fügen Sie eine leichte Review für risikoreiche Änderungen hinzu

Sie brauchen keinen großen Prozess, aber einen Pause-Knopf für alles, was Geld oder Kernmetriken berührt.

Vor dem Mergen einer Änderung, die Abrechnung oder Reporting betrifft, bestätigen Sie:

• der Wörterbuch-Eintrag wurde aktualisiert (Tabelle, Spalte, Bedeutung, Beispiel)
• abhängige Reports/Exporte/Rechnungsberechnungen wurden identifiziert
• alte Werte sind behandelt (Migrationsplan oder Default-Verhalten)
• jemand besitzt die Definition (ein Name, nicht “Engineering”)

Wenn Sie eine KI-generierte Codebasis geerbt haben und unsicher sind, was sicher zu ändern ist, kann ein kurzes Audit Tage an Rückfragen sparen. FixMyMess (fixmymess.ai) bietet Codebasis-Diagnose und Reparaturen für KI-erstellte Apps und bietet ein kostenloses Code-Audit an, um Probleme in Abrechnung, Reporting und Datenbanklogik zu kartieren, bevor Sie Produktionsdaten anfassen.