ED03 - Format de journal : artefacts JSON, signature temporelle, V7GUID, sidecars

Problème

Un entrepreneur veut tenir son journal dans Git - mais à quoi ressemble techniquement une entrée, exactement ? La pratique actuelle ne connaît aucune réponse contraignante :

• Notes en texte libre en Markdown, Word ou papier - ni lisibles par machine, ni validées par schéma, ni traçables
• Lignes Excel avec date, activité, heures - non versionnées, non ancrées cryptographiquement, non à l'épreuve des révisions
• Exports de logiciel de paie en PDF - non exploitables par machine (§ 147 Abs. 6 AO), non traçables de manière rétrograde/progressive
• Aucune identité unique - chaque entrée a un nom de fichier, mais le nom de fichier peut changer ; l'identité de l'entrée n'est pas stable
• Aucun ancrage temporel - la date figure comme chaîne de caractères dans le document, mais qui a réellement effectué la saisie, et quand ? L'heure de saisie n'est pas liée cryptographiquement à l'identité

Message clé

Une entrée de journal GitCover est un artefact JSON avec :

1. JSON-Schema-First - le schéma existe avant l'entrée ; l'entrée est validée par rapport au schéma (Pre-Commit-Hook)
2. V7GUID (Class Identifier) - classifie le document/l'action selon la Registry .gitcover (quoi/quel type) ; sert à l' organisation du classement et aux requêtes DB (p. ex. EF Core dans Vertical App)
3. uuidV7 (Object ID) - est déjà, à elle seule, l'identité unique (DocID) de l'entrée, RFC 9562 §5.7, générée à partir d'une marque temporelle prédéfinie (ou de now()) via le Helper GitCover (UuidV7Gen), le reste étant rempli de manière aléatoire
4. Composite Key V7GUID:uuidV7 - le Composite Key du sidecar GCPN, sert à l'organisation du classement et aux requêtes ; l'heure de saisie est contenue dans la uuidV7 (horodatage 48 bits), aucun champ datetime/date séparé
5. Obligation de sidecar - chaque pièce justificative reçoit un sidecar .v7g.md avec sa propre uuidV7 (acte de classification) et la uuidV7 du document
6. Traçabilité rétrograde/progressive - résoluble de l'écriture comptable → pièce justificative → entrée de journal → uuidV7 et en sens inverse

Compliance by Design : le format n'est pas ajouté après coup - il est structurel. Le schéma, le V7GUID (Class), la uuidV7 (Object) et le sidecar sont des champs obligatoires, sans lesquels une entrée n'est pas admise dans le dépôt.

Pas de datetime/date redondant : l'heure de saisie est ancrée dans la uuidV7 elle-même (horodatage 48 bits, RFC 9562 §5.7). Une représentation sous forme de chaîne séparée dans les schémas JSON ou les données JSON est redondante et n'est pas consignée dans les faits. La représentation sous forme de chaîne pour le transfert DTO/HTMX relève de la responsabilité du Harness, pas de la couche des faits.

Le schéma JSON (Schema-First)

Le schéma existe avant l'entrée - il est stocké dans .gitcover/schemas/diary-entry-1.0.schema.json et est versionné. Une entrée sans référence de schéma ($schema) est rejetée par le Pre-Commit-Hook.

Schéma diary-entry-1.0.schema.json (simplifié)

{
  "$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" } }
  }
}

Important - pas de champ datetime/date : l'heure de saisie est contenue dans la uuidV7 (horodatage 48 bits, RFC 9562 §5.7). Une représentation sous forme de chaîne séparée est redondante et n'est pas consignée dans les faits. La uuidV7 seule constitue la DocID unique ; le Composite Key V7GUID:uuidV7 sert à l'organisation du classement et aux requêtes DB.

V7GUID - structure et horodatage 48 bits

Principe central : la composante horodatage 48 bits (bits 0–47) fait autorité pour l'heure de saisie. Elle est ancrée dans la uuidV7 elle-même et ne peut pas être modifiée a posteriori sans invalider le GUID. Un champ datetime séparé n'existe pas - le temps est contenu dans la uuidV7. La représentation sous forme de chaîne pour DTO/HTMX est de la responsabilité du Harness.

Extension GitCover : hiérarchie et IDs de processus dans les bits 66–127

La spécification V7GUID de GitCover (work/OSS/TOP/.gitcover/specs/v7guid/) étend la composante aléatoire de 62 bits (bits 66–127) avec une hiérarchie à 6 niveaux et des IDs de processus - il s'agit de l'extension protégée par brevet (DPMA Az. 10 2025 003 091.6) :

Remarque : cette extension n'est pas strictement nécessaire pour la série consacrée au journal - elle devient pertinente dans ED02 (Tenant/Sphère/Rôle) et dans des articles ultérieurs (Harness). Ici, la base RFC 9562 avec horodatage 48 bits suffit.

