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 ghi nhật ký của mình trong Git - nhưng một mục nhập trông như thế nào về mặt kỹ thuật? Thực tiễn hiện nay không có câu trả lời ràng buộc:

• Ghi chú dạng 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 lược đồ, không thể truy vết
• Dòng Excel với ngày, hoạt động, số giờ - không được quản lý phiên bản, không được neo giữ bằng mật mã, không an toàn cho việc kiểm toán
• Xuất phần mềm tính 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 ngược/xuôi
• Không có danh tính duy nhất - mỗi mục nhập có một tên tệp, nhưng tên tệp có thể thay đổi; danh tính của mục nhập không ổn định
• Không có neo giữ thời gian - ngày tháng nằm dưới dạng chuỗi trong tài liệu, nhưng ai đã thực sự ghi nhận khi nào? Thời gian ghi nhận không được liên kết bằng mật mã với danh tính

Tuyên bố cốt lõi

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

1. JSON-Schema-First - lược đồ tồn tại trước mục nhập; mục nhập được xác thực dựa trên lược đồ (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à danh tính duy nhất (DocID) của mục nhập, 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 (gc-v7guid), phần còn lại được lấp đầy bằng 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
5. Bắt buộc Sidecar - mỗi chứng từ nhận một .gc.md-Sidecar với uuidV7 riêng (hành vi phân loại) và uuidV7 của tài liệu
6. Khả năng truy vết ngược/xuôi - từ bút toán → chứng từ → mục 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, nếu thiếu thì một mục nhập không được đưa vào repo.

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

Mục nhật ký như một nút tuân thủ

Mục nhập kỹ thuật không phải là mục đích tự thân. Nó là nút thời gian nơi nhiều chuỗi bằng chứng hội tụ:

Diary-SSoT cho biết công việc đã được thực hiện theo chương trình nghị sự nào. Ur-Docs, Sidecars, GCPN và các tạo tác sổ cái/thanh toán cung cấp các chứng từ tương ứng. Sự tách biệt này ngăn ngừa hai lỗi: một mục Diary không bị hiểu nhầm là thay thế cho chứng từ bên ngoài, và một chứng từ được thu thập sau đó không bị trình bày sai thành bằng chứng công việc kịp thời.

JSON-Schema (Schema-First)

Lược đồ tồn tại trước mục nhập - nó được lưu trong .gitcover/schemas/diary-entry-1.0.schema.json và được quản lý phiên bản. Một mục nhập không có tham chiếu lược đồ ($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 là dư thừa và không được đưa vào các sự kiện. Chỉ riêng 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 (bit 0–47) là có thẩm quyền đối với thời gian ghi nhận. Nó được neo giữ trong chính uuidV7 và không thể bị thay đổi sau đó mà không làm GUID trở nên không hợp lệ. Một trường datetime riêng 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ệ thống phân cấp và Process-ID trong bit 66–127

Đặc tả GitCover-V7GUID (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ệ thống phân cấp 6 cấp 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ó 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 thủ tục Helper: Tạo V7GUID từ khóa ngoài

Công cụ GitCover-OSS gc-v7guid (work/OSS/gc-v7guid) cung cấp các thao tác:

gen — Tạo Object-ID UUIDv7

# n Objekt-IDs mit vorgegebener Zeitmarke (nicht now()) und Zufalls-Tail (RFC 9562)
gc-v7guid gen 1 --ts 2026-08-15T09:00:00Z
# Ausgabe: 01a17e18-c662-7874-9e1c-85d47895304f

gen-doc — Xác định từ siêu dữ liệu tài liệu

# Dokumentgebundene ID aus Zeitmarke + SHA-256 des Ur-Dokuments
gc-v7guid gen-doc --ts 2026-08-15T09:00:00Z --doc-sha256 <64-hex>

decode — Trích xuất dấu thời gian và cấu trúc từ uuidV7

gc-v7guid decode 019f2c6f-0900-7000-8000-000000000000
# Ausgabe: unix_ms, utc (ISO-8601), version=7, variant=2, rfc9562

Khóa ngoài → uuidV7

Các thủ tục 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 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 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 GoBD - việc ghi nhận kịp thời được neo giữ có thể truy vết (không có trường datetime riêng)

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

Cấu trúc Sidecar (.gc.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-2.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 được chỉ định trước (khi nào được phân loại?), 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?)
• sha256 - danh tính của tài liệu gốc được phân loại — bằng chứng về tính nguyên bản, luôn luôn và ở 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ận diện duy nhất (thông qua SHA-256 của nó), mà cả bản thân hành vi phân loại - bao gồm thời điểm (trong uuidV7), ai đã phân loại và trong 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 ngược và xuôi

Liên hệ GoBD: Khả năng truy vết ngược tương ứng GoBD Rz. 146 (khả năng truy vết). Khả năng truy vết xuôi tương ứng GoBD Rz. 147 (khả năng kiểm tra). Cả hai được đảm bảo by Design thông qua uuidV7 + SHA-256 - không phải thông qua 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:

Quy tắc cột: Cột Mục đích chỉ mang dự án FuE (FZul1, FZul2, …). Công việc không phải FuE được ghi là Verwaltung (Sphäre/Kategorie) với mục đích —. Mỗi giờ FZul thuộc về đúng một dự án (§ 7 FZulG).

Liên hệ FZul: Việc ghi nhận thời gian là nền tảng cho bảng chứng nhận giờ FZul (ED29). Việc tách F&E so với Verwaltung được thực hiện qua cột Mục đích theo từng dòng thời gian - không chỉ qua trường role của mục nhập. role mô tả chức năng của người hành động (xem bên dưới), không phải việc phân bổ tài trợ.

Ghi nhận là đầy đủ - chỉ giới hạn khi thanh toán

Nhật ký ghi nhận toàn bộ thời gian làm việc thực tế đã thực hiện và không có giới hạn trên - kể cả khi thời gian đó vượt quá giới hạn tuần theo luật tài trợ (ví dụ 40 giờ mỗi tuần và mỗi người). Một giới hạn như vậy là yếu tố tính toán trong tổng tuần và việc xác định tài trợ, không phải giới hạn của từng dòng thời gian: Không dòng nào bị cắt, rút ngắn hoặc ghi lại, chỉ vì đã đạt đến một giới hạn. Việc ghi nhận đầy đủ là điều kiện tiên quyết cho tính hợp lý của nhật ký và độ vững chắc của chuỗi bằng chứng. Việc nhóm lại giữa dự án và Verwaltung là câu hỏi thanh toán/dự phóng, không phải chỉnh sửa trên chứng từ.

Diễn biến trong ngày: Chứng từ trước, bút toán sau

Một ngày nhật ký có một trình tự cố định. Ghi nhận (chứng từ) và thanh toán/bút toán được tách biệt nghiêm ngặt:

Phân định: Thông tin FZul-/Sphäre trong nhật ký là một trường chứng từ. Nó độc lập với mọi bảo lưu chứng nhận và không tạo ra bút toán. Nhật ký là bằng chứng; việc ghi sổ được thực hiện trong Sổ cái, việc tính trọng số trong các dự phóng. Nguyên tắc tương tự áp dụng cho chứng từ: một chứng từ làm chứng, bút toán đến sau và riêng biệt.

Vai trò trong nhật ký - Cá nhân, chức năng, bên, thực thi

Trường role không phải là cá nhân. Để có hiểu biết vai trò vững chắc, GitCover phân biệt năm cấp độ, vẫn tách biệt ngay cả khi cùng một người thực hiện mọi thứ trong một lần (điển hình cho KMU):

Một người có thể có nhiều chức năng và nhiều hành vi chữ ký trên cùng một tài liệu - ví dụ với tư cách giám đốc điều hành của hai công ty. Điều này không tạo ra nhiều người, cũng không nhất thiết tạo ra nhiều tài khoản hoặc khóa. Tuy nhiên, các vai trò không được trùng nhau chỉ vì cá nhân hoặc thông tin xác thực giống hệt nhau: Mỗi hành vi chữ ký ràng buộc bản thể tài liệu + cá nhân + chức năng + bên được đại diện + sự đồng ý được bao phủ rõ ràng. Một câu hỏi chung gửi đến cá nhân có thể bao phủ nhiều chữ ký chức năng, nếu các chức năng được bao phủ được nêu rõ ràng; nó không thay thế việc phê duyệt gắn với tài liệu. Chi tiết: DS03 - Quy trình chữ ký và DS13 - Phân lớp các bên tham gia.

Ranh giới trung thực: Sự tách biệt này được mô tả như một yêu cầu và mô hình dữ liệu. Một sự ràng buộc bị ép buộc hoàn toàn về mặt kỹ thuật giữa cá nhân, chức năng, bên và sự đồng ý (đặc biệt là các role-claim từ Identity-Provider đến các sự kiện chữ ký) là đối tượng của phát triển đang diễn ra và chưa được triển khai ở mọi nơi.

Làm việc với tác nhân trong nhật ký

Nếu doanh nhân sử dụng tác nhân AI, nguyên tắc là: điều khiển, chỉ dẫn, giám sát và xác thực các tác nhân là việc sử dụng công cụ lao động bởi người hành động - thời gian được ghi nhận là thời gian của cá nhân. Nhật ký không có danh mục riêng "Agenten-Zeit" và không yêu cầu xác nhận "chồng lấn" khi các hoạt động diễn ra song song. Thay vào đó:

• mỗi hoạt động/dự án dòng riêng;
• đối với các hoạt động ngoài tài trợ FuE (đặc biệt là phát triển công cụ và tác nhân), bổ sung: tác nhân nào hoặc agent nào đã hành động với danh tính thực thi hiệu lực nào - không tiết lộ bí mật (token, khóa).

Khả năng được tài trợ không xuất phát từ việc sử dụng tác nhân, mà từ câu hỏi liệu hoạt động có liên quan đến một câu hỏi nghiên cứu kỹ thuật mở hay không (phân định trong từng dự án).

Những gì vào Git-Repo - và những gì không

Quan trọng: Chỉ các tạo tác có cấu trúc (JSON, Sidecars, chứng từ, schemata, từ điển) đượ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 tạo tác. Đâ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 đủ 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/ (quy phạm)
• DPMA Az. 10 2025 003 091.6 - Bằng sáng chế V7GUID (yêu cầu chính 2, yêu cầu 5–8)
• Công cụ GitCover OSS gc-v7guid - work/OSS/gc-v7guid (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ể đánh giá bằng máy", § 147 Abs. 6 - truy cập dữ liệu)
• E1/agents/ (ẩn danh) - khái niệm SSoT với JSON-Artifacts, Sidecars

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

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