clinicpro/docs/api/doctor.md

# Doctor API

> **Prefix:** `/api/v1/doctor`, `/api/v1/doctors`, `/api/v1/clinic-pro/doctor-address*`

---

## POST `/api/v1/doctor`

Create a doctor profile for the authenticated user.

**Permission:** `AUTH` — any authenticated user

### Request Body (`application/json`)
```json
{
  "title": "دکتر علی احمدی",
  "gender": "male",
  "medical_system_code": "12345",
  "degree": "متخصص",
  "info": "توضیحات درباره پزشک",
  "specialties": [1, 2],
  "doctor_services": [3, 4]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | ✅ | Full name with title |
| `gender` | string | ❌ | `"male"` or `"female"` |
| `medical_system_code` | string | ❌ | Nظام پزشکی code |
| `degree` | string | ❌ | Academic degree |
| `info` | string | ❌ | Bio/description |
| `specialties` | integer[] | ❌ | Array of specialty IDs |
| `doctor_services` | integer[] | ❌ | Array of doctor service IDs |

### Response `201`
```json
{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "title": "دکتر علی احمدی",
    "gender": "male",
    "medical_system_code": "12345",
    "degree": "متخصص",
    "info": "...",
    "doctor_rate": null,
    "active_doctor_appointment": false,
    "specialties": [],
    "doctor_services": [],
    "created_at": 1717000000
  }
}
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing or invalid token |
| `ERR_CONFLICT_001` | 409 | Doctor profile already exists for this user |
| `ERR_VALIDATION_002` | 422 | Missing required field |

---

## GET `/api/v1/doctor/{uuid}`

Get doctor detail with clinics.

**Permission:** `PUBLIC`

### Path Parameters
| Param | Type | Description |
|-------|------|-------------|
| `uuid` | string (UUID) | Doctor UUID |

### Response `200`
```json
{
  "success": true,
  "data": {
    "data": {
      "uuid": "550e8400-...",
      "title": "دکتر علی احمدی",
      "gender": "male",
      "medical_system_code": "12345",
      "degree": "متخصص",
      "info": "...",
      "image": "https://...",
      "doctor_rate": 4.5,
      "active_doctor_appointment": true,
      "specialties": [{ "id": 1, "name": "قلب و عروق" }],
      "doctor_services": [{ "id": 3, "name": "نوار قلب" }],
      "clinics": [{ "uuid": "...", "name": "کلینیک الوند" }],
      "created_at": 1717000000
    }
  }
}
```

> ⚠️ **Double-nested:** Frontend extracts with `data?.data?.data`

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |

---

## GET `/api/v1/doctors`

List doctors with pagination and filters.

**Permission:** `PUBLIC`

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

### Response `200`
```json
{
  "success": true,
  "data": [
    {
      "uuid": "...",
      "title": "دکتر علی احمدی",
      "degree": "متخصص",
      "doctor_rate": 4.5,
      "image": "https://..."
    }
  ],
  "meta": {
    "totalRecords": 50,
    "totalPages": 3,
    "currentPage": 1
  }
}
```

---

## PATCH `/api/v1/doctor/{uuid}`

Update doctor profile.

**Permission:** `AUTH` — must be the owner (or `ROLE_ADMIN`)

### Path Parameters
| Param | Type | Description |
|-------|------|-------------|
| `uuid` | string (UUID) | Doctor UUID |

### Request Body (`application/json`)
Same fields as POST — all optional.

### Response `200`
Updated doctor object (same structure as GET single).

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_FORBIDDEN_001` | 403 | Not the owner |
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |

---

## DELETE `/api/v1/doctor/{uuid}`

Delete a doctor profile.

**Permission:** `ROLE_ADMIN`

### Path Parameters
| Param | Type | Description |
|-------|------|-------------|
| `uuid` | string (UUID) | Doctor UUID |

### 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 | Doctor not found |

---

## POST `/file/upload/clinic_pro/doctor/field_image`

Upload doctor profile image.

**Permission:** `AUTH`

### Request
`Content-Type: multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file` | binary | ✅ | Image file (max 5MB) |

### Response `200`
```json
{
  "success": true,
  "data": {
    "url": "https://clinic-pro.ddev.site/uploads/doctor/abc123.jpg",
    "uuid": "...",
    "filename": "abc123.jpg",
    "filemime": "image/jpeg",
    "filesize": 204800
  }
}
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_FILE_001` | 422 | Invalid file type |
| `ERR_AUTH_001` | 401 | Missing token |

---

## GET `/api/v1/clinic-pro/doctor-addresses/{doctorId}`

Get all practice addresses for a doctor.

**Permission:** `PUBLIC`

### Path Parameters
| Param | Type | Description |
|-------|------|-------------|
| `doctorId` | integer | Doctor's numeric ID |

### Response `200`
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "مطب تهران",
      "address": "تهران، خیابان...",
      "telephone": "02112345678",
      "latitude": 35.6892,
      "longitude": 51.3890
    }
  ]
}
```

---

## POST `/api/v1/clinic-pro/doctor-address`

Add a new practice address.

**Permission:** `AUTH` — must own the doctor profile

### Request Body
```json
{
  "name": "مطب تهران",
  "address": "تهران، خیابان ولیعصر",
  "telephone": "02112345678",
  "latitude": 35.6892,
  "longitude": 51.3890
}
```

| Field | Type | Required |
|-------|------|----------|
| `name` | string | ❌ |
| `address` | string | ❌ |
| `telephone` | string | ❌ |
| `latitude` | float | ❌ |
| `longitude` | float | ❌ |

### Response `201`
```json
{
  "success": true,
  "data": {
    "id": 1,
    "name": "مطب تهران",
    "address": "تهران، خیابان ولیعصر",
    "telephone": "02112345678",
    "latitude": 35.6892,
    "longitude": 51.3890
  }
}
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_FORBIDDEN_001` | 403 | Not the doctor owner |
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |

---

## PATCH `/api/v1/clinic-pro/doctor-address/{id}`

Update a practice address.

**Permission:** `AUTH` — must own the doctor profile

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

### Request Body
Same fields as POST — all optional.

### Response `200`
Updated address object.

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_FORBIDDEN_001` | 403 | Not the owner |
| `ERR_NOT_FOUND_001` | 404 | Address not found |

---

## DELETE `/api/v1/clinic-pro/doctor-address/{id}`

Delete a practice address.

**Permission:** `AUTH` — must own the doctor profile

### Response `200`
```json
{ "success": true, "data": { "message": "آدرس حذف شد" } }
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_FORBIDDEN_001` | 403 | Not the owner |
| `ERR_NOT_FOUND_001` | 404 | Address not found |

---

## POST `/api/v1/clinic-pro/doctor-address/from-clinic/{clinicUuid}`

Create a doctor address automatically from a clinic's location.

**Permission:** `AUTH` — must own the doctor profile and be associated with the clinic

### Path Parameters
| Param | Type | Description |
|-------|------|-------------|
| `clinicUuid` | string (UUID) | Clinic UUID |

### Response `201`
Address object created from clinic data.

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_FORBIDDEN_001` | 403 | Not associated with this clinic |
| `ERR_NOT_FOUND_001` | 404 | Clinic not found |