Spezifikationssystem und fachliche Wahrheitsquellen¶

Status: verbindlich
Spezifikationsversion: 1.2.1
Modellbezug: 0.6.2
Stand: 2026-07-05

1. Grundsatz¶

Immohai verwendet keine parallelen Wahrheiten. Jede verbindliche Aussage besitzt genau ein führendes Dokument. Andere Dokumente dürfen diese Aussage referenzieren, erläutern oder für einen konkreten Anwendungsfall zusammenfassen, aber nicht abweichend neu definieren.

Bei Widersprüchen gilt zuerst das führende Dokument des betroffenen Themas. Ein Widerspruch wird nicht durch Interpretation aufgelöst, sondern über den Änderungsprozess korrigiert.

2. Normative Dokumentklassen¶

verbindlich:
  aktuell gültige fachliche oder technische Regel

verbindlicher Zielentwurf:
  freigegebenes Zielbild für eine spätere Ausbaustufe
  noch keine Aussage über den aktuellen Implementierungsstand

informativ:
  Überblick, Arbeitsstand, Architekturübersicht oder abgeleitete Erklärung

Entwurf:
  nicht freigegebener Inhalt
  gehört grundsätzlich in docs/changes/proposals/

Zusätzliche Erläuterungen wie Dokumenttyp oder Implementierungsbezug dürfen ergänzt werden. Der Wert hinter Status: verwendet ausschließlich eine dieser vier Klassen.

Dateien unter docs/changes/proposals/ sind niemals fachliche Wahrheit und niemals direkte Implementierungsgrundlage.

3. Führende Dokumente je Thema¶

Thema	Führendes Dokument
Deterministische Formeln, Szenarien, KPIs, Case Ratings, Investment Rating und Modellgrenzen	`docs/calculations/model-specification.md`
Datenstrukturen und Feldverträge	`docs/specification/data-quality-and-validation/data-model.md`
Übergänge zwischen Eingabe, Engine, Speicherung, Vergleich und Reporting	`docs/specification/model-and-calculations/calculation-interfaces.md`
Datenqualitätsmethode der Investitionsanalyse	`docs/specification/data-quality-and-validation/data-quality-assessment.md`
KPI-Assessments, Case Ratings und Investment Rating	`docs/specification/model-and-calculations/kpi-assessments.md`
Marktmietdaten, Aggregation und Dataset-Lifecycle	`docs/specification/product-domains-and-workflows/market-rent-import.md`
RentEstimate und Übernahme in PropertyInput	`docs/specification/product-domains-and-workflows/rent-analysis.md`
PropertyRecord, Snapshot und Meine Objekte	`docs/specification/product-domains-and-workflows/saved-objects.md`
Reporting-Vertrag	`docs/specification/user-interface-and-reporting/reporting.md`
Reporttypen	`docs/specification/user-interface-and-reporting/report-types.md`
Batch-Import, Pre-Screening und Vollanalyse	`docs/specification/product-domains-and-workflows/batch-analysis.md`
Validierungs- und Abnahmeregeln	`docs/specification/data-quality-and-validation/validation.md`
App-Domänen und Verantwortungsgrenzen	`docs/specification/product-domains-and-workflows/application-domains.md`
Aktueller sichtbarer Frontend-Stand	`docs/specification/user-interface-and-reporting/frontend-mvp.md`
Verbindliche Entwicklungsreihenfolge	`docs/roadmap/roadmap.md`
Aktueller Arbeits- und Deploymentstand	`docs/roadmap/current-status.md`

4. Quellenhierarchie innerhalb des Berechnungsmodells¶

1. docs/calculations/model-specification.md
2. docs/specification/data-quality-and-validation/data-model.md
3. docs/specification/model-and-calculations/calculation-interfaces.md
4. weitere führende Spezifikationen des jeweiligen Themas
5. maschinenlesbare Schemas und Modellkonfiguration
6. Implementierung und Tests
7. UI und Reports

Maschinenlesbare Verträge müssen die verbindlichen Spezifikationen abbilden. Sie dürfen keine zusätzliche fachliche Regel einführen.

