ED03 - Tagebuch-Format: JSON-Artifacts, temporale Signatur, V7GUID, Sidecars

Problem

Ein Unternehmer will sein Tagebuch in Git führen - aber wie genau sieht ein Eintrag technisch aus? Die heutige Praxis kennt keine verbindliche Antwort:

• Freitext-Notizen in Markdown, Word oder Papier - nicht maschinenlesbar, nicht schemavalidiert, nicht nachvollziehbar
• Excel-Zeilen mit Datum, Tätigkeit, Stunden - nicht versioniert, nicht kryptographisch verankert, nicht revisionssicher
• Lohnsoftware-Exporte als PDF - nicht maschinell auswertbar (§ 147 Abs. 6 AO), nicht retrograd/progressiv nachverfolgbar
• Keine eindeutige Identität - jeder Eintrag hat einen Dateinamen, aber der Dateiname kann sich ändern; die Identität des Eintrags ist nicht stabil
• Keine temporale Verankerung - das Datum steht als String im Dokument, aber wer hat wann wirklich erfasst? Die Erfassungszeit ist nicht kryptographisch mit der Identität verknüpft

Kernaussage

Ein GitCover-Tagebucheintrag ist ein JSON-Artifact mit:

1. JSON-Schema-First - das Schema existiert vor dem Eintrag; der Eintrag wird gegen das Schema validiert (Pre-Commit-Hook)
2. V7GUID (Class Identifier) - klassifiziert das Dokument/die Action anhand der .gitcover Registry (was/welcher Typ); dient der Ablage-Organisation und DB-Query (z. B. EF Core in Vertical App)
3. uuidV7 (Object ID) - ist bereits allein die eindeutige Identität (DocID) des Eintrags, RFC 9562 §5.7, generiert aus einer vorgegebenen Zeitmarke (nicht now()) via GitCover Helper (UuidV7Gen), Rest mit Zufall aufgefüllt
4. Composite Key V7GUID:uuidV7 - der GCPN Sidecar Composite Key, dient Ablage-Organisation und Query; die Erfassungszeit steckt in der uuidV7 (48-Bit-Zeitstempel), kein separates datetime/date-Feld
5. Sidecar-Pflicht - jeder Beleg erhält einen .v7g.md-Sidecar mit eigener uuidV7 (Klassifizierungsakt) und der uuidV7 des Dokuments
6. Retrograde/progressive Nachverfolgbarkeit - vom Buchungssatz → Beleg → Tagebucheintrag → uuidV7 und zurück auflösbar

Compliance by Design: Das Format ist nicht nachträglich - es ist strukturell. Schema, V7GUID (Class), uuidV7 (Object) und Sidecar sind Pflichtfelder, ohne die ein Eintrag nicht ins Repo aufgenommen wird.

Kein redundantes datetime/date: Die Erfassungszeit ist in der uuidV7 selbst verankert (48-Bit-Zeitstempel, RFC 9562 §5.7). Eine separate String-Darstellung in JSON-Schemata oder JSON-Daten ist redundant und wird nicht in den Fakten geführt. String-Darstellung für DTO/HTMX-Transfer ist Harness-Verantwortung, nicht Fakten-Ebene.

Das JSON-Schema (Schema-First)

Das Schema existiert vor dem Eintrag - es wird im .gitcover/schemas/diary-entry-1.0.schema.json abgelegt und ist versioniert. Ein Eintrag ohne Schema-Referenz ($schema) wird vom Pre-Commit-Hook abgelehnt.

Schema diary-entry-1.0.schema.json (vereinfacht)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gitcover.org/schemas/diary-entry-1.0.schema.json",
  "title": "GitCover Diary Entry v1.0",
  "type": "object",
  "required": [
    "$schema", "V7GUID", "uuidV7",
    "author", "role", "tenant", "sphere", "source"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri",
      "const": "https://gitcover.org/schemas/diary-entry-1.0.schema.json"
    },
    "V7GUID": {
      "type": "string",
      "description": "Class Identifier - klassifiziert das Dokument/die Action aus .gitcover Registry (was/welcher Typ)"
    },
    "uuidV7": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
      "description": "Object ID - RFC 9562 §5.7 UUIDv7, generiert aus vorgegebener Zeitmarke (nicht now()), 48-Bit-Zeitstempel in der GUID verankert"
    },
    "author": { "type": "string", "description": "Akteur-Platzhalter, z. B. E1" },
    "role": {
      "type": "string",
      "enum": ["GF", "Buchhalter", "Lohnverantwortlicher", "F&E-Leiter", "Administrator"]
    },
    "tenant": { "type": "string", "description": "Tenant-Platzhalter, z. B. ORG-1" },
    "sphere": {
      "type": "string",
      "enum": ["ideell", "vermögensverwaltend", "zweckbetrieblich", "wirtschaftlich", "n/a"]
    },
    "source": {
      "type": "string",
      "enum": ["E1", "StB", "Notar", "Bank", "DRV", "FA", "BA", "VBG", "KK", "auto"]
    },
    "source_sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "SHA-256 des referenzierten Belegs (eindeutige Beleg-ID)"
    },
    "tags": { "type": "array", "items": { "type": "string" } }
  }
}

