Files

Siavash Sameni 4cf5c49274 docs(audit): align documentation with post-remediation backend reality

- Update data model enums to match backend models
- Update API reference auth requirements
- Add dispute module references and warning blocks
- Add 2026-05-24 audit remediation callout to Overview
- Generate task breakdowns and audit artifacts
- Add doc alignment report (.taskmaster/reports/)

2026-05-24 11:16:29 +04:00

4.9 KiB

Raw Blame History

title, tags

title

Dispute API

[!warning] Not implemented The Dispute module is documented but not yet implemented in the backend. There is no backend/src/services/dispute/ directory, no backend/src/routes/disputeRoutes.ts, and no /api/disputes mount in app.ts. The API specification below reflects the intended design only.

Endpoints are planned to live under /api/disputes/*. The router would be backend/src/routes/disputeRoutes.ts and delegate to DisputeController (backend/src/controllers/disputeController.ts). The router would apply authenticateToken globally — every endpoint requires Bearer JWT.

Model: Dispute. A dispute references a PurchaseRequest plus optional Payment and is the input to the mediation workflow that ends in either a resolved_buyer or resolved_seller decision and triggers an escrow release or refund via the Payment API.

Create

POST /api/disputes

Description: Open a dispute against a purchase request. Auth required: Bearer JWT (buyer or seller participant in the request) Request body:

{
  purchaseRequestId: string;
  reason: "not_delivered" | "wrong_item" | "damaged" | "quality" | "other";
  description: string;
  evidence?: string[];          // URLs from [[File API]]
  paymentId?: string;
}

Response 201: { success: true, data: { dispute } } Errors: 400 validation, 403 not a participant of the request, 409 dispute already open for this request. Side effects:

Notifies the counter-party via POST /api/notifications (new-notification socket event).
Pauses any in-flight payout (sets a hold flag on the related Payment).

Read

GET /api/disputes

Description: List disputes the caller can see (their own as buyer/seller, all for admins). Auth required: Bearer JWT Query params:

status (open | under_review | resolved_buyer | resolved_seller | closed)
purchaseRequestId
page, limit, sortBy, sortOrder Response 200: { success, data: { disputes, pagination } }

GET /api/disputes/statistics

Description: Aggregated counts (open, by reason, average resolution time) for admin dashboards. Auth required: Bearer JWT (admin) Response 200: { success, data: { open, byReason, avgResolutionHours, ... } }

GET /api/disputes/:id

Description: Full dispute including evidence list, messages, assigned admin, decision (if any). Auth required: Bearer JWT (participant or admin) Errors: 403 not allowed, 404 not found.

Admin operations

POST /api/disputes/:id/assign

Description: Assign an admin moderator to the dispute. Sets assignedAdminId and transitions status to under_review. Auth required: Bearer JWT (admin) Request body: { adminId: string } Side effects: Notifies all participants.

PATCH /api/disputes/:id/status

Description: Generic status update (e.g. close without resolution). Auth required: Bearer JWT (admin) Request body: { status: string; note?: string }

POST /api/disputes/:id/resolve

Description: Final adjudication. Records the decision and triggers the appropriate escrow action. Auth required: Bearer JWT (admin) Request body:

{
  decision: "buyer" | "seller" | "split";
  refundAmount?: number;        // required when "split"
  releaseAmount?: number;       // required when "split"
  reasoning: string;
}

Response 200: { success, data: { dispute, paymentAction } } Side effects:

decision === "buyer" → triggers POST /api/payment/shkeeper/:id/refund flow.
decision === "seller" → triggers POST /api/payment/shkeeper/:id/release flow.
decision === "split" → admin executes both partial release and partial refund manually.
Notifies both participants and updates PurchaseRequest status to disputed_resolved.

Evidence and messages

POST /api/disputes/:id/evidence

Description: Attach additional evidence (image / document URLs from the File API) to the dispute. Either party can call. Auth required: Bearer JWT (participant or admin) Request body:

{
  url: string;
  description?: string;
  type?: "image" | "document" | "video";
}

Response 200: { success, data: { dispute } } with the evidence appended.

Messages

Direct messages between disputants and the admin moderator are handled via a dedicated Chat created automatically when the dispute is opened (type: "dispute"). Use the Chat API endpoints (POST /api/chat/:id/messages, GET /api/chat/:id/messages) once you have the chatId from the dispute payload.

Real-time

Dispute mutations emit notifications via POST /api/notifications which delivers new-notification socket events to each participant's user-<userId> room. See Socket Events for payload shape.

4.9 KiB Raw Blame History