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

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 ghi 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 nào:

• Ghi chú văn bản tự do trong Markdown, Word hoặc trên 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, số giờ - không được quản lý phiên bản, 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 thể đánh giá bằng máy (§ 147 Abs. 6 AO), không thể truy vết hồi tố/xuôi
• Không có danh tính duy nhất - mỗi mục ghi có một tên tệp, nhưng tên tệp có thể thay đổi; danh tính của mục ghi không ổn định
• Không có điểm neo thời gian - ngày tháng chỉ tồn tại dưới dạng String trong tài liệu, nhưng ai đã thực sự ghi nhận và vào lúc nào? Thời điểm ghi nhận không được liên kết bằng mật mã với danh tính

Nội dung 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 ghi; mục ghi được xác thực đối chiếu với schema (Pre-Commit-Hook)
2. V7GUID (Class Identifier) - phân loại tài liệu/hành động dựa trên .gitcover Registry (cái gì/loại nào); phục vụ tổ chức lưu trữ và DB-Query (ví dụ: EF Core trong Vertical App)
3. uuidV7 (Object ID) - bản thân nó đã là danh tính duy nhất (DocID) của mục ghi, RFC 9562 §5.7, được tạo từ một mốc thời gian định trước (hoặc now()) thông qua GitCover Helper (UuidV7Gen), phần còn lại được điền bằng giá trị ngẫu nhiên
4. Composite Key V7GUID:uuidV7 - GCPN Sidecar Composite Key, phục vụ tổ chức lưu trữ và truy vấn; thời điểm 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ố/xuôi - từ bút toán → chứng từ → mục nhật ký → uuidV7 và phân giải được 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ục ghi sẽ không được đưa vào Repo.

Không có datetime/date dư thừa: Thời điểm 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 duy trì trong dữ liệu thực. Biểu diễn chuỗi phục vụ truyền DTO/HTMX là trách nhiệm của Harness, không thuộc tầng dữ liệu thực.

JSON-Schema (Schema-First)

Schema tồn tại trước mục ghi - nó được lưu tại .gitcover/schemas/diary-entry-1.0.schema.json và được quản lý phiên bản. Mục ghi 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", "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" } }
  }
}

Quan trọng - không có trường datetime/date: Thời điểm 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 duy trì trong dữ liệu thực. Một mình uuidV7 đã là DocID duy nhất; Composite Key V7GUID:uuidV7 phục vụ tổ chức lưu trữ và DB-Query.

V7GUID - Cấu trúc 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 (các bit 0–47) là thành phần có thẩm quyền đối với thời điểm 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 trở nên vô hiệu. Không tồn tại trường datetime riêng biệt - 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ệ thống 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 (các bit 66–127) bằng một hệ thống phân cấp 6 cấp và các Process-ID - đây chính là phần mở rộng được bảo hộ bằng 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 có liên quan trong ED02 (Tenant/Sphäre/Rolle) và các bài viết sau này (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 cốt lõi:

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, chứ không phải now():

1. Phân tích khóa ngoại - 260815_0900 → 2026-08-15T09:00:00Z
2. Tính toán 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 bằng giá trị ngẫu nhiên
4. Composite Key - V7GUID (Class từ Registry) : uuidV7 (Object mang mốc thời gian)
5. Tài liệu hóa GoBD - việc ghi nhận kịp thời được neo một cách có thể kiểm chứng (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 - chứ không chỉ là lời khẳng định. Dấu thời gian là một phần của danh tính, không thể bị 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>",
  "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 (trường 1) - Class Identifier của Sidecar (phân loại từ .gitcover Registry: 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?)

Như vậy không chỉ tài liệu được nhận diện duy nhất mà cả hành động phân loại tự thân - bao gồm cả 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 - thời gian nằm trong các giá trị uuidV7.

Khả năng truy vết hồi tố và xuôi

Liên hệ GoBD: Khả năng truy vết hồi tố tương ứng với GoBD Rz. 146 (tính truy vết). Khả năng truy vết xuôi tương ứng với GoBD Rz. 147 (khả năng kiểm toán). Cả hai đều được bảo đảm ngay từ thiết kế (by Design) nhờ uuidV7 + SHA-256 - chứ không phải nhờ 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 nhận giờ FZul (ED18). Việc tách biệt giữa F&E và công việc hành chính đượ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, từ điển) 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 dưới dạng artifact và được phân loại. Đây là yêu cầu về bảo vệ dữ liệu và tuân thủ (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/ (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 - tính truy vết, Rz. 147 - khả năng kiểm toán)
• 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

Topology nguồn và các liên kết tham chiếu CDN

Lưu ý: Cách phân bổ này giữa nguồn, Mirror và Community-Hub phản ánh hiện trạng hiện tại và có thể thay đổi. Vui lòng kiểm tra nguồn chính tắc tương ứng trên gitcover.org để biết trạng thái mới nhất.