# EV-001 — Evaluation Export — ED Implementation Plan

- **Status:** Implemented Draft
- **Date:** 2026-08-08
- **Scope:** Phase 1 — OpenRefine Project Archive → ODS Evaluation Table
- **Related:** `EV-001_Evaluation_Dataset_v0.1_DRAFT.md`

## 1. Ziel

Die bestehende Evaluation-Export-Logik aus Reconcilix v0.1 wird auf EV-001 ausgerichtet.

Minimaler technischer Pfad:

```text
OpenRefine Project Archive
        ↓
OpenRefineProjectReader
        ↓
EvaluationTableBuilder
        ↓
OdsEvaluationTableExporter
        ↓
ODS für Domainexpert:in
```

Phase 1 endet mit der erzeugten ODS-Datei. Reimport und statistische Auswertung sind nicht Bestandteil dieser Umsetzung.

## 2. Wiederverwendete Komponenten

- `src/Evaluation/OpenRefineProjectReader.php`
- `src/Evaluation/EvaluationTableBuilder.php`
- `src/Evaluation/EvaluationRow.php`
- `src/Evaluation/EvaluationCandidate.php`
- `tools/exportOpenRefineEvaluationTable.php`
- `public/evaluation-export.php`

Die bestehende Trennung zwischen Reader, fachlichem Tabellenaufbau und Exporter bleibt erhalten.

## 3. Wesentliche Anpassungen

### 3.1 OpenRefineProjectReader

Der Reader übernimmt zusätzlich:

- `id`
- `entityType`
- optional `TEI`
- Reconciliation-Konfiguration des reconcilierten Feldes
- Vocabulary ID und Label über `reconConfig.type`

Bei vorhandenem TEI-Kontext wird der Context Type aus EV-001 gesetzt:

```text
https://reconcilix.vocnet.org/context/0001
```

### 3.2 Trennung Rx-Vorschlag / OpenRefine-Entscheidung

Die bisherige Implementierung setzte bei einem manuellen OpenRefine-Match den gewählten Candidate als `Best Candidate` ein.

Das vermischt zwei Ebenen:

```text
Rx-Vorschlag
OpenRefine-Entscheidung
```

Für EV-001 werden diese Ebenen getrennt:

- `Best Candidate` = erster von Rx gelieferter Candidate
- `OR Selected Candidate` = in OpenRefine gewählter Candidate
- `Match Status` = OpenRefine Judgment

Diese Trennung ist für die spätere Evaluation erforderlich. Beispiel aus dem Testarchiv:

```text
Source Value          = Schlossturm
Best Candidate        = Turm
OR Selected Candidate = Turm (Einzelbauwerk)
```

### 3.3 ODS Export

Neu:

```text
src/Evaluation/OdsEvaluationTableExporter.php
```

Der Export verwendet PHP `PharData` mit ZIP-Format und benötigt daher keine zusätzliche Spreadsheet-Library.

Die drei Expert:innenfelder werden visuell hervorgehoben:

- `Expert Decision`
- `Expert Comment`
- `Suggested Target`

Für `Expert Decision` ist eine ODS-Validierung mit den EV-001-Werten hinterlegt:

```text
accept
reject
unclear
better_candidate
needs_context
```

### 3.4 Web-Oberfläche

`public/evaluation-export.php` enthält bewusst nur:

- kurze Einführung zu Reconcilix
- Beschreibung des Evaluation-Ziels
- Anleitung für Domainexpert:innen
- Upload eines OpenRefine Project Archive
- ODS-Download

Es entsteht keine allgemeine Reconcilix-Webanwendung.

## 4. ODS-Spalten Phase 1

```text
Source ID
Source Value
Entity Type
Vocabulary
Vocabulary URI
Context Type
Context Value
Match Status
Best Candidate
Best Candidate URI
Score
Candidate Count
Further Candidates
OR Selected Candidate
OR Selected Candidate URI
Expert Decision
Expert Comment
Suggested Target
```

`OR Selected Candidate` und `OR Selected Candidate URI` ergänzen EV-001 minimal, weil nur damit die in EV-001 geforderte Trennung von Rx-Vorschlag und OpenRefine-Entscheidung vollständig erhalten bleibt.

## 5. CLI

Der bestehende CLI-Pfad bleibt erhalten:

```bash
php tools/exportOpenRefineEvaluationTable.php \
  --input project.openrefine.tar.gz \
  --output evaluation.ods
```

Damit kann der Export unabhängig vom Web-GUI getestet werden.

## 6. Test

Neu:

```text
tests/Evaluation/EvaluationExportTest.php
```

Geprüft mit dem realen 50-Record-Testarchiv:

- 50 Evaluation Rows werden erzeugt.
- Rx Best Candidate bleibt vom OpenRefine-Match getrennt.
- OpenRefine Selected Candidate bleibt erhalten.
- ODS-Datei wird technisch korrekt erzeugt.

## 7. Nicht Bestandteil

- ODS-Reimport
- Statistik
- Evaluation Metrics
- Fehler-/Erfolgsklassen
- Analyseoberfläche
- Persistenz der Expert:innenurteile

Diese Punkte bleiben entsprechend EV-001 außerhalb von Phase 1.

## Update 2026-08-08 — Expert Submission

Following the first successful integration test, Phase 1 was extended with a minimal return channel for completed expert evaluations.

Implemented:

- input column aliases `Source ID` and `Entity Type` while retaining backwards-compatible aliases;
- ODS view settings freeze the first two columns (split at C1);
- return form on `public/evaluation-export.php` for completed ODS files;
- optional dataset comment plus required expert name and e-mail address;
- name and e-mail are stored for internal communication only and are not intended for publication;
- evaluation results may later be used in published analyses;
- submissions are stored outside the web root under `var/evaluation/submissions/`;
- each submission receives one UUID shared by the ODS file and its JSON metadata sidecar;
- filename pattern: `<dataset>.<evaluation-id>.YYYY-MM-DD.ods|json`;
- uploaded ODS files are validated as ODF spreadsheets before storage;
- no re-import into the Reconcilix domain model and no statistical analysis are introduced by this change.