---
feature: <Feature name, e.g. Order Management>
slug: <kebab-case file name from PROJECT_BRAIN registry>
surface: <admin | …a React surface from config/docs.php>
consumer: react
version: 1.0.0
status: <in-progress | ready | deprecated | base (TD-xx) — base endpoints only, version 0.x>
brd_version: "<BRD version in force>"
brd_ids: [<ADMIN-013>]
business_rules: [<BR-22>, <BR-29>]
decisions: [<DEC-14>]
schema_tables: [<orders>, <order_items>]
related_docs: [<../client/orders.md>]
last_updated: <YYYY-MM-DD>
---

# <Feature name> — React Dashboard Integration Guide

> **Base URL:** `{HOST}/api/v1/admin` · Shared rules (headers, envelope, errors,
> pagination, axios setup, TS types): [API_CONVENTIONS.md](../API_CONVENTIONS.md)

## Quick reference

<!-- Read-this-first summary (≤ ~40 lines, budget docs.budgets.quick_reference_bytes).
     get-integration-brief / docs:brief return this section on its own, so it must be
     enough to start coding. One line per item; details live in the numbered sections. -->

| | |
|---|---|
| Version | 1.0.0 (YYYY-MM-DD) — latest change: <one line>; dashboard action: <None / what to change> |
| Status | <ready> · BRD <IDs> · decisions <D1, DEC-xx> |
| Auth | <Bearer token of this surface · guest allowed? · RBAC: `admin.<group>.<action>`> |

**Endpoints**

| Method | Path | Route name | Purpose |
|--------|------|------------|---------|
| `GET` | `/<path>` | `<surface>.<group>.index` | <one line> |

**Statuses:** `<value>` (<meaning>) · `<value>` (<meaning>) — full table §7.
**Error codes:** `<ERROR_CODE>` (<when>) · `<ERROR_CODE>` (<when>).
**Open decisions:** <DEC-xx: one line> or None.

---

## 1. Business summary

<Two to four plain sentences: what the admin manages here and the rules that
limit what they can do.>

## 2. Pages and permissions

| Page / component | Purpose | Endpoint(s) | RBAC permission (route name) |
|------------------|---------|-------------|------------------------------|
| <OrdersListPage> | Table of orders | `GET /orders` | `admin.orders.index` |
| <OrderDetailsPage> | Full order view | `GET /orders/{id}` | `admin.orders.show` |
| <CancelOrderDialog> | Cancel before execution | `POST /orders/{id}/cancel` | `admin.orders.cancel` |

Sidebar entry: <menu group → item>. Hide the item when the admin lacks the index permission.

## 3. List / table

`GET /api/v1/admin/<resource>` — list key in `data`: `<resource_table_name>`

| Column | Field | Sortable (`sort[...]`) | Filter (`filters[...]`) | Notes |
|--------|-------|------------------------|-------------------------|-------|
| ID | `id` (uuid) | no | — | Show as a short copy-able string, not a number |
| Status | `status.label` | no | `filters[status]=<value>` | Badge color by `status.value` |
| Created | `created_at` | yes | `filters[created_from]`, `filters[created_to]` | ISO 8601 |

`search` matches: <fields>.

```json
<Real paginated response, trimmed to 1–2 items>
```

## 4. Details view

`GET /api/v1/admin/<resource>/{id}`

```json
<Real response>
```

| Field | Type | Nullable | Description |
|-------|------|----------|-------------|
| `…` | | | |

## 5. Forms (create / edit)

`POST /api/v1/admin/<resource>` · `PUT /api/v1/admin/<resource>/{id}`
(update accepts partial payloads — every field is `sometimes`)

| Field | Input type | Required on create | Validation (mirror in zod/yup) | Notes |
|-------|-----------|--------------------|-------------------------------|-------|
| `en.name` / `ar.name` | text | yes | string, max 255 | Translatable |
| `is_active` | switch | no | boolean | |
| `image` | file | no | jpg/jpeg/png/webp, ≤ 2048 KB, ≤ 800×800 | multipart |

```json
<Example request body>
```

## 6. Actions (non-CRUD)

<Repeat per action: approve, reject, hide, cancel, record payout…>

### 6.x <Action name>

`<METHOD> /api/v1/admin/<path>` · Permission: `<route name>`

| Field | Type | Required | Validation | Description |
|-------|------|----------|-----------|-------------|

```json
<Real response>
```

| HTTP | `error_code` | When | Dashboard behavior |
|------|--------------|------|--------------------|
| 403 | — | Missing permission | Hide/disable the action |
| 422 | `BUSINESS_RULE_VIOLATED` | <BR-xx> | Toast `message` |

## 7. Statuses and enums

| Enum | `value` | Label (en) | Badge color | Actions allowed |
|------|---------|------------|-------------|-----------------|

## Data model

| Table | Read / write | Notes |
|-------------------------|--------------|-------|
| `<orders>` | read + write | <status values exposed, snapshots taken> |

## 8. TypeScript types

```ts
export interface <Entity> {
  id: string; // the public id exactly as the API returns it
  status: EnumValue<'pending' | 'approved' | 'rejected'>;
  total_amount: Money;
  created_at: string; // ISO 8601
}

export interface <Entity>Details extends <Entity> {
  en: { name: string };
  ar: { name: string };
}

export type <Entity>List = Paginated<'<table_name>', <Entity>>;
```

## 9. Business rules enforced by the backend

| Rule | What the backend does | What the admin sees |
|------|-----------------------|---------------------|
| BR-xx | <…> | <…> |

## 10. Notifications triggered

| Event | Who is notified | Channel |
|-------|-----------------|---------|
| <Admin approves an account> | Account owner | push + in-app |

## 11. Integration checklist

- [ ] Types match the real responses above
- [ ] Menu items/buttons gated by the listed permissions
- [ ] Table filters, sorting, search, and pagination wired to the documented params
- [ ] Form validation mirrors §5
- [ ] Every error code handled
- [ ] RTL (`ar`) and `en` verified

## 12. Acceptance scenarios

| AC ID | Scenario | Expected |
|-------|----------|----------|
| AC-ADMIN-<xxx> | <from BRD Project Guide §14> | <…> |

## 13. Open decisions and known limitations

| ID | Impact on this feature | Current behavior |
|----|------------------------|------------------|
| DEC-xx | <…> | <working assumption from docs/DECISIONS.md> |

---

## Version history

<!-- Keep the newest 5 rows here. Older rows and their changelog entries move to
     docs/<surface>/_history/<slug>.md (link it below) — agents rarely need them. -->

Newest first. Never edit an old row.

| Version | Date | Type | Summary | Dashboard action required |
|---------|------|------|---------|---------------------------|
| 1.0.0 | YYYY-MM-DD | Initial | First release of the feature. | Integrate as described above. |

## Changelog

<!-- Copy this block for every new version, newest on top. -->

### 1.0.0 — YYYY-MM-DD
- **Added:** <endpoints / fields / filters / permissions>
- **Changed:** —
- **Fixed:** —
- **Removed / Deprecated:** —
- **Breaking:** No
- **Endpoints affected:** `<METHOD /path>`
- **Dashboard action required:** <exact steps for the React developer, or "None">
- **BRD / decisions:** <IDs this version implements or depends on>