ED03 - Định dạng nhật ký: JSON-Artifacts, chữ ký thời gian, V7GUID, Sidecar

Vấn đề

Một doanh nhân muốn quản lý nhật ký của mình trong Git - nhưng về mặt kỹ thuật, một mục nhập trông chính xác như thế nào? Thực tiễn hiện nay chưa có câu trả lời ràng buộc:

• Ghi chú văn bản tự do trong Markdown, Word hoặc giấy - không đọc được bằng máy, không được xác thực theo schema, không thể truy vết
• Các dòng Excel với ngày tháng, hoạt động, giờ công - không được phiên bản hóa, không được neo bằng mật mã, không an toàn kiểm toán
• Các bản xuất từ phần mềm lương dưới dạng PDF - không đánh giá được bằng máy (§ 147 Abs. 6 AO), không truy vết được theo chiều hồi tố/tiến triển
• Không có định danh duy nhất - mỗi mục có một tên tệp, nhưng tên tệp có thể thay đổi; định danh của mục không ổn định
• Không có neo thời gian - ngày tháng chỉ là một chuỗi trong tài liệu, nhưng ai đã thực sự ghi nhận vào lúc nào? Thời gian ghi nhận không được liên kết bằng mật mã với định danh

Thông điệp cốt lõi

Một mục nhật ký GitCover là một JSON-Artifact với:

1. JSON-Schema-First - schema tồn tại trước mục; mục được xác thực dựa trên schema (Pre-Commit-Hook)
2. V7GUID (Class Identifier) - phân loại tài liệu/Action dựa trên registry .gitcover (cái gì/loại nào); phục vụ tổ chức lưu trữ và truy vấn DB (ví dụ: EF Core trong Vertical App)
3. uuidV7 (Object ID) - bản thân nó đã là định danh duy nhất (DocID) của mục, RFC 9562 §5.7, được tạo từ một mốc thời gian định trước (hoặc now()) qua GitCover Helper (UuidV7Gen), phần còn lại được lấp bằng giá trị ngẫu nhiên
4. Composite Key V7GUID:uuidV7 - Composite Key của GCPN Sidecar, phục vụ tổ chức lưu trữ và truy vấn; thời gian ghi nhận nằm trong uuidV7 (dấu thời gian 48 bit), không có trường datetime/date riêng biệt
5. Nghĩa vụ Sidecar - mỗi chứng từ nhận một sidecar .v7g.md với uuidV7 riêng (hành động phân loại) và uuidV7 của tài liệu
6. Khả năng truy vết hồi tố/tiến triển - có thể phân giải từ bút toán → chứng từ → mục nhật ký → uuidV7 và theo chiều ngược lại

Compliance by Design: Định dạng này không phải là thứ bổ sung sau - nó mang tính cấu trúc. Schema, V7GUID (Class), uuidV7 (Object) và Sidecar là các trường bắt buộc; thiếu chúng, một mục sẽ không được đưa vào repo.

Không có datetime/date dư thừa: Thời gian ghi nhận được neo ngay trong uuidV7 (dấu thời gian 48 bit, RFC 9562 §5.7). Một biểu diễn chuỗi riêng biệt trong JSON-Schema hoặc dữ liệu JSON là dư thừa và không được đưa vào các fact. Biểu diễn chuỗi cho việc truyền DTO/HTMX là trách nhiệm của Harness, không phải của tầng fact.

JSON-Schema (Schema-First)

Schema tồn tại trước mục - nó được lưu trong .gitcover/schemas/diary-entry-1.0.schema.json và được phiên bản hóa. Một mục không có tham chiếu schema ($schema) sẽ bị Pre-Commit-Hook từ chối.

Schema diary-entry-1.0.schema.json (đơn giản hóa)

{
  "$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", "docUid",
    "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)"
    },
    "docUid": {
      "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" } }
  }
}

Quan trọng - không có trường datetime/date: Thời gian ghi nhận nằm trong uuidV7 (dấu thời gian 48 bit, RFC 9562 §5.7). Một biểu diễn chuỗi riêng biệt là dư thừa và không được đưa vào các fact. Một mình uuidV7 đã là DocID duy nhất; Composite Key V7GUID:uuidV7 phục vụ tổ chức lưu trữ và truy vấn DB.

V7GUID - Cấu tạo và dấu thời gian 48 bit

Nguyên tắc cốt lõi: Thành phần dấu thời gian 48 bit (bit 0–47) là có tính thẩm quyền đối với thời gian ghi nhận. Nó được neo ngay trong uuidV7 và không thể bị thay đổi sau này nếu không làm GUID vô hiệu. Một trường datetime riêng biệt không tồn tại - thời gian nằm trong uuidV7. Biểu diễn chuỗi cho DTO/HTMX là trách nhiệm của Harness.

Phần mở rộng GitCover: Hệ phân cấp và Process-ID trong các bit 66–127

Đặc tả V7GUID của GitCover (work/OSS/TOP/.gitcover/specs/v7guid/) mở rộng thành phần ngẫu nhiên 62 bit (bit 66–127) bằng một hệ phân cấp 6 mức và Process-ID - đây là phần mở rộng được bảo hộ bằng sáng chế (DPMA Az. 10 2025 003 091.6):

Lưu ý: Phần mở rộng này không bắt buộc đối với loạt bài về nhật ký - nó sẽ trở nên liên quan trong ED02 (Tenant/Sphäre/Rolle) và các bài viết sau (Harness). Ở đây, nền tảng RFC 9562 với dấu thời gian 48 bit là đủ.

Các Helper-Routine: Tạo V7GUID từ khóa ngoài

