> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Reviews — Outlet API handoff (dashboard)

> **Verification boundary:** The detailed contract below was derived from repository source, not from live HTTP captures. Fields explicitly marked unverified remain open. The earlier route inventory is retained below for cross-checking; where it says “not verified”, the more recent source-reviewed contract takes precedence.

## Controller-reviewed contracts


**Source:** `alalmiyalhura/outlet` GitLab `main`, `modules/Reviews/Routes/api.php`, controllers under `modules/Reviews/Interfaces/Http/Controllers/`, `ReviewViews.php`, `ReviewFilters.php`, `Review.php`, `ReviewPolicy.php`. **Base path:** `/api/v1`. **Locale:** `Accept-Language: ar|en` controls human-facing labels. All JSON examples below are **illustrative, code-derived shapes**, not recorded live responses. Fields shown as `null` are genuinely nullable or conditional; labels may vary with locale. Unless specified otherwise, successful JSON responses wrap content in `data`. Validation errors use platform error envelope; exact error status/code should be confirmed with integration tests.

**Auth:** App and admin routes require `Authorization: Bearer <token>` via Sanctum. Dashboard routes additionally require a dashboard session and permission stated per operation. `GET /sellers/{id}/reviews` is public. **Pagination:** list endpoints return `{data:[...],links:{first,last,prev,next},meta:{current_page,from,last_page,per_page,to,total,...}}`; `page` is standard Laravel pagination query. ISO dates use ISO-8601 strings.

**Shared response shapes**

`rating_summary`: `{average:string|null,count:integer,count_label:string,stars_filled:integer,empty:boolean,empty_text:string|null,distribution:[{stars:integer,count:integer,percent:integer}]}`. `distribution` is present for full summaries, not compact counterpart ratings.

`review_state`: `{order_ref:string,role:"buy"|"sell",direction:string,public:boolean,can_rate:boolean,can_edit:boolean,blocked:null|{code:string,message:string},closes_at:string|null,window_note:string|null,action:object|null,form:object|null,review:object|null,sent:object|null,received:object|null,counterpart_rating:object|null}`. `form`, when allowed: `{title:string,question:string,counterpart:{name:string,initial:string,role_label:string},sub:string,item:{title:string,image_url:string|null},stars:{value:integer,min:integer,max:integer,labels:[{stars:integer,label:string,aria:string}],label_empty:string,aria:string,required_message:string},comment:{label:string,placeholder:string,max_length:integer,value:string,counter:string},note:string,send_label:string,method:"POST"|"PATCH",endpoint:string}`. `review`, if already submitted: `{id:integer,direction:string,stars:integer,label:string,comment:string|null,date_label:string,submitted_at:string,edited_at:string|null,editable_until:string|null,can_edit:boolean,hidden:boolean,hidden_note:string|null}`. `action` is a UI descriptor (`key`, `label`, `style`, `screen`, `toast`). `sent` contains completion-screen copy and navigation buttons. `received` contains counterparty's rating where visible.

`admin_review_row`: `{id:integer,order_ref:string,direction:string,direction_label:{ar:string,en:string},public:boolean,author:{id:integer,name:string},subject:{id:integer,name:string},stars:integer,comment:string|null,has_comment:boolean,item_title:string,submitted_at:string,edited_at:string|null,hidden:boolean,hidden_at:string|null,visibility:"visible"|"hidden",visibility_label:{ar:string,en:string}}`.

`audit_row`: `{id:integer,event:string,old_values:object,new_values:object,actor_id:integer|null,at:string|null,subject:string,subject_id:integer}`.

---
## GET /sellers/{id}/reviews

**Purpose:** Public seller profile reviews tab; buyer→seller visible reviews only.

**Access:** Public, throttled 120/min.

**Path / query parameters:** `id` required integer seller ID; `stars` optional integer 1–5; `per_page` optional integer 1–configured maximum (normally 100); `page` optional positive pagination page.

**Request body:** None.

