Orchestrator/bahn/wissensdatenbank/docs/TODO.md

TODO / Roadmap

Leitprinzipien (immer beachten)

• Qualitaet vor Menge. Lieber weniger, dafuer sauberes/freigegebenes Wissen.
• Einfach konfigurierbar. Neues Wissen ueber config/tools.yaml / config/general.yaml ergaenzbar (Domaene/Tool + Link + Strategie + Scope), ohne Code zu aendern.
• Transparenz. Jederzeit sichtbar, welches Wissen wo liegt und mit welchen Tags (GitLab Pages: Uebersicht + Wissensquellen, Frontmatter).

Offen (Code/Inhalt)

Bugs / beobachten

• Confluence-Abruf schlug im CI fehl (gefunden 2026-06-28 im ETL-Log): alle confluence_*-Quellen brachen mit No scheme supplied ab (CI-Variable CONFLUENCE_URL ohne https://) -> pathos/nur/mateo/infraportal/rechnungsbahnhof wurden nicht aktualisiert. URL inzwischen korrigiert - der naechste ETL-Lauf muss bestaetigen, dass es wieder laedt (jetzt in output/run_log.jsonl als sources_failed: 0 sichtbar).
• ETL-Sichtung insb. wegen Dateigroesse (naechster Check: 2026-06-30): nach dem Merge von chore/data-to-output (v2.0.0) pruefen, ob der naechste ETL-Lauf sauber durchlaeuft (output/staging-Trennung in CI korrekt? run_log.jsonl Fehler-frei?). Ausserdem Repo-Groesse im Auge behalten – gerade die INB-Chunks erzeugen viele Dateien. Ggf. alte Chunk-Generationen (output/chunks/) per Shallow-Clone oder LFS-Strategie entschaerfen, falls das Repo >500 MB waechst.

Monitoring / Logging

• ETL-Laeufe regelmaessig pruefen - jetzt einfach ueber output/run_log.jsonl (letzte Laeufe inkl. Fehler je Quelle) bzw. die Health-Zeile in der Pages-Fusszeile.
• Lauf-Log umgesetzt (output/run_log.jsonl, append-only, gekappt auf 500): Zeit, verarbeitete Dokumente, Status-Counts, Fehler je Quelle; Health-Zeile auf der Uebersicht; Manifest-Eintrag auf der Chatbot-Seite. (v1.3.0)

Inhalt / Datenqualitaet

• Dedup ueberlappender Quellen (v1.4.0): gleiche Seite je scope/domaene nur ein Dokument (Gate-Dedup per page_identity, spezifischere Aufbereitung gewinnt) + prune_duplicate_files. Einmalig 42 Alt-Duplikate entfernt (v.a. nur).
• pathOS „FAQ PathOS Extern" wieder erfasst (v1.3.1): Seite ist h2/Absatz-basiert, nicht als Q/A-Tabelle -> Strategie von confluence_faq auf confluence_page umgestellt. Vorher landete das komplette externe FAQ leer in pending.
• Confluence-Anhaenge (eingebundene PDFs) werden erfasst (v1.5.0): bei confluence_page/confluence_tree werden view-file/viewpdf-Anhaenge ueber den PDF-Parser zu Markdown und als eigene Dokumente (kind: attachment, parent_url -> Seite) abgelegt. Inkrementell. Default an, per options: { attachments: false } abschaltbar. Bilder: alt-Text bleibt als [Bild: ...] erhalten (Variante A). Offen/optional: drawio-Diagramme (Text aus XML extrahieren) - aktuell nicht erfasst.
• INB-Sectioning / Chunking umgesetzt (v1.1.0/1.2.0): heading-basiert, deterministisch, inkrementell, output/chunks/, Katalog output/_index.json. Default aus, aktiv fuer INB. Spaeter ggf. weitere grosse Dokumente (Regelwerk).

Ideen (Konzept steht, Entscheidung offen)

• #1 Nachtraegliches Taggen. Regelbasiert: config/tag_rules.yaml (match: domain/url/titel/keyword -> add_tags) + Befehl python -m src.retag, der NUR die tags:-Zeile im Frontmatter neu schreibt (Body unveraendert -> content_hash stabil, kein Netz, idempotent), committet. Optional spaeter LLM/Keyword-Vorschlaege, die in die Regeln einfliessen. Auf Pages ggf. Tag-Filter/Tag-Wolke. Gut v.a. fuer allgemeines Wissen (Kundeninfos). Aufwand: mittel.
• #5 Intern/extern aus EINER Confluence-Seite trennen. Regel: extern ⊆ intern (nur EINE Richtung). Marker fuer interne Abschnitte (Konvention zu entscheiden: Panel/Info-Makro vs. Textmarker [[intern]]..[[/intern]] vs. Ueberschrift „Nur intern"). Quelle scope: "intern,extern": intern = ganze Seite; extern = interne Bloecke entfernt (zu kurz -> nur intern). Sicherheitsnetz: content_filter prueft extern weiter. Erkennung im md_converter + Tests + Redakteurs-Doku. Aufwand: mittel-hoch, Leak-Risiko bei vergessenem Marker -> „im Zweifel raus".

Bedienbarkeit

• Helfer scripts/add_tool.py (interaktiv: Domaene + Link + Strategie + Scope, inkl. yaml-Validierung) als Zwischenschritt zur Web-App.
• Web-App (Option C, mittelfristig): Flask auf DBCS, Formular -> GitLab-API legt MR an, mit Live-Vorschau. Pages verlinkt darauf. (Skill dbcs-python-webapp.)
• Issue->MR-Bot verdrahten: Webhook-Service ODER scheduled glab-Job, der scripts/issue_to_source.py ausfuehrt und automatisch einen MR samt Vorschau anlegt. (Bausteine scripts/issue_to_source.py + scripts/issue_to_mr.sh sind da.)

Quality Gates

• min_quality-Schwelle in filter_rules.json: content_filter setzt Docs unter der Schwelle auf pending („niedrige Qualitaet"). Erst Verteilung sichten, dann aktiv schalten. (Score + Aufschluesselung sind jetzt auf den Pages sichtbar.)
• gitleaks-Baseline (.gitleaks.toml) fuer False Positives in data/, dann secret-scan scharf schalten (aktuell allow_failure: true).

Vereinfachungen

• Strategie kundeninfo entfernt (war redundant zu crawler/sitemap); inkl. ComponentType.KUNDENINFO + ComponentType.DEEPLINK (beide ungenutzt).
• docs/catalog.md (src/catalog.py) abgeschafft – Seite „Wissensquellen" (config.html) ersetzt es.
• docs/review_queue.md (src/review_queue.py) abgeschafft – Pages-Uebersicht zeigt pending/rejected inkl. Grund + Aktionslinks.
• --only bleibt (vom MR-preview-Job genutzt).

Betrieb / Skalierung

• CI-Timeout fuer knowledge-etl im Auge behalten (inkrementell unkritisch, ein Timeout wird vom naechsten Lauf nachgeholt).
• Hinweis: Korpus bleibt bewusst in Git (kein externer Speicher) – Repo = Single Source of Truth.

---

Out of scope (vorerst, bewusst zurueckgestellt)

• Mehr externes Wissen pro Tool (eigene kund:innenfaehige Confluence-Seite).
• Owners-Backfill fuer alte kundeninfo-/INB-Dokumente (bleiben ohne Owner).

---

Erledigt (Kern)

• ETL-Grundgeruest: Extract (Confluence/Web/Sitemap/PDF/GitLab/File) -> Transform (md_converter, tagger, content_filter) -> Review-Gate (approved/pending).
• Strategien: confluence_page/tree/faq, crawler, sitemap, pdf, gitlab_md, file.
• Strategie-Erkennung pro URL (src/strategy_detect.py), unbekannte URLs flaggen.
• Scope-Modell: tool-weit intern|extern|allgemein|mixed, source intern,extern (ganze Seite fuer beide). Pro-Seite-Trennlogik bewusst entfernt.
• Output output/processed/<scope>/<domaene>[/<tool>] IST der Vektor-DB-Feed (kein separater ingest-Export).
• Gate 2: Allowlist config/approvals.yaml (URL/Hash) im content_filter; review_notes erklaeren WARUM pending.
• Quality-Score (0-100) pro Dokument (src/quality.py), auf Pages + Hilfe erklaert.
• INB-Feintuning: pymupdf4llm-Parser (parser: pymupdf) -> echte Markdown-Tabellen; INB 2026/2027 + Regelwerk; PDF-Connector inkrementell (max_pdfs, keep_raw, redact-Option).
• Confluence inkrementell (options: { incremental: true }): Versions-Check pro Seite, unveraenderte Seiten werden uebersprungen (source_version im Frontmatter).
• GitLab Pages (DB-UX): Logo, Footer (Sebastian Reinig · V.IWF 91 · #Einfachbahn), Filter (extern/intern/allgemein/pending), Suche, Quality-Score sichtbar, Modal mit Inhalt/Quality-Aufschluesselung/Aktionslinks.
• Smoke-Test fuer src.site.build() (erzeugt index/hilfe/chatbot/config/changelog + json).
• Hilfe-Seite (hilfe.html): Strategien-Tabelle, Ablauf, pending/rejected-Gruende.
• Chatbot-Anschluss-Seite (chatbot.html): welche Pfade pro Bot-Typ, wie Frontmatter zu interpretieren ist, Pruefhinweis, RAG-Ablauf.
• CI: PyPI-Mirror (PIP_INDEX_URL) statt Deps-Image; test/etl/pages ohne Custom-Image. Test-Fix python -m pytest. renovate.
• CI: stuendlicher Daten-Commit (Mo-Fr 8-17) loest pages-Refresh aus (kein ci.skip mehr), damit die Live-Seite nach dem Schedule aktuell ist.
• Owners (1-2 Ansprechpartner) pro Tool/Quelle -> Frontmatter/Katalog/Pages.
• Issue-/MR-Templates, CODEOWNERS, docs/SETUP.md, scm-info.yaml, Architektur-Steering mit Diagrammen.
• Pages: einheitliches Sticky-Menu auf allen Seiten (Logo + Uebersicht/ Wissensquellen/Chatbot/Hilfe + CTA), Zaehler (Dokumente, Quellen); Ziel prominent; Strategien gruppiert/vereinfacht; Konfig-Transparenzseite (config.html).
• Pages: Domaenen-Filter auf der Uebersicht (Dropdown mit Anzahl je Domaene).
• CI: MR-Vorschau ueber GitLab-Pages parallel deployments (pages.path_prefix), Produktion auf Root.