Wichtig - kein datetime/date-Feld: Die Erfassungszeit steckt in der uuidV7 (48-Bit-Zeitstempel, RFC 9562 §5.7). Eine separate String-Darstellung ist redundant und wird nicht in den Fakten geführt. Die uuidV7 allein ist die eindeutige DocID; der Composite Key V7GUID:uuidV7 dient der Ablage-Organisation und DB-Query.

V7GUID - Aufbau und 48-Bit-Zeitstempel

Kernprinzip: Die 48-Bit-Zeitstempel-Komponente (Bits 0–47) ist autoritativ für die Erfassungszeit. Sie ist in der uuidV7 selbst verankert und kann nicht nachträglich geändert werden, ohne die GUID ungültig zu machen. Ein separates datetime-Feld existiert nicht - die Zeit steckt in der uuidV7. String-Darstellung für DTO/HTMX ist Harness-Verantwortung.

GitCover-Erweiterung: Hierarchie und Prozess-IDs in Bits 66–127

Die GitCover-V7GUID-Spezifikation (work/OSS/TOP/.gitcover/specs/v7guid/) erweitert die 62-Bit-Zufallskomponente (Bits 66–127) um eine 6-Level-Hierarchie und Prozess-IDs - das ist die patentgeschützte Erweiterung (DPMA Az. 10 2025 003 091.6):

Hinweis: Diese Erweiterung ist für die Tagebuch-Serie nicht zwingend erforderlich - sie wird in ED02 (Tenant/Sphäre/Rolle) und späteren Artikeln (Harness) relevant. Hier genügt die RFC-9562-Basis mit 48-Bit-Zeitstempel.

Helper-Routinen: V7GUID aus Fremd-Keys erstellen

Das GitCover OSS Tool UuidV7Gen (work/OSS/TOP/tools/UuidV7Gen/) stellt zwei zentrale Operationen bereit:

gen - uuidV7 (guid) erzeugen

# Erzeugt eine neue uuidV7 mit vorgegebener Zeitmarke (nicht now())
# Zeitmarke z. B. aus Dateiname "260815_0900" → ISO 2026-08-15T09:00:00Z
uuidv7gen gen "2026-08-15T09:00:00Z" "Tagebucheintrag-260815"

# Ausgabe: Label;UUID;ISO-Zeitstempel
# Tagebucheintrag-260815;019f2c6f-0900-7000-8000-000000000000;2026-08-15T09:00:00.000Z

decode - Zeitstempel aus uuidV7 extrahieren

# Extrahiert den 48-Bit-Zeitstempel aus einer uuidV7
uuidv7gen decode 019f2c6f-0900-7000-8000-000000000000

# Ausgabe: ISO-8601-Zeitstempel
# 2026-08-15T09:00:00.000Z

Fremd-Key → uuidV7

Die Helper-Routinen erlauben, aus einem Fremd-Key (z. B. eine Zeitmarke im Dateinamen wie 260815_0900_Lohnabrechnung.pdf) einen gültigen uuidV7-Schlüssel zu erstellen - mit vorgegebener Zeitmarke, nicht now():

1. Fremd-Key parsen - 260815_0900 → 2026-08-15T09:00:00Z
2. 48-Bit-Zeitstempel berechnen - Unix-Millisekunden seit Epoch
3. uuidV7 generieren - Guid.CreateVersion7() mit explizitem Zeitstempel, Rest mit Zufall
4. Composite Key - V7GUID (Class aus Registry) : uuidV7 (Object mit Zeitmarke)
5. GoBD-Dokumentation - zeitnahe Erfassung nachvollziehbar verankert (kein separates datetime-Feld)

GoBD-Bezug: Die zeitnahe Erfassung (GoBD Rz. 146) wird durch den 48-Bit-Zeitstempel in der uuidV7 kryptographisch dokumentiert - nicht nur behauptet. Der Zeitstempel ist Teil der Identität, nicht nachträglich änderbar.

Sidecar-Struktur (.v7g.md)

Jeder Beleg erhält einen Sidecar mit zwei uuidV7 Bezügen:

Sidecar-Beispiel