**Success:** 200 paginated public review rows; `meta.seller_id`, `meta.tab_label`, `meta.summary` (full rating summary), `meta.empty`. Public row fields: `id:int,stars:int,label:string,reviewer:string,reviewer_initial:string,is_mine:bool,comment:string|null,date_label:string,submitted_at:ISO8601`.

**Example success response:**

```json
{"data":[{"id":15,"stars":5,"label":"ممتاز","reviewer":"أحمد م.","reviewer_initial":"أ","is_mine":false,"comment":"منتج ممتاز","date_label":"22 نوفمبر","submitted_at":"2026-11-22T10:00:00+00:00"}],"links":{"first":"...","last":"...","prev":null,"next":null},"meta":{"current_page":1,"from":1,"last_page":1,"per_page":20,"to":1,"total":1,"seller_id":7,"tab_label":"التقييمات","summary":{"average":"5.0","count":1,"count_label":"تقييم واحد","stars_filled":5,"empty":false,"empty_text":null,"distribution":[{"stars":5,"count":1,"percent":100}]},"empty":null}}
```

**Behavior, errors and implementation:** Unknown seller: `ReviewSubjectNotFound`. Hidden and seller→buyer reviews are excluded; current user’s review, if authenticated, appears first. Source: `SellerReviewsController::index`, `ReviewViews::publicRow/summary`.

---

## GET /orders/{ref}/review

**Purpose:** Load buyer/seller review state and dynamic form for an order.

**Access:** Sanctum; order buyer or seller only.

**Path / query parameters:** `ref` required order reference matching `[A-Za-z]{3}-\d{4,12}`.

**Request body:** None.

**Success:** 200 `data:review_state` (shape above).

**Example success response:**

```json
{"data":{"order_ref":"OUT-1234","role":"buy","direction":"buyer_to_seller","public":true,"can_rate":true,"can_edit":false,"blocked":null,"closes_at":null,"window_note":null,"action":{"key":"rate","label":"قيّم البائع","style":"primary","screen":"rate","toast":null},"form":{"title":"تقييم البائع","question":"كيف كانت تجربتك؟","counterpart":{"name":"سارة","initial":"س","role_label":"البائع"},"sub":"الطلب OUT-1234","item":{"title":"حقيبة","image_url":null},"stars":{"value":5,"min":1,"max":5,"labels":[],"label_empty":"","aria":"","required_message":"التقييم مطلوب"},"comment":{"label":"تعليق","placeholder":"","max_length":300,"value":"","counter":"0 / 300"},"note":"","send_label":"إرسال","method":"POST","endpoint":"/api/v1/orders/OUT-1234/review"},"review":null,"sent":null,"received":null,"counterpart_rating":null}}
```

**Behavior, errors and implementation:** Other users and missing orders receive `review_order_not_found` (404). Form and action are conditional. Source: `OrderReviewController::show`, `ReviewViews::state/form`.

---

## POST /orders/{ref}/review

**Purpose:** Submit own order review.

**Access:** Sanctum; order buyer or seller only.

**Path / query parameters:** `ref` required order reference `[A-Za-z]{3}-\d{4,12}`.

**Request body:** JSON `{ "stars": 5, "comment": "Great item" }`. `stars`: required integer 1–5; `comment`: optional nullable string, hard max 1000 characters, additionally limited by live `reviews.comment_max_length` setting. `comment` whitespace is trimmed and empty becomes null.

**Success:** HTTP 201 `data:review_state` (same full response as GET /orders/{ref}/review).

**Example success response:**

```json
{"data":{"order_ref":"OUT-1234","role":"buy","direction":"buyer_to_seller","public":true,"can_rate":false,"can_edit":false,"blocked":null,"closes_at":null,"window_note":null,"action":{"key":"rated","label":"تم التقييم","style":"secondary","screen":"rate_sent","toast":null},"form":null,"review":{"id":15,"direction":"buyer_to_seller","stars":5,"label":"ممتاز","comment":"Great item","date_label":"22 نوفمبر","submitted_at":"2026-11-22T10:00:00+00:00","edited_at":null,"editable_until":null,"can_edit":false,"hidden":false,"hidden_note":null},"sent":null,"received":null,"counterpart_rating":null}}
```

