From e718baadc2554a79981b0c7553e592ecb0f02a31 Mon Sep 17 00:00:00 2001
From: openclaw <openclaw@forgejo.local>
Date: Thu, 5 Mar 2026 15:33:49 +0000
Subject: [PATCH] Document dispute/contract flow and add audit trail model

---
 README.md                            |   2 +
 docs/dispute-flow.md                 | 122 +++++++++++++++++++++++++++
 docs/drafts/contract_flow.initial.md |   8 ++
 3 files changed, 132 insertions(+)
 create mode 100644 docs/dispute-flow.md
 create mode 100644 docs/drafts/contract_flow.initial.md

diff --git a/README.md b/README.md
index 1a465f9..355f755 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,8 @@ npm run start
 
 ## API Governance
 
+- Dispute-Flow Doku: `docs/dispute-flow.md`
+
 - OpenAPI: `openapi.yaml` (Spiegel: `docs/openapi.yaml`)
 - Versioning/Deprecation Policy: `docs/api-versioning.md`
 
diff --git a/docs/dispute-flow.md b/docs/dispute-flow.md
new file mode 100644
index 0000000..7bdbf99
--- /dev/null
+++ b/docs/dispute-flow.md
@@ -0,0 +1,122 @@
+# Vertrags-/Dispute-Flow nach Deal-Abschluss
+
+Diese Doku definiert den verbindlichen Konfliktprozess nach einem abgeschlossenen Deal.
+
+## Ziel
+
+- Streitfaelle standardisiert bearbeiten
+- Entscheidungen nachvollziehbar und auditierbar machen
+- Klare Eskalationspfade fuer User und Moderation
+
+## Scope
+
+Gilt fuer alle Deals im Status `agreed` oder `completed`, bei denen eine Partei einen Konflikt meldet.
+
+## Dispute-Statusmodell
+
+Ein Dispute durchlaeuft genau diese Stati:
+
+1. `open`  
+   Fall wurde erstellt, Basisdaten vorhanden.
+2. `evidence`  
+   Evidenzphase aktiv (Dateien, Chatverlauf, Zahlungsbelege, Fotos).
+3. `mediation`  
+   Moderierte Klaerung/Schlichtung laeuft.
+4. `resolved`  
+   Endentscheid dokumentiert (z. B. refund, partial_refund, reject).
+5. `cancelled`  
+   Fall durch Melder zurueckgezogen (nur vor finaler Entscheidung).
+
+## Rollen und Rechte
+
+- `requester` und `helper`: duerfen Dispute eroeffnen, Evidenz einreichen, Kommentare hinterlassen.
+- `moderator`: darf in `mediation` ueberfuehren und final entscheiden.
+- `admin`: darf Entscheidungen uebersteuern (mit Pflicht zur Begruendung im Audit-Log).
+
+## Mindestdaten pro Streitfall
+
+Beim Erstellen eines Disputes sind mindestens erforderlich:
+
+- `dealId`
+- `openedByUserId`
+- `reasonCode` (z. B. `NO_SHOW`, `QUALITY_ISSUE`, `PAYMENT_DISPUTE`, `ABUSE`)
+- `summary` (kurze, strukturierte Beschreibung)
+- `requestedOutcome` (`refund`, `partial_refund`, `complete_work`, `other`)
+
+## Evidenzregeln
+
+- Jede Evidenz wird als Event mit Zeitstempel gespeichert.
+- Dateien werden ueber Referenzen (`storageKey`, `contentHash`) protokolliert.
+- Nachtraegliche Aenderungen an Evidenz sind verboten; nur neue Event-Eintraege.
+
+## Entscheidungs- und Eskalationsregeln
+
+- SLA-Vorschlag:
+  - Erstreaktion: < 24h
+  - Mediation starten: < 72h
+  - Finalentscheid: < 7 Tage nach vollstaendiger Evidenz
+- Auto-Eskalation:
+  - Falls in `evidence` > 72h keine Aktivitaet: Reminder
+  - Falls in `mediation` > 7 Tage offen: Escalate an Admin
+- Jeder Finalentscheid braucht:
+  - `decision`
+  - `decidedByUserId`
+  - `decisionReason`
+  - `decidedAt`
+
+## Auditierbarkeit und Reproduzierbarkeit
+
+Zur Nachvollziehbarkeit werden zwei Ebenen persistiert:
+
+1. **Current State** in `disputes`
+2. **Immutable History** in `dispute_events`
+
+### Vorgeschlagenes Datenmodell (SQL-Skizze)
+
+```sql
+CREATE TABLE disputes (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  deal_id BIGINT NOT NULL,
+  opened_by_user_id BIGINT NOT NULL,
+  status ENUM(open,evidence,mediation,resolved,cancelled) NOT NULL DEFAULT open,
+  reason_code VARCHAR(64) NOT NULL,
+  summary TEXT NOT NULL,
+  requested_outcome VARCHAR(64) NOT NULL,
+  final_decision VARCHAR(64) NULL,
+  final_reason TEXT NULL,
+  decided_by_user_id BIGINT NULL,
+  decided_at TIMESTAMP NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  FOREIGN KEY (deal_id) REFERENCES deals(id),
+  FOREIGN KEY (opened_by_user_id) REFERENCES users(id)
+);
+
+CREATE TABLE dispute_events (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  dispute_id BIGINT NOT NULL,
+  event_type VARCHAR(64) NOT NULL,
+  actor_user_id BIGINT NOT NULL,
+  payload_json JSON NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (dispute_id) REFERENCES disputes(id),
+  FOREIGN KEY (actor_user_id) REFERENCES users(id)
+);
+```
+
+## API-Endpunkte (Plan)
+
+- `POST /disputes` -> Dispute erstellen
+- `POST /disputes/{id}/evidence` -> Evidenz anhängen
+- `POST /disputes/{id}/status` -> Statuswechsel (rollenbasiert)
+- `POST /disputes/{id}/resolve` -> Finalentscheid
+- `GET /disputes/{id}` -> aktueller Fallstatus
+- `GET /disputes/{id}/events` -> vollstaendige Historie
+
+## Definition of Done fuer Implementierung
+
+- Statusmaschine serverseitig durchgesetzt
+- Jede relevante Aktion erzeugt `dispute_events`-Eintrag
+- Finalentscheid ist inklusive Begruendung auditierbar
+- OpenAPI um Dispute-Endpunkte erweitert
+- Contract-Tests fuer Happy Path + Eskalation vorhanden
diff --git a/docs/drafts/contract_flow.initial.md b/docs/drafts/contract_flow.initial.md
new file mode 100644
index 0000000..d97e00c
--- /dev/null
+++ b/docs/drafts/contract_flow.initial.md
@@ -0,0 +1,8 @@
+# Contract flow work
+This branch will implement contract and dispute handling after deal closure.
+
+## Tasks
+- Add endpoints for contract creation.
+- Implement dispute validation.
+- Update OpenAPI spec.
+- Write tests.