Trục 5: Quy trình thực hiện

Onboarding cho KMU

Việc các doanh nghiệp vừa và nhỏ (KMU) bắt đầu với Compliance Git-native tuân 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, các khối BSI hoặc hồ sơ 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ỗi chủ thể một cặp khóa GPG
5. Bắt đầu chuỗi chứng từ - Gán các V7GUID đầu tiên, bắt đầu liên kết prev-hash

Dành cho các doanh nhân từ cấp độ kinh doanh phụ

Việc bắt đầu có thể xuất phát từ một câu chuyện 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: "Thành phố Compliance"

Thay vì các bảng hỏi truyền thống, onboarding được thực hiện dưới dạng một quá trình lắp dựng mô-đun theo khái niệm một thành phố trên một tấm nền 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 nhóm lắp ráp (Lego-Set), được lưu trữ và quản lý phiên bản dưới dạng mô-đun có cấu trúc trong Git-Repository mặc định mới được khởi tạo.

Sự tương tự dành cho người dùng:

• Tấm nền: Git-Repository trống, mới được tạo cho Tenant trong hạ tầng của nó. Nó cung cấp khung được chuẩn hóa (các núm gờ), nơi mọi thứ kết nối 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 (Git-Commit), chức năng hoặc kiểm tra Compliance tương ứng mới được kích hoạt.

Giai đoạn 1 - Lót tấm nền (Khởi tạo & Định danh):

Hệ thống tự động tạo Repository mặc định 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 Compliance có thể kiểm toán đầu tiên. Nhân tiện: Các Tenant dĩ nhiên cũng có thể được tổ chức theo cấu trúc phân cấp, 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 (Lưới cung cấp):

Trợ lý ghi nhận toàn cảnh CNTT: trạm làm việc laptop, File-Server, hạ tầng Cloud-first hoặc hạ tầng lai. Các tham số như kết nối Internet, tên miền, đường dẫn Storage v.v. được đưa vào các thông tin hạ tầng và chuẩn bị các đường dẫn cho các kết nối ngang (others.json).

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

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

Người dùng không bao giờ nhìn thấy các tệp cấu hình hay mã nguồn. 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 hoàn toàn an toàn kiểm toán theo GoBD và AO ngay từ phút đầu tiên.

Cách ly Tenant 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 tối ưu cho các môi trường Compliance đa tenant, an toàn cho người không chuyên. Trong others.json tập hợp:

1. Các tuyến chuẩn tắc đến các Git-Repository riêng của Tenant
2. Các kết nối ngang đến các 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à các tư cách thành viên nhóm). Một Inlet-Pipeline đọc others.json tùy theo User-Claim và chèn các đường dẫn được phép dưới dạng System-Prompt:

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

Mô hình Claim hai cấp cho quyền truy cập PII

Đối với việc truy cập dữ liệu cá nhân (PII), GCBoK định nghĩa một phân cấp Claim với hai cấp (xem Kỹ thuật: Git với tư cách IdP:

others.json ánh xạ các Claim này đến 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 có org_unit_id = ORG-1-Portfolio nhận được quyền truy cập vào PII/ORG-1-Portfolio, nhưng không truy cập được vào PII/ORG-2-IT — ngay cả khi có 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 an ninh này vẫn vô hình. Họ đăng nhập, thấy môi trường làm việc quen thuộc của mình và AI tự động biết nơi mình được phép hoạt động.

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

Các Chat-Interface phù hợp cho ngữ cảnh và phân tích, không phù hợp cho việc thu thập dữ liệu đòi hỏi kiểu dữ liệu nghiêm ngặt (IBAN, mã bưu chính, OSCAL-Schema). 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 địa điểm kinh doanh mới."
2. URL biểu mẫu động: AI đưa ra một liên kết đến một màn hình nhập liệu Web đã được xác thực (Blazor WASM/PWA), được ghép nối với quản lý Session và User.
3. Nhập liệu được bao bọc: Người dùng điền vào biểu mẫu - được xác thực 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 Repository Tenant và kích hoạt Commit.
5. AI tiếp quản lại: MCP-Server báo "Tệp đã được cập nhật", AI xác nhận trong Chat.

Ưu điểm: Xác thực trước khi lưu bảo vệ Single Source of Truth. Các LLM 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/ ở thư mục gốc của một GitCover-Repository là kho lưu trữ trung tâm cho tất cả các hiện vật không phải mã nguồn. Nó phục vụ tính an toàn kiểm toán, Compliance (GoBD/AO) và việc quản lý 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}_{Mô tả}.v7g.md

