initial commit

CLAUDE.md

@@ -0,0 +1,107 @@
+# 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
+
+```bash
+# Connect to Oracle DB and run scripts in order:
+sqlplus user/pass@db @"Scripts/Datenmodell DocumentCheck.sql"
+sqlplus 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 the`original_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.
+
+```bash
+# 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:**
+```bash
+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
+
+1. ORDS: Projekt laden + `status → IN_PROGRESS`
+2. ORDS: Dokumente + Fragen laden
+3. ORDS: Alte Ergebnisse löschen (Re-Processing-fähig)
+4. **Phase A** (pro Dokument): Download → OCR/Konvertierung → Übersetzung → ORDS `PUT /texts`
+5. **Phase B** (pro Dokument × Frage): Auswertung → Abweichungs-Berechnung → ORDS `POST /results`
+6. ORDS: `status → COMPLETED`
+
+Abweichung/Hinweis wird in Java berechnet (nicht durch KI): `score < threshold` → prüfe `result_handling` (ABWEICHUNG/HINWEIS).