# Stiftung Starter: Schema, Usage, and Cleanup Plan (2025-08-31)

This document consolidates the current domain model, relationships, active usage across the codebase, and targeted cleanup/migration proposals.

## Summary
- Server and date-handling fixes completed earlier; stack is healthy.
- New vs. legacy lease models both in use; annual accounting (LandAbrechnung) is the hub.
- Orphans: a few likely candidates (LandAbrechnung.zahlungen, file fields; ApplicationPermission stub). Several legacy fields still referenced; plan deprecation after migration.

## Entities and Relationships

- CSVImport
  - Tracks CSV imports; fields: import_type, filename, file_size, status, totals, error_log, created_by, started_at, completed_at

- Paechter (Tenant)
  - Fields: vorname, nachname, geburtsdatum, email, telefon, iban, strasse, plz, ort, personentyp, pachtnummer, pachtbeginn_erste, pachtende_letzte, pachtzins_aktuell, landwirtschaftliche_ausbildung, berufserfahrung_jahre, spezialisierung, notizen, aktiv
  - Relations: Verpachtung (legacy) M:1; LandVerpachtung (new) M:1; reverse from Land.aktueller_paechter
  - Helpers: get_full_name, get_aktive_verpachtungen, get_gesamt_pachtflaeche, get_gesamt_pachtzins

- Destinataer (Beneficiary)
  - Fields: familienzweig, vorname, nachname, geburtsdatum, email, telefon, iban, strasse, plz, ort, berufsgruppe, ausbildungsstand, institution, projekt_beschreibung, jaehrliches_einkommen, finanzielle_notlage, notizen, aktiv, ist_abkoemmling, haushaltsgroesse, monatliche_bezuege, vermoegen, unterstuetzung_bestaetigt, standard_konto(FK StiftungsKonto), vierteljaehrlicher_betrag, studiennachweis_erforderlich, letzter_studiennachweis
  - Relations: Foerderung 1:M (via destinataer), DestinataerUnterstuetzung 1:M, DestinataerNotiz 1:M
  - Helpers: get_full_name, totals, erfuellt_voraussetzungen, naechste_studiennachweis_termine

- Person (Legacy)
  - Legacy stand-in for beneficiaries; still referenced in views/templates; used by Foerderung.person

- Land (Parcel)
  - Identity: lfd_nr(unique), ew_nummer, grundbuchblatt, amtsgericht, gemeinde, gemarkung, flur, flurstueck, adresse
  - Area: groesse_qm, gruenland_qm, acker_qm, wald_qm, sonstiges_qm
  - Legacy pacht: verpachtete_gesamtflaeche, flaeche_alte_liste, verp_flaeche_aktuell
  - Current pacht snapshot: aktueller_paechter(FK), paechter_name, paechter_anschrift, pachtbeginn, pachtende, verlaengerung_klausel, zahlungsweise, pachtzins_pro_ha, pachtzins_pauschal
  - USt/Tax: ust_option, ust_satz, grundsteuer_umlage, versicherungen_umlage, verbandsbeitraege_umlage, jagdpacht_anteil_umlage, anteil_grundsteuer, anteil_lwk
  - Status/meta: aktiv, notizen, erstellt_am, aktualisiert_am
  - Relations: Verpachtung (legacy) 1:M; LandVerpachtung (new) 1:M; LandAbrechnung 1:M
  - Helpers: area conversions; pachtfläche calculators

- LandVerpachtung (New Lease)
  - land(FK), paechter(FK), vertragsnummer(unique), pachtbeginn, pachtende?, verlaengerung_klausel
  - verpachtete_flaeche, pachtzins_pauschal, pachtzins_pro_ha?, zahlungsweise
  - USt/umlagen flags; status, bemerkungen; timestamps
  - Behavior: save/delete sync LandAbrechnung; rent proration per year; umlage calc currently 0

- LandAbrechnung (Annual Accounting)
  - land(FK), abrechnungsjahr(unique per land)
  - Einnahmen: pacht_vereinnahmt, umlagen_vereinnahmt, sonstige_einnahmen, zahlungen(JSON?)
  - Ausgaben buckets; vorsteuer_aus_umlagen; offene_posten; bemerkungen
  - File fields for uploads; timestamps; derived totals incl. ust_pacht_betrag

- Verpachtung (Legacy Lease)
  - land(FK), paechter(FK), vertragsnummer(unique), pachtbeginn, pachtende, verlaengerung?
  - pachtzins_pro_qm, pachtzins_jaehrlich, verpachtete_flaeche; status; verwendungsnachweis; bemerkungen; timestamps
  - Behavior: save/delete sync LandAbrechnung; rent proration with verlängerung

- DokumentLink (Paperless linking)
  - paperless_document_id, kontext, titel, beschreibung
  - Flexible UUID links: verpachtung_id, land_verpachtung_id, land_id, paechter_id, destinataer_id, foerderung_id, rentmeister_id

