Merge pull request #28 from Pitastic/tags_vs_category

Tagging und Kategorisieren auftrennen

Author: Pitastic

Models.md

@@ -1,6 +1,37 @@
-## Models
+# Models
 
-### Datenbankeintrag für eine Transaktion
+## Dictionary einer Config
+
+```
+{
+    'uuid': str             # (generated)
+    'metatype': str         # (config)
+    'name': str,            # Typ des Configeintrags (user, group, ui...)
+
+    -------- Zusatz je Config Typ -------
+
+    **kwargs
+    
+    . . . . . . . z.B. User . . . . . . .
+
+    'username': str,
+    'password': str         # hashed
+    'ibans': list           # Eigentümer
+    'rules': dict           # private Regeln
+    'parser': dict          # private Parser
+
+    . . . . . . . z.B. Gruppe . . . . . .
+
+    'groupname': str
+    "ibans": list,          # IBANs, die zur Gruppe gheören
+    "members": [
+        { "user": "anna", "role": "owner" },
+        { "user": "bob", "role": "viewer" }
+    ]
+}
+```
+
+## Datenbankeintrag für eine Transaktion
 
 ```
 {
@@ -17,78 +48,127 @@
     'currency': str,
     'parsed': dict( str: str )
     'category': str,
-    'subcategory': str,
     'tags': list[str],
     'priority': int,
 }
 ```
 
-### Metadaten
+## Parsing Objects
 
-#### Dictionary eines Rulesets (Tag/Parse)
+Beim Import eines Kontoauszugs werden die Transaktionen in ihre Grunddaten zerlegt und in einer Datenbankgespeichert. Das Parsing erkennt nach bestimmten Regeln Informationen, die sich aus den Rohdaten ergeben und reichert damit den Informationsgehalt der einzelnen Transaktion an.
 
-Regeln können Attribute einer Transaktion untersuchen und anhand dessen klassifizieren oder taggen. Zu den Werten kann nicht die primäre Kategorie zählen, wohl aber andere Tags, parsing Informationen oder Regexes auf den Buchungstext (und mehr).
+Bei jeder Regex-Regel gilt, dass der Ausdruck genau eine Matching-Group ergeben muss, deren Informationen als Wert des Parsings übernommen wird.
 
 ```
 {
-    'uuid': str             # (generated)
-    'metatype': str         # (config|rule|parser)
+    'metatype': str,
     'name': str,
-    'regex': r-str( RegEx ),
+    'regex': r-str(RegEx)
+}
+```
 
-    -------- Zusatz bei Rules -------
+#### .metatype, str (`parser`)
 
-    'category': str | None,
-    'tags': list[str] | None,
+Klassifiziert das Objekt als Regel für das Parsing.
+
+#### .name, str
+
+Frei wählbarer Name der Regel.
+
+#### .regex, r-str (optional)
 
-    . . . . . . . optional . . . . . .
+Regex String, der auf den Buchungstext angewendet werden soll. Er muss genau eine Matching-Group enthalten. Der Wert dieses Treffers (der Gruppe) wird als Wert mit dem Namen der Regel in der Transaktion als Ergebnis gespeichert.
 
-    'prioriry': int,
+## Rule Objects
+
+```
+{
+    'metatype': str
+    'name': str,
+    'multi': str,
     'parsed': dict(
-        'multi': str,       # (AND|OR)
-        'query': dict       # (key=Name, val=Value)
+        key, str | int : value str | int | bool | list
     )
+    'filter': list( dict(
+        'key': str,
+        'value': int, str, bool, list,
+        'compare': str
+    ) )
+    'category': str | None,
+    'tags': list,
+    'prioriry': int | None
 }
 ```
 
-#### Dictionary einer Config
+Regeln können Attribute einer Transaktion untersuchen und anhand dessen klassifizieren oder taggen. Bei den Regeln zum Tagging können auch zuvor geparste Informationen zählen; bei den Regeln zum Kategorisieren zusätzlich auch bereits gesetzte Tags einer Transaktion. Beide Typen unterscheiden sich in der Angabe beim Schlüssel `metatype`, sind aber sonst sehr ähnlich. Persistente Regeln werden als `json` im Ordner `settings/rule` abgelegt. Die Nummerierung im Dateinamen gibt die Lade-Reihenfolge an. Später geladene Regeln mit gleichem Namen können frühere überschreiben.
 
