# Doctor Service API

> **Prefix:** `/api/v1/doctor-services`, `/api/v1/admin/doctor-service`

---

## GET `/api/v1/doctor-services`

List all active doctor services.

**Permission:** `PUBLIC`

### Query Parameters
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `specialty_id` | integer | ❌ | Filter by parent specialty |

### Response `200`
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "نوار قلب (ECG)",
      "slug": "navar-ghalb",
      "specialty_id": 1,
      "status": "active",
      "weight": 5
    }
  ]
}
```

---

## GET `/api/v1/admin/doctor-services`

List all services with pagination (admin view).

**Permission:** `ROLE_ADMIN`

### Query Parameters
| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | ❌ | Default: 1 |
| `limit` | integer | ❌ | Default: 20 |
| `search` | string | ❌ | Search in name |
| `specialty_id` | integer | ❌ | Filter by specialty |

### Response `200`
```json
{
  "success": true,
  "data": [ ... ],
  "meta": { "totalRecords": 30, "totalPages": 2, "currentPage": 1 }
}
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_AUTH_006` | 403 | Not admin |

---

## POST `/api/v1/admin/doctor-service`

Create a new doctor service.

**Permission:** `ROLE_ADMIN`

### Request Body (`application/json`)
```json
{
  "name": "نوار قلب (ECG)",
  "slug": "navar-ghalb",
  "specialty_id": 1,
  "status": "active",
  "weight": 5
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | ✅ | Service name |
| `slug` | string | ❌ | Auto-generated from name if omitted |
| `specialty_id` | integer | ❌ | Link to specialty |
| `status` | string | ❌ | `"active"` or `"inactive"` |
| `weight` | integer | ❌ | Sort weight |

### Response `201`
Service object.

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_AUTH_006` | 403 | Not admin |
| `ERR_VALIDATION_002` | 422 | Missing name |

---

## PATCH `/api/v1/admin/doctor-service/{id}`

Update a doctor service.

**Permission:** `ROLE_ADMIN`

### Path Parameters
| Param | Type | Description |
|-------|------|-------------|
| `id` | integer | Service ID |

All body fields optional.

### Response `200`
Updated service object.

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_AUTH_006` | 403 | Not admin |
| `ERR_NOT_FOUND_001` | 404 | Service not found |

---

## DELETE `/api/v1/admin/doctor-service/{id}`

Delete a doctor service.

**Permission:** `ROLE_ADMIN`

### Response `200`
```json
{ "success": true, "data": { "message": "خدمت پزشکی حذف شد" } }
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_AUTH_006` | 403 | Not admin |
| `ERR_NOT_FOUND_001` | 404 | Service not found |

---

## Bulk import / export

Full-table JSON export and strict wipe+replace import for this category live under
`/api/v1/admin/categories/{bundle}/{export|import}` — see [category-import.md](category-import.md).


### Sorting by id

The admin list endpoint accepts `sort=id&order=asc|desc` to order by `id`
(used by the admin «دسته‌بندی‌ها» page when clicking the «شناسه» column).
Without `sort`, the default ordering (weight/name) is unchanged.
