feat(disputes): add structured payment dispute resolution with evidence management #641

[salienne]

Overview

This PR adds a structured Payment Dispute Resolution system with evidence management, resolution tracking, dispute notifications, and analytics — addressing informal dispute handling.

Related Issue

Closes #641

Changes

⚖️ Dispute Resolution Engine

• [ADD] backend/src/services/dispute-resolution/workflow-engine.ts

  • Pure state machine for dispute statuses (pending → awaiting_response → under_review → resolved / dismissed / escalated).
  • SLA helpers (72h response / 168h escalation) and auto-escalation rules.

• [ADD] backend/src/services/dispute-resolution/dispute-resolution-service.ts

  • End-to-end orchestration: create, respond, evidence CRUD (SHA-256), assign arbitrator, escalate, resolve.
  • Resolution records + audit timeline.
  • Multi-channel dispute notifications (email / push / in-app).
  • Analytics (by status/reason/outcome, escalation rate, avg resolution hours, refunds, SLA breaches).
  • In-memory fallback + resetForTests() (same pattern as payment-reconciliation).

• [ADD] backend/src/routes/dispute-resolution.ts

  • Full REST API mounted at /api/v1/dispute-resolution.

• [MODIFY] backend/src/index.ts

  • Mount router; wire scheduled escalations alongside legacy cron.

• [ADD] backend/docs/DISPUTE_RESOLUTION.md

  • Feature documentation covering workflow, evidence, notifications, analytics, API, and ops.

• [ADD] backend/src/services/__tests__/dispute-resolution.test.ts

  • Coverage for workflow, evidence hashing, resolution tracking, notifications, SLA escalation, analytics.

Verification Results

npx vitest run src/services/__tests__/dispute-resolution.test.ts
✅ 10/10 passed

Acceptance Criteria	Status
Structured dispute workflow	✅ State machine + SLA escalation
Evidence upload and management	✅ Add/list/remove with SHA-256 integrity hash
Resolution tracking	✅ Resolution records + timeline
Dispute analytics	✅ GET /analytics metrics
Dispute notifications	✅ Channel fan-out on lifecycle events
Dispute API	✅ /api/v1/dispute-resolution CRUD + ops endpoints
Dispute documentation	✅ backend/docs/DISPUTE_RESOLUTION.md

Made with Cursor

[drips-wave]

@salienne Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[vercel]

@salienne is attempting to deploy a commit to the smartdevs17's projects Team on Vercel.

A member of the Team first needs to authorize it.