betriebsdokumentation-pruefung_v1.1

YAML-Inhalt

# =============================================================================
# BETRIEBSDOKUMENTATION VALIDATION CONTRACT
# =============================================================================
# Normatives Dokument zur Validierung von Server- und Betriebsdokumentation
# Version: 1.1.0
# Erstellt: 2025-12-20
# =============================================================================

meta:
  document_type: operations_documentation_validation_contract
  normative: true
  binding: mandatory
  created: 2025-12-20
  updated: 2025-12-20
  author: system_generated_under_supervision
  supersedes: betriebsdokumentation-pruefung_v1.0.yaml

identity:
  name: betriebsdokumentation_validation
  version: 1.1.0
  status: active

# =============================================================================
# SCOPE (technisch definiert)
# =============================================================================
scope:
  document_format: php_html
  file_extension: .php

  applies_to_paths:
    - /var/www/dev.campus.systemische-tools.de/src/View/docs/**/*.php
    - /var/www/prod.campus.systemische-tools.de/src/View/docs/**/*.php

  platform:
    os: Debian GNU/Linux 13 (trixie)
    init_system: systemd
    shell: bash
    web_server: Apache 2.4
    privileges_required: root

  excludes_paths:
    - "**/layout.php"
    - "**/partials/**"

# =============================================================================
# SEVERITY LEVELS (mit abgeleiteten Actions)
# =============================================================================
severity_levels:
  critical:
    description: Dokumentation ist faktisch falsch oder gefährlich
    action: reject_document
    examples:
      - Falscher Dateipfad für Konfiguration
      - Befehl mit falscher Syntax
      - Falsche Portnummer für Dienst

  major:
    description: Dokumentation ist unvollständig oder veraltet
    action: flag_for_revision
    examples:
      - Fehlende Einleitung
      - Veraltete Versionsnummer
      - Fehlender wichtiger Befehl

  minor:
    description: Kosmetische oder stilistische Probleme
    action: log_only
    examples:
      - Inkonsistente Formatierung
      - Fehlender Breadcrumb
      - Uneinheitliche Begriffe

# Action wird IMMER aus severity abgeleitet:
# critical -> reject_document
# major -> flag_for_revision
# minor -> log_only

# =============================================================================
# PASS THRESHOLD (explizite Operatoren)
# =============================================================================
pass_threshold:
  critical_violations_max: 0      # 0 erlaubt, ab 1 rejected
  major_violations_max: 2         # 0-2 erlaubt, ab 3 revision required
  minor_violations_max: 5         # 0-5 erlaubt, ab 6 approved with notes

  outcome_logic:
    - condition: "critical_violations > 0"
      result: document_rejected
    - condition: "major_violations > 2"
      result: revision_required
    - condition: "minor_violations > 5"
      result: approved_with_notes
    - condition: "all within limits"
      result: document_approved

