Zum Inhalt

Xolib Score -- Spezifikation v2

Format: DOCX Datei: docs/input/xolib_score_v2_spezifikation.docx (auch in docs/specs/)

Was sich von v1 zu v2 geaendert hat

Die v1-Spezifikation hatte drei strukturelle Schwaechen: (1) Substanz und Technologie basierten fast vollstaendig auf manuellen Eingaben, (2) es gab keine Messung der Verwaltungsqualitaet (nur Ticket-Quantitaet), (3) der Score war eine Zahl ohne Erklaerung und ohne Vertrauensbeweis. Fuer Banken und Versicherungen war er damit nicht verwertbar.

Ziel von v2: Der Score wird von einer internen Kennzahl zu einem extern verwertbaren, manipulationssicheren, vollstaendig transparenten Bewertungsprodukt.

Drei-Stufen-Versionierungsprinzip

Jeder Score-Faktor wird mit einem Versions-Badge versehen:

  • V1 (Sofort): Manuell eingegeben oder aus bestehenden Xolib-Daten automatisch berechnet
  • V2 (6-12 Monate): Automatisch aus API-Integrationen (Techem/Ista) oder NLP-Verarbeitung
  • V3 (2+ Jahre): IoT-Sensoren, externe Datenquellen, eigenes KI-Modell

Grundregel: Faktor vorhanden und aktuell = voller Beitrag, hohe Konfidenz. Veraltet (>2 Jahre) = 70% Beitrag, gelbe Warnung. Manuell statt automatisch = 80% Beitrag. Fehlend = neutraler Wert 50, niedrige Konfidenz, rote Luecke in UI.

Die 6 neuen Datenpunkte

  1. Energieverbrauchsdaten (hoechste Prio) -- realer Heizenergie- und Stromverbrauch pro Einheit/Monat. Macht Technologie-Score von Schaetzung zur Messung. Normalisierung: <50 kWh/m2a = 100, >160 = 15. Neues Prisma-Modell: EnergyReading.
  2. Handwerker-Qualitaetsbewertungen -- strukturierte Bewertung nach jedem abgeschlossenen Ticket (1-5 Sterne, Nachbearbeitungsquote, Kostenabweichung). Neues Modell: WorkerRating.
  3. BK-Abweichungsquote -- Nachzahlungsquote, durchschnittliche Abweichungshoehe, Abrechnungspuenktlichkeit (Frist nach Par. 556 BGB). Aus bestehendem OperatingCost-Modell ableitbar.
  4. Kommunikations-Sentiment -- NLP-Analyse auf Ticket-Texte. Eskalierende Kommunikation korreliert mit Mieterfluktuation und Rechtskosten. Feld: Ticket.sentimentScore.
  5. Dokument-Vollstaendigkeit -- Compliance-Checkliste der Pflichtdokumente (Energieausweis, Versicherungen, Freistellungsbescheinigungen, Uebergabeprotokolle, Aufzug-TUEV).
  6. Wartungsvertrags-Dokumentation -- Alle relevanten Wartungsvertraege dokumentiert (Heizung, Aufzug, Rauchwarnmelder, Feuerschutz).

Hash-Chaining (Integritaetssicherung)

Jeder Score-Eintrag in PropertyScoreHistory enthaelt einen SHA-256-Hash (scoreHash), der den vorherigen Hash einschliesst (previousHash). Damit ist die Score-Historie manipulationssicher und laesst sich fuer Bank-APIs verifizieren. Felder: chainValid, chainValidatedAt, externalAnchorTx, externalAnchorAt.

Implementierungsstatus

Die v2-Spezifikation wurde implementiert in:

  • src/lib/score/calculator.ts -- 44KB, Hauptberechnung mit allen Kategorien und Normalisierungen
  • src/lib/score/normalization.ts -- Normalisierungsregeln
  • src/lib/score/integrity.ts -- Hash-Chain-Verifizierung
  • src/lib/score/trigger.ts -- Automatische Neuberechnung bei Datenaenderungen