122 lines
3.9 KiB
Markdown
122 lines
3.9 KiB
Markdown
# 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
|