Trục 5: Các cách thức thực hiện

Onboarding doanh nghiệp vừa và nhỏ

Việc bắt đầu với tuân thủ Git-native đối với doanh nghiệp vừa và nhỏ đi theo một lộ trình từng bước:

1. Khởi tạo Git-Repository - Cấu trúc với thư mục .gitcover/, cấu hình V7GUID
2. Chọn OSCAL-Katalog - GoBD-Baseline, BSI-Bausteine hoặc profile riêng
3. Kích hoạt OPA-Policies - Pre-receive-Hooks để xác thực trước commit
4. Thiết lập ký GPG - Một cặp khóa GPG cho mỗi tác nhân
5. Khởi động chuỗi chứng từ - Cấp các V7GUID đầu tiên, bắt đầu nối chuỗi prev-hash

Dành cho Entrepreneurs từ cấp độ kinh doanh phụ

Khởi đầu có thể là một thiết lập rất đơn giản: GCDMS để lưu trữ chứng từ, GCPN cho các chuỗi bằng chứng. Sau đó mở rộng: OSCAL-Policies, xác thực OPA, Multi-Tenant.

Onboarding tương tác: „Compliance City"

Thay vì các bảng hỏi cổ điển, onboarding diễn ra như một quá trình lắp ráp mô-đun theo khái niệm một thành phố trên một tấm đế Lego. Mỗi quyết định kiến trúc và mỗi yêu cầu nghiệp vụ tương ứng với một viên gạch hoặc một cụm lắp ráp (Lego-Set), được lưu giữ như một mô-đun có cấu trúc trong Default-Git-Repository vừa được khởi tạo và được phiên bản hóa.

Phép ẩn dụ dành cho người dùng:

• Tấm đế: Git-Repository trống, vừa được tạo mới cho Tenant trong hạ tầng của Tenant đó. Nó cung cấp khung chuẩn hóa (các nút gờ), nơi mọi thứ gắn vào.
• Các viên gạch: Cấu hình mô-đun và các tệp dịch vụ. Chỉ khi một viên gạch khớp vào vị trí (Git-Commit), chức năng hoặc kiểm tra tuân thủ tương ứng mới trở nên hoạt động.

Giai đoạn 1 - Trải tấm đế (Khởi tạo & Danh tính):

Hệ thống tự động tạo Default-Repository cho Tenant. Trợ lý onboarding xác định danh tính của doanh nghiệp. Dữ liệu được lưu trữ có cấu trúc trong repository 'TOP' (Tenant Organization Profile) - Git-Commit đầu tiên đã là quy trình tuân thủ đầu tiên có thể kiểm toán. Nhân tiện: Tenants tất nhiên cũng có thể được tổ chức theo thứ bậc, giống như các cấu trúc doanh nghiệp mà chúng thuộc về.

Giai đoạn 2 - Đi dây hạ tầng (Mạng lưới cung ứng):

Trợ lý ghi nhận cảnh quan IT: chỗ làm việc Laptop, File-Server, hạ tầng Cloud-first hoặc hybrid. Các tham số như kết nối Internet, domain, đường dẫn Storage v.v. được đưa vào các thông tin hạ tầng và chuẩn bị sẵn các đường dẫn cho các kết nối chéo (others.json).

Giai đoạn 3 - Dựng các tòa nhà (Phạm vi nghiệp vụ):

Người dùng quyết định theo kiểu mô-đun thành phố của mình cần bao phủ những lĩnh vực pháp quy nào:

Người dùng không bao giờ nhìn thấy tệp cấu hình hay mã nguồn tại bất kỳ thời điểm nào. Vì mỗi bước ngay lập tức tạo ra một Git-Commit sạch, hệ thống được tài liệu hóa ngay từ phút đầu tiên hoàn toàn an toàn kiểm soát sửa đổi theo GoBD và AO.

Cách ly Mandant và kiểm soát truy cập

OIDC-Claims và others.json

Việc liên kết OIDC-Claims với others.json là con đường vàng cho các môi trường tuân thủ hỗ trợ nhiều Mandant và an toàn cho người không chuyên. Trong others.json tập hợp:

1. Các route chính tắc đến các Git-Repository của chính Tenant
2. Các kết nối chéo đến Git-Repository của các Tenant khác, khi Tenant là thành viên của một nhóm