**Behavior, errors and implementation:** POST uses idempotency middleware; retry with same `Idempotency-Key` replays; without it a duplicate can raise `review_already_submitted` (409). Requires completed order and eligibility window. Invalid stars => validation error; overlong comment => `review_comment_too_long`. Source: `OrderReviewController::store`, `Review::submit`.

---

## PATCH /orders/{ref}/review

**Purpose:** Edit own order review.

**Access:** Sanctum; order buyer or seller only.

**Path / query parameters:** `ref` required order reference `[A-Za-z]{3}-\d{4,12}`.

**Request body:** JSON `{ "stars": 5, "comment": "Great item" }`. `stars`: required integer 1–5; `comment`: optional nullable string, hard max 1000 characters, additionally limited by live `reviews.comment_max_length` setting. `comment` whitespace is trimmed and empty becomes null.

**Success:** HTTP 200 `data:review_state` (same full response as GET /orders/{ref}/review).

**Example success response:**

```json
{"data":{"order_ref":"OUT-1234","role":"buy","direction":"buyer_to_seller","public":true,"can_rate":false,"can_edit":false,"blocked":null,"closes_at":null,"window_note":null,"action":{"key":"rated","label":"تم التقييم","style":"secondary","screen":"rate_sent","toast":null},"form":null,"review":{"id":15,"direction":"buyer_to_seller","stars":5,"label":"ممتاز","comment":"Great item","date_label":"22 نوفمبر","submitted_at":"2026-11-22T10:00:00+00:00","edited_at":null,"editable_until":null,"can_edit":false,"hidden":false,"hidden_note":null},"sent":null,"received":null,"counterpart_rating":null}}
```

**Behavior, errors and implementation:** PATCH requires prior own review, unexpired edit window, and review not hidden. Edit window defaults to zero (not editable). Invalid stars => validation error; overlong comment => `review_comment_too_long`. Source: `OrderReviewController::update`, `Review::edit`.

---

## GET /me/reviews/given

**Purpose:** Reviews authored by signed-in user (both directions, including own hidden reviews).

**Access:** Sanctum, self-scoped.

**Path / query parameters:** `per_page` optional integer 1–configured max (normally 100); `page` pagination page.

**Request body:** None.

**Success:** 200 paginated `ReviewViews::mineRow` records, `meta.title`, `meta.summary` (full rating summary for received, null for given), `meta.empty`. Row fields: `id:int,order_ref:string,direction:string,role:string,counterpart:string,item_title:string,item_image_url:string|null,stars:int,label:string,comment:string|null,date_label:string,submitted_at:ISO8601,public:bool,hidden:bool,hidden_note:string|null`. 

**Example success response:**

```json
{"data":[{"id":15,"order_ref":"OUT-1234","direction":"buyer_to_seller","role":"buy","counterpart":"سارة","item_title":"حقيبة","item_image_url":null,"stars":5,"label":"ممتاز","comment":"Great item","date_label":"22 نوفمبر","submitted_at":"2026-11-22T10:00:00+00:00","public":true,"hidden":false,"hidden_note":null}],"links":{"first":"...","last":"...","prev":null,"next":null},"meta":{"current_page":1,"from":1,"last_page":1,"per_page":20,"to":1,"total":1,"title":"تقييماتي","summary":null,"empty":null}}
```

**Behavior, errors and implementation:** Given rows flag hidden reviews; received rows exclude hidden and seller→buyer reviews. Source: `MyReviewsController::given`, `ReviewViews::mineRow`.

---

## GET /me/reviews/received

**Purpose:** Visible buyer→seller reviews received by signed-in user as seller.

**Access:** Sanctum, self-scoped.

**Path / query parameters:** `per_page` optional integer 1–configured max (normally 100); `page` pagination page.

**Request body:** None.

