Lars/mitai-jinkendo
1
0
Fork 0
Code Issues 33 Pull Requests Actions Packages Projects Releases 5 Wiki Activity
a515a5d563
mitai-jinkendo/.claude/docs/technical/UNIVERSAL_CSV_IMPORT_AGENT_GUIDE.md
Lars b453ce63c6
All checks were successful
Deploy Development / deploy (push) Successful in 53s
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(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.
2026-04-11 08:14:20 +02:00

4.2 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)

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