FSCash/README.md

# FSCash

Dokumentiere Ausgaben on-the-go als Webapp
& behalte den Überblick über Dein Aktiendepot

## ToDo

- [ ] Zusammenfassen von mehreren Einträgen zu einer Aktie
- [ ] Prüfen ob APIKEYS leer sind und ggfs die Aktualisierung ausblenden

## V.2.5

- [X] Lesende HTTP-Schnittstelle für den Buchungsabgleich externer Tools (Issue #13): `GET /api/v1/buchungen` sucht Buchungen anhand von Zeitraum, Betrag (mit Toleranz) und Währung; `GET /api/v1/status` dient als Verbindungstest. Beide Endpunkte sind rein lesend, ohne Seiteneffekte, und per HTTP Basic Auth mit den bestehenden FSCash-Zugangsdaten (Tabelle `users`) geschützt. Die Endpunkte benötigen `mod_rewrite` (siehe `html/.htaccess`), da die Pfade ohne `.php`-Endung erreichbar sein müssen. FSCash führt Bargeldausgaben intern als positiven Betrag; die Schnittstelle rechnet das für den Abgleich in die vom Finanzmanager erwartete Konvention um (Ausgaben negativ).

## V.2.4

- [X] Buchungszeilen im Dashboard haben ein zusätzliches Feld "abgeglichen" (Standard: nicht abgeglichen). Ein Klick auf die Zeile schaltet den Wert um und speichert ihn sofort in der DB. Abgeglichene Zeilen werden mit grünem Hintergrund dargestellt.

## V.2.3

- [X] Listen mit Spaltenfiltern (Dashboard) zeigen unterhalb eine optisch abgesetzte Summenzeile, die die Beträge der aktuell sichtbaren (gefilterten) Einträge in der Spalte "Betrag" aufsummiert.

## V.2.2

- [X] Unit-Tests (PHPUnit) für die wichtigsten Funktionen, gebündelt in `html/lib/fscash.php`: Monatsnavigation, Admin-/Aktien-Rollenprüfung, Aktien-GuV-Berechnung, OpenFIGI-/Alpha-Vantage-Antwortauswertung, Eingabevalidierung, CSV-Export und Migrations-Logik (siehe Abschnitt "Tests" unten).
- [X] `update.sh` führt die Tests jetzt automatisch vor jedem Deploy aus (inkl. `composer install`, falls nötig) und bricht bei Fehlschlag ab, bevor irgendetwas kopiert oder migriert wird.

## V.2.1

- [X] `update.sh` zum Deployen auf einen Zielserver: prüft PHP-Syntax, kopiert den aktuellen git-Stand ins Webroot (ohne die produktive `config.php` zu überschreiben) und wendet danach ausstehende Datenbank-Migrationen an.
- [X] neues Verzeichnis `migrations/` mit versioniertem Migrationssystem: nummerierte `.sql`-Dateien werden über eine `schema_migrations`-Tabelle nachverfolgt und jeweils nur einmal angewendet (siehe `migrations/README.md` für die Konvention).

## V.2.0

- [X] neue Haupt-Funktion: Aktien zeigt eine Liste mit gespeicherten, zu beobachtenden Aktien
- [X] Die Tabelle errechnet automatisch den aktuellen Gewinn oder Verluststand jeder Aktieneintragung
- [X] neue Aktie hinzufügen mit Kaufdatum und Kaufpreis, wird je Benutzer separat hinterlegt (user_id)
- [X] es KANN eine ISIN oder WKN eingetragen werden
- [X] Beim Abruf von aktuellen Kursdaten muss vorher ein API Key von https://www.alphavantage.co/support/#api-key beantragt werden.
- [X] Suchen von Symbolen passend zur ISIN geht über einen API Key von https://www.openfigi.com/user/signup
- [X] Alternativ kann auch nach dem Aktiennamen bei alphavantage gesucht werden - dafür muss man auf den Namen klicken
- [X] Aktien können geändert und gelöscht werden.

## V.1.2

- [X] Einträge löschen als Button im Editier-Fenster (UX dient der Prävention versehentlichen löschens auf der Startseite)

## V.1.1

Admin-Funktion:
- in der config.php kann vorkonfiguriert werden, welchen User_ids erlaubt ist, weitere User anzulegen.

Auswertungen:

- [X] CSV Export des ausgewählten Monats in der Kategorieübersicht
- [X] Monatssumme je Kategorie
  - [X] Filter monatsweise
  - [X] monate durchblättern zurück und vor, defaut aktueller Monat
- [X] Monatssumme je Person
  - [X] Haken, welche Kategorieen eingeschlossen werden
  - [X] Filter monatssummen
  - [X] monate durchblättern zurück und vor, defaut aktueller Monat

## V.1.0

Das erste Release enthält:

- [x] mariadb setup
- [x] apache2 setup
- [x] Auswahl des UI frameworks
- [x] login
- [x] Anzeige bestehender Ausgaben des aktuellen Monats
- [x] "+" Button zum Aufruf der Eingabemaske
- [x] Eingabemaske für Ausgaben
- [x] Speichern der Ausgaben in mariadb

Eingabe:

- [x] Betrag
- [x] Personn derzeit individuell direkt über die Mariadb Tabelle individualiserbar
- [x] für wen (Person1, Person2) jeweils mit Haken
- [x] Kategorie, derzeit individuell direkt über die Mariadb Tabelle individualiserbar
  - [x] Einkaufen
  - [x] Essengehen
  - [x] Freizeit
  - [x] PuFra
  - [x] Urlaub gemeinsam
  - [x] Urlaub Pössi
  - [x] Barausgaben
- [x] Datum ohne Uhrzeit, default heute, wählbar via Picker
- [x] Zahlungsmittel, derzeit individuell direkt über die Mariadb Tabelle individualiserbar
  - [x] Bar
  - [x] Karte
  - [x] Paypal
- [x] nicht löschbar!
- [x] alles MUSS-Felder

Ausgabe

- [x] Anzeige aller Ausgaben des aktuellen Monats
- [x] "+" Symbol für neue Ausgabe

Weiteres

- [x] Login/User aktiv halten
- [x] Datenspeicher MariaDB
- [x] Strato-Server
- [x] Kategorieanzeige in Übersicht durch Strings ersetzen
- [x] Übersicht rückwärts sortiert neu -> alt
- [x] Betrag deutsche Zahlen und rechtsbündig
- [x] Kommentarfeld freitext drei Zeilen

# Installationshinweise:

1. webserver & DB server aufsetzen
2. init.sql script als berechtigter DB user laufen lassen (meist root), der Datenbanken anlegen und Berechtigungen setzen kann.
3. html Ordner ins webroot kopieren
4. config_sample.php in config.php umbenennen und DB credentials setzen
5. webroot (z.B. http://localhost/) aufrufen und mit user test / test123 einloggen.
6. obige Schritte sind nur das Nötigste, um die Funktionalität herzustellen. Insbesondere bei Zugriffsmöglichkeiten aus dem Internet ist es wichtig, https Protokolle, vpns und/oder ggfs zusätzliche Sicherungsmassnahmen (hardening) zu ergreifen.
7. für die lesende API unter `/api/v1/` (siehe Abschnitt V.2.5) muss auf dem Apache-Server `mod_rewrite` aktiviert sein (`a2enmod rewrite`) und `AllowOverride All` für den Webroot gesetzt sein, damit die Regeln aus `html/.htaccess` greifen.

Ausserdem solltet Ihr User registrieren und ggfs. die Kategorien anpassen.

Das sollte alles sein. Bitte erstellt ein Bug-Ticket, wenn ich etwas übersehen habe. Gerne könnt Ihr auch Pull-Requests erstellen.

# Tests

Die wichtigsten, DB- und netzwerkfreien Funktionen liegen gebündelt in `html/lib/fscash.php`
(Monatsnavigation, Rollenprüfung, Aktien-GuV-Berechnung, Auswertung der OpenFIGI-/Alpha-Vantage-Antworten,
Eingabevalidierung, CSV-Export, Migrations-Logik) und werden über PHPUnit in `tests/FscashTest.php` geprüft.

Einmalig Abhängigkeiten installieren:

```
composer install
```

Tests lokal ausführen:

```
bash tests/run.sh
```

`update.sh` führt diesen Schritt automatisch vor jedem Deploy aus (inkl. `composer install`, falls `vendor/`
noch fehlt) und bricht bei einem Testfehlschlag ab, bevor irgendetwas kopiert oder migriert wird.