Lars/mitai-jinkendo
1
0
Fork 0
Code Issues 21 Pull Requests Actions Packages Projects Releases 5 Wiki Activity
c1873a47b1
mitai-jinkendo/.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md
Lars 79ec249bc3
Some checks failed
Deploy Development / deploy (push) Successful in 1m9s
Details
Build Test / pytest-backend (push) Failing after 5s
Details
Build Test / lint-backend (push) Successful in 0s
Details
Build Test / build-frontend (push) Successful in 24s
Details
feat: feature enforcement imports (#37/#38) and Universal CSV validation (#71) 
Activity and nutrition legacy CSV imports enforce tier limits with UsageBadge UI; Universal CSV gets mapping validation on copy/import, format-check parity, and structured error_details.

version: 0.9u
module: activity 1.2.1, nutrition 1.0.3, csv_import 0.4.0
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-24 16:59:12 +02:00

4.6 KiB
Raw Blame History

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)
Effektives Listentrennzeichen backend/csv_parser/core.py (resolve_effective_csv_delimiter) — Datei kann ; (z. B. Apple DE) haben, Vorlage , (EN); Import/Diagnose nicht nur das gespeicherte Trennzeichen blind nutzen.

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. Validierung & Dry-Run (Stand 2026-07-23, Gitea #71)

  • Admin „Format prüfen“ sendet dieselbe import_row_processing-Spec wie Speichern (AdminCsvTemplateEditorPage → POST /api/admin/csv-templates/validate).
  • Profil-Mappings: POST /api/csv/mappings/{id}/copy und POST /api/csv/import prüfen vor dem Schreiben mit validate_csv_template (HTTP 422 bei Fehlern).
  • Diagnose: GET /api/csv/mappings/{id}/validate — Strukturprüfung ohne Import.
  • Nutzer-UI: UniversalCsvImportPage zeigt error_details mit Zeile, code und hint (CsvImportErrorDetails).

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