feat(universal-csv-import): Introduce Universal CSV Import module and related documentation

- Added the Universal CSV Import module, including the `UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md` for guidelines on new import modules, executors, and templates.
- Updated relevant rules in `ARCHITECTURE.md` and `CODING_RULES.md` to include references to the new import module and its requirements.
- Revised the Gitea Issues Index to reflect the latest updates and added context for ongoing issues related to the CSV import functionality.
- Enhanced the README files to provide clearer navigation and documentation for the Universal CSV Import features.

.claude/README.md

@@ -12,6 +12,7 @@ Dieser Ordner ist der **primäre Orientierungspunkt** für Claude Code / Cursor-
 | 2 | **`rules/DOCUMENTATION.md`** – Ablage- und Dokumentationsregeln |
 | 3 | `rules/ARCHITECTURE.md`, `rules/CODING_RULES.md`, `rules/LESSONS_LEARNED.md` |
 | 4 | Issue-Landkarte: **`.claude/docs/GITEA_ISSUES_INDEX.md`** |
+| 5 | **Universal CSV Import** (Modul/Executor/Vorlagen): **`docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md`** (unter `.claude/`) |
 
 Themen mit UI/Nav/PWA: siehe `../docs/issues/GUI_IA_ADMIN_NAV_2026-04-05.md` (im **Projekt**-`docs/`, nicht hier).
 

.claude/docs/GITEA_ISSUES_INDEX.md

@@ -1,6 +1,6 @@
 # Gitea Issues – Landkarte (Auswertung)
 