Schema 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 bằng Git-Hooks và Webhooks

Các GitCover-Repo được tự động cấu hình 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: Xác thực .gitcover/ trước khi Push
• Webhooks: Tạo Issue, thay đổi dự án, ghi nhận thời gian - mỗi loại kích hoạt việc xuất dưới dạng .v7g.md
• Compliance-Claim: Kích hoạt ngay lập tức các cơ chế OSCAL/OPA

Việc quản lý phiên bản của các Hooks/Webhooks này cũng được thực hiện qua Git, để các thay đổi có thể truy vết và kiểm toán (tự tham chiếu, có phiên bản, an toàn kiểm toán). Bản thân các Hook có thể là các hiện vật mã nguồn có phiên bản, nằm trong .gitcover/hooks/, được cập nhật khi cần và được tài liệu hóa phù hợp với GoBD hoặc NIS2.

V7GUID-Sidecar

Một V7GUID-Sidecar là một tệp siêu dữ liệu *.v7g.md, được lưu trữ bên cạnh một tài liệu gốc kỹ thuật số - ví dụ Rechnung_2026.pdf nhận được 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 giữ tài liệu gốc trong chuỗi chứng từ và trong GCDMS.

Thông tin tối thiểu

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

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

Bên cạnh đó, nó thường còn chứa danh tính, phân loại và vị trí (xem mẫu tại Trục 6: Mẫu).

Gán 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, vốn cụ thể hóa tài liệu đơn lẻ (xem Trục 2: Khái niệm). Do đó, nó cần được phân biệt với v7guid đã phân loại, vốn mã hóa ngữ cảnh nghiệp vụ (Lớp, Tenant, Lĩnh vực).

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

1. Công cụ: Một Sidecar-Tool tạo 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 quyết định), ngày này được sử dụng thay cho mtime - DocID như vậy gắn với ngày phát sinh của tài liệu.

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

Mối quan hệ với V7GUID và Registry

• V7GUID: Khối v7g_taxonomy xếp tài liệu thông qua v7guid đã phân loại của nó vào hệ thống phân cấp Business sáu cấp và lĩnh vực của Tenant (xem Trục 2: Khái niệm).
• Registry: Khối locations tài liệu hóa vị trí lưu trữ vật lý (đường dẫn UNC, khoảng thời gian hiệu lực). Các định danh Tenant đã đăng ký được quản lý trong sổ đăng ký Tenant trung tâm (Sổ đăng ký Tenant trung tâm, 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 nền tảng dữ kiện Git

Mô tả vấn đề

Các Gitea-Issue là các mục cơ sở dữ liệu - không phải là đối tượng Git nguyên sinh. Chúng không được quản lý phiên bản 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ạng văn bản (Fixes #123); tham chiếu này không được Git diễn giải.

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

Quy trình làm việc từ cơ sở dữ liệu Gitea đến nền tảng dữ kiện an toàn kiểm toán:

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, các Hash, các chữ ký
4. Git-Commit có chữ ký → git commit -S
5. Xác thực OSCAL/OPA → Kiểm tra Compliance
6. Dấu thời gian → Tích hợp ELSTER/Bundesanzeiger (nếu cần)

Quy tắc OPA mẫu cho 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])
}

Tính tuân thủ GoBD/AO

Audit-Readiness

