# OGV Haushaltsplan – Technische Dokumentation

<time class="ldoc-chip" data-atom="date" data-chip="date" data-ts="&quot;2026-10-07&quot;" datetime="2026-10-07">7. Okt. 2026</time> · <span class="ldoc-mention" data-atom="mention" data-mention-id="u_3ZteHVlpfEKymeT5bYbm9Q" data-principal="u_3ZteHVlpfEKymeT5bYbm9Q">@Matthias Boeddinghaus</span>

## Überblick

Der OGV-Haushaltsplan ist eine kleine PHP-Webanwendung unter [ohofer-verband.de/bu20dg26et](https://www.ohofer-verband.de/bu20dg26et/), mit der der Vorstand den Haushalt gemeinsam plant. Sie läuft ohne Datenbank auf dem vorhandenen WordPress-Hosting und speichert alles in geschützten Dateien.

<table id="bkmrk-bereich-umfang-nutze"><colgroup><col></col><col></col></colgroup><tbody><tr><th colspan="1" rowspan="1">Bereich

</th><th colspan="1" rowspan="1">Umfang

</th></tr><tr><td colspan="1" rowspan="1">Nutzer

</td><td colspan="1" rowspan="1">1 Admin, 10 Zugänge (01a–10a), davon 7 per Einladungscode selbst einrichtbar

</td></tr><tr><td colspan="1" rowspan="1">Planung

</td><td colspan="1" rowspan="1">Kategorien A–D, Betrag = Vorgabe × Faktor, Beträge in ganzen Euro

</td></tr><tr><td colspan="1" rowspan="1">Personal

</td><td colspan="1" rowspan="1">AG-Brutto aus AVR-DD-Tabelle (gültig ab 01.09.2026) nach EG und Stufe

</td></tr><tr><td colspan="1" rowspan="1">Nachvollziehbarkeit

</td><td colspan="1" rowspan="1">Änderungsmarkierung je Zugang in fester Farbe, Änderungsliste, 40 Versionen

</td></tr><tr><td colspan="1" rowspan="1">Export

</td><td colspan="1" rowspan="1">CSV (Semikolon, UTF-8 mit BOM, für Excel)

</td></tr></tbody></table>

Eine zweite, getrennte Fassung läuft als Artifact in Claude; sie teilt keine Daten mit der Webversion.

## Architektur und Dateien

Die App liegt als eigener Ordner `bu20dg26et/` im WordPress-Webroot; WordPress leitet nur Anfragen um, für die es keine Datei gibt, und lässt den Ordner daher in Ruhe.

<div caption="Aufbau · Browser, zwei Einstiege, eine Bibliothek, ein Datenordner" data-lfile-embed="node/ae3f626a-f259" id="bkmrk-%5Bembed%3A-node%2Fae3f626" ref="node/ae3f626a-f259">[embed: node/ae3f626a-f259]</div>Der Browser holt die Seite über <code>index&#46;php</code> und arbeitet danach nur noch über <code>api&#46;php</code>; beide nutzen <code>lib&#46;php</code>, das allein auf <code>data&#47;</code> zugreift.

<table id="bkmrk-datei-aufgabe-index."><colgroup><col></col><col></col></colgroup><tbody><tr><th colspan="1" rowspan="1">Datei

</th><th colspan="1" rowspan="1">Aufgabe

</th></tr><tr><td colspan="1" rowspan="1"><code>index&#46;php</code>

</td><td colspan="1" rowspan="1">Anmeldung, Selbst-Anmeldung, Seitengerüst für angemeldete Nutzer

</td></tr><tr><td colspan="1" rowspan="1"><code>api&#46;php</code>

</td><td colspan="1" rowspan="1">JSON-Schnittstelle für Laden, Speichern, Versionen, Konto, Admin-Funktionen

</td></tr><tr><td colspan="1" rowspan="1"><code>lib&#46;php</code>

</td><td colspan="1" rowspan="1">Speicher, Sitzung, Anmeldung, Bereinigung, Berechnung, Änderungsvergleich, AVR-Tabelle; direkt aufgerufen 403

</td></tr><tr><td colspan="1" rowspan="1"><code>app&#46;js</code>

</td><td colspan="1" rowspan="1">Oberfläche: Tabelle, Kategorien, Live-Rechnung, Markierungen, CSV-Export, Abfrage alle 20 s

</td></tr><tr><td colspan="1" rowspan="1"><code>app&#46;css</code>

</td><td colspan="1" rowspan="1">Gestaltung, heller und dunkler Modus, Signalfarben

</td></tr><tr><td colspan="1" rowspan="1"><code>login&#46;js</code>

</td><td colspan="1" rowspan="1">Umschalten zwischen Anmelden und Zugang einrichten

</td></tr><tr><td colspan="1" rowspan="1"><code>&#46;htaccess</code>

</td><td colspan="1" rowspan="1">kein Verzeichnislisting, <code>lib&#46;php</code> gesperrt, <code>noindex</code>

</td></tr><tr><td colspan="1" rowspan="1"><code>data&#47;&#46;htaccess</code>

</td><td colspan="1" rowspan="1">sperrt den Datenordner komplett

</td></tr></tbody></table>

## Datenhaltung und Datenmodell

Alle Daten liegen im Ordner `data/` als JSON in PHP-Dateien mit vorangestelltem `<?php exit; ?>`. Direkt aufgerufen liefern sie nichts; zusätzlich sperrt `data/.htaccess` den Zugriff. Schreibvorgänge laufen unter einer Dateisperre (`data/.lock`) und werden über eine Temporärdatei atomar ersetzt.

<table id="bkmrk-datei-inhalt-data%2Fst"><colgroup><col></col><col></col></colgroup><tbody><tr><th colspan="1" rowspan="1">Datei

</th><th colspan="1" rowspan="1">Inhalt

</th></tr><tr><td colspan="1" rowspan="1"><code>data&#47;state&#46;php</code>

</td><td colspan="1" rowspan="1">Aktueller Plan: <code>version</code>, <code>plan</code>, <code>cfg</code>, <code>marks</code>, <code>savedAt</code>, <code>savedBy</code>

</td></tr><tr><td colspan="1" rowspan="1"><code>data&#47;users&#46;php</code>

</td><td colspan="1" rowspan="1">Zugänge: Kennwort-Hash (bcrypt), Rolle, Anzeigename, Farbe, <code>open</code>, <code>mustChange</code>

</td></tr><tr><td colspan="1" rowspan="1"><code>data&#47;settings&#46;php</code>

</td><td colspan="1" rowspan="1">Einladungscode als Hash, Migrationsstand <code>v2</code>

</td></tr><tr><td colspan="1" rowspan="1"><code>data&#47;attempts&#46;php</code>

</td><td colspan="1" rowspan="1">Fehlversuche je IP (als SHA-256-Hash), Sperrzeit

</td></tr><tr><td colspan="1" rowspan="1"><code>data&#47;history&#47;&#60;Zeit&#62;&#45;&#60;id&#62;&#46;php</code>

</td><td colspan="1" rowspan="1">Je Speichern ein Stand mit Plan, Vorgaben und Summen; die neuesten 40 bleiben

</td></tr></tbody></table>

**Plan (`plan`)** – `title`, `year`, `rows[]`. Jede Zeile: `id`, `name`, `cat` (A–D), `f2` (Faktor), `f2typ` (`pct` oder `qty`), `ein` (Einnahme/Refinanzierung in €), `stufe` (1–5).

**Vorgaben (`cfg`)** – `agPct` (AG-Nebenkosten in %), `jsz` (Jahressonderzahlung in Monatsentgelten), `v{zeilen-id}` mit `f1` (Vorgabe in €), `tarif` (leer oder `AVR-DD`), `eg` (1–13). Vorgaben liegen getrennt vom Plan, damit nur der Admin sie ändern kann.

**Markierungen (`marks`)** – je Zeile und Feld: wer (`by`), wann (`at`), Ausgangswert (`from`); dazu `meta` für Titel, Jahr und AVR-Werte, `removed[]` für gelöschte Zeilen und `since` für den zuletzt festgeschriebenen Stand.

## Anmeldung, Rollen und Sicherheit

Der Server prüft jede Berechtigung selbst; die Oberfläche blendet nur aus, was ohnehin abgelehnt würde.

<table id="bkmrk-aktion-admin-zugang-"><colgroup><col></col><col></col><col></col></colgroup><tbody><tr><th colspan="1" rowspan="1">Aktion

</th><th colspan="1" rowspan="1">Admin

</th><th colspan="1" rowspan="1">Zugang

</th></tr><tr><td colspan="1" rowspan="1">Titel, Faktor, Stufe, Einnahmen ändern, Zeilen anlegen/löschen

</td><td colspan="1" rowspan="1">ja

</td><td colspan="1" rowspan="1">ja

</td></tr><tr><td colspan="1" rowspan="1">Vorgabe, Tarif, EG, AG-Nebenkosten, Jahressonderzahlung

</td><td colspan="1" rowspan="1">ja

</td><td colspan="1" rowspan="1">nein (vom Server ignoriert)

</td></tr><tr><td colspan="1" rowspan="1">Stand festschreiben, Anzeigenamen, Einladungscode, Plätze freigeben

</td><td colspan="1" rowspan="1">ja

</td><td colspan="1" rowspan="1">nein

</td></tr><tr><td colspan="1" rowspan="1">Eigenes Kennwort ändern, CSV-Export, Versionen laden

</td><td colspan="1" rowspan="1">ja

</td><td colspan="1" rowspan="1">ja

</td></tr></tbody></table>

**Selbst-Anmeldung** – Mit gültigem Einladungscode, Name und eigenem Kennwort (mind. 10 Zeichen) belegt eine Person den nächsten freien Platz 01a–07a und sieht danach ihren Benutzernamen. Ohne gesetzten Code ist die Selbst-Anmeldung aus. Doppelte Namen werden abgewiesen.

**Pflicht-Kennwortwechsel** – Zugänge mit `mustChange` (Musterkennwort, Admin nach Zurücksetzen) sehen nur das Kennwortformular; `save`, `ack`, `names`, `invite` und `slot` liefern bis dahin 403.

**Schutzmaßnahmen**

- Kennwörter und Einladungscode nur als bcrypt-Hash (`password_hash`)
- Nach 5 Fehlversuchen 15 Minuten Sperre je IP, zusätzlich 0,4 s Verzögerung je Fehlversuch
- Sitzungscookie `OGVHP`: HttpOnly, Secure, SameSite=Strict, auf den Ordner begrenzt; Abmeldung nach 4 Std. Inaktivität; neue Sitzungs-ID bei Anmeldung und Kennwortwechsel
- CSRF-Token bei jedem POST (Header `X-CSRF` bzw. Formularfeld)
- Header: Content-Security-Policy (Skripte nur vom eigenen Server), `X-Frame-Options: DENY`, `noindex`, `no-store`
- Eingaben werden serverseitig bereinigt: Längen, Zahlenbereiche, erlaubte Werte, max. 200 Zeilen, max. 500 KB je Anfrage

## Berechnungslogik

Jede Zeile ergibt einen Betrag aus Vorgabe und Faktor, auf ganze Euro gerundet; Summen addieren die gerundeten Zeilen. Browser (`app.js`) und Server (`lib.php`) rechnen identisch, der Server für Versionen und Summen.

```latex
\text{Betrag} = \operatorname{round}\left(\lvert \text{Vorgabe} \rvert \cdot \text{Faktor}\right), \quad \text{Faktor} = \begin{cases} f_2 / 100 & \text{bei \%} \\ f_2 & \text{bei Anzahl} \end{cases}
```

- **Kategorie A (Einnahmen):** Betrag zählt als Einnahme.
- **Kategorien B–D:** Betrag zählt als Ausgabe; das Feld „Einnahmen“ der Zeile (Refinanzierung) zählt zusätzlich als Einnahme.
- **Saldo** = Summe Einnahmen − Summe Ausgaben; **Kostendeckung** = Einnahmen ÷ Ausgaben.

**AVR-DD-Zeilen** – Ist der Tarif `AVR-DD`, ersetzt das AG-Brutto die frei eingetragene Vorgabe:

```latex
\text{AG-Brutto} = \operatorname{round}\left(M_{EG,Stufe} \cdot (12 + \text{JSZ}) \cdot \left(1 + \tfrac{\text{AG-Nebenkosten}}{100}\right)\right)
```

M ist das Monatsentgelt Vollzeit (39 Std.) aus der eingebauten Tabelle EG 1–13, Stufe 1–5, gültig ab 01.09.2026. Voreinstellung: JSZ = 1,0 Monatsentgelt, AG-Nebenkosten = 25 % (Schätzwert, mit Lohnbuchhaltung abgleichen). Stufen, die es in einer EG nicht gibt (z. B. EG 1, Stufe 1), sind nicht wählbar.

Die Tabellenwerte stammen von [tarifvertrag-online.de](https://tarifvertrag-online.de/entgelttabelle/kirche/avr-diakonie/2026) und [tarif-gehalt.de](https://www.tarif-gehalt.de/oeffentlicher-dienst/entgelttabelle/avr-diakonie); vor Beschlüssen mit der offiziellen ARK.DD-Tabelle abgleichen.

## Änderungsverfolgung und Versionen

Der Server vergleicht beim Speichern den neuen mit dem gespeicherten Stand und trägt jede Abweichung mit dem angemeldeten Zugang ein; der Browser kann den Urheber nicht vorgeben.

- **Farben:** fest je Zugang (Admin 0, Zugang 01–10 = Farbe 1–10), in hellem und dunklem Modus definiert.
- **Markierung:** farbiger Balken und Hintergrund am geänderten Feld, Tooltip mit Person, Zeit und Vorher-Wert. Änderungen in ausgeblendeten Spalten markieren zusätzlich den Titel. Zugeklappte Kategorien zeigen Farbpunkte im Kopf.
- **Ungespeichert:** gestrichelter Rahmen in der eigenen Farbe, nur im eigenen Browser.
- **Rückkehr zum Ausgangswert:** Wird ein Feld auf den festgeschriebenen Wert zurückgesetzt, verschwindet die Markierung.
- **Festschreiben (Admin):** setzt alle Markierungen zurück; der aktuelle Stand wird neuer Ausgangspunkt (`marks.since`).

**Gleichzeitiges Arbeiten** – Jeder Stand hat eine `version`. Speichern sendet die Basisversion mit; weicht sie ab, antwortet der Server mit 409 und dem neuen Stand. Die eigenen Eingaben bleiben erhalten, ein Hinweis bietet „Neuere Fassung laden“ an. Alle 20 Sekunden fragt die Seite neue Stände ab (nicht bei verstecktem Tab).

**Versionen** – Jedes Speichern mit Änderungen legt eine Datei in `data/history/` an; ältere als die 40 neuesten werden gelöscht. „Laden“ holt einen Stand in den Editor, übernommen wird er erst mit „Speichern“. Ein Zugang ohne Admin-Recht lädt nur den Plan, die Vorgaben bleiben.

## API-Referenz

Alle Aufrufe gehen an `api.php?a=<aktion>`, brauchen eine gültige Sitzung (sonst 401) und antworten mit JSON. POST-Aufrufe brauchen den Header `X-CSRF` und einen JSON-Körper.

<table id="bkmrk-aktion-methode-recht"><colgroup><col></col><col></col><col></col><col></col></colgroup><tbody><tr><th colspan="1" rowspan="1">Aktion

</th><th colspan="1" rowspan="1">Methode

</th><th colspan="1" rowspan="1">Recht

</th><th colspan="1" rowspan="1">Zweck

</th></tr><tr><td colspan="1" rowspan="1"><code>state</code>

</td><td colspan="1" rowspan="1">GET

</td><td colspan="1" rowspan="1">alle

</td><td colspan="1" rowspan="1">Plan, Vorgaben, Markierungen, Zugänge, eigener Zugang, CSRF-Token

</td></tr><tr><td colspan="1" rowspan="1"><code>save</code>

</td><td colspan="1" rowspan="1">POST

</td><td colspan="1" rowspan="1">alle\*

</td><td colspan="1" rowspan="1"><code>&#123;base&#44; plan&#44; cfg&#63;&#125;</code> speichern; 409 bei veralteter <code>base</code>; <code>cfg</code> nur vom Admin

</td></tr><tr><td colspan="1" rowspan="1"><code>history</code>

</td><td colspan="1" rowspan="1">GET

</td><td colspan="1" rowspan="1">alle

</td><td colspan="1" rowspan="1">Liste der Versionen mit Zeit, Person, Summen

</td></tr><tr><td colspan="1" rowspan="1"><code>version</code>

</td><td colspan="1" rowspan="1">GET

</td><td colspan="1" rowspan="1">alle

</td><td colspan="1" rowspan="1"><code>&#38;id&#61;</code> einen Stand laden (<code>plan</code>, <code>cfg</code>)

</td></tr><tr><td colspan="1" rowspan="1"><code>passwd</code>

</td><td colspan="1" rowspan="1">POST

</td><td colspan="1" rowspan="1">alle

</td><td colspan="1" rowspan="1"><code>&#123;old&#44; new&#125;</code>, mind. 10 Zeichen, hebt <code>mustChange</code> auf

</td></tr><tr><td colspan="1" rowspan="1"><code>ack</code>

</td><td colspan="1" rowspan="1">POST

</td><td colspan="1" rowspan="1">Admin\*

</td><td colspan="1" rowspan="1">Markierungen zurücksetzen (Stand festschreiben)

</td></tr><tr><td colspan="1" rowspan="1"><code>names</code>

</td><td colspan="1" rowspan="1">POST

</td><td colspan="1" rowspan="1">Admin\*

</td><td colspan="1" rowspan="1"><code>&#123;names&#58;&#123;login&#58; name&#125;&#125;</code> Anzeigenamen setzen

</td></tr><tr><td colspan="1" rowspan="1"><code>invite</code>

</td><td colspan="1" rowspan="1">POST

</td><td colspan="1" rowspan="1">Admin\*

</td><td colspan="1" rowspan="1"><code>&#123;code&#125;</code> Einladungscode setzen (mind. 8 Zeichen), leer = abschalten

</td></tr><tr><td colspan="1" rowspan="1"><code>slot</code>

</td><td colspan="1" rowspan="1">POST

</td><td colspan="1" rowspan="1">Admin\*

</td><td colspan="1" rowspan="1"><code>&#123;login&#125;</code> Platz 01a–07a freigeben (Kennwort löschen)

</td></tr><tr><td colspan="1" rowspan="1"><code>logout</code>

</td><td colspan="1" rowspan="1">POST

</td><td colspan="1" rowspan="1">alle

</td><td colspan="1" rowspan="1">Sitzung beenden

</td></tr></tbody></table>

\* gesperrt (403), solange der Zugang sein Kennwort ändern muss.

Anmeldung und Selbst-Anmeldung laufen nicht über die API, sondern als Formular-POST an `index.php` (Felder `login`/`pass` bzw. `reg`, `code`, `name`, `p1`, `p2`, jeweils mit `csrf`).

## Betrieb

Wichtigste Regel: Bei Updates nur Programmdateien überschreiben, den Ordner `data/` nie hochladen – sonst gehen Planstände, Zugänge und Kennwörter verloren.

**Voraussetzungen** – Apache mit `.htaccess` (AllowOverride), PHP ab 7.4, Schreibrechte des Webservers auf `data/` und `data/history/`. Das WordPress-Hosting erfüllt das.

**Erstinstallation**

1. Ordner `bu20dg26et` per FTP in das Hauptverzeichnis der Website laden (neben `wp-config.php`), inklusive `.htaccess`-Dateien.
2. Schreibrechte für `data/` und `data/history/` setzen (meist 755 oder 775).
3. Prüfen: `/bu20dg26et/data/state.php` zeigt nichts oder 403.
4. Als Admin anmelden, Start-Kennwort ändern, Einladungscode setzen.

**Update** – Geänderte Dateien aus `index.php`, `api.php`, `lib.php`, `app.js`, `app.css`, `login.js` überschreiben. In `index.php` die Variable `$v` erhöhen, damit Browser neue CSS/JS laden; danach Strg + F5. Datenänderungen (z. B. Migration `v2`) laufen beim ersten Aufruf automatisch.

**Sicherung** – Ordner `data/` regelmäßig per FTP herunterladen. Wiederherstellen = Ordner zurückspielen.

**Admin-Kennwort vergessen** – Einmal-Datei `reset-admin.php` hochladen und aufrufen: setzt das Admin-Kennwort auf das Start-Kennwort mit Pflichtwechsel, hebt Sperren auf und löscht sich selbst. Danach prüfen, dass die Datei weg ist.

**Neue AVR-DD-Tabelle** – Die Werte stehen doppelt: `AVR` in `lib.php` und in `app.js`. Beide gleich ändern, Gültigkeitsdatum anpassen, `$v` erhöhen.

## Grenzen und offene Punkte

- **Ein Plan:** Es gibt genau einen Haushaltsplan; für ein neues Jahr wird er überschrieben (Versionen bleiben). Mehrere Jahre parallel bräuchten eine Erweiterung.
- **Konflikte:** Gleichzeitiges Speichern wird erkannt, aber nicht zusammengeführt; die zweite Person prüft und speichert erneut.
- **Musterkennwörter 08a–10a:** solange ungenutzt, mit bekanntem Muster anmeldbar (Pflichtwechsel greift). Bei Bedarf freigeben oder zufällige Kennwörter setzen.
- **Kein Kennwort-Reset per E-Mail:** Vergessene Kennwörter setzt der Admin über „Freigeben“ zurück (01a–07a); der Admin selbst über `reset-admin.php`.
- **AVR-DD-Werte doppelt im Code:** muss bei jeder Tarifrunde von Hand nachgezogen werden.
- **AG-Nebenkosten pauschal:** ein Prozentsatz für alle Stellen; Beitragsbemessungsgrenzen und Zusatzversorgung im Einzelnen sind nicht abgebildet.
- **Claude-Fassung getrennt:** Änderungen dort erreichen die Webversion nicht.