-**Quelle:** Gitea `Lars/mitai-jinkendo`, Stand **2026-04-08** (Abfrage `state=all`).  
+**Quelle:** Gitea `Lars/mitai-jinkendo`, Stand **2026-04-09** (Abfrage `state=all`, ergänzt: #71).  
 **URL:** http://192.168.2.144:3000/Lars/mitai-jinkendo/issues  
 
 Dieses Dokument ist ein **Orientierungs-Index** für Agenten und Entwickler. Verbindliches Tracking bleibt **in Gitea**; hier: Kategorien, Dubletten-Hinweise, grobe Prioritätseinschätzung.
@@ -88,7 +88,6 @@ Dieses Dokument ist ein **Orientierungs-Index** für Agenten und Entwickler. Ver
 | # | Titel |
 |---|--------|
 | 15 | [FEAT-002] Quality-Filter für KI-Auswertungen & Charts integrieren |
-| 21 | [FEATURE] Universeller CSV-Parser mit lernbarem Feldmapping |
 | 36 | BUG-009: Trainingstyp-Erstellung führt zu Internal Server Error |
 
 ---

.claude/docs/README.md

@@ -54,6 +54,7 @@ _Dieser Ordner `.claude/docs/` ist per `.gitignore`-Ausnahme **versioniert** (Sp
 | Platzhalter / Registry | `technical/PLACEHOLDER_REGISTRY_FRAMEWORK.md`, `technical/PLACEHOLDER_DEVELOPMENT_GUIDE.md` | `backend/placeholder_registrations/`, `backend/placeholder_resolver.py` |
 | Dashboard-Lab-Widgets | `technical/DASHBOARD_WIDGETS_AGENT_GUIDE.md` | Widget-Katalog + Registrierung (siehe Guide) |
 | Training Profiler / Resolver | `technical/TRAINING_PROFILE_RESOLVER_LAYER1.md`, `functional/TRAINING_TYPE_PROFILES.md` | Resolver-Module wie im Guide genannt |
+| Universal CSV Import | `technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md` | `backend/csv_parser/`, `routers/csv_import.py`, `routers/admin_csv_templates.py` |
 | Mitgliedschaft / Features | `technical/MEMBERSHIP_SYSTEM.md`, `architecture/FEATURE_ENFORCEMENT.md` | `backend/auth.py`, Feature-Logging, Router mit Enforcement |
 
 ---
@@ -111,6 +112,7 @@ _Dieser Ordner `.claude/docs/` ist per `.gitignore`-Ausnahme **versioniert** (Sp
 | `PROFILE_REFERENCE_VALUES.md` | Profil-Referenzwerte |
 | `TRAINING_PROFILE_RESOLVER_LAYER1.md` | Training-Resolver Schicht 1 |
 | `TRAINING_TYPE_PROFILES_TECHNICAL.md` | Trainingsprofile technisch |
+| `UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md` | Universal CSV: Registry, Executor, Vorlagen, Agent-Checkliste |
 | `V9D_PHASE2_VITALS_SLEEP.md` | v9d Vitalwerte/Schlaf (Release-Bezug) |
 
 ---
@@ -174,4 +176,4 @@ Siehe [`audit/README.md`](./audit/README.md).
 
 ---
 
-**Letzte Aktualisierung:** 8. April 2026 (Struktur-Index, Duplikatbereinigung, Abgleich-Hinweise)
+**Letzte Aktualisierung:** 9. April 2026 (Universal CSV Agent-Guide, Abgleich-Tabelle)

.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md

@@ -0,0 +1,63 @@
+# Universal CSV Import – Agent-Leitfaden
+
+**Stand:** 2026-04-09 · **Kontext:** Issue #21 (Universeller CSV-Parser), Prod-Migrationen u. a. 051–053.
+
+Dieses Dokument ist **normativ für Agenten**, die ein neues Import-Zielmodul anlegen oder bestehende Import-Pfade (Executor, Vorlagen, DB) ändern.
+
+---
+
+## 1. Architektur (Kurz)
+
+| Komponente | Pfad / Rolle |
+|------------|----------------|
+| Modul-Definitionen | `backend/csv_parser/module_registry.py` (`MODULE_DEFINITIONS`) |
+| Typ-/Einheiten-Konvertierung | `backend/csv_parser/type_converter.py`, `field_units.py` |
+| Zeilen-Aggregation (z. B. Ernährung pro Tag) | `backend/csv_parser/import_row_processing.py` |
+| Import-Ausführung | `backend/csv_parser/executor.py` |
+| Fehlertexte / Transaktions-Hinweise | `backend/csv_parser/import_errors.py` (`enrich_row_error`) |
+| Admin-Systemvorlagen | `backend/routers/admin_csv_templates.py` |
+| Nutzer-Import (Profil-Mappings) | `backend/routers/csv_import.py` |
+| Vorlagen-Validierung (strukturell + Sample) | `backend/csv_parser/template_validator.py` (`validate_csv_template`) |
+
+**Single Source of Truth** für erlaubte Zielfelder, Typen und Duplikat-Keys ist **`module_registry.py`**. Keine parallele Feldliste in Routern duplizieren.
+
+---
+
+## 2. Checkliste: Neues Zielmodul
+
+1. **`MODULE_DEFINITIONS`** um Eintrag erweitern: `table`, `fields` (Typen `date` / `datetime` / `float` / `int` / `string`), `duplicate_key`, `duplicate_strategy`, ggf. `derive_date_from_datetime_field`, `import_mode` (Spezialpfade wie Schlaf).
+2. **DB:** Migration nur nach Projektregel (`backend/migrations/NNN_*.sql`). Spaltenbreiten/Typen so wählen, dass importierte Werte (z. B. kJ→kcal, große Energiebeträge) **keinen NUMERIC-Overflow** verursachen.
+3. **`source` / CHECK-Constraints:** Wenn die Zieltabelle `source` hat, muss der Wert **`csv`** (oder der vereinbarte Import-Tag) in der DB erlaubt sein (Migration anpassen, nicht nur App-Code).
+4. **Executor:** Einfügen/Aktualisieren in `executor.py` nur über bestehende Muster (ein Cursor, **kein** verschachteltes `get_db()` im gleichen Request). Bei mehreren Zeilen pro Transaktion: bei **Zeilenfehlern** SAVEPOINT pro Zeile nutzen (siehe Activity-Pattern), damit die Transaktion nicht dauerhaft abgebrochen ist.
+5. **Trainingstyp / FK-Auflösung:** DB-Zugriffe für abhängige Entitäten (z. B. `get_training_type_for_activity_with_cursor`) **mit dem gleichen Cursor** wie der Import – keine zweite Connection aus dem Importpfad.
+6. **Vorlagen:** System-Templates in Migration/Seed pflegen (`csv_field_mappings`, `is_system=true`). `type_conversions` und `source_unit` dort setzen, wo Einheiten aus Exporten abweichen (z. B. Apple kJ).
+7. **Validierung:** Neue/angepasste Admin-Vorlagen müssen **`validate_csv_template`** passieren (Create/Update liefert bei Fehlern **422** mit `validation`). Tests für Randfälle ergänzen (`tests/test_template_validator.py` o. ä.).
+8. **API / Frontend:** Neue Admin-Endpunkte in `main.py` registrieren; Frontend **nur** über `api.js`. Bei strukturierten FastAPI-Fehlern (`detail` als Objekt/Liste) bestehende Hilfen (`formatFastApiDetail`) nutzen.
+
+---
+
+## 3. Checkliste: Bestehendes Modul ändern
+
+- Schema-Änderung: Migration + ggf. **`module_registry`**-Felder anpassen.
+- Neue Spalte im Import: Executor-Mapping, optional `type_conversions` / Validator.
+- Änderung an Duplikatlogik: `duplicate_key` / `ON CONFLICT`-Pfad im Executor prüfen.
+- Datums-/Zeit-Parsing: **`type_converter`** – ISO-Daten `YYYY-MM-DD` konsistent (**`dayfirst=False`**), Zeiten `HH:MM` ohne Sekunden unterstützen wo nötig.
+
+---
+
+## 4. Bekannte Einschränkungen (Follow-up in Gitea)
+
+- Admin **„Format prüfen“** kann `import_row_processing` derzeit weglassen; volle Parität mit dem gespeicherten Template erst beim Speichern / echten Import.
+- Nutzer-Mappings (Copy aus Systemvorlage) laufen nicht automatisch durch **`validate_csv_template`** – Tracking: **Gitea #71** (http://192.168.2.144:3000/Lars/mitai-jinkendo/issues/71).
+
+---
+
+## 5. Verwandte Regeln
+
+- `.claude/rules/ARCHITECTURE.md` – Router, DB, `source`-Tracking
+- `.claude/rules/CODING_RULES.md` – Kurzverweis Universal CSV
+- `.claude/rules/DOCUMENTATION.md` – Ablage technischer Specs
+
+---
+
+**Version:** 1.0

.claude/rules/ARCHITECTURE.md

@@ -216,8 +216,11 @@ updated_at  TIMESTAMP DEFAULT NOW()
 Tabellen die Daten aus externen Quellen empfangen brauchen:
 ```sql
 source  VARCHAR(50) DEFAULT 'manual'
--- Werte: 'manual' | 'apple_health' | 'garmin' | 'withings'
+-- Werte u. a.: 'manual' | 'apple_health' | 'garmin' | 'withings' | 'csv'
 ```
+Importe über den **Universal CSV**-Pfad setzen `source = 'csv'`, sofern die Tabelle ein `source`-Feld hat; CHECK-Constraints und Migrationen müssen diesen Wert erlauben.
+
+**Agent-Pflicht bei neuen Import-Zielen oder Executor-Änderungen:** `.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md`
 
 Manuelle Einträge (`source = 'manual'`) haben IMMER Vorrang bei Reimport:
 ```sql

.claude/rules/CODING_RULES.md

@@ -39,6 +39,13 @@ from slowapi import Limiter
 def sensitive(request: Request, ...):
 ```
 
+### 6. Universal CSV Import / Admin-Vorlagen
+Neues **Import-Zielmodul**, Änderungen an **`csv_parser`**, Executor, DB-`source`/`CHECK`, oder System-CSV-Vorlagen:
+
+- Pflichtlektüre und Checkliste: **`.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md`**
+- Keine zweite DB-Connection im Importpfad; Zeilenfehler ohne „aborted transaction“ (SAVEPOINT-Muster wo nötig)
+- Admin Create/Update von Systemvorlagen: Validierung über `validate_csv_template` nicht umgehen
+
 ## Frontend
 
 ### 1. api.js für alle API-Calls

CLAUDE.md

@@ -8,6 +8,7 @@
 > | Coding-Regeln      | `.claude/rules/CODING_RULES.md` |
 > | Lessons Learned    | `.claude/rules/LESSONS_LEARNED.md` |
 > | **Gitea-Landkarte (lokal gepflegt)** | **`.claude/docs/GITEA_ISSUES_INDEX.md`** |
+> | **Universal CSV Import** (neues Modul / Executor / Vorlagen) | **`.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md`** |
 > | **GUI / IA / Admin / Nav / PWA-Leiste** | **`docs/issues/GUI_IA_ADMIN_NAV_2026-04-05.md`** |
 > | **Dashboard-Lab-Widgets** (Katalog, Registrierung, `config`) | **`.claude/docs/technical/DASHBOARD_WIDGETS_AGENT_GUIDE.md`** |
 > | **Agent-Einstieg** | **`.claude/README.md`** |
@@ -98,6 +99,12 @@ frontend/src/
 **Branch:** develop
 **Nächster Schritt:** Frontend Chart Integration → Testing → Prod Deploy v0.9i
 
+### Updates (09.04.2026 - Universal CSV Import, Prod-Migration abgeschlossen)
+
+- **Agent-Leitfaden:** `.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md` (Checkliste für neue Import-Module, Executor, Vorlagen, `source=csv`, SAVEPOINT-/Cursor-Regeln)
+- **Regeln:** Verweise in `.claude/rules/ARCHITECTURE.md` (§3.2 `source`), `.claude/rules/CODING_RULES.md` (§6)
+- **Follow-ups:** **Gitea #71** – Dry-Run inkl. `import_row_processing`, Nutzer-Mapping-Validierung, Fehler-Hints in der Import-UI ([Issue](http://192.168.2.144:3000/Lars/mitai-jinkendo/issues/71))
+
 ### GUI / Informationsarchitektur (Abnahme dieser Iteration, 2026-04-05)
 
 Admin-Bereich (`AdminShell`, Hub-Routen), Hauptnavigation inkl. **Ziele** (`config/appNav.js`), Einstellungen nur aktives Profil + E-Mail, KI-Analyse Ergebnis in rechter Spalte, **PWA** Bottom-Nav inkl. iOS Safe Area. Zentrale Agent-Doku: **`docs/issues/GUI_IA_ADMIN_NAV_2026-04-05.md`**. Responsive-Epic **Gitea #30:** Phasenplan `docs/issues/PHASE_PLAN_RESPONSIVE_UI.md` — **P7 Kern erledigt**, **P8** (Regression/Abnahme) ausstehend; Issue bewusst **nicht** geschlossen.