- Foerderung (Grant)
  - person(FK legacy, nullable), destinataer(FK, nullable), jahr, betrag, kategorie, status, verwendungsnachweis(FK), bemerkungen, antragsdatum, entscheidungsdatum

- DestinataerUnterstuetzung (Support)
  - destinataer(FK), konto(FK StiftungsKonto), betrag, faellig_am, status, beschreibung, timestamps; indexes

- DestinataerNotiz
  - destinataer(FK), titel, text, datei, erstellt_von(FK auth.User), erstellt_am

- Rentmeister
  - person/address/bank fields; seit_datum, bis_datum?, aktiv, monatliche_verguetung, km_pauschale; used by Verwaltungskosten

- StiftungsKonto
  - kontoname, bank_name, iban, bic, konto_typ, saldo, saldo_datum, zinssatz, laufzeit_bis, aktiv, notizen, timestamps

- BankTransaction
  - konto(FK), datum, valuta?, betrag, waehrung, verwendungszweck, empfaenger_zahlungspflichtiger, iban_gegenpartei, bic_gegenpartei, referenz, transaction_type, status, kommentare, verwaltungskosten(FK?), import_datei, importiert_am, saldo_nach_buchung
  - unique_together: (konto, datum, betrag, referenz)

- Verwaltungskosten
  - bezeichnung, kategorie, betrag, datum, lieferant_firma, rechnungsnummer, status, rentmeister(FK), zahlungskonto(FK), quellkonto(FK), konto(FK legacy), km_anzahl, km_satz, von_ort, nach_ort, zweck, beschreibung, notizen, timestamps

- ApplicationPermission (managed=False)
  - Declares custom permission codenames; no table created

- AuditLog
  - user(FK), username, timestamp, action, entity_type, entity_id, entity_name, description, changes(JSON), ip_address, user_agent, session_key; indexes

- BackupJob
  - backup_type, status, created_by(FK), created_at/started_at/completed_at, backup_filename, backup_size, error_message, database_size, files_count; helpers

## Usage observations (workspace-wide scans)
- Legacy vs. new lease models are both heavily referenced across views/templates/forms.
- LandAbrechnung core fields are used in forms and detail pages; pacht_vereinnahmt updated by save/delete hooks and a sync command.
- DokumentLink UUID references are widely used for cross-entity navigation.
- Destinataer support fields power quarterly payout scheduling.
- Person (legacy) still appears in Foerderung flows and person pages.

## Likely orphans / cleanup candidates
- LandAbrechnung.zahlungen (JSON): no UI/logic usage detected.
- LandAbrechnung file fields (pachtvertrag_datei, grundsteuer_bescheid_datei, versicherungsnachweis_datei): unused in UI; Paperless appears primary doc source.
- ApplicationPermission: only a managed=False stub with permissions; keep if used for seeding, otherwise move to data migration and remove the class.
- LandVerpachtung._calculate_umlage_for_year: returns 0; umlage flags are gathered but not used to compute revenue.
- Legacy Land fields: still used (imports, displays). Plan deprecation after migration to new lease model.
- Foerderung.person vs destinataer: both used; plan single-source migration and drop legacy.

## Recommendations and plan
1) Consolidate to LandVerpachtung
  - Stop creating new legacy Verpachtung in UI; a feature flag now blocks legacy create (`DISABLE_LEGACY_VERPACHTUNG_CREATE`, default True) and guides users to the new flow.
  - A conversion command `convert_legacy_verpachtungen` is scaffolded (dry-run by default; use `--commit` to persist) to create `LandVerpachtung` rows from `Verpachtung`.
   - After migration and verification: remove legacy model, views, and Land’s legacy pacht snapshot fields.

2) DRY date handling
  - A shared helper exists: `stiftung/utils/date_utils.py` with `ensure_date` and `get_year_from_date`. Models now import and use it.

3) Implement Umlage allocation to Abrechnung
   - For each LandAbrechnung year, distribute expense buckets (grundsteuer_betrag, versicherungen_betrag, verbandsbeitraege_betrag, ggf. jagdpacht) across active leases using area share; increase umlagen_vereinnahmt accordingly.
   - Extend sync_abrechnungen to recompute Umlagen similar to Pacht.

4) Prune unused LandAbrechnung fields
   - If Paperless is canonical: drop the three file fields.
   - If no plan for zahlungen JSON: remove or replace with a Payment model.

5) Indexing
   - Add selective DB indexes on frequent filters (year, status, land, konto+datum).

6) Permissions
   - If using custom permissions, define them in a data migration or settings; remove the managed=False model class.

7) Template consolidation
   - Extract shared partials for lease display to reduce duplication between legacy and new renders.

## Notes
- Date: 2025-08-31
- Compose services OK; app checks pass (docker-compose exec web python manage.py check).
 - To try conversion: `python manage.py convert_legacy_verpachtungen` (dry-run), add `--commit` to apply changes; optionally `--limit N`.