Công cụ OSS GitCover UuidV7Gen (work/OSS/TOP/tools/UuidV7Gen/) cung cấp hai thao tác trung tâm:

gen - tạo 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 - trích xuất dấu thời gian từ 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

Khóa ngoài → uuidV7

Các Helper-Routine cho phép tạo một khóa uuidV7 hợp lệ từ một khóa ngoài (ví dụ: một mốc thời gian trong tên tệp như 260815_0900_Lohnabrechnung.pdf)

• với mốc thời gian định trước, không phải now():

1. Phân tích khóa ngoài - 260815_0900 → 2026-08-15T09:00:00Z
2. Tính dấu thời gian 48 bit - số mili giây Unix kể từ Epoch
3. Tạo uuidV7 - Guid.CreateVersion7() với dấu thời gian tường minh, phần còn lại lấp bằng giá trị ngẫu nhiên
4. Composite Key - V7GUID (Class từ registry) : uuidV7 (Object với mốc thời gian)
5. Tài liệu hóa GoBD - ghi nhận kịp thời được neo một cách kiểm chứng được (không có trường datetime riêng biệt)

Liên hệ GoBD: Việc ghi nhận kịp thời (GoBD Rz. 146) được tài liệu hóa bằng mật mã thông qua dấu thời gian 48 bit trong uuidV7 - không chỉ là lời khẳng định suông. Dấu thời gian là một phần của định danh, không thể thay đổi sau này.

Cấu trúc Sidecar (.v7g.md)

Mỗi chứng từ nhận một sidecar với hai tham chiếu uuidV7:

Ví dụ Sidecar

{
  "$schema": "https://gitcover.org/schemas/v7g-sidecar-1.0.schema.json",
  "V7GUID": "<V7GUID-Class-aus-Registry>",
  "docUid": "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 (trường 1) - Class Identifier của sidecar (phân loại từ registry .gitcover: cái gì/loại nào)
• uuidV7 (trường 2) - Object ID của chính sidecar, được tạo với mốc thời gian định trước (phân loại vào lúc nào?), dấu thời gian 48 bit được neo trong GUID
• v7g_taxonomy[].v7guid - Object ID của tài liệu được phân loại (tài liệu nào đang được phân loại?)
• sha256 - định danh của tài liệu gốc được phân loại — bằng chứng về tính nguyên bản, mọi lúc, mọi nơi (kể cả khi tài liệu di chuyển: độc lập với đường dẫn/tên, được tính từ nội dung)

Như vậy, không chỉ tài liệu được định danh duy nhất (qua SHA-256 của nó), mà cả hành động phân loại - bao gồm thời điểm (trong uuidV7), ai đã phân loại và với vai trò nào. Không có trường datetime riêng biệt - thời gian nằm trong các giá trị uuidV7.

Khả năng truy vết hồi tố và tiến triển

Liên hệ GoBD: Khả năng truy vết hồi tố tương ứng với GoBD Rz. 146 (khả năng truy vết). Khả năng truy vết tiến triển tương ứng với GoBD Rz. 147 (khả năng kiểm chứng). Cả hai đều được bảo đảm by Design thông qua uuidV7 + SHA-256 - không phải thông qua các tham chiếu chéo thủ công.

Ghi nhận thời gian trong nhật ký

Mỗi mục nhật ký chứa một bảng ghi nhận thời gian:

Liên hệ FZul: Việc ghi nhận thời gian là cơ sở cho các chứng từ giờ công FZul (ED28). Việc tách biệt giữa F&E và quản lý được thực hiện qua trường role (F&E-Leiter so với GF) và các tags (["fzul", "forschung"] so với ["verwaltung"]).

Những gì được đưa vào Git-Repo - và những gì không

Quan trọng: Chỉ những artifact có cấu trúc (JSON, sidecar, chứng từ, schema, dictionary) mới được đưa vào Git-Repo. Tài liệu riêng tư không bao giờ được đưa vào repo, trừ khi chúng đã được đưa vào một cách tường minh với tư cách artifact và được phân loại. Đây là yêu cầu về bảo vệ dữ liệu và compliance (DSGVO, GoBD).

Đòn bẩy rủi ro

Yêu cầu Harness (xem trước)

Có thể suy ra từ ED03:

Danh sách yêu cầu đầy đủ nằm trong Harness-Anforderungen.md.

Nguồn

• RFC 9562 §5.7 (UUIDv7) - dấu thời gian Unix-ms 48 bit
• Đặc tả V7GUID - work/OSS/TOP/.gitcover/specs/v7guid/ (mang tính chuẩn tắc)
• DPMA Az. 10 2025 003 091.6 - Bằng sáng chế V7GUID (yêu cầu chính 2, các yêu cầu 5–8)
• Công cụ OSS GitCover UuidV7Gen - work/OSS/TOP/tools/UuidV7Gen/ (Helper gen/decode)
• GoBD (công văn BMF, Rz. 146 - khả năng truy vết, Rz. 147 - khả năng kiểm chứng)
• AO (§ 147 Abs. 2 - „có thể đánh giá bằng máy", § 147 Abs. 6 - truy cập dữ liệu)
• AFJD/agents/ (đã ẩn danh hóa) - khái niệm SSoT với JSON-Artifact, sidecar

Cấu trúc nguồn và các liên kết tham chiếu CDN

Lưu ý: Phân bổ này giữa nguồn, mirror và community hub phản ánh hiện trạng và có thể thay đổi. Vui lòng kiểm tra nguồn chuẩn tắc tương ứng trên gitcover.org để biết trạng thái hiện tại.