clinicpro/docs/api/secretary.md

# Secretary API

> **Prefix:** `/api/v1/secretary`, `/api/v1/secretaries`

Secretaries are linked to a doctor and have granular permissions controlling what they can do on behalf of the doctor.

---

## POST `/api/v1/secretary`

Create a secretary for a doctor.

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

### Request Body (`application/json`)
```json
{
  "doctor_uuid": "550e8400-...",
  "mobile_number": "09123456789",
  "password": "secretaryPass123",
  "permissions": {
    "version": 1,
    "resources": {
      "appointments": { "view": true, "create": true, "cancel": false, "update_status": true },
      "addresses":    { "view": true, "create": false, "update": false, "delete": false },
      "clinic_info":  { "view": true, "update": false },
      "insurances":   { "view": true, "create": false, "update": false, "delete": false }
    }
  }
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `doctor_uuid` | string (UUID) | ✅ | Doctor to assign secretary to |
| `mobile_number` | string | ✅ | Secretary's login mobile |
| `password` | string | ❌ | Initial password (auto-generated if omitted) |
| `permissions` | object | ❌ | Permission set (see structure below) |

**Permissions Structure:**
```json
{
  "version": 1,
  "resources": {
    "appointments": {
      "view":          true,   // Can view appointments list
      "create":        true,   // Can book appointments
      "cancel":        false,  // Can cancel appointments
      "update_status": true    // Can mark as completed/no_show
    },
    "addresses": {
      "view":   true,
      "create": false,
      "update": false,
      "delete": false
    },
    "clinic_info": {
      "view":   true,
      "update": false
    },
    "insurances": {
      "view":   true,
      "create": false,
      "update": false,
      "delete": false
    }
  }
}
```

### Response `201`
```json
{
  "success": true,
  "data": {
    "uuid": "sec-uuid-...",
    "mobile_number": "09123456789",
    "active": true,
    "permissions": { ... },
    "doctor": { "uuid": "...", "title": "دکتر علی احمدی" },
    "created_at": 1717000000
  }
}
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_AUTH_006` | 403 | Not a doctor or not the doctor's owner |
| `ERR_NOT_FOUND_001` | 404 | Doctor not found |
| `ERR_CONFLICT_001` | 409 | Mobile number already in use |
| `ERR_SECRETARY_001` | 422 | Plan limit for secretaries reached |

---

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

Get secretary detail.

**Permission:** `AUTH` — must be the linked doctor or `ROLE_ADMIN`

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

### Response `200`
```json
{
  "success": true,
  "data": {
    "uuid": "...",
    "mobile_number": "09123456789",
    "active": true,
    "permissions": { ... },
    "doctor": { "uuid": "...", "title": "دکتر علی احمدی" },
    "created_at": 1717000000
  }
}
```

### Errors
| Code | HTTP | Description |
|------|------|-------------|
| `ERR_AUTH_001` | 401 | Missing token |
| `ERR_FORBIDDEN_001` | 403 | Not authorized |
| `ERR_NOT_FOUND_001` | 404 | Secretary not found |

---

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

Update secretary active status or permissions.

**Permission:** `ROLE_DOCTOR` — must be the linked doctor

### Request Body (`application/json`)
```json
{
  "active": false,
  "permissions": {
    "version": 1,
    "resources": {
      "appointments": { "view": true, "create": false, "cancel": false, "update_status": false }
    }
  }
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `active` | boolean | ❌ | Enable/disable secretary |
| `permissions` | object | ❌ | New permissions object |

### Response `200`
Updated secretary object.

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

---

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

Delete a secretary.

**Permission:** `ROLE_DOCTOR` — must be the linked doctor

### Response `200`
```json
{ "success": true, "data": { "message": "منشی حذف شد" } }
```

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

---

## GET `/api/v1/secretaries/{doctorUuid}`

Get all secretaries for a specific doctor.

**Permission:** `AUTH` — must be the doctor or `ROLE_ADMIN`

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

### Response `200`
```json
{
  "success": true,
  "data": [
    {
      "uuid": "...",
      "mobile_number": "09...",
      "active": true,
      "permissions": { ... },
      "created_at": 1717000000
    }
  ]
}
```

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

---

## محدودیت پنل اشتراکی

تعداد منشی‌های مجاز بر اساس پنل فعال doctor تعیین می‌شود:

| پنل | حداکثر منشی |
|-----|-------------|
| Free (بدون اشتراک) | ۱ |
| Basic | ۳ |
| Professional | ۱۰ |

اگر تعداد منشی‌های فعال به حد مجاز رسیده باشد، ایجاد منشی جدید خطای زیر را برمی‌گرداند:

```json
{
  "success": false,
  "errors": [
    {
      "code": "ERR_SECRETARY_001",
      "message": "پلن فعلی اجازه منشی بیشتر را نمی‌دهد"
    }
  ]
}
```

برای افزایش محدودیت، باید پنل را از `POST /api/v1/subscription/trial` (تریال) یا `POST /api/v1/subscription-payment` (پرداخت) ارتقاء داد.