shieldx/ai-act-kompass/src/engine/extraDocs.ts

import type { Locale } from '../i18n/types';
import { docStrings, formatDocDate } from './docStrings';
import type { AISystem, CompanyProfile, ContentPack } from './types';

/** Anforderung im Lastenheft. */
interface Requirement {
  readonly id: string;
  readonly must: boolean;
  readonly de: string;
  readonly en: string;
  /** Nur bei Hochrisiko aufnehmen. */
  readonly highOnly?: boolean;
}

const REQUIREMENTS: readonly Requirement[] = [
  { id: 'REQ-01', must: true, highOnly: true,
    de: 'CE-Kennzeichnung und EU-Konformitätserklärung (Art. 47, 48) liegen vor und werden mitgeliefert.',
    en: 'CE marking and EU declaration of conformity (Art. 47, 48) exist and are supplied.' },
  { id: 'REQ-02', must: true, highOnly: true,
    de: 'Registrierung des Systems in der EU-Datenbank (Art. 49) ist nachgewiesen.',
    en: 'Registration of the system in the EU database (Art. 49) is evidenced.' },
  { id: 'REQ-03', must: true,
    de: 'Vollständige Betriebsanleitung nach Art. 13 (Zweckbestimmung, Genauigkeit, Grenzen, Aufsicht, Wartung) in der Vertragssprache.',
    en: 'Complete instructions for use under Art. 13 (purpose, accuracy, limitations, oversight, maintenance) in the contract language.' },
  { id: 'REQ-04', must: true, highOnly: true,
    de: 'Logging-Fähigkeit nach Art. 12: automatische Ereignisprotokolle sind für den Betreiber zugänglich und mind. 6 Monate speicherbar.',
    en: 'Logging capability under Art. 12: automatic event logs are accessible to the deployer and storable for at least 6 months.' },
  { id: 'REQ-05', must: true, highOnly: true,
    de: 'Schnittstellen für menschliche Aufsicht nach Art. 14 (Eingriff, Abbruch, Übersteuerung) sind vorhanden und dokumentiert.',
    en: 'Human oversight interfaces under Art. 14 (intervention, stop, override) exist and are documented.' },
  { id: 'REQ-06', must: true, highOnly: true,
    de: 'Nachweis von Genauigkeit, Robustheit und Cybersicherheit nach Art. 15 inkl. Schutz gegen Prompt Injection, Data Poisoning und Adversarial Attacks.',
    en: 'Evidence of accuracy, robustness and cybersecurity under Art. 15 incl. protection against prompt injection, data poisoning and adversarial attacks.' },
  { id: 'REQ-07', must: true,
    de: 'Transparenzfunktionen nach Art. 50 (KI-Offenlegung, maschinenlesbare Kennzeichnung synthetischer Inhalte) sind implementiert, soweit einschlägig.',
    en: 'Transparency features under Art. 50 (AI disclosure, machine-readable marking of synthetic content) are implemented where applicable.' },
  { id: 'REQ-08', must: true,
    de: 'Unterstützung bei Vorfallmeldungen: Anbieter meldet schwerwiegende Vorfälle (Art. 73) und informiert den Auftraggeber unverzüglich.',
    en: 'Incident reporting support: provider reports serious incidents (Art. 73) and informs the customer without undue delay.' },
  { id: 'REQ-09', must: true,
    de: 'DSGVO-Konformität: Auftragsverarbeitungsvertrag, Angaben zu Datenflüssen, Speicherorten (EU), Unterauftragnehmern und Löschkonzept.',
    en: 'GDPR conformity: data processing agreement, information on data flows, storage locations (EU), sub-processors and deletion concept.' },
  { id: 'REQ-10', must: false,
    de: 'Update- und Support-Zusagen: Sicherheitsupdates, Re-Zertifizierung bei wesentlichen Änderungen, Reaktionszeiten.',
    en: 'Update and support commitments: security updates, re-certification upon substantial modification, response times.' },
  { id: 'REQ-11', must: false,
    de: 'Exit-Strategie: Datenexport in offenem Format, Übergabe von Konfiguration und Protokollen bei Vertragsende.',
    en: 'Exit strategy: data export in an open format, handover of configuration and logs at contract end.' },
  { id: 'REQ-12', must: false, highOnly: true,
    de: 'Einsicht in relevante Teile der technischen Dokumentation (Annex IV) unter Vertraulichkeit, soweit für Betreiberpflichten erforderlich.',
    en: 'Access to relevant parts of the technical documentation (Annex IV) under confidentiality, insofar as required for deployer duties.' },
];