Routines utilitaires : création d'un V7GUID à partir de clés étrangères

L'outil OSS GitCover UuidV7Gen (work/OSS/TOP/tools/UuidV7Gen/) fournit deux opérations centrales :

gen - génération d'une uuidV7 (guid)

# 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 - extraction de l'horodatage depuis une uuidV7

# 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

Clé étrangère → uuidV7

Les routines utilitaires permettent de créer, à partir d'une clé étrangère (p. ex. un horodatage dans le nom de fichier comme 260815_0900_Lohnabrechnung.pdf), une clé uuidV7 valide - avec une marque temporelle prédéfinie, et non now() :

1. Parser la clé étrangère - 260815_0900 → 2026-08-15T09:00:00Z
2. Calculer l'horodatage 48 bits - millisecondes Unix depuis l'Epoch
3. Générer la uuidV7 - Guid.CreateVersion7() avec horodatage explicite, le reste étant aléatoire
4. Composite Key - V7GUID (Class issue de la Registry) : uuidV7 (Object avec marque temporelle)
5. Documentation GoBD - saisie en temps utile ancrée de manière traçable (pas de champ datetime séparé)

Lien avec la GoBD : la saisie en temps utile (GoBD Rz. 146) est documentée cryptographiquement par l'horodatage 48 bits dans la uuidV7 - et pas seulement affirmée. L'horodatage fait partie de l'identité, il n'est pas modifiable a posteriori.

Structure du sidecar (.v7g.md)

Chaque pièce justificative reçoit un sidecar avec deux références uuidV7 :

Exemple de sidecar

{
  "$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 (champ 1) - Class Identifier du sidecar (classification issue de la Registry .gitcover : quoi/quel type)
• uuidV7 (champ 2) - Object ID du sidecar lui-même, générée avec une marque temporelle prédéfinie (quand la classification a-t-elle eu lieu ?), horodatage 48 bits ancré dans le GUID
• v7g_taxonomy[].v7guid - Object ID du document classifié (quel document est classifié ?)

Ainsi, non seulement le document est identifié de manière unique, mais aussi l' acte de classification lui-même - y compris le moment (dans la uuidV7), qui a classifié et dans quel rôle. Pas de champ datetime séparé - le temps est contenu dans les valeurs uuidV7.

Traçabilité rétrograde et progressive

Lien avec la GoBD : la traçabilité rétrograde correspond à la GoBD Rz. 146 (traçabilité). La traçabilité progressive correspond à la GoBD Rz. 147 (vérifiabilité). Toutes deux sont by Design garanties par uuidV7 + SHA-256

• et non par des renvois croisés manuels.

Saisie du temps dans le journal

Chaque entrée de journal contient un tableau de saisie du temps :

Lien avec la FZul : la saisie du temps est la base des justificatifs d'heures FZul (ED28). La séparation R&D vs. administration s'effectue via le champ role (F&E-Leiter vs. GF) et les tags ([\"fzul\", \"forschung\"] vs. [\"verwaltung\"]).

Ce qui va dans le dépôt Git - et ce qui n'y va pas

Important : seuls les artefacts structurés (JSON, sidecars, pièces justificatives, schémas, dictionnaires) sont admis dans le dépôt Git. Les documents privés ne sont jamais admis dans le dépôt, sauf s'ils ont été expressément introduits comme artefacts et classifiés comme tels. Il s'agit d'une exigence de protection des données et de conformité (RGPD, GoBD).

Levier de risque

Exigences Harness (aperçu)

Déductibles de ED03 :

La liste complète des exigences dans Harness-Anforderungen.md.

Sources

• RFC 9562 §5.7 (UUIDv7) - horodatage Unix-ms 48 bits
• Spécification V7GUID - work/OSS/TOP/.gitcover/specs/v7guid/ (normatif)
• DPMA Az. 10 2025 003 091.6 - brevet V7GUID (revendication principale 2, revendications 5–8)
• Outil OSS GitCover UuidV7Gen - work/OSS/TOP/tools/UuidV7Gen/ (Helper gen/decode)
• GoBD (circulaire BMF, Rz. 146 - traçabilité, Rz. 147 - vérifiabilité)
• AO (§ 147 Abs. 2 - "maschinell auswertbar", § 147 Abs. 6 - accès aux données)
• AFJD/agents/ (anonymisé) - concept SSoT avec artefacts JSON, sidecars

Topologie des sources et liens de référence CDN

Remarque : cette répartition entre sources, miroir et hub communautaire reflète l' état actuel et peut changer. Veuillez vérifier la source canonique respective sur gitcover.org pour connaître l'état actuel.