nick-doc/04 - Flows/Dispute Flow.md

title, tags, related_models, related_apis, audit

title	tags	related_models	related_apis	audit
Dispute Flow	flow dispute mediator evidence chat state-machine	Dispute Chat PurchaseRequest Payment	POST /api/disputes POST /api/disputes/:id/assign POST /api/disputes/:id/resolve POST /api/disputes/:id/evidence PATCH /api/disputes/:id/status	2026-05-29 — corrected against source: Dispute.ts, DisputeService.ts, routes/disputeRoutes.ts (dashboard), services/dispute/disputeRoutes.ts (release-hold), app.ts. Previous version had wrong resolution schema, invented status values, missing security issues, and incorrect socket-event description.

Last updated: 2026-05-29 — aligned with code (see Doc vs Code Audit Report)

Dispute Flow

When something goes wrong (item not delivered, wrong item, seller misbehaviour), either party can open a dispute. A three-way chat (buyer, seller, admin mediator) is created automatically. After evidence is gathered, the admin resolves the dispute — selecting an action such as refund, replacement, compensation, warning, or ban.

[!success] Security fixes applied (2026-05-30) The three privilege-escalation bugs documented in the original Security Gaps section were fixed in commit 1d881c5 (ISSUE-003, ISSUE-004) and fce8a19 (resolver role). Role guards are now enforced on assign/status/resolve; route shadowing is eliminated by remounting the release-hold router at /api/disputes/pr. See Security Gaps for the historical record and current state.

[!warning] Real-time events not implemented Every Socket.IO emit in DisputeService is currently commented out. No dispute-updated, new-notification, or any other socket event fires for dispute creation, admin assignment, status changes, evidence uploads, or resolution. The dispute feature is CRUD-only at this stage.

Actors

• Buyer — typical initiator.
• Seller — party against whom the dispute is raised (or in rarer cases, initiator).
• Admin / Mediator — assigned to investigate.
• Frontend — buyer/seller "Report issue" buttons in the request detail view; admin dispute dashboard.
• Admin / Mediator — assigned to investigate (role admin or resolver).
• Backend — DisputeService (backend/src/services/dispute/DisputeService.ts), dashboard/controller routes at backend/src/routes/disputeRoutes.ts (mounted at /api/disputes), and release-hold helpers in backend/src/services/dispute/disputeRoutes.ts (mounted at /api/disputes/pr since commit 1d881c5).
• MongoDB — disputes, chats, purchaserequests, payments.
• Socket.IO — no events fire today; all emits are TODO stubs (see warning above).

Preconditions

• The related PurchaseRequest exists.
• The initiator is the request's buyer or the related seller.
• Funds are typically held in escrow (Payment.escrowState = 'funded') — disputes on unfunded orders are accepted but have no monetary impact.

Dispute state machine (Dispute.status)

Valid status values (from Dispute.ts): pending | in_progress | waiting_response | resolved | rejected | closed.

[!caution] under_review does NOT exist. The correct progressed status is in_progress.

stateDiagram-v2
    [*] --> pending: createDispute()\nresponseDeadline=+48h\ndeadline=+7d
    pending --> in_progress: admin assigned\nassignAdmin()
    pending --> waiting_response: status update
    in_progress --> waiting_response: status update
    waiting_response --> in_progress: status update
    in_progress --> resolved: admin resolves\nresolveDispute()
    in_progress --> rejected: admin rejects
    in_progress --> closed: admin closes without resolution\n(e.g. duplicate/spam)
    pending --> closed: same
    resolved --> [*]
    rejected --> [*]
    closed --> [*]

Resolution schema (Dispute.resolution)

resolution?: {
  action: 'refund' | 'replacement' | 'compensation' | 'warning_seller' | 'ban_seller' | 'no_action';
  amount?: number;
  currency?: string;   // 'USD' | 'EUR' | 'IRR' | 'USDT'
  notes?: string;
  resolvedBy: ObjectId;
  resolvedAt: Date;
}

[!caution] Incorrect in previous docs: decision: buyer|seller|split and refundAmount do NOT exist in the model. The field is action with the six values listed above.

Dispute categories (Dispute.category)

Valid values: product_quality | delivery_delay | wrong_item | payment_issue | seller_behavior | other

[!caution] fraud is NOT a valid category. Use seller_behavior or other for fraud-type reports.

---

Security Gaps (Historical — All Closed as of 2026-05-30)

The following bugs were identified in the 2026-05-29 audit and fixed in commits 1d881c5 and fce8a19. The descriptions below are preserved for historical reference and audit trail.