Audit-Readiness có nghĩa là: Mọi cuộc kiểm toán đều có thể diễn ra bất kỳ lúc nào - không cần xử lý hậu kỳ.

Luận điểm: Pháp y chính là Git-Repo, HTML chỉ là trình bày Gói kiểm tra HTML (Audit-Website, các báo cáo được tạo) là một dẫn xuất phục vụ khả năng đọc của con người. Giá trị chứng minh pháp y nằm hoàn toàn trong chính Git-Repository: Commit-History bất biến, các Commit ký GPG, các chuỗi chứng từ V7GUID, các Registry/Dictionary .gitcover/ ở định dạng JSON/JSONL. Trong một cuộc kiểm toán 10 năm sau, một git clone (hoặc giải nén git bundle) là đủ — 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 Mẫu: V7GUID-Schema) và dẫn xuất gcbok-audit-evidence-docs/docs/02-audit-website-als-pruefungsartefakt.

Kết sổ năm theo GoBD

Kết sổ năm theo GoBD với Compliance Git-native:

1. Chốt kỳ kế toán - Đóng băng Git-Branch FY2026 (Tag)
2. Xác thực chuỗi chứng từ - Kiểm tra liên kết 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 tảng Git:

1. Kiểm kê tài sản - Các Git-Repository làm sổ đăng ký tài sản
2. Nhận diện rủi ro - OPA-Policies cho các kịch bản đ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 máy chủ AI 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 máy chủ AI headless trong LAN, máy chủ này cung cấp một cách tập trung suy luận LLM và các Compliance-Agent hỗ trợ RAG. Môi trường AI chạy trong một môi trường Container cách ly (Rootless Podman), tuy nhiên ghép nối với các dịch vụ được cài đặt nguyên sinh trên Host cho việc suy luận và tìm kiếm Web.

SSH Script Host (OSSH)

Đối với các nhiệm vụ đòi hỏi cao (biên dịch mã, các thao tác Git, các kiểm tra Compliance) 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, sang hệ thống Host:

1. Agent quyết định: "Thực thi dotnet-build"
2. Kênh SSH: kết nối được mã hóa qua id_rsa.pub đến Host-User
3. Quá trình nguyên sinh: Lệnh được thực thi trong bối 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 Compiler trong bối cảnh LLM

Điều kiện tiên quyết về an ninh: Khóa SSH được tạo trong Container phải được đưa 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 có việc truyền tệp.

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

Để tránh tình trạng không nhất quán đường dẫn giữa Workstation, Container và Script-Host, các chia sẻ File-Server được gắn kết 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 chỉ dẫn đường dẫn tuyệt đối giống hệt nhau tại mọi thời điểm.

Khả năng đa thiết bị

Nhờ tập trung hóa vào máy chủ AI, 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 mã trên Desktop
• Anh ấy theo dõi tiến độ của Agent theo thời gian thực trên Smartphone qua VPN
• Không có tình trạng chặn lẫn nhau - Script-Host mở các quá trình Shell riêng biệt, ngắn hạn

Share-Frontend: Nextcloud với tư cách Read-Only-Frontend

Phân bổ vai trò

Điều kiện để triển khai

Nextcloud có thể được triển khai chọn lọc cho Share trong một môi trường dựa trên GCBoK, nếu:

1. Chỉ Read-Only-Share - Không có thay đổi nào qua Nextcloud; mọi biến đổi đều chạy qua Git
2. Tích hợp Git - Nextcloud gắn kết 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ỉ hiện thực hóa chúng
4. Audit-Logging - Các log Nextcloud được chuyển tiếp đến GCAL (Syslog/Loki)
5. Tuân thủ Open-Source - Chỉ Community-Edition, không có plugin độc quyền

Tiêu chí loại trừ

• Quyền ghi qua Nextcloud (vi phạm lưu trữ Git-native)
• Các phần 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ó thể truy cập vào các Git-Repo)

Xem thêm: Các mẫu cho OSCAL-Katalog và OPA-Policies tại Trục 6: Mẫu.