# Provider Dashboard — New Features

> Covers role management, permissions, statistics, and order communication changes.

---

## 🆕 Roles & Permissions

### Who can do what

- **`provider`** (main) — full access, bypasses all permission checks
- **`provider_admin`** — role-based access only; profile + notifications always allowed regardless of role

### Always allowed for provider_admin (no permission needed)

- All `profile.*` routes
- All `notifications.*` routes
- `auth.logout`

---

### Request Format (Create / Update)

```json
{
  "ar": { "name": "مشرف الطلبات" },
  "en": { "name": "Orders Supervisor" },
  "permissions": [12, 15, 23]
}
```

`permissions` is optional. `ar.name` and `en.name` required on create.

---

### Role Response Shape

```json
{
  "id": 15,
  "name": "Orders Supervisor",
  "translations": {
    "ar": { "name": "مشرف الطلبات" },
    "en": { "name": "Orders Supervisor" }
  },
  "type": "provider",
  "permissions_count": 3,
  "users_count": 2,
  "permissions": [...],
  "created_at": 1725198388,
  "updated_at": 1725198388
}
```

- `name` — current request locale
- `translations` — full bilingual data for edit forms

---

### Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/roles` | List this provider's roles |
| POST | `/roles` | Create role |
| GET | `/roles/{id}` | Role details with permissions + users |
| PUT | `/roles/{id}` | Update role |
| DELETE | `/roles/{id}` | Delete role (fails if users assigned) |
| GET | `/permissions` | Paginated list of provider permissions |
| GET | `/permissions/grouped` | Permissions grouped by module |
| GET | `/permissions/my-permissions` | Current user's permission map |

---

### `GET /permissions/my-permissions`

Returns action keys grouped by module:

```json
{
  "status": "success",
  "data": {
    "wallet": ["balance", "transactions", "withdrawal-requests", "bank-account-show", "bank-account-save", "withdraw"],
    "urgent-orders": ["index", "show", "accept", "reject"],
    "chats": ["index", "show", "send-message"],
    "service-orders": ["index", "show", "accept", "reject", "start", "upload-files", "finish"],
    "provider-admins": ["index", "store", "show", "update", "destroy", "toggle-status"],
    "provider-roles": ["index", "store", "show", "update", "destroy"],
    "provider-permissions": ["index", "grouped"]
  }
}
```

Main providers get all permissions. Provider admins get only what their roles grant.

---

## 🆕 Statistics

New endpoints under `/statistics`:

| Endpoint | Description |
|----------|-------------|
| `GET /statistics/overview` | All KPIs in one call |
| `GET /statistics/service-orders` | All statuses, rates, 12-month chart |
| `GET /statistics/urgent-orders` | All statuses, rates, 12-month chart |
| `GET /statistics/financials` | Wallet, earnings (SO + UO), withdrawals, chart |
| `GET /statistics/earnings?period=monthly&year=2026` | Earnings breakdown by period |
| `GET /statistics/ratings` | Avg rating, count, 1–5 distribution |

**Service order statuses covered** (provider only sees post-payment):
`pending` → `accepted` → `active` → `provider_finished` → `pending_admin_review` → `completed` / `cancelled` / `rejected`

**Urgent order statuses covered:**
`searching_for_provider` → `accepted` → `completed` / `cancelled`

**Earnings breakdown** (`/statistics/earnings`):
- No params → all-time grouped by month
- `?period=monthly&year=2026` → that year by month
- `?period=yearly` → last 5 years

Both service order earnings (`base_price`) and urgent order earnings (`provider_amount`) are included separately and as a combined total.

---

## 🆕 Service Order Show — `chat_id`

`GET /service-orders/{id}` now includes:

```json
{
  "chat_id": 12
}
```

Use this to open the relevant chat from the order detail screen.

---

## Permissions Reference

Provider permissions are scoped to `prefix = 'Provider'`. They cover:

- **wallet** — balance, transactions, withdrawal-requests, bank-account-show, bank-account-save, withdraw
- **urgent-orders** — index, show, accept, reject
- **chats** — index, show, send-message
- **service-orders** — index, show, accept, reject, start, upload-files, finish
- **provider-admins** — index, store, show, update, destroy, toggle-status
- **provider-roles** — index, store, show, update, destroy
- **provider-permissions** — index, grouped

**Not in the permission system** (always allowed):
- profile (all routes)
- notifications (all routes)
- logout