-```
-{
-    'uuid': str             # (generated)
-    'metatype': str         # (config)
-    'name': str,            # Typ des Configeintrags (user, group, ui...)
+### Schlüssel dieses Objektes
 
-    -------- Zusatz je Config Typ -------
+#### .metatype, str (`rule` | `category`)
 
-    **kwargs
-    
-    . . . . . . . z.B. User . . . . . . .
+Klassifiziert das Objekt als Regel für das Tagging oder zur Kategorisierung. Einige Schlüssel werden abhängig von dieser Angabe anders genutzt (siehe unten).
 
-    'username': str,
-    'password': str         # hashed
-    'ibans': list           # Eigentümer
-    'rules': dict           # private Regeln
-    'parser': dict          # private Parser
+#### .name, str
 
-    . . . . . . . z.B. Gruppe . . . . . .
+Frei wählbarer Name der Regel.
+
+##### .multi, str (`AND` | `OR`)
+
+Art der Verkettung der Filter. Ohne diese Angabe wird der Default `AND` gewählt. Wird hier `OR` angegeben, werden alle Filter (`regex`, `filter`, `parsed`-keys) mit `OR` verknüpft.
+
+#### .parsed, dict (optional)
+
+Ein Dictionary, bei dem der `key` der Bezeichner für den geparsten Wert einer Transaktion unter `.parsed.$WERT` ist, der mit dem `value` abgeglichen wird.
+
+##### .parsed[].key, str, int
+
+Die Bezeichnung (Schlüssel) des Werts, der geprüft werden soll.
+
+#### filter, list (optional)
+
+Liste mit Dictionaryies, die Argumenten zum durchsuchen von allgemeinen Werten einer Transaktion enthalten.
+
+##### filter[].key, str | int
+
+Die Bezeichnung (Schlüssel) des Werts, der geprüft werden soll. `key` kann hier jeder Bezeichner sein, der in der ersten Ebene des Transaktionsobjektes vorkommen könnte. Ausgenommen sind hier die `parsed` Werte, für die es ja aber dafür eine eigene Filterangabe gibt.
+
+#### filter[].value, str | int | bool | list
+
+Der Wert, mit dem der Wert aus der Datenbank abgeglichen werden soll.
+
+#### filter[].compare, str (`==` | `!=` | `<` | `>` | `<=` | `>=` | `in` | `notin` | `all` | `regex`)
+
+Art des Vergleichs:
 
-    'groupname': str
-    "ibans": list,          # IBANs, die zur Gruppe gheören
-    "members": [
-        { "user": "anna", "role": "owner" },
-        { "user": "bob", "role": "viewer" }
-    ]
-}
 ```
+Wert-aus-DB von rule.key
+$compare
+rule.value
+```
+
+Dabei haben die Operatoren folgende Bedeutung:
+
+- `==` : Die Werte müssen exakt gleich sein (default).
+- `!=` : Die Werte müssen ungleich sein.
+- `<` : Der Wert in der Datenbank muss kleiner sein als der Vergleichswert.
+- `>` : Der Wert in der Datenbank muss größer sein als der Vergleichswert.
+- `<=` : Der Wert in der Datenbank muss kleiner oder gleich sein wie der Vergleichswert.
+- `>=` : Der Wert in der Datenbank muss größer oder gleich sein wie der Vergleichswert.
+- `in`: Mindestens ein Wert der Vergleichsliste muss in dem Listenwert aus der Datenbank vorkommen.
+- `all`: Alle Werte der Vergleichsliste müssen in dem Listenwert aus der Datenbank vorkommen.
+- `notin`: Kein Wert der Vergleichsliste darf in dem Listenwert aus der Datenbank vorkommen.
+- `regex`: Regex String, der auf den Buchungstext angewendet werden soll. Ein Teil-Treffer des RegExes wird als Treffer gewertet.
+
+#### .tags, list (nur bei metatype: `rule`)
+
+Liste mit Tags, die bei getroffene Einträge hinzugefügt werden.
 
-## Handling von Prioritäten
+#### .category, str (nur bei metatype: `category`)
 
-Die Priorität wird zwischen 0 und 100 automatisch gesetzt, kann aber auch abgegen werden. 0 ist unwichtig, 100 ist wichtig.
+Name der Hauptkategorie, die bei einem Treffer für den Eintrag gesetzt werden soll. Es muss entweder eine Haupt- oder eine Sekundärkategorie angegeben werden.
 
-Beim Tagging werden nur Einträge selektiert, die eine niedrigere Priorität haben als die akutelle Regel.
+#### .priority, int (nur bei metatype: `category`)
 
-Es wird beim Taggen entweder die Priorität 1 (automatisches Taggen), die der Regel gesetzt (wenn diese höher ist) oder die explizit übermittelte. Ausnahmen sind:
+Priorität der Regel. Eine höhere Priorität (größere Zahl) überschreibt zuvor gesetzt Kategorien mit einer niedrigeren Priorität.
 
-- Das manuelle Taggen: Hier wird immer eine Priorität von 99 gesetzt.
-- Das automatische Tagging mit einer explizit angegebenen Regel: Hier werden Einträge < 99 selektiert und überschrieben, dann aber wieder die Priorät der Regel (oder 1) gesetzt.
+Ein manuelles Kategorisieren hat immer die höchste Priorität.

app/static/js/index.js

@@ -141,7 +141,6 @@ function removeTags() {
  */
 function manualTagEntries() {
     const category = document.getElementById('input_manual_category').value;
-    const subcategory = document.getElementById('input_manual_subcategory').value;
     let tags = document.getElementById('input_manual_tags').value;
     const iban = document.getElementById('input_iban').value;
 
@@ -164,7 +163,6 @@ function manualTagEntries() {
 
     let tagging = {
         'category': category,
-        'subcategory': subcategory,
         'tags': tags
     }
 

app/templates/index.html

@@ -83,7 +83,6 @@ <h3>Tagging</h3>
             </select>
             <button onclick="tagEntries()">Auto Tag</button>
             <input type="text" value="" id="input_manual_category" placeholder="Manual Category">
-            <input type="text" value="" id="input_manual_subcategory" placeholder="Manual Sub-Category">
             <input type="text" value="" id="input_manual_tags" placeholder="Manual Tag">
             <button onclick="manualTagEntries()">Manuelles Taggen</button>
             <button onclick="removeTags()">Tags entfernen</button>