# =============================================================================
# VALIDATION FACTORS
# =============================================================================
validation_factors:

  path_existence:
    priority: 1
    severity: critical
    # Action: reject_document (abgeleitet aus severity)
    description: Alle dokumentierten Dateipfade müssen auf dem System existieren.
    validation:
      method: filesystem_verification
      scope: "Pfade in <td> und <code> Tags, die mit / beginnen"
      verification_approach: "Prüfung ob Datei oder Verzeichnis existiert"
      excludes:
        - Platzhalter wie {name}, PORT, PASSWORD
        - Relative Pfade
        - URLs
    examples:
      valid:
        - "/etc/ssh/sshd_config.d/99-custom.conf"
        - "/opt/scripts/backup.sh"
      invalid:
        - "/etc/ssh/custom.conf"  # Existiert nicht

  command_validity:
    priority: 2
    severity: critical
    # Action: reject_document (abgeleitet aus severity)
    description: Dokumentierte Befehle müssen syntaktisch plausibel sein.
    validation:
      method: syntactic_plausibility_check
      scope: "Befehle in <pre><code> Blöcken"
      checks:
        - Befehlsname ist ein bekanntes Executable oder Builtin
        - Keine offensichtlichen Tippfehler
        - Grundlegende Optionssyntax (-- oder -)
      does_not_check:
        - Funktionale Korrektheit zur Laufzeit
        - Alle möglichen Optionskombinationen
        - Exit-Codes
    examples:
      valid:
        - "systemctl status apache2"
        - "certbot renew --dry-run"
      invalid:
        - "systemctl status apche2"  # Tippfehler
        - "cerbot renew"  # Falscher Befehlsname

  service_accuracy:
    priority: 3
    severity: critical
    # Action: reject_document (abgeleitet aus severity)
    description: Dienst-Informationen müssen mit laufendem System übereinstimmen.
    platform_requirement: "Debian 13 mit Systemd, Root-Rechte"
    validation:
      method: service_state_verification
      checks:
        port:
          description: "Dokumentierter Port muss vom Dienst genutzt werden"
          tolerance: none
        version:
          description: "Major.Minor Version muss stimmen"
          tolerance: patch_version  # 8.4.x ist ok wenn 8.4 dokumentiert
        status:
          description: "Dokumentierter Status muss aktuell sein"
          tolerance: none

  config_correctness:
    priority: 4
    severity: major
    # Action: flag_for_revision (abgeleitet aus severity)
    description: Konfigurationsbeispiele müssen mit echten Dateien übereinstimmen.
    validation:
      method: config_comparison
      scope: "Konfig-Blöcke in <pre><code> mit referenziertem Dateipfad"
      tolerance:
        whitespace: ignore
        comments: ignore
        order: flexible
      allowed_placeholders:
        - "{{REDACTED}}"
        - "PASSWORD"
        - "SECRET"
        - "your-value-here"
      note: "Dokumentation darf bewusst reduzierte oder anonymisierte Konfigs zeigen"

  structure_compliance:
    priority: 5
    severity: major
    # Action: flag_for_revision (abgeleitet aus severity)
    description: Module müssen die PHP/HTML-Strukturvorgaben einhalten.
    format: php_html
    required_elements:
      breadcrumb:
        element: "nav.breadcrumb"
        contains: "Links zu /docs und Kategorie"
      title:
        element: "h1"
        content: "Modulname"
      introduction:
        element: "p"
        position: "Direkt nach h1"
        content: "1-2 Sätze Erklärung"
      info_table:
        element: "table"
        contains: "Mindestens Version/Port/Pfad"
      commands:
        element: "pre > code"
        content: "Wichtigste Verwaltungsbefehle"
    optional_elements:
      - "h2 Subsections"
      - "Zusätzliche Tabellen"
      - "Listen (ul/ol)"

  link_integrity:
    priority: 6
    severity: major
    # Action: flag_for_revision (abgeleitet aus severity)
    description: Interne Links müssen zu existierenden Routen führen.
    validation:
      method: route_verification
      scope: 'href Attribute die mit "/docs" beginnen'
      checks:
        - Route existiert im DocsController
        - Ziel-View-Datei existiert

  terminology:
    priority: 7
    severity: minor
    # Action: log_only (abgeleitet aus severity)
    description: Begriffe im Fließtext sollten einheitlich sein.
    validation:
      method: terminology_consistency
      scope: "Nur Fließtext (p, li), NICHT code, pre, td mit Pfaden"
      preferred_terms:
        - prefer: "Dienst"
          avoid: "Service"
          context: "Fließtext"
        - prefer: "Befehl"
          avoid: "Command"
          context: "Fließtext"
      exceptions:
        - "Service in englischen Eigennamen (systemd service)"
        - "Technische Begriffe in Code-Kontexten"

# =============================================================================
# ENFORCEMENT (harte Regeln)
# =============================================================================
enforcement:
  on_sync_to_prod:
    rule: "BLOCKIERT bei critical_violations > 0"
    process:
      1: "Validierung vor /opt/scripts/sync-dev-prod.sh"
      2: "Bei critical violation: Sync wird NICHT ausgeführt"
      3: "Fehler müssen erst behoben werden"

  on_new_module:
    rule: "Alle required_elements aus structure_compliance müssen vorhanden sein"

  periodic_review:
    frequency: monthly
    scope: all_modules
    focus: "service_accuracy (Versionen, Ports)"

# =============================================================================
# REPORT TEMPLATE (empfohlen, nicht normativ)
# =============================================================================
report_template:
  note: "Dieses Template ist eine Empfehlung, keine Pflicht"
  fields:
    - module_name
    - validation_date
    - critical_count
    - major_count
    - minor_count
    - outcome
    - findings_list

Aktionen

← Zurück zur Übersicht