**Success:** 200 paginated `ReviewViews::mineRow` records, `meta.title`, `meta.summary` (full rating summary for received, null for given), `meta.empty`. Row fields: `id:int,order_ref:string,direction:string,role:string,counterpart:string,item_title:string,item_image_url:string|null,stars:int,label:string,comment:string|null,date_label:string,submitted_at:ISO8601,public:bool,hidden:bool,hidden_note:string|null`. 

**Example success response:**

```json
{"data":[{"id":15,"order_ref":"OUT-1234","direction":"buyer_to_seller","role":"buy","counterpart":"سارة","item_title":"حقيبة","item_image_url":null,"stars":5,"label":"ممتاز","comment":"Great item","date_label":"22 نوفمبر","submitted_at":"2026-11-22T10:00:00+00:00","public":true,"hidden":false,"hidden_note":null}],"links":{"first":"...","last":"...","prev":null,"next":null},"meta":{"current_page":1,"from":1,"last_page":1,"per_page":20,"to":1,"total":1,"title":"تقييماتي","summary":null,"empty":null}}
```

**Behavior, errors and implementation:** Given rows flag hidden reviews; received rows exclude hidden and seller→buyer reviews. Source: `MyReviewsController::received`, `ReviewViews::mineRow`.

---

## GET /me/rating

**Purpose:** Own seller-rating summary on account page.

**Access:** Sanctum, self-scoped.

**Path / query parameters:** None.

**Request body:** None.

**Success:** 200 `data.as_seller:rating_summary`.

**Example success response:**

```json
{"data":{"as_seller":{"average":"4.8","count":10,"count_label":"10 تقييمات","stars_filled":5,"empty":false,"empty_text":null,"distribution":[{"stars":5,"count":8,"percent":80}]}}}
```

**Behavior, errors and implementation:** Buyer-rating summary is not returned. Source: `MyReviewsController::rating`, `ReviewViews::summary`.

---

## GET /admin/reviews/settings

**Purpose:** Retrieve review policy and editable limits.

**Access:** Dashboard session; `settings.manage`.

**Path / query parameters:** None.

**Request body:** None.

**Success:** 200 `data` settings object: `comment_max_length:int`, `edit_window_hours:int`, `window_days:int`, `notify_rated_user:bool`, `notify_author_on_hide:bool`, `low_rating_max_stars:int`, `limits:{comment_max_length:{min,max},edit_window_hours:{min,max},window_days:{min,max},low_rating_max_stars:{min,max}}`.

**Example success response:**

```json
{"data":{"comment_max_length":300,"edit_window_hours":0,"window_days":30,"notify_rated_user":true,"notify_author_on_hide":true,"low_rating_max_stars":2,"limits":{"comment_max_length":{"min":1,"max":1000},"edit_window_hours":{"min":0,"max":720},"window_days":{"min":0,"max":365},"low_rating_max_stars":{"min":1,"max":4}}}}
```

**Behavior, errors and implementation:** Values are illustrative, limits verified in `ReviewPolicy`; source `ReviewSettingsController::show/view`.

---

## PATCH /admin/reviews/settings

**Purpose:** Partially change review policy and audit old→new values.

**Access:** Dashboard session; `settings.manage`.

**Path / query parameters:** None.

**Request body:** JSON e.g. `{ "comment_max_length": 300, "edit_window_hours": 24, "reason": "Policy update" }`. All optional: `comment_max_length` integer 1–1000; `edit_window_hours` integer 0–720; `window_days` integer 0–365; `notify_rated_user` boolean; `notify_author_on_hide` boolean; `low_rating_max_stars` integer 1–4; `reason` nullable string max 500.

**Success:** 200 same `data` settings shape as GET; reason is audit metadata, not part of settings response.

**Example success response:**

```json
{"data":{"comment_max_length":300,"edit_window_hours":24,"window_days":30,"notify_rated_user":true,"notify_author_on_hide":true,"low_rating_max_stars":2,"limits":{"comment_max_length":{"min":1,"max":1000},"edit_window_hours":{"min":0,"max":720},"window_days":{"min":0,"max":365},"low_rating_max_stars":{"min":1,"max":4}}}}
```