{
  "$schema": "https://gitcover.org/schemas/v7g-sidecar-1.0.schema.json",
  "V7GUID": "<V7GUID-Class-aus-Registry>",
  "uuidV7": "019f2c6f-0900-7001-8000-000000000001",
  "sha256": "ab94670c0dd8499c27ef2feddd1d9c5925977d55a52150a6fca0f6567d2e5e79",
  "title": "260815_Lohnabrechnung.pdf",
  "original_filename": "260815_Lohnabrechnung.pdf",
  "locations": [
    {
      "unc_path": "./ORG-1/sources/lohn/260815_Lohnabrechnung.pdf",
      "from": "260815",
      "to": null,
      "note": "Primärspeicherort"
    }
  ],
  "v7g_taxonomy": [
    {
      "v7guid": "019f2c6f-0900-7000-8000-000000000000",
      "taxonomy": "ORG-1/Lohn",
      "valid_from": "260815",
      "valid_to": null,
      "note": "Tenant: ORG-1, Category: Lohn, Sphäre: ideell"
    }
  ],
  "gcpn": {
    "prima_nota_ref": null,
    "journal_entry_ref": null
  },
  "obsolescence": {
    "status": "active",
    "superseded_by": null,
    "superseded_at": null
  }
}

Composite Key V7GUID:uuidV7:

• V7GUID (Feld 1) - Class Identifier des Sidecars (Klassifizierung aus .gitcover Registry: was/welcher Typ)
• uuidV7 (Feld 2) - Object ID des Sidecars selbst, generiert mit vorgegebener Zeitmarke (wann wurde klassifiziert?), 48-Bit-Zeitstempel in der GUID verankert
• v7g_taxonomy[].v7guid - Object ID des klassifizierten Dokuments (welches Dokument wird klassifiziert?)

So ist nicht nur das Dokument eindeutig identifiziert, sondern auch der Klassifizierungsakt selbst - inklusive Zeitpunkt (in uuidV7), wer klassifiziert hat und in welcher Rolle. Kein separates datetime-Feld - die Zeit steckt in den uuidV7-Werten.

Retrograde und progressive Nachverfolgbarkeit

GoBD-Bezug: Die retrograde Nachverfolgbarkeit entspricht GoBD Rz. 146 (Nachvollziehbarkeit). Die progressive Nachverfolgbarkeit entspricht GoBD Rz. 147 (Prüfbarkeit). Beide sind by Design durch uuidV7 + SHA-256 gewährleistet - nicht durch manuelle Querverweise.

Zeit-Erfassung im Tagebuch

Jeder Tagebucheintrag enthält eine Zeit-Erfassungstabelle:

FZul-Bezug: Die Zeit-Erfassung ist die Grundlage für FZul-Stundennachweise (ED18). Die Trennung F&E vs. Verwaltung erfolgt über das role-Feld (F&E-Leiter vs. GF) und die tags (["fzul", "forschung"] vs. ["verwaltung"]).

Was im Git-Repo landet - und was nicht

Wichtig: Nur strukturierte Artefakte (JSON, Sidecars, Belege, Schemata, Dictionaries) werden ins Git-Repo aufgenommen. Private Dokumente werden nie ins Repo aufgenommen, sofern sie nicht ausdrücklich als Artefakt eingeführt und klassifiziert wurden. Das ist eine Datenschutz- und Compliance-Anforderung (DSGVO, GoBD).

Risiko-Leverage

Harness-Anforderung (Vorschau)

Aus ED03 ableitbar:

Die vollständige Anforderungsliste in Harness-Anforderungen.md.

Quellen

• RFC 9562 §5.7 (UUIDv7) - 48-Bit Unix-ms-Zeitstempel
• V7GUID-Spezifikation - work/OSS/TOP/.gitcover/specs/v7guid/ (normativ)
• DPMA Az. 10 2025 003 091.6 - V7GUID-Patent (Hauptanspruch 2, Ansprüche 5–8)
• GitCover OSS Tool UuidV7Gen - work/OSS/TOP/tools/UuidV7Gen/ (Helper gen/decode)
• GoBD (BMF-Schreiben, Rz. 146 - Nachvollziehbarkeit, Rz. 147 - Prüfbarkeit)
• AO (§ 147 Abs. 2 - "maschinell auswertbar", § 147 Abs. 6 - Datenzugriff)
• AFJD/agents/ (anonymisiert) - SSoT-Konzept mit JSON-Artifacts, Sidecars

Quellen-Topologie und CDN-Referenz-Links

Hinweis: Diese Zuordnung von Quellen, Mirror und Community-Hub spiegelt den aktuellen Stand wider und kann sich ändern. Bitte prüfen Sie die jeweilige kanonische Quelle auf gitcover.org für den aktuellen Zustand.