1. PATCH /api/disputes/:id/status — no role guard ✅ FIXED

Fix: authorizeRoles('admin', 'resolver') added in commit fce8a19. Only admins and resolvers can change dispute status.

2. POST /api/disputes/:id/resolve (dashboard router) — no role guard ✅ FIXED

Fix: authorizeRoles('admin', 'resolver') added in commit fce8a19. Only admins and resolvers can resolve disputes.

Additional fix (ISSUE-004, commit 1d881c5): DisputeService.resolveDispute now calls releaseHoldResolve() on the linked purchaseRequestId, clearing the escrow hold automatically so the payment release is unblocked after resolution.

3. POST /api/disputes/:id/assign — no role guard ✅ FIXED

Fix: authorizeRoles('admin', 'resolver') added in commit fce8a19. Only admins and resolvers can assign mediators.

---

Route Shadowing (Historical — Resolved as of 2026-05-30)

Previously both routers were mounted at /api/disputes, causing the dashboard router to intercept release-hold requests. Fixed in commit 1d881c5 (ISSUE-003):

// app.ts — current state
app.use("/api/disputes", dashboardDisputeRoutes);  // src/routes/disputeRoutes.ts
app.use("/api/disputes/pr", disputeRoutes);        // src/services/dispute/disputeRoutes.ts — new prefix

Release-hold endpoints now use the /api/disputes/pr/ prefix:

• POST /api/disputes/pr/:purchaseRequestId/raise
• GET /api/disputes/pr/:purchaseRequestId/status
• POST /api/disputes/pr/:purchaseRequestId/resolve

---

Step-by-step narrative

Phase 1 — Opening

1. Buyer or seller opens the request detail and clicks "Report problem" (frontend/src/sections/request/components/report-problem-to-admin.tsx).
2. They select a category (product_quality | delivery_delay | wrong_item | payment_issue | seller_behavior | other), a priority (low | medium | high | urgent), write a description, and optionally upload evidence (images, screenshots, video, document) via POST /api/files/upload.
3. Frontend POSTs POST /api/disputes with { purchaseRequestId, reason, description, priority, category, evidence: [...] }.
4. Backend DisputeService.createDispute (:12-119):
   • Loads the purchase request with populate('selectedOfferId').
   • Resolves the counter-party sellerId by priority: explicit data.sellerId → selectedOffer.sellerId → first of preferredSellerIds. Once an offer is accepted, the dispute targets the actual seller, not the entire preferred list.
   • Creates the Dispute with status: 'pending', responseDeadline = now + 48h, deadline = now + 7 days, and an empty timeline[]. The pre-save hook appends an automatic dispute_created timeline entry.
   • Creates a Chat of type group with the buyer (and seller, if resolved) as participants. The opening message is a system-typed line "اختلاف جدید ایجاد شد: {reason}". The chat's relatedTo = { type: 'PurchaseRequest', id }.
   • Persists dispute.chatId = chat._id.
5. Notifications: none fire. The notification block is a TODO stub in DisputeService.createDispute (:107-116).

[!note] Release hold behavior Opening a dispute through the release-hold router (POST /api/disputes/:purchaseRequestId/raise) sets hold fields on the purchase request and related payments via releaseHoldService.raiseDispute(). Release/refund gates can consult those fields. This is a separate code path from DisputeService.createDispute above.

Phase 2 — Admin assignment

6. The admin dispute dashboard lists pending disputes (sorted by priority: -1, createdAt: -1).
7. Admin clicks "Pick up" → POST /api/disputes/:id/assign with { adminId }.

[!danger] No role guard on this endpoint — any authenticated user can call it (see Security Gaps).

