From b453ce63c69ab987ba304d75588e268d9aa95475 Mon Sep 17 00:00:00 2001 From: Lars Date: Sat, 11 Apr 2026 08:14:20 +0200 Subject: [PATCH] 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 | 1 + .claude/docs/GITEA_ISSUES_INDEX.md | 3 +- .claude/docs/README.md | 4 +- .../UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md | 63 +++++++++++++++++++ .claude/rules/ARCHITECTURE.md | 5 +- .claude/rules/CODING_RULES.md | 7 +++ CLAUDE.md | 7 +++ 7 files changed, 86 insertions(+), 4 deletions(-) create mode 100644 .claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md diff --git a/.claude/README.md b/.claude/README.md index 36b294e..3c91fc5 100644 --- a/.claude/README.md +++ b/.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). diff --git a/.claude/docs/GITEA_ISSUES_INDEX.md b/.claude/docs/GITEA_ISSUES_INDEX.md index ca04bda..3b711b6 100644 --- a/.claude/docs/GITEA_ISSUES_INDEX.md +++ b/.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 | --- diff --git a/.claude/docs/README.md b/.claude/docs/README.md index 713510a..eb9d192 100644 --- a/.claude/docs/README.md +++ b/.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) diff --git a/.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md b/.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md new file mode 100644 index 0000000..5bdcea0 --- /dev/null +++ b/.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 diff --git a/.claude/rules/ARCHITECTURE.md b/.claude/rules/ARCHITECTURE.md index e715af3..d5e4e3b 100644 --- a/.claude/rules/ARCHITECTURE.md +++ b/.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 diff --git a/.claude/rules/CODING_RULES.md b/.claude/rules/CODING_RULES.md index a703ec1..542bc53 100644 --- a/.claude/rules/CODING_RULES.md +++ b/.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 diff --git a/CLAUDE.md b/CLAUDE.md index f234606..01e648f 100644 --- a/CLAUDE.md +++ b/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.