108 lines
4.5 KiB
Markdown
108 lines
4.5 KiB
Markdown
# 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).
|