Refine ADR structure and context

2026-07-29 11:17:50 +02:00
parent 83639b9957
commit 6c07d1cc7b
5 changed files with 44 additions and 3 deletions
@@ -4,6 +4,10 @@

 Akzeptiert

+## Kontext
+
+RollCalc benötigt eine erzeugte Artikeldatendatei. Import, Validierung, manuelle Datenpflege und ERP-Verarbeitung sind eigenständige Verantwortlichkeiten. Diese Aufgaben würden das RollCalc-Repository unnötig mit Datenpflege- und Integrationslogik belasten.
+
 ## Entscheidung

 Der Article Data Manager wird als eigenstaendiges Projekt gefuehrt und nicht in das RollCalc-Repository integriert.
@@ -4,6 +4,10 @@

 Akzeptiert

+## Kontext
+
+Artikeldaten stammen aus mehreren Quellen mit unterschiedlicher Datenhoheit. Dazu gehören ERP-Daten, bestehende RollCalc-Daten, manuelle Zusatzdaten und generierte Ergebnisse. Ohne klare Trennung wären Herkunft, Priorität und Verantwortlichkeit schwer nachvollziehbar.
+
 ## Entscheidung

 ERP-Daten, bestehende RollCalc-Daten, manuelle Daten und generierte Daten werden physisch und logisch getrennt.
@@ -14,4 +18,4 @@ Die Trennung macht Herkunft, Verantwortlichkeit und Konflikte nachvollziehbar. S

 ## Konsequenzen

-Importer und Merge-Logik muessen Quelle und Prioritaet explizit beruecksichtigen. Produktive Datenverzeichnisse werden nicht standardmaessig versioniert.
+Importer und Merge-Logik muessen Quelle und Prioritaet explizit beruecksichtigen. Produktive Datenverzeichnisse werden nicht standardmaessig versioniert. Manuell gepflegte Daten benötigen eine unabhängige Backup- und Versionierungsstrategie, da sie nicht standardmäßig im Repository versioniert werden.
@@ -4,6 +4,10 @@

 Akzeptiert

+## Kontext
+
+Artikelnummern dienen als technische und fachliche Identifikatoren. Mindestens eine vorhandene Artikelnummer enthält eine führende Null. Eine numerische Behandlung könnte Identität und Format verändern.
+
 ## Entscheidung

 Artikelnummern werden durchgaengig als Strings behandelt.
@@ -4,6 +4,10 @@

 Akzeptiert

+## Kontext
+
+`article-data.json` wird aus mehreren Quellen erzeugt. Direkte Änderungen an dieser Datei wären bei einem erneuten Export nicht zuverlässig erhalten. Die Datei ist ein abgeleitetes Artefakt und keine führende Datenquelle.
+
 ## Entscheidung

 Die erzeugte `article-data.json` ist ein Build-Artefakt. Aenderungen duerfen nicht direkt ausschliesslich in dieser Datei vorgenommen werden.
@@ -14,4 +18,4 @@ Primaere Aenderungen gehoeren in ERP, bestehende RollCalc-Quelldaten oder manuel

 ## Konsequenzen

-`data/generated/article-data.json` wird nicht standardmaessig versioniert. Relevante Aenderungen muessen reproduzierbar aus den Quellen erzeugt werden.
+`data/generated/article-data.json` wird nicht standardmaessig versioniert. Relevante Aenderungen muessen reproduzierbar aus den Quellen erzeugt werden. Der Exportprozess muss deterministisch sein, damit identische Eingabedaten eine identische Ausgabedatei erzeugen.
@@ -1,3 +1,28 @@
 # Architecture Decision Records

-ADRs dokumentieren zentrale Architekturentscheidungen. Neue ADRs werden fortlaufend nummeriert und sollen Entscheidung, Kontext und Konsequenzen enthalten.
+ADRs dokumentieren zentrale Architekturentscheidungen. Sie werden fortlaufend nummeriert.
+
+## Verbindliche Struktur
+
+Jedes ADR verwendet diese Gliederung:
+
+```text
+# ADR NNNN - Titel
+## Status
+## Kontext
+## Entscheidung
+## Begründung
+## Konsequenzen
+```
+
+## Abschnitte
+
+- `Status`: aktueller Zustand der Entscheidung, zum Beispiel Vorgeschlagen, Akzeptiert, Ersetzt oder Verworfen.
+- `Kontext`: Ausgangslage und Problemstellung.
+- `Entscheidung`: konkret getroffene Architekturentscheidung.
+- `Begründung`: Gründe für die gewählte Lösung.
+- `Konsequenzen`: positive, negative und organisatorische Folgen.
+
+## Umgang mit bestehenden ADRs
+
+Bereits akzeptierte ADRs werden nicht stillschweigend inhaltlich umgedeutet. Wird eine Entscheidung ersetzt, soll ein neues ADR angelegt und das alte ADR entsprechend referenziert werden.