feat: implement staff management and subscription system

- Added StaffController for managing clinic staff, including listing, creating, updating, and toggling staff status. - Created ClinicStaff entity and repository for staff data handling. - Developed SubscriptionController to manage subscription plans and periods, including trial subscriptions. - Introduced SubscriptionPlan, SubscriptionPeriod, and ClinicSubscription entities for subscription management. - Implemented SubscriptionService for handling subscription logic, including trial activation and subscription creation from payments. - Added necessary repositories for subscription entities to facilitate data access and manipulation.
2026-06-14 22:10:28 +03:30
parent dcd631f503
commit b0244f28f5
53 changed files with 4434 additions and 40 deletions
@@ -0,0 +1,139 @@
+# Staff API
+
+مدیریت پرسنل مطب/کلینیک (بدون حذف — فقط toggle فعال/غیرفعال).
+
+---
+
+## GET /api/v1/staff
+
+دریافت لیست پرسنل entity جاری (از JWT).
+
+**Permission:** `IS_AUTHENTICATED_FULLY` (ROLE_DOCTOR یا ROLE_CLINIC)
+
+**Response 200:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "uuid": "a1b2c3d4-...",
+      "entity_type": "clinic",
+      "entity_id": 5,
+      "full_name": "علی محمدی",
+      "phone": "09121234567",
+      "job_title": "منشی",
+      "address": null,
+      "national_code": "0012345678",
+      "active": true,
+      "created_at": 1718000000,
+      "updated_at": 1718000000
+    }
+  ]
+}
+```
+
+---
+
+## POST /api/v1/staff
+
+ایجاد پرسنل جدید.
+
+**Permission:** `IS_AUTHENTICATED_FULLY` (ROLE_DOCTOR یا ROLE_CLINIC)
+
+**Request Body:**
+```json
+{
+  "full_name": "علی محمدی",
+  "phone": "09121234567",
+  "job_title": "منشی",
+  "address": "تهران، خیابان ولیعصر",
+  "national_code": "0012345678"
+}
+```
+
+| فیلد | نوع | الزامی |
+|------|-----|--------|
+| full_name | string | ✅ |
+| phone | string | ❌ |
+| job_title | string | ❌ |
+| address | string | ❌ |
+| national_code | string(10) | ❌ |
+
+**Response 201:**
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "a1b2c3d4-...",
+    "entity_type": "clinic",
+    "entity_id": 5,
+    "full_name": "علی محمدی",
+    "phone": "09121234567",
+    "job_title": "منشی",
+    "address": "تهران، خیابان ولیعصر",
+    "national_code": "0012345678",
+    "active": true,
+    "created_at": 1718000000,
+    "updated_at": 1718000000
+  }
+}
+```
+
+**Errors:**
+| Code | HTTP | توضیح |
+|------|------|-------|
+| ERR_VALIDATION_001 | 422 | full_name خالی است |
+| ERR_FORBIDDEN_001 | 403 | پروفایل doctor/clinic یافت نشد |
+
+---
+
+## PATCH /api/v1/staff/{uuid}
+
+ویرایش اطلاعات پرسنل.
+
+**Permission:** `IS_AUTHENTICATED_FULLY` — فقط owner یا ROLE_ADMIN
+
+**Request Body (همه فیلدها اختیاری):**
+```json
+{
+  "full_name": "علی محمدی ویرایش‌شده",
+  "phone": "09129999999",
+  "job_title": "منشی ارشد",
+  "address": null,
+  "national_code": null
+}
+```
+
+**Response 200:** همان ساختار staff object
+
+**Errors:**
+| Code | HTTP | توضیح |
+|------|------|-------|
+| ERR_STAFF_NOT_FOUND | 404 | پرسنل یافت نشد |
+| ERR_FORBIDDEN_001 | 403 | دسترسی ندارید |
+
+---
+
+## PATCH /api/v1/staff/{uuid}/toggle
+
+تغییر وضعیت فعال/غیرفعال پرسنل (soft toggle — هیچ حذفی انجام نمی‌شود).
+
+**Permission:** `IS_AUTHENTICATED_FULLY` — فقط owner یا ROLE_ADMIN
+
+**Response 200:**
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "a1b2c3d4-...",
+    "active": false,
+    ...
+  }
+}
+```
+
+**Errors:**
+| Code | HTTP | توضیح |
+|------|------|-------|
+| ERR_STAFF_NOT_FOUND | 404 | پرسنل یافت نشد |
+| ERR_FORBIDDEN_001 | 403 | دسترسی ندارید |