Lars/mitai-jinkendo
1
0
Fork 0
Code Issues 33 Pull Requests Actions Packages Projects Releases 5 Wiki Activity
62729d0648
mitai-jinkendo/.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md
Lars 7226e04e9c
All checks were successful
Deploy Development / deploy (push) Successful in 1m0s
Details
Build Test / pytest-backend (push) Successful in 4s
Details
Build Test / lint-backend (push) Successful in 0s
Details
Build Test / build-frontend (push) Successful in 17s
Details
feat: implement effective CSV delimiter resolution for imports 
- Added `resolve_effective_csv_delimiter` function to determine the correct delimiter based on the uploaded file and template.
- Updated CSV import logic to utilize the new delimiter resolution method, ensuring accurate parsing of CSV files with varying delimiters.
- Enhanced documentation to reflect changes in delimiter handling.
- Added unit tests for the new delimiter resolution functionality.
2026-04-18 10:12:33 +02:00

4.4 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. 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 (#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