const PROC = {
  de: {
    title: 'Lastenheft KI-Beschaffung — AI-Act-Anforderungen an den Anbieter',
    intro:
      'Dieses Lastenheft definiert die regulatorischen Mindestanforderungen (EU AI Act, DSGVO) an den Anbieter des unten bezeichneten KI-Systems. Es ist Grundlage für Angebot, Pflichtenheft und Vertrag.',
    colId: 'Nr.', colReq: 'Anforderung', colPrio: 'Priorität', colFulfilled: 'Erfüllt (Anbieter)',
    must: 'MUSS', should: 'SOLL', fulfilled: 'JA / NEIN / TEILWEISE',
    note: 'Hinweis: Bei Hochrisiko-Systemen gelten alle MUSS-Anforderungen zwingend; Nichterfüllung schließt die Beauftragung aus.',
  },
  en: {
    title: 'AI procurement requirements specification — AI Act requirements for the provider',
    intro:
      'This requirements specification defines the minimum regulatory requirements (EU AI Act, GDPR) for the provider of the AI system identified below. It forms the basis for offer, implementation specification and contract.',
    colId: 'No.', colReq: 'Requirement', colPrio: 'Priority', colFulfilled: 'Fulfilled (provider)',
    must: 'MUST', should: 'SHOULD', fulfilled: 'YES / NO / PARTIALLY',
    note: 'Note: For high-risk systems all MUST requirements are mandatory; non-fulfilment excludes the award.',
  },
} as const;

/**
 * Erzeugt das Lastenheft für die KI-Beschaffung (Betreiber-Perspektive):
 * AI-Act-Anforderungen, die der Anbieter erfüllen und im Pflichtenheft
 * beantworten muss.
 *
 * @param system - Bewertetes KI-System
 * @param pack - Regulatorischer Content-Pack
 * @param today - Stichtag im ISO-Format
 * @param profile - Firmenprofil für den Berichtskopf (optional)
 * @param locale - Dokumentsprache (Default: Deutsch)
 */
export function procurementSpec(
  system: AISystem,
  pack: ContentPack,
  today: string,
  profile?: CompanyProfile,
  locale: Locale = 'de',
): string {
  const s = docStrings(locale);
  const p = PROC[locale];
  const high = system.classification.riskClass === 'high';
  const requirements = REQUIREMENTS.filter((r) => high || !r.highOnly);

  const lines = [
    `# ${p.title}`,
    '',
    `| | |`,
    `|---|---|`,
    ...(profile && profile.name.trim() !== '' ? [`| **${s.meta.company}** | ${profile.name} |`] : []),
    `| **${s.meta.system}** | ${system.name} |`,
    `| **${s.meta.purpose}** | ${system.purpose || '—'} |`,
    `| **${s.meta.riskClass}** | ${s.risk[system.classification.riskClass]} |`,
    `| **${s.meta.createdAt}** | ${formatDocDate(today, locale)} |`,
    `| **${s.meta.contentPack}** | v${pack.version} |`,
    '',
    s.disclaimer,
    '',
    p.intro,
    '',
    `| ${p.colId} | ${p.colReq} | ${p.colPrio} | ${p.colFulfilled} |`,
    '|---|---|---|---|',
  ];
  for (const r of requirements) {
    lines.push(`| ${r.id} | ${r[locale]} | ${r.must ? p.must : p.should} | ${p.fulfilled} |`);
  }
  lines.push('', p.note);
  return lines.join('\n');
}

const DECL = {
  de: {
    title: 'EU-Konformitätserklärung (Entwurf, Art. 47 / Annex V)',
    intro:
      'Entwurf auf Basis von Annex V der Verordnung (EU) 2024/1689. Vor Verwendung rechtlich prüfen und durch die Geschäftsleitung unterzeichnen.',
    fields: [
      ['1. KI-System (Name, Typ, Version)', ''],
      ['2. Anbieter (Name und Anschrift)', ''],
      ['3. Verantwortung', 'Die alleinige Verantwortung für die Ausstellung dieser Konformitätserklärung trägt der Anbieter.'],
      ['4. Gegenstand der Erklärung', 'Das oben bezeichnete KI-System steht im Einklang mit der Verordnung (EU) 2024/1689 und ggf. weiteren einschlägigen Harmonisierungsvorschriften der Union.'],
      ['5. Angewandte harmonisierte Normen / gemeinsame Spezifikationen', '_[AUSFÜLLEN]_'],
      ['6. Notifizierte Stelle (falls einschlägig)', 'Name, Kennnummer, Bescheinigung: _[AUSFÜLLEN]_'],
      ['7. DSGVO-Erklärung (falls personenbezogene Daten verarbeitet werden)', 'Das System entspricht den Verordnungen (EU) 2016/679 und (EU) 2018/1725 bzw. der Richtlinie (EU) 2016/680.'],
      ['8. Ort, Datum der Ausstellung', '_[AUSFÜLLEN]_'],
      ['9. Unterzeichnet für und im Namen von', 'Name, Funktion, Unterschrift: _[AUSFÜLLEN]_'],
    ],
  },
  en: {
    title: 'EU declaration of conformity (draft, Art. 47 / Annex V)',
    intro:
      'Draft based on Annex V of Regulation (EU) 2024/1689. Have it legally reviewed and signed by management before use.',
    fields: [
      ['1. AI system (name, type, version)', ''],
      ['2. Provider (name and address)', ''],
      ['3. Responsibility', 'This declaration of conformity is issued under the sole responsibility of the provider.'],
      ['4. Object of the declaration', 'The AI system identified above is in conformity with Regulation (EU) 2024/1689 and, where applicable, other relevant Union harmonisation legislation.'],
      ['5. Applied harmonised standards / common specifications', '_[TO BE COMPLETED]_'],
      ['6. Notified body (where applicable)', 'Name, identification number, certificate: _[TO BE COMPLETED]_'],
      ['7. GDPR statement (where personal data is processed)', 'The system complies with Regulations (EU) 2016/679 and (EU) 2018/1725 or Directive (EU) 2016/680.'],
      ['8. Place and date of issue', '_[TO BE COMPLETED]_'],
      ['9. Signed for and on behalf of', 'Name, function, signature: _[TO BE COMPLETED]_'],
    ],
  },
} as const;

/**
 * Erzeugt den Entwurf der EU-Konformitätserklärung (Anbieter, Hochrisiko).
 *
 * @param system - Bewertetes KI-System
 * @param pack - Regulatorischer Content-Pack
 * @param today - Stichtag im ISO-Format
 * @param profile - Firmenprofil (Anbieterangaben werden vorbefüllt)
 * @param locale - Dokumentsprache (Default: Deutsch)
 */
export function conformityDeclaration(
  system: AISystem,
  _pack: ContentPack,
  today: string,
  profile?: CompanyProfile,
  locale: Locale = 'de',
): string {
  const s = docStrings(locale);
  const d = DECL[locale];
  const provider =
    profile && profile.name.trim() !== ''
      ? [profile.name, profile.street, profile.zipCity].filter((x) => x.trim() !== '').join(', ')
      : s.todo;

  const lines = [`# ${d.title}`, '', s.disclaimer, '', d.intro, ''];
  for (const [label, preset] of d.fields) {
    let value: string = preset;
    if (label.startsWith('1.')) value = `${system.name}${system.purpose ? ` — ${system.purpose}` : ''}`;
    if (label.startsWith('2.')) value = provider;
    if (label.startsWith('8.')) value = `${profile?.zipCity ?? ''} ${formatDocDate(today, locale)}`.trim();
    lines.push(`## ${label}`, '', value || s.todo, '');
  }
  return lines.join('\n');
}