**Behavior, errors and implementation:** Updates apply to future reviews; already-submitted reviews retain edit deadline. Source: `ReviewSettingsController::update`.

---

## GET /admin/reviews/settings/history

**Purpose:** Paginated settings audit history.

**Access:** Dashboard session; `settings.manage`.

**Path / query parameters:** `per_page` optional integer 1–100 (default 25); `page` pagination.

**Request body:** None.

**Success:** 200 paginated `audit_row` list, with `links` and `meta`.

**Example success response:**

```json
{"data":[{"id":100,"event":"updated","old_values":{"comment_max_length":200},"new_values":{"comment_max_length":300},"actor_id":1,"at":"2026-11-22T10:00:00+00:00","subject":"review_setting","subject_id":3}],"links":{"first":"...","last":"...","prev":null,"next":null},"meta":{"current_page":1,"from":1,"last_page":1,"per_page":25,"to":1,"total":1}}
```

**Behavior, errors and implementation:** Source: `ReviewSettingsController::history`, `ReviewAdminController::audits`.

---

## GET /admin/reviews

**Purpose:** Moderation list with search, filtering, sort and pagination.

**Access:** Dashboard session; `reviews.view`.

**Path / query parameters:** `filter[direction]` enum direction; `filter[stars]` comma-separated digits 1–5; `filter[stars_min]`, `filter[stars_max]` integers 1–5; `filter[has_comment]`, `filter[hidden]` one of 0/1/true/false; `filter[seller_id]`, `filter[buyer_id]`, `filter[author_id]`, `filter[subject_id]` positive integer; `filter[order_ref]` string max 20; `filter[submitted_from]`, `filter[submitted_to]` dates; `filter[search]` string max 100; `sort` one of `submitted_at`, `stars`, `id`, `hidden_at`, with optional `-` prefix; `per_page` integer 1–configured max; `page` pagination.

**Request body:** None.

**Success:** 200 paginated `admin_review_row` with `meta.sorts`, `meta.filters`, `meta.directions`.

**Example success response:**

```json
{"data":[{"id":15,"order_ref":"OUT-1234","direction":"buyer_to_seller","direction_label":{"ar":"من المشتري للبائع","en":"Buyer to seller"},"public":true,"author":{"id":9,"name":"أحمد"},"subject":{"id":7,"name":"سارة"},"stars":5,"comment":"Great","has_comment":true,"item_title":"حقيبة","submitted_at":"2026-11-22T10:00:00+00:00","edited_at":null,"hidden":false,"hidden_at":null,"visibility":"visible","visibility_label":{"ar":"ظاهر","en":"Visible"}}],"links":{"first":"...","last":"...","prev":null,"next":null},"meta":{"current_page":1,"from":1,"last_page":1,"per_page":25,"to":1,"total":1,"sorts":["submitted_at","stars","id","hidden_at"],"filters":["direction","stars","stars_min","stars_max","has_comment","hidden","seller_id","buyer_id","author_id","subject_id","order_ref","submitted_from","submitted_to","search"],"directions":[]}}
```

**Behavior, errors and implementation:** Filter semantics in `ReviewFilters::apply`. Unknown sort => validation error. Source: `ReviewAdminController::index/row`, `ReviewFilters`.

---

## GET /admin/reviews/users/{userId}

**Purpose:** Get both seller and restricted buyer rating summaries for a user.

**Access:** Dashboard session; `reviews.view`.

**Path / query parameters:** `userId` required integer.

**Request body:** None.

**Success:** 200 `data:{user_id:int,as_seller:rating_summary,as_buyer:rating_summary,reviews_url:string}`.

**Example success response:**

```json
{"data":{"user_id":7,"as_seller":{"average":"4.5","count":2,"count_label":"2 تقييم","stars_filled":5,"empty":false,"empty_text":null,"distribution":[]},"as_buyer":{"average":null,"count":0,"count_label":"0 تقييم","stars_filled":0,"empty":true,"empty_text":"لا توجد تقييمات","distribution":[]},"reviews_url":"/api/v1/admin/reviews?filter[subject_id]=7"}}
```

