# Admin API

All endpoints require:

```http
Authorization: Bearer <accessToken>
```

Role must be **`admin`** (enforced by `JwtAuthGuard` + `RolesGuard` via `@ApiAuthPermission(true, 'admin')`).

Customers and drivers receive **403 Forbidden**. Unauthenticated requests receive **401**.

Response wrapper matches the project convention (`listingApiWrapper` / `listingApiWrapperPaginate`).

Currency for revenue and payments follows `DEFAULT_RIDE_CURRENCY` (**USD** in this codebase).

---

## Authentication

Reuse existing auth:

- `POST /auth/login` — admin users must already have `role=admin` in DB (not assignable via public register)
- `POST /auth/refresh`
- `GET /user/me`

---

## Dashboard

### `GET /admin/dashboard`

**Purpose:** Aggregate metrics for the admin home screen.

**Auth:** JWT + admin

**Response data fields:**

| Field | Source |
| ----- | ------ |
| totalUsers | COUNT users |
| totalCustomers | COUNT role=customer |
| totalDrivers | COUNT role=driver |
| pendingDrivers | COUNT verificationStatus=PENDING |
| approvedDrivers | COUNT APPROVED |
| suspendedDrivers | COUNT SUSPENDED |
| rejectedDrivers | COUNT REJECTED |
| availableDrivers | COUNT APPROVED + AVAILABLE |
| activeRides | COUNT ACCEPTED/DRIVER_ARRIVING/DRIVER_ARRIVED/IN_PROGRESS |
| completedRides | COUNT COMPLETED |
| cancelledRides | COUNT CANCELLED |
| pendingPayments | COUNT PENDING |
| paidPayments | COUNT PAID |
| totalRevenue | SUM(amount) WHERE PAID |
| currency | USD |

---

## Users

### `GET /admin/users`

**Query:** `page`, `take` (max 100), `search`, `role` (`customer|driver|admin`), `status` (`active|deactive`)

**Purpose:** Paginated user directory (no passwords/OTP/reset fields).

### `GET /admin/users/:id`

**Purpose:** Safe user detail.

### `PATCH /admin/users/:id/status`

**Body:**

```json
{ "status": "active" | "deactive" }
```

**Rules:**

- Cannot change own status
- Cannot deactivate another admin via this endpoint

---

## Drivers

### Existing verification APIs (unchanged)

| Method | Path | Purpose |
| ------ | ---- | ------- |
| GET | `/admin/drivers/pending` | Pending list |
| GET | `/admin/drivers/:id` | Verification-focused detail |
| PATCH | `/admin/drivers/:id/approve` | PENDING→APPROVED (requires docs) |
| PATCH | `/admin/drivers/:id/reject` | PENDING→REJECTED (`reason` required) |
| PATCH | `/admin/drivers/:id/suspend` | APPROVED→SUSPENDED |
| PATCH | `/admin/drivers/:id/reactivate` | SUSPENDED→APPROVED |
| PATCH | `/admin/drivers/:id/reopen` | REJECTED→PENDING |

### New list / enriched detail

### `GET /admin/drivers`

**Query:** `page`, `take`, `search`, `verificationStatus`, `availabilityStatus`, `userStatus`

### `GET /admin/drivers/detail/:id`

**Purpose:** Enriched detail — user, documents metadata, location, vehicles+images, rating summary.

Does **not** replace verification mutations.

---

## Rides (read-only)

### `GET /admin/rides`

**Query:** `page`, `take`, `status`, `rideId`, `search` (customer/driver name/email)

### `GET /admin/rides/:id`

Includes pickup/destination/stops, vehicle, payment summary, `ridePinVerified` boolean.

**Never** exposes ride PIN plaintext or `ridePinHash`.

**No** admin ride status mutation endpoints (lifecycle stays in ride service).

---

## Payments (read-only)

### `GET /admin/payments`

**Query:** `page`, `take`, `status`, `rideId`

### `GET /admin/payments/:id`

CASH MVP — no card/gateway secrets.

---

## Vehicle categories (existing)

| Method | Path |
| ------ | ---- |
| GET/POST | `/admin/vehicle-categories` |
| GET/PATCH/DELETE | `/admin/vehicle-categories/:id` |

`GET /admin/vehicle-categories` supports pagination like other admin lists:

- Query: `page`, `take` (or `limit`), optional `isActive`, optional `search`
- Response: `listingApiWrapperPaginate` (`data`, `total`, `currentPage`, `lastPage`, …)

Soft-deactivate on delete.

---

## Notifications

Admin uses the existing shared APIs (any authenticated user, own notifications):

- `GET /notifications`
- `GET /notifications/unread-count`
- `PATCH /notifications/:id/read`
- `PATCH /notifications/read-all`

No duplicate admin notification module.

---

## Socket.IO

No admin-specific socket gateway added. Existing events unchanged.

---

## Database

**No schema migrations** for this step — Admin APIs use existing tables.

---

## Audit logging

Admin audit logging is **not currently available** in this codebase (no dedicated audit table/service).