Dokumenten-Check/CLAUDE.md

# 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`.

```bash
# 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 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).