Quyền truy cập được điều khiển qua OIDC-Claims (các vai trò và Custom Claims như tenant_id, org_unit_id và tư cách thành viên nhóm). Một Inlet-Pipeline đọc others.json tùy theo User-Claim và tiêm các đường dẫn được phép vào dưới dạng System-Prompt:

Bạn là GitCover Agent cho Mandant X. Bạn chỉ có quyền truy cập vào các Repositories sau: [Đường dẫn 1], [Đường dẫn 2]. Không thực hiện bất kỳ lệnh nào ngoài các thư mục này.

Mô hình Claim hai tầng cho truy cập PII

Để truy cập dữ liệu cá nhân (PII), GCBoK định nghĩa một Claim-Hierarchie gồm hai tầng (xem Kỹ thuật: Git làm IdP:

others.json ánh xạ các Claim này sang các đường dẫn Repository:

{
  "tenant_id": "0197a3b2-f3c0-7b00-8001-000000000042",
  "org_unit_id": "ORG-1-Portfolio",
  "allowed_repos": [
    "TOP",
    "PII/ORG-1-Portfolio"
  ]
}

Một người dùng với org_unit_id = ORG-1-Portfolio có quyền truy cập PII/ORG-1-Portfolio, nhưng không có quyền truy cập PII/ORG-2-IT — ngay cả khi cùng tenant_id. Điều này hiện thực hóa nguyên tắc đặc quyền tối thiểu (NIS2 Art. 21) ở cấp Repository.

Đối với người dùng cuối, bộ máy bảo mật này vẫn vô hình. Người đó đăng nhập, nhìn thấy môi trường làm việc quen thuộc của mình và AI tự động biết mình được phép hành động ở đâu.

Thu thập dữ liệu hỗ trợ bởi AI qua Formular-Bridging

Chat-Interfaces phù hợp cho các ngữ cảnh và phân tích, không phù hợp cho việc nắm bắt kiểu dữ liệu nghiêm ngặt (IBANs, mã bưu chính, OSCAL-Schemata). Do đó GCBoK khuyến nghị một Formular-Bridging:

1. AI nhận diện nhu cầu: Người dùng nói „Tôi muốn thêm một cơ sở hoạt động mới."
2. URL biểu mẫu động: AI đưa ra một liên kết tới biểu mẫu nhập web đã được kiểm tra hợp lệ (Blazor WASM/PWA), gắn với quản lý Session và User.
3. Nhập liệu được đóng gói: Người dùng điền biểu mẫu - được kiểm tra hợp lệ nghiêm ngặt trước khi lưu.
4. Ghi trực tiếp vào Git: Biểu mẫu ghi kết quả dưới dạng tệp có cấu trúc trực tiếp vào Working-Directory của Mandant-Repository và kích hoạt commit.
5. AI tiếp quản lại: MCP-Server báo „Tệp đã cập nhật", AI xác nhận trong chat.

Lợi thế: Xác thực trước khi lưu bảo vệ Single Source of Truth. LLMs không thao túng quá trình ghi. Git-Hook/OPA-Validierung được kích hoạt ngay lập tức.

Cấu trúc thư mục .gitcover/

Thư mục .gitcover/ ở root của một GitCover-Repository là kho lưu trữ trung tâm cho mọi artifact không phải mã nguồn. Nó phục vụ an toàn kiểm soát sửa đổi, tuân thủ (GoBD/AO) và việc duy trì Audit-Trail.

Bố cục thư mục

.gitcover/
├── issues/              # Gitea-Issues als .v7g.md
├── projects/            # Projekt-Management-Daten
├── time_tracking/       # Zeiterfassung und Aufwandsnachweise
├── workflows/           # Workflow-Zustände und Genehmigungen
├── compliance/
│   ├── oscals/          # OSCAL-Dokumente (System Security Plans)
│   ├── opa/             # OPA-Regeln (Rego-Policies)
│   └── hooks/           # Git-Hooks für Automatisierung
├── audit/
│   ├── signatures/      # Kryptografische Signaturen
│   ├── timestamps/      # Zeitstempel (ELSTER/Bundesanzeiger)
│   └── logs/            # Protokolle
└── README.md            # Dokumentation der Struktur

Quy ước đặt tên tệp

Định dạng chung: {uuidV7}_{human-readable-key}_{Beschreibung}.v7g.md

Lược đồ siêu dữ liệu (.v7g.md Frontmatter)

---
uuid: 018e312f-3e4f-7000-8000-000000000000
key: "#123"
type: "issue"
title: "Bugfix: Login-Modul"
original_source: "Gitea"
original_repo_hash: "a1b2c3d4e5f6..."
related_commits: ["abc123", "def456"]
related_elements:
  project: "Projekt-X"
  milestone: "v1.0"
forensic_attributes:
  created_at: "2026-06-29T12:00:00Z"
  updated_at: "2026-06-29T14:30:00Z"
  created_by: "Person A"
compliance:
  gobd_relevant: true
  audit_trail: true
  signature: "GPG-Signatur-Hash"
  timestamp: "ELSTER-2026-06-29-120000"
---

Tự động hóa qua Git-Hooks và Webhooks

Các GitCover-Repo được cấu hình tự động với Hooks/Webhooks khi init hoặc khi Tenant Onboarding:

• post-commit: Cập nhật .gitcover/ khi có commit mới
• pre-push: Kiểm tra hợp lệ .gitcover/ trước khi push
• Webhooks: Tạo Issue, thay đổi dự án, chấm công - mỗi trường hợp đều kích hoạt xuất dưới dạng .v7g.md
• Compliance-Claim: Kích hoạt ngay các cơ chế OSCAL/OPA

Việc phiên bản hóa các Hooks/Webhooks này cũng diễn ra qua Git, nhờ đó các thay đổi có thể truy vết và kiểm toán được (tự tham chiếu, có phiên bản, an toàn kiểm soát sửa đổi). Bản thân các Hooks có thể là các Code-Artifact được phiên bản hóa, nằm trong .gitcover/hooks/, được cập nhật khi cần và được tài liệu hóa tuân thủ GoBD hoặc NIS2.

V7GUID-Sidecars

Một V7GUID-Sidecar là một tệp siêu dữ liệu *.v7g.md được đặt cạnh một tài liệu gốc số - ví dụ Rechnung_2026.pdf nhận Rechnung_2026.pdf.v7g.md trong cùng thư mục. Sidecar mang các siêu dữ liệu mà Git không thể lưu trữ bên trong một tệp nhị phân (PDF, DOCX, EML, hình ảnh), và nhờ đó neo tài liệu gốc vào chuỗi chứng từ và trong GCDMS.

Thông tin tối thiểu

Mỗi Sidecar bắt buộc phải chứa:

• sha256 - SHA-256-Hash của tài liệu gốc số (bằng chứng toàn vẹn).

Ngoài ra, nó thường ghi nhận danh tính, phân loại học và định vị lưu trữ (mẫu xem Trục 6: Các mẫu).

Cấp DocID

Nếu tài liệu chưa được quản lý trong DMS, một DocID mới sẽ được tạo. DocID là uuidv7 thuần túy - định danh thực thể cụ thể (Object ID) của Dual-Identifier, thứ material hóa từng tài liệu đơn lẻ (xem Trục 2: Các khái niệm). Cần phân biệt nó với v7guid đã được phân loại, vốn mã hóa ngữ cảnh nghiệp vụ (lớp, Tenant, Sphäre).

DocID được tạo từ một dấu thời gian, nhờ đó nó gắn với thời gian và có thể sắp xếp:

1. Công cụ: Một Sidecar-Tool tạo ra một UUIDv7 từ một đối số TimeStamp làm DocID.
2. Nguồn mặc định: dấu thời gian tệp (mtime) của tài liệu gốc.
3. Nguồn nghiệp vụ (nếu có): Nếu tên tệp hoặc nội dung cung cấp một ngày có ý nghĩa nghiệp vụ (ví dụ ngày hóa đơn, ngày email hoặc ngày văn bản quyết định), ngày này sẽ được sử dụng thay cho mtime - nhờ đó DocID gắn với ngày hình thành của tài liệu.

Cả hai định danh - DocID (uuidv7) và v7guid đã phân loại - được quản lý trong Sidecar và liên kết với nhau qua composite_key ({v7guid}:{uuidv7}).

Mối liên hệ với V7GUID và Registry

• V7GUID: Khối v7g_taxonomy sắp xếp tài liệu qua v7guid đã phân loại của nó vào hệ phân cấp Business sáu bậc và Sphäre của Tenant (xem Trục 2: Các khái niệm).
• Registry: Khối locations ghi nhận vị trí lưu trữ vật lý (UNC-Pfad, khoảng thời gian hiệu lực). Các Tenant-Identifier đã đăng ký được quản lý trong sổ đăng ký Tenant trung tâm (Zentrales Tenant-Register, Trục 2).

Cấu trúc (Ví dụ)

# V7G Sidecar - Rechnung_2026.pdf

**SHA-256:** `7d4e2f...`
**Tenant:** ORG-1
**Kategorie:** Finanzen und Buchführung
**Sphäre:** ideell

```json
{
  "$schema": "https://gitcover.org/schemas/v7g-sidecar-1.0.schema.json",
  "uuidV7": "0197a3b2-f3c0-7b00-8001-000000000042",
  "sha256": "7d4e2f...",
  "original_filename": "Rechnung_2026.pdf",
  "locations": [
    { "unc_path": "./ORG-1/FY2026/Rechnung_2026.pdf", "from": "260506", "to": null, "note": "Primärspeicherort" }
  ],
  "v7g_taxonomy": [
    { "v7guid": "0197a3b2-...-8001-...", "taxonomy": "ORG-1/Financial", "valid_from": "260506", "valid_to": null }
  ],
  "verification": { "verified_by": "auto", "method": "sha256_file", "intact": true }
}
```

Lưu trữ Issue: từ Gitea-DB đến cơ sở dữ kiện Git

Đặt vấn đề

Các Gitea-Issue là các bản ghi cơ sở dữ liệu - không phải các đối tượng Git gốc. Chúng không được phiên bản hóa và không thể tái tạo khi mất cơ sở dữ liệu Gitea. Các commit chỉ tham chiếu Issue dưới dạng văn bản (Fixes #123); tham chiếu này không được Git diễn giải.

Giải pháp: Xuất tự động dưới dạng .v7g.md

Quy trình làm việc từ cơ sở dữ liệu Gitea đến cơ sở dữ kiện an toàn kiểm soát sửa đổi:

1. Gitea-Issue được tạo → Webhook kích hoạt việc xuất
2. Xuất dưới dạng .v7g.md → Lưu vào .gitcover/issues/
3. Trích xuất siêu dữ liệu → UUID, Hashes, chữ ký
4. Git-Commit có chữ ký → git commit -S
5. OSCAL/OPA-Validierung → Kiểm tra tuân thủ
6. Dấu thời gian → Tích hợp ELSTER/Bundesanzeiger (nếu cần thiết)

Quy tắc OPA ví dụ cho việc xác thực Issue

package gcbok.compliance

violation[msg] {
  input.path == "issues"
  file := input.files[_]
  not startswith(file.name, "018")  # UUIDv7-Prüfung
  msg := sprintf("Issue %s hat keine gueltige UUIDv7 im Dateinamen", [file.name])
}

Tuân thủ GoBD/AO

Sẵn sàng kiểm toán

Sẵn sàng kiểm toán có nghĩa là: bất kỳ cuộc kiểm toán nào cũng có thể diễn ra bất cứ lúc nào - không cần chuẩn bị thêm.

Luận điểm: Phần forensic chính là Git-Repo, HTML chỉ là phần trình bày Gói kiểm tra HTML (Audit-Website, các report được tạo) là một bản phái sinh phục vụ khả năng đọc của con người. Giá trị chứng cứ forensic nằm hoàn toàn trong chính Git-Repository: Commit-History không thể thay đổi, các commit được ký GPG, các chuỗi chứng từ V7GUID, các .gitcover/ Registries/Dictionaries ở định dạng JSON/JSONL. Khi kiểm toán 10 năm sau, chỉ cần một git clone (hoặc giải nén git bundle) — không cần hạ tầng web, không cần cơ sở dữ liệu, không cần các dịch vụ đang chạy. Điều này tương ứng với Schema-Tiering (xem Các mẫu: V7GUID-Schema) và bản phái sinh gcbok-audit-evidence-docs/docs/02-audit-website-als-pruefungsartefakt.

Kết toán năm GoBD

Kết toán năm GoBD với tuân thủ Git-native:

1. Chốt kỳ - Đóng băng Git-Branch FY2026 (Tag)
2. Xác thực chuỗi chứng từ - Kiểm tra nối chuỗi V7GUID (Script)
3. Tạo OSCAL-Assessment-Results - Tự động từ các xác thực OPA
4. Cấp dấu GPG - Commit kết thúc với chữ ký GF
5. Lưu trữ - Container .v7g.zip, v7g-export

Phân tích rủi ro NIS2

Phân tích rủi ro NIS2 trên nền Git:

1. Kiểm kê asset - Các Git-Repository làm sổ đăng ký asset
2. Nhận diện rủi ro - Các OPA-Policy cho các kịch bản mối đe dọa
3. Đánh giá - Phân loại V7GUID cho các danh mục rủi ro
4. Giảm thiểu - Pre-receive-Hooks để thực thi policy
5. Báo cáo - OSCAL-Assessment-Results làm bằng chứng NIS2

Tích hợp AI-Server trong LAN

Nguyên tắc kiến trúc

GCBoK mô tả một mô hình tham chiếu cho việc tích hợp một AI-Server headless trong LAN, cung cấp tập trung suy luận LLM và các agent tuân thủ hỗ trợ bởi RAG. Môi trường AI chạy trong một môi trường container được cách ly (Rootless Podman), nhưng kết nối tới các dịch vụ được cài đặt gốc trên host để suy luận và tìm kiếm web.

SSH Script Host (OSSH)

Cho các tác vụ đòi hỏi cao (biên dịch code, thao tác Git, kiểm tra tuân thủ) vượt ra ngoài Container-Sandbox, Agent sử dụng một SSH Script Host - một lối thoát có kiểm soát, dựa trên khóa, ra khỏi hệ thống host:

1. Agent quyết định: „Chạy dotnet-build"
2. Kênh SSH: kết nối mã hóa qua id_rsa.pub tới Host-User
3. Tiến trình gốc: lệnh được thực thi trong ngữ cảnh hệ điều hành thực
4. Trả về stream: stdout/stderr được trả về dưới dạng Text-Stream
5. Agent phân tích: đầu ra trình biên dịch trong ngữ cảnh LLM

Điều kiện bảo mật: Khóa SSH được tạo trong container phải được nhập vào authorized_keys trên host. Giao tiếp diễn ra thuần túy qua các luồng dữ liệu chuẩn (stdin, stdout, stderr) - không truyền tệp.

Địa chỉ hóa đường dẫn nhất quán (FQN)

Để tránh sự không nhất quán về đường dẫn giữa Workstation, container và Script-Host, các thư mục chia sẻ của File-Server được mount tại các Mount-Point giống hệt nhau trên tất cả các hệ thống. Các AI-Agent và lập trình viên con người tham chiếu các đường dẫn tuyệt đối giống hệt nhau tại mọi thời điểm.

Khả năng Multi-Device

Nhờ tập trung hóa vào AI-Server, nhiều thiết bị đầu cuối có thể truy cập song song vào cùng một môi trường:

• Lập trình viên khởi động một phân tích code trên desktop
• Anh ta theo dõi tiến trình của Agent theo thời gian thực trên smartphone qua VPN
• Không có sự chặn lẫn nhau - Script-Host mở các Shell-Process riêng biệt, tồn tại ngắn hạn

Share-Frontends: Nextcloud làm Read-Only-Frontend

Phân vai

Điều kiện triển khai

Nextcloud có thể được sử dụng cho Shares một cách chọn lọc trong môi trường dựa trên GCBoK, nếu:

1. Chỉ Read-Only-Shares - Không thay đổi qua Nextcloud; mọi thay đổi đều chạy qua Git
2. Tích hợp Git - Nextcloud mount các Git-Repo làm bộ nhớ ngoài (WebDAV, S3-Gateway hoặc GCSYNC)
3. Xác thực policy - GCPN định nghĩa các quy tắc truy cập (OPA/Rego); Nextcloud chỉ thực thi các quy tắc đó
4. Audit-Logging - Nextcloud-Logs được chuyển tiếp tới GCAL (Syslog/Loki)
5. Tuân thủ Open-Source - Chỉ Community-Edition, không dùng plugin độc quyền

Tiêu chí loại trừ

• Ghi dữ liệu qua Nextcloud (vi phạm lưu trữ Git-native)
• Các tiện ích mở rộng Nextcloud độc quyền (vi phạm các nguyên tắc OSS)
• Thiếu tích hợp Git (Nextcloud phải có khả năng truy cập các Git-Repo)

Xem thêm: Các mẫu cho OSCAL-Katalog và OPA-Policy trong Trục 6: Các mẫu.