5. Metadaten jeder Spezifikation¶

Jede verbindliche oder informative Spezifikation verwendet:

Status:
Spezifikationsversion:
Modellbezug: optional
Implementierungsbezug: optional
Dokumenttyp: optional
Stand:

Spezifikationsversion bezeichnet die Version des Dokuments. Modellbezug bezeichnet die fachliche Modellversion. Beide Begriffe dürfen nicht vermischt werden.

6. Maschinenlesbare Verträge¶

Aktuelle führende Schemafamilie:

PropertyInput 0.5.1
AnalysisResult 0.1.1
PropertyRecord 0.1.1
RentEstimate 0.1.0
MarketRentImport 0.3.0
AnalysisDataQualityAssessment 0.2.0

Die aktuellen Versionen stehen in:

model/config/model-manifest.json

Frontend-Kopien müssen bytegleich mit den Modellverträgen sein.

7. Proposal-Ablage¶

Neue Änderungswünsche werden als einzelne Dateien in drei Kategorien dokumentiert:

docs/changes/proposals/
├── architecture/
│   └── ARCH-YYYY-NNN-<slug>.md
├── roadmap/
│   └── ROAD-YYYY-NNN-<slug>.md
└── specification/
    └── SPEC-YYYY-NNN-<slug>.md

Die erste Erfassung betrachtet den thematisch relevanten bestehenden Stand und dient der Einordnung sowie der Vermeidung offensichtlicher Dubletten. Sie verändert keine verbindlichen Dokumente, Verträge, Konfigurationen, Implementierungen oder Tests.

Die vollständige Prüfung beginnt vor einer Annahme oder Integration. Erst nach dokumentierter Entscheidung wird ein Proposal in die betroffenen führenden Dokumente und nachgelagerten Artefakte übernommen.

8. Spezifikationsänderungen während der Entwicklung¶

Spezifikationsvorschläge liegen unter:

docs/changes/proposals/specification/

Ein Vorschlag wird vor einer Übernahme mindestens geprüft gegen:

bestehende fachliche Wahrheit
bestehende Datenverträge
maschinelle Schemas und Konfigurationen
Implementierung und Legacy-Kompatibilität
Tests und Referenzfälle
Reporting und UI
Versionierungsfolgen
Roadmap und Abhängigkeiten

Erst nach dokumentierter Entscheidung wird der Vorschlag in alle betroffenen führenden Dokumente übernommen. Danach werden Schemas, Konfiguration, Code, Tests, Reporting, Roadmap und Arbeitsstand synchronisiert.

9. Roadmap- und Architekturänderungen¶

Roadmap-Vorschläge liegen unter docs/changes/proposals/roadmap/. Architekturvorschläge liegen unter docs/changes/proposals/architecture/.

Ein Roadmap-Vorschlag ändert weder die verbindliche Roadmap noch die Spezifikation. Ein Architekturvorschlag ändert weder das verbindliche Architekturziel noch bestehende Verträge. Die Übernahme erfolgt erst nach Prüfung und dokumentierter Entscheidung.

10. Keine stillen Änderungen¶

Nicht zulässig:

fachliche Regeln nur im Code ändern
Formeln in UI oder Reports ergänzen
Vorschläge direkt implementieren
Roadmap-Prioritäten ohne dokumentierte Entscheidung ändern
alte Spezifikationen still überschreiben
abweichende Feldnamen in mehreren Dokumenten pflegen

11. Fixierter Stand¶

Ein Spezifikationsstand gilt erst als fixiert, wenn:

führende Dokumente widerspruchsfrei sind
Querverweise stimmen
maschinenlesbare Verträge synchron sind
Implementierung und Tests den Vertrag erfüllen
Dokumentationsbuild erfolgreich ist
Browserabnahme erfolgt ist, soweit UI betroffen ist
Review abgeschlossen ist

Fixiert bedeutet nicht unveränderlich. Jede spätere Änderung folgt erneut dem dokumentierten Vorschlags- und Übernahmeprozess.