Files

Philipp Ostmeyer c75f460ec5 feat: Externe Dokument-Referenzen erkennen, herunterladen & mitbewerten

Nach der Transkription eines Dokuments werden referenzierte externe
Dokumente (AGB, Verhaltenskodex) erkannt, sicher heruntergeladen und ihr
Text dem Hauptdokument fuer die "Summen"-Bewertung angehaengt (Option D).
Die Referenzen werden zusaetzlich als eigene, herunterladbare Zeilen
gespeichert.

- DB: dc_project_documents um parent_document_id, is_reference, source_url
  erweitert (DC_REFERENCES_ALTER.sql)
- ORDS: Dokumentenliste um die Felder erweitert; neue Endpunkte
  POST /documents/:id/references und DELETE /projects/:id/references;
  q-Quote-Parserfehler im ai-costs-Handler ('[]') behoben
- Backend: ReferenceDownloadService (SSRF-sicher via DNS-/Public-IP-
  Validierung, Redirect-Pruefung, Groessen-/Timeout-Limits, jsoup fuer HTML),
  EvaluationService.extractReferenceUrls (LLM-basierte URL-Erkennung),
  Orchestrierung (Discovery in Phase A, Referenz-Skip + combinedText in Phase B)
- Config: dc.references.* in application.properties

Verifiziert an Projekt 144: AGB-PDF/-HTML heruntergeladen, verknuepft,
"Summen"-Bewertung zitiert AGB-Klauseln aus dem Referenzdokument.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-22 12:45:55 +02:00

4.5 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Dokumenten-Check is a document pre-verification system for Frigosped (freight forwarding). It checks transport documents and general terms & conditions (AGB) against configurable question catalogs, with AI-powered document translation and evaluation. Built on Oracle APEX + Oracle Database 23c.

Database Setup

Tool: Always use sql (SQLcl), never sqlplus.

# Connect to Oracle DB and run scripts in order:
sql user/pass@db @"Scripts/Datenmodell DocumentCheck.sql"
sql user/pass@db @"Scripts/Fragenkatalog-AGB anlegen.sql"

No build/compilation step — APEX applications deploy directly to Oracle instances.

Architecture

Data Model (10 tables in `Scripts/Datenmodell DocumentCheck.sql`)

Configuration hierarchy:

dc_document_types → dc_question_catalogs → dc_question_categories → dc_questions

Execution hierarchy:

dc_projects → dc_project_documents → dc_results

Supporting: dc_users, dc_user_roles, dc_reference_documents

Key Patterns

Audit triggers on all tables: Every table has BEFORE INSERT/UPDATE triggers that set created_at, created_by, updated_at, updated_by, row_version. User identity comes from APEX_APPLICATION.G_USER.
Oracle Identity columns: All PKs use GENERATED BY DEFAULT AS IDENTITY.
Config-driven evaluation: Each question defines evaluation_type, threshold, result_on_deviation (ABWEICHUNG/HINWEIS), plus example answers for 0%/100% cases.
Async processing: Projects progress through PENDING → IN_PROGRESS → COMPLETED with a 0–100% processing_progress field and email notification on completion.
Filestorage: dc_project_documents stores theoriginal_file (BLOB) with MIME type and filename metadata. The original text original_text (CLOB) after after OCR and conversion to Markdown and the translated_file after Translation to German (CLOB)

Result Types

OK, UNKLAR (unclear), NOK (not OK)
Boolean flags: is_deviation, is_warning

User Roles

ADMIN — configuration management
AUDITOR — document verification

Key Files

File	Purpose
`Scripts/Datenmodell DocumentCheck.sql`	Full DB schema: 10 tables + 8 triggers
`Scripts/Fragenkatalog-AGB anlegen.sql`	Sample AGB question catalog (6 categories, 25 questions)
`Scripts/ORDS REST Services.sql`	All 11 ORDS REST endpoints (idempotent, run after schema)
`Doku/Projektbeschreibung.md`	German requirements specification
`Doku/Dokumenten-Check.md`	Data model + UI dialog specifications

Backend Service (Quarkus)

Located in dc-backend/. Java 21, Quarkus 3.15.1, LangChain4J 0.36.2.

# Dev-Modus (hot reload)
cd dc-backend
mvn quarkus:dev

# Produktion bauen
mvn package -DskipTests
java -jar target/quarkus-app/quarkus-run.jar

Trigger-Endpunkt:

POST http://localhost:8090/check/{projectId}
# → 202 Accepted, Verarbeitung läuft asynchron

Backend-Architektur

CheckResource           POST /check/{projectId}  → 202, Fire & Forget
CheckOrchestrationService  Haupt-Ablauf (Phase A: OCR/Übersetzung, Phase B: Auswertung)
DocumentProcessingService  PDF→KI-OCR, DOCX→POI→Markdown, ODT→ODF-Toolkit→Markdown
EvaluationService          translate() + evaluate() via LangChain4J ChatLanguageModel
OrdsClient (REST Client)   MicroProfile REST Client für alle /api/dc/-Endpunkte
AiModelProducer (CDI)      @Named("main") gpt-oss:20b + @Named("ocr") quen3.5:9b

KI-Modelle

Qualifier	Modell	Zweck
`@Named("main")`	`gpt-oss:20b`	Übersetzung + Fragenauswertung
`@Named("ocr")`	`quen3.5:9b`	PDF-Seiten als Bild → Markdown-Text

Beide sprechen https://ollama.aquantico.de an (Ollama-API /api/chat) mit X-API-KEY-Header. Konfiguration in dc-backend/src/main/resources/application.properties.

Verarbeitungsablauf

ORDS: Projekt laden + status → IN_PROGRESS
ORDS: Dokumente + Fragen laden
ORDS: Alte Ergebnisse löschen (Re-Processing-fähig)
Phase A (pro Dokument): Download → OCR/Konvertierung → Übersetzung → ORDS PUT /texts
Phase B (pro Dokument × Frage): Auswertung → Abweichungs-Berechnung → ORDS POST /results
ORDS: status → COMPLETED

Abweichung/Hinweis wird in Java berechnet (nicht durch KI): score < threshold → prüfe result_handling (ABWEICHUNG/HINWEIS).

4.5 KiB Raw Permalink Blame History Unescape Escape