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 bản 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:

• Ghi chú văn bản tự do trong Markdown, Word hoặc trên giấy - không thể đọc bằng máy, không được xác thực theo schema, không thể kiểm chứng
• Các dòng Excel với ngày tháng, hoạt động, số giờ - 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 thể xử lý bằng máy (§ 147 Abs. 6 AO), không thể truy vết ngược/tiến
• Không có định danh duy nhất - mỗi bản ghi có một tên tệp, nhưng tên tệp có thể thay đổi; định danh của bản ghi không ổn định
• Không có neo thời gian - ngày tháng chỉ được lưu dưới dạng chuỗi (String) 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 bản ghi nhật ký GitCover là một JSON-Artifact với:

1. JSON-Schema-First - schema tồn tại trước bản ghi; bản ghi đượ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/hành động 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 bản ghi, RFC 9562 §5.7, được tạo từ một mốc thời gian được chỉ định trước (hoặc now()) 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 - Composite Key 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 ngược/tiến - từ bút toán → chứng từ → bản ghi nhật ký → uuidV7 và có thể phân giải ngược lại

Compliance by Design: Định dạng này không phải là 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 bản ghi 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 String riêng biệt trong JSON-Schema hoặc dữ liệu JSON là dư thừa và không được đưa vào dữ liệu thực tế. Biểu diễn String cho việc truyền DTO/HTMX là trách nhiệm của Harness, không phải tầng dữ liệu thực tế.

JSON-Schema (Schema-First)

Schema tồn tại trước bản ghi - nó được lưu tại .gitcover/schemas/diary-entry-1.0.schema.json và được phiên bản hóa. Một bản 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 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 String riêng biệt là dư thừa và không được đưa vào dữ liệu thực tế. 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 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 (Bits 0–47) 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 String cho DTO/HTMX là trách nhiệm của Harness.

Phần mở rộng GitCover: Phân cấp và ID quy trình trong Bits 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 (Bits 66–127) bằng một phân cấp 6 mức và các ID quy trình - đây 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 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 hàm Helper: 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 hàm Helper 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 được chỉ định trước, không phải now():

1. Phân tích cú pháp khóa ngoài - 260815_0900 → 2026-08-15T09:00:00Z
2. Tính dấu thời gian 48 bit - 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 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)

Tham chiếu 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à tuyên bố 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>",
  "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ừ 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 được chỉ đị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 được phân loại?)

Như vậy, không chỉ tài liệu được định danh duy nhất 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 ngược và tiến

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

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

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

Tham chiếu 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 phân tách F&E so với quản lý 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"]).

Cái gì được đưa vào Git-Repo - và cái gì không

Quan trọng: Chỉ các artifact có cấu trúc (JSON, Sidecars, 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 và phân loại rõ ràng như một artifact. Đâ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ể rút 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 mili giây Unix 48 bit
• Đặc tả V7GUID - work/OSS/TOP/.gitcover/specs/v7guid/ (mang tính quy phạm)
• 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 (BMF-Schreiben, Rz. 146 - khả năng truy vết, Rz. 147 - khả năng kiểm tra)
• AO (§ 147 Abs. 2 - "có thể xử lý bằng máy", § 147 Abs. 6 - truy cập dữ liệu)
• AFJD/agents/ (đã ẩn danh) - khái niệm SSoT với JSON-Artifacts, Sidecars

Topologie nguồn và 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 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 hiện tại.