clinicpro/docs/api/secretary.md

Secretary API

Prefix: /api/v1/secretary, /api/v1/secretaries

مدل Scope

هر رابطه منشی-پزشک دارای یک scope است که از تداخل بین محیط‌های مختلف جلوگیری می‌کند:

Scope	owner_type	تعریف‌کننده	دسترسی
مطب شخصی	doctor	خود پزشک	فقط نوبت‌ها و داده‌های مطب شخصی
کلینیک	clinic	مدیر کلینیک	فقط نوبت‌ها و داده‌های کلینیک

• یک منشی می‌تواند هم در مطب شخصی یک دکتر و هم در کلینیک همان دکتر فعال باشد (دو ردیف مجزا)
• منشی کلینیک می‌تواند به چند دکتر در همان کلینیک متصل باشد
• scope فعال در runtime از جدول user_active_context (db_uuid) خوانده می‌شود

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 — creates owner_type='doctor') | ROLE_CLINIC (must have the doctor in its clinic — creates owner_type='clinic') | ROLE_ADMIN

Request Body (application/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:

{
  "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

{
  "success": true,
  "data": {
    "uuid": "sec-uuid-...",
    "user_name": "علی محمدی",
    "mobile_number": "09123456789",
    "doctor_name": "دکتر احمد رضایی",
    "doctor_uuid": "...",
    "owner_type": "doctor",
    "clinic_uuid": null,
    "is_active": true,
    "permissions": { ... },
    "created_at": 1717000000
  }
}

مقادیر owner_type:

مقدار	معنی
doctor	منشی توسط خود دکتر تعریف شده — فقط مطب شخصی
clinic	منشی توسط مدیر کلینیک تعریف شده — فقط کلینیک

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_AUTH_006	403	Not the doctor owner / clinic owner / admin
ERR_NOT_FOUND_001	404	Doctor not found
ERR_CONFLICT_001	409	Secretary already added for this doctor
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

{
  "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)

{
  "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

{ "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: ROLE_DOCTOR (must own doctor) | ROLE_CLINIC (must have doctor in clinic) | ROLE_ADMIN

Path Parameters

Param	Type	Description
doctorUuid	string (UUID)	Doctor UUID

Response 200

{
  "success": true,
  "data": [
    {
      "uuid": "...",
      "user_name": "علی محمدی",
      "mobile_number": "09...",
      "doctor_name": "دکتر احمد رضایی",
      "doctor_uuid": "...",
      "is_active": true,
      "permissions": { ... },
      "created_at": 1717000000
    }
  ]
}

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_FORBIDDEN_001	403	Not authorized
ERR_NOT_FOUND_001	404	Doctor not found

---

GET /api/v1/secretaries/clinic/{clinicUuid}

Get all secretaries across all doctors of a clinic.

Permission: ROLE_CLINIC (must own clinic) | ROLE_ADMIN

Path Parameters

Param	Type	Description
clinicUuid	string (UUID)	Clinic UUID

Response 200

{
  "success": true,
  "data": [
    {
      "uuid": "...",
      "user_name": "علی محمدی",
      "mobile_number": "09...",
      "doctor_name": "دکتر احمد رضایی",
      "doctor_uuid": "...",
      "is_active": true,
      "permissions": { ... },
      "created_at": 1717000000
    }
  ]
}

Notes

• این endpoint فقط منشیانی را برمی‌گرداند که با owner_type='clinic' تعریف شده‌اند
• منشیانی که خود دکتر (با owner_type='doctor') تعریف کرده از این لیست مخفی هستند
• یک منشی می‌تواند به چند دکتر در همان کلینیک متصل باشد — در لیست چندبار ظاهر می‌شود (یک ردیف به ازای هر دکتر)

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_FORBIDDEN_001	403	Not clinic owner
ERR_NOT_FOUND_001	404	Clinic not found

---

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

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

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

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

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

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