**Behavior, errors and implementation:** Buyer rating is dashboard-only. Source: `ReviewAdminController::user`.

---

## GET /admin/reviews/{id}

**Purpose:** Review detail with order snapshot, parties, counterpart review, audit and moderation actions.

**Access:** Dashboard session; `reviews.view`.

**Path / query parameters:** `id` required integer.

**Request body:** None.

**Success:** 200 `data` extends `admin_review_row` with `hidden_by:int|null`, `hidden_reason:string|null`, `editable_until:ISO8601|null`, `item_image_url:string|null`, `order:object|null`, `seller:{id,rating}`, `buyer:{id,rating}`, `counterpart_review:object|null`, `audit:array`, `actions:{hide:{allowed,method,endpoint,reason:{required,min,max}},restore:{...}}`.

**Example success response:**

```json
{"data":{"id":15,"order_ref":"OUT-1234","direction":"buyer_to_seller","direction_label":{"ar":"من المشتري للبائع","en":"Buyer to seller"},"public":true,"author":{"id":9,"name":"أحمد"},"subject":{"id":7,"name":"سارة"},"stars":5,"comment":"Great","has_comment":true,"item_title":"حقيبة","submitted_at":"2026-11-22T10:00:00+00:00","edited_at":null,"hidden":false,"hidden_at":null,"visibility":"visible","visibility_label":{"ar":"ظاهر","en":"Visible"},"hidden_by":null,"hidden_reason":null,"editable_until":null,"item_image_url":null,"order":null,"seller":{"id":7,"rating":{}},"buyer":{"id":9,"rating":{}},"counterpart_review":null,"audit":[],"actions":{"hide":{"allowed":true,"method":"POST","endpoint":"/api/v1/admin/reviews/15/hide","reason":{"required":true,"min":3,"max":500}},"restore":{"allowed":false,"method":"POST","endpoint":"/api/v1/admin/reviews/15/restore","reason":{"required":true,"min":3,"max":500}}}}}
```

**Behavior, errors and implementation:** Example `rating:{}` abbreviates the full `rating_summary` contract above. Missing review => `ReviewNotFound`. Source: `ReviewAdminController::show`.

---

## GET /admin/reviews/{id}/history

**Purpose:** Paginated audit history for one review.

**Access:** Dashboard session; `reviews.view`.

**Path / query parameters:** `id` integer; `per_page` optional integer 1–100 (default 25); `page` pagination.

**Request body:** None.

**Success:** 200 paginated `audit_row` list.

**Example success response:**

```json
{"data":[{"id":22,"event":"updated","old_values":{"hidden_at":null},"new_values":{"hidden_at":"2026-11-22 10:00:00"},"actor_id":1,"at":"2026-11-22T10:00:00+00:00","subject":"review","subject_id":15}],"links":{"first":"...","last":"...","prev":null,"next":null},"meta":{"current_page":1,"from":1,"last_page":1,"per_page":25,"to":1,"total":1}}
```

**Behavior, errors and implementation:** Missing review => `ReviewNotFound`. Source: `ReviewAdminController::history/audits`.

---

## POST /admin/reviews/{id}/hide

**Purpose:** Hide a visible review from public lists and aggregates.

**Access:** Dashboard session; `reviews.hide`.

**Path / query parameters:** `id` required integer review ID.

**Request body:** JSON `{ "reason": "Violates review policy" }`. `reason` required string 3–500 characters (trimmed).

**Success:** 200 `data:{id:int,changed:bool,hidden:bool}`.

**Example success response:**

```json
{"data":{"id":15,"changed":true,"hidden":true}}
```

**Behavior, errors and implementation:** Idempotent: repeating on already-hidden review returns `changed:false`. Reason audited. Missing review => `ReviewNotFound`. Source: `ReviewAdminController::hide/moderate`, `Review::hide`.

---

## POST /admin/reviews/{id}/restore

**Purpose:** Restore a hidden review to public lists and aggregates.