8. DisputeService.assignAdmin (:184-223):
   • dispute.adminId = adminId; dispute.status = 'in_progress'.
   • Appends timeline entry { action: 'admin_assigned', performedBy: adminId, ... }.
   • Adds the admin to the dispute chat.participants[] (role admin).
   • Saves.
   • No socket event fires. (// TODO: Notify buyer and seller via Socket.IO)

Phase 3 — Investigation

9. All three parties chat in the dispute chat room (same socket mechanics as Chat Flow). Each party can upload more evidence via POST /api/disputes/:id/evidence — DisputeService.addEvidence (:305-337) appends to dispute.evidence[] and writes a timeline entry evidence_added. No socket event fires for evidence uploads.
10. The admin may also PATCH /api/disputes/:id/status with intermediate states or notes; this updates dispute.status and writes a timeline entry status_changed. No socket event fires.

[!note] PATCH /api/disputes/:id/status now requires admin or resolver role (authorizeRoles('admin', 'resolver'), commit fce8a19). The previously open privilege-escalation gap is closed.

Phase 4 — Resolution

11. Once the admin has enough information, they call POST /api/disputes/:id/resolve with:

    {
      "action": "refund | replacement | compensation | warning_seller | ban_seller | no_action",
      "amount": 150,
      "currency": "USD",
      "notes": "Seller failed to deliver item"
    }
    

12. DisputeService.resolveDispute (:262-300):
    • dispute.status = 'resolved'
    • dispute.resolution = { action, amount, currency, notes, resolvedBy: adminId, resolvedAt: now }
    • dispute.closedAt = now
    • Appends timeline entry dispute_resolved.
    • Saves.
    • Calls releaseHoldResolve(purchaseRequestId) — this clears the escrow hold automatically so the payment release is unblocked (ISSUE-004 fix, commit 1d881c5).
    • No socket event fires. (// TODO: Send notifications via Socket.IO)
13. Financial side-effect: as of commit 1d881c5 the escrow hold is cleared automatically on resolution. The admin still needs to separately trigger the ledger-gated release (Payout Flow / Escrow Flow) or refund for actual fund movement.

[!note] POST /api/disputes/:id/resolve now requires admin or resolver role (authorizeRoles('admin', 'resolver'), commit fce8a19). The previously open privilege-escalation gap is closed.

---

Sequence diagram

sequenceDiagram
    autonumber
    actor B as Buyer
    actor S as Seller
    actor A as Admin
    participant FE as Frontend
    participant BE as Backend
    participant DB as MongoDB
    participant IO as Socket.IO

    B->>FE: "Report problem" on request
    B->>FE: Choose category, priority, evidence
    FE->>BE: POST /api/disputes
    BE->>DB: Dispute.create({status:"pending"})
    BE->>DB: Chat.create({type:"group", participants:[buyer, seller], system message})
    BE->>DB: dispute.chatId = chat._id
    BE-->>FE: { dispute }
    Note over IO: ⚠️ No socket events fire (TODO stubs)

    A->>FE: Admin dashboard, click "Pick up"
    FE->>BE: POST /api/disputes/{id}/assign
    Note right of BE: ⚠️ No role guard
    BE->>DB: dispute.adminId, status="in_progress", timeline.push
    BE->>DB: chat.participants.push(admin)
    BE-->>FE: { dispute }
    Note over IO: ⚠️ No socket events fire (TODO stubs)

    loop investigation
        A->>FE: Chat with B & S
        B-->>BE: POST /api/disputes/{id}/evidence (image)
        BE->>DB: dispute.evidence.push, timeline.push
        Note over IO: ⚠️ No socket events fire (TODO stubs)
    end

    A->>FE: Click "Resolve" choose action
    FE->>BE: POST /api/disputes/{id}/resolve { action, amount?, notes? }
    Note right of BE: ⚠️ No role guard (dashboard router)
    BE->>DB: dispute.status="resolved", resolution={action, amount, currency, notes, ...}
    alt action="refund"
        A->>BE: trigger refund payout to buyer\n[[Escrow Flow]] / [[Payout Flow]]
    else action="replacement"
        A->>BE: arrange replacement item (manual)
    else action="compensation"
        A->>BE: partial payment to buyer (manual)
    else action="warning_seller" / "ban_seller"
        A->>BE: admin account action (manual)
    else action="no_action"
        A->>BE: dismiss dispute
    end
    BE-->>FE: { dispute }
    Note over IO: ⚠️ No socket events fire (TODO stubs)

---

API calls

Dashboard router (backend/src/routes/disputeRoutes.ts) — mounted first at /api/disputes

Method	Endpoint	Auth	Role Guard	Notes
POST	/api/disputes	authenticateToken	None	Create dispute
GET	/api/disputes	authenticateToken	None	List with filters
GET	/api/disputes/statistics	authenticateToken	None	Aggregate stats
GET	/api/disputes/:id	authenticateToken	None	Get by ID
POST	/api/disputes/:id/assign	authenticateToken	MISSING ⚠️	Self-assign possible
PATCH	/api/disputes/:id/status	authenticateToken	MISSING ⚠️	Any user can change status
POST	/api/disputes/:id/resolve	authenticateToken	MISSING ⚠️	Any user can resolve
POST	/api/disputes/:id/evidence	authenticateToken	None	Add evidence

Release-hold router (backend/src/services/dispute/disputeRoutes.ts) — mounted second at /api/disputes

Method	Endpoint	Auth	Role Guard	Notes
POST	/api/disputes/:purchaseRequestId/raise	authenticateToken	Buyer or admin (inline check)	Sets hold fields on PurchaseRequest
POST	/api/disputes/:purchaseRequestId/resolve	authenticateToken	authorizeRoles('admin') ✓	Clears hold fields
GET	/api/disputes/:purchaseRequestId/status	authenticateToken	Participant or admin (inline check)	Returns hold/block status

[!warning] Route shadowing: POST /api/disputes/:id/resolve in the dashboard router (no guard, mounted first) will intercept requests before they reach the release-hold router's POST /:purchaseRequestId/resolve (has guard). See Route Shadowing.

---

Database writes

• disputes — insert on open; updates adminId, status, timeline[], evidence[], resolution, closedAt over the lifecycle.
• chats — new group chat on open; admin appended to participants[] on assignment; messages appended throughout.
• purchaserequests — hold fields (disputeRaised, disputeRaisedAt, disputeResolved, disputeResolvedAt, disputeHoldReason, holdUntil) mutated by the release-hold service. Not touched by DisputeService directly.
• payments — touched indirectly when the admin performs the financial resolution.
• notifications — TODO; no writes happen today.

Socket events emitted

[!warning] None of the following events actually fire. Every emit block in DisputeService is commented out as a TODO stub.

Planned events (not yet implemented):

• new-notification → user-{buyerId} and user-{sellerId} on creation, assignment, evidence-added, and resolution.
• dispute-updated → planned but not implemented.

The only real-time activity in the dispute flow today is through the standard Chat socket (new-message on chat-{disputeChatId}) when participants send chat messages — this flows through ChatService.sendMessage, which is separate from the dispute service and does emit.

Side effects

• Three-way chat creation is the most visible side effect — pulls the buyer and seller into a controlled conversation room.
• Timeline append-only log is the audit trail. The pre-save hook auto-appends dispute_created on insert. Surface this in the admin UI for compliance.
• Response deadline = 48h — used by reminders / SLA dashboards (no automated enforcement today). Past-deadline disputes could auto-escalate priority.
• Hard deadline = 7d — same intent: a watchdog could mark long-unresolved disputes for admin attention.

Error / edge cases

• Purchase request missing → 400 Purchase request not found.
• No seller identifiable (orphan request) → dispute still created but with sellerId: undefined; the chat becomes 2-party (buyer only, no seller). Recommended: reject creation in this case to avoid mediator-less situations.
• Initiator is neither buyer nor seller → not enforced at service level — should be validated in DisputeController (recommended hardening).
• Same user opens multiple disputes for the same request → no uniqueness constraint today. Consider adding a unique index on (purchaseRequestId, status) filtered to pending|in_progress to prevent duplicates.
• Evidence URL is hot-linked → frontend uploads through POST /api/files/upload and the URL is served from /uploads. Ensure auth on the upload endpoint to prevent random users from polluting evidence.
• Dispute resolved without financial follow-up → the dispute is "resolved" in record only; the escrow stays in its previous state until the admin completes release/refund. Add automation that dispatches the policy-checked release/refund instruction when the admin selects a financial resolution action.
• Admin resigns mid-dispute → no transfer-of-mediator endpoint today. Add POST /api/disputes/:id/reassign.
• Route collision → both routers share /api/disputes. See Route Shadowing for details and recommendation.

[!tip] Sort disputes by priority + age The query Dispute.find().sort({ priority: -1, createdAt: -1 }) already used in getDisputes ensures urgent ones bubble to the top. Make sure the admin dashboard uses this default sort.

Linked flows

• Chat Flow — message-level mechanics inside the dispute chat.
• Escrow Flow — the financial state being contested.
• Payout Flow — executed on refund / compensation resolutions.
• Notification Flow — channels for dispute alerts (not yet wired).
• Delivery Confirmation Flow — disputes often arise from failed delivery.

Source files

• backend/src/services/dispute/DisputeService.ts — core service logic
• backend/src/services/dispute/disputeRoutes.ts — release-hold router (admin-guarded resolve)
• backend/src/services/dispute/releaseHoldService.ts — hold field helpers
• backend/src/routes/disputeRoutes.ts — dashboard/controller router (missing role guards)
• backend/src/models/Dispute.ts — canonical schema and enums
• backend/src/app.ts lines 521 and 585 — mount order (shadowing risk)
• frontend/src/sections/request/components/report-problem-to-admin.tsx
• frontend/src/sections/admin/ — admin dispute dashboard (subject to organisation)