**Access:** Dashboard session; `reviews.hide`.

**Path / query parameters:** `id` required integer review ID.

**Request body:** JSON `{ "reason": "Violates review policy" }`. `reason` required string 3–500 characters (trimmed).

**Success:** 200 `data:{id:int,changed:bool,hidden:bool}`.

**Example success response:**

```json
{"data":{"id":15,"changed":true,"hidden":false}}
```

**Behavior, errors and implementation:** Idempotent: repeating on already-visible review returns `changed:false`. Reason audited. Missing review => `ReviewNotFound`. Source: `ReviewAdminController::restore/moderate`, `Review::restore`.

---
## Screen-to-API mapping (from controller comments / implementation)

| Client screen | APIs | Verification scope |
|---|---|---|
| Flutter `seller.html` reviews tab | `GET sellers/{id}/reviews` | Backend contract checked; actual Flutter source not inspected |
| Flutter `order.html`, `incoming-order.html` | `GET orders/{ref}/review` | Backend contract checked |
| Flutter `rate.html` | `GET`, `POST`, `PATCH orders/{ref}/review` | Backend contract checked |
| Flutter `rate-sent.html` | Review state returned by GET/POST/PATCH | Backend contract checked |
| Flutter account / reviews history | `GET me/reviews/given`, `GET me/reviews/received`, `GET me/rating` | Backend contract checked |
| Dashboard review management list/detail | `GET admin/reviews`, `GET admin/reviews/{id}`, `GET admin/reviews/users/{userId}`, `GET admin/reviews/{id}/history` | Backend contract checked |
| Dashboard moderation | `POST admin/reviews/{id}/hide`, `POST admin/reviews/{id}/restore` | Backend contract checked |
| Dashboard review settings | `GET/PATCH admin/reviews/settings`, `GET admin/reviews/settings/history` | Backend contract checked |

## Coverage and remaining verification

- **Routes accounted for:** 16/16 routes declared in `modules/Reviews/Routes/api.php`.
- **Source-verified:** Request validation, routing, permissions, and response structures traced to controllers/presenters. Examples are illustrative, not live captures. Conditional response fields depend on review eligibility, locale, configured settings and actual records.
- **Not yet verified:** Running backend responses, frontend integration, all possible error codes/statuses from exception mapping, production/staging environment parity. This file does **not** certify all Flutter or Dashboard screens in the product.


---

## Earlier route inventory (historical; superseded by contracts above)

# Reviews API — Dashboard

Source: [`modules/Reviews/Routes/api.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Reviews/Routes/api.php).

> **Verification:** HTTP methods, paths, route-level authentication and route comments are confirmed from source. Exact request and response schemas are **not verified** unless explicitly described. Do not treat illustrative placeholders as real API payloads.

Endpoints in this file: **9**.

## `GET /api/admin/reviews/settings`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** settings.manage
- **Path parameters:** None
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `PATCH /api/admin/reviews/settings`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** settings.manage
- **Path parameters:** None
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** Requires controller / FormRequest verification; do not assume an empty body.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/admin/reviews/settings/history`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** settings.manage
- **Path parameters:** None
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/admin/reviews`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** reviews.view
- **Path parameters:** None
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/admin/reviews/users/{userId}`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** reviews.view
- **Path parameters:** userId
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/admin/reviews/{id}`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** reviews.view
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `GET /api/admin/reviews/{id}/history`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** reviews.view
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** No body expected for GET.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `POST /api/admin/reviews/{id}/hide`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** reviews.hide
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** Requires controller / FormRequest verification; do not assume an empty body.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.

## `POST /api/admin/reviews/{id}/restore`

- **Authentication:** Bearer token (`auth:sanctum`)
- **Permission:** reviews.hide
- **Path parameters:** id
- **Query parameters:** Not verified from controller / request yet.
- **Request body:** Requires controller / FormRequest verification; do not assume an empty body.
- **Success response:** Not verified from presenter / resource yet.
- **Error responses:** Authentication/authorization/validation and business errors depend on middleware and handler; status and JSON shape pending verification.
