Implement SMS panel user flow and patient records system; add wallet charging, automatic reminders, and patient session management with detailed database schema and user flows.

2026-06-14 21:15:40 +03:30
parent a72a6da621
commit b58aacc37f
28 changed files with 3169 additions and 0 deletions
@@ -0,0 +1,155 @@
+# تسک ۱۵: پرونده بیمار (Patient Records)
+
+## توضیح
+پیاده‌سازی سیستم پرونده الکترونیک بیمار. هر بیمار یک پرونده در هر کلینیک/مطب دارد.
+هر مراجعه یک سشن است که شامل اطلاعات بیمه، مبلغ ویزیت و سرویس‌های انجام‌شده است.
+دسترسی فقط در پنل **Basic+** — gate: `hasFeature('patient_records')`.
+
+## Endpoint ها
+
+| متد | مسیر | Gate | توضیح |
+|-----|------|------|-------|
+| GET | `/api/v1/patients` | Basic+ | لیست بیماران — `?search=name/phone` |
+| POST | `/api/v1/patient` | Basic+ | ایجاد پرونده دستی |
+| GET | `/api/v1/patient/{uuid}` | Basic+ | جزئیات پرونده |
+| GET | `/api/v1/patient/{uuid}/sessions` | Basic+ | لیست مراجعات |
+| POST | `/api/v1/patient/{uuid}/session` | Basic+ | ثبت مراجعه جدید |
+| PATCH | `/api/v1/session/{uuid}` | Basic+ | ویرایش مراجعه |
+
+## پیش‌نیازها
+- **تسک ۱۰** (ClinicStaff — برای staff_id در SessionService)
+- **تسک ۱۱** (Subscription — gate check)
+- **تسک ۱۳** (ClinicService — ServiceItem در session)
+
+## زمان تخمینی
+۱۶ تا ۲۰ ساعت
+
+## نمونه Request
+
+### POST /api/v1/patient (ایجاد دستی)
+```json
+{
+  "user_uuid": "uuid-of-user"
+}
+```
+
+### POST /api/v1/patient/{uuid}/session
+```json
+{
+  "appointment_uuid": null,
+  "insurance_base_uuid": "category-uuid-insurance-type",
+  "insurance_supplementary_uuid": null,
+  "visit_price_rials": 500000,
+  "base_insurance_discount_percent": 30,
+  "supplementary_discount_percent": 0,
+  "payment_method": "cash",
+  "notes": "بیمار شکایت از کمردرد داشت",
+  "services": [
+    { "service_item_uuid": "uuid-of-service-item", "staff_uuid": "uuid-of-staff" },
+    { "service_item_uuid": "uuid-of-another-item", "staff_uuid": null }
+  ]
+}
+```
+
+### PATCH /api/v1/session/{uuid}
+```json
+{
+  "notes": "ویرایش یادداشت",
+  "payment_method": "card"
+}
+```
+
+## فرمول محاسبه final_price
+
+```
+after_base    = visit_price_rials × (1 - base_insurance_discount_percent / 100)
+after_supp    = after_base × (1 - supplementary_discount_percent / 100)
+services_total = Σ service_item.price_rials (قیمت در زمان ثبت — نه قیمت فعلی)
+final_price   = round(after_supp) + services_total
+```
+
+مثال عددی:
+```
+visit_price  = 500,000
+base_disc    = 30% → after_base = 350,000
+supp_disc    = 10% → after_supp = 315,000
+services     = [85,000 + 45,000] = 130,000
+final        = 315,000 + 130,000 = 445,000
+```
+
+## نمونه Response
+
+### GET /api/v1/patients?search=علی
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "uuid": "...",
+      "user": { "uuid": "...", "name": "علی محمدی", "phone": "09121234567" },
+      "sessions_count": 5,
+      "last_session_at": 1718000000,
+      "created_at": 1710000000
+    }
+  ],
+  "meta": { "totalRecords": 12, "totalPages": 2, "currentPage": 1 }
+}
+```
+
+### GET /api/v1/patient/{uuid}
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "...",
+    "user": { "uuid": "...", "name": "علی محمدی", "phone": "09121234567" },
+    "sessions_count": 5,
+    "total_paid_rials": 2250000,
+    "created_at": 1710000000
+  }
+}
+```
+
+### GET /api/v1/patient/{uuid}/sessions
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "uuid": "...",
+      "appointment_uuid": null,
+      "visit_price_rials": 500000,
+      "base_insurance_discount_percent": 30,
+      "services_total_rials": 130000,
+      "final_price_rials": 445000,
+      "payment_method": "cash",
+      "notes": "...",
+      "services": [
+        { "name": "سرم ۵۰۰cc", "price_rials": 85000, "staff_name": "علی رضایی" }
+      ],
+      "created_at": 1718000000
+    }
+  ],
+  "meta": { "totalRecords": 5, "totalPages": 1, "currentPage": 1 }
+}
+```
+
+## ایجاد خودکار پرونده هنگام تأیید نوبت
+
+```
+AppointmentController::updateStatus(uuid, 'confirmed')
+  → اگر entityType/entityId پنل Basic+ دارد:
+    → PatientService::autoCreateOnAppointmentConfirm(appointment)
+      → PatientRecord.findOrCreate(entityType, entityId, userId)
+      → PatientSession جدید با appointment_id و visit_price پیش‌فرض (0)
+      → کاربر بعداً در پرونده می‌تواند اطلاعات بیمه و قیمت را تکمیل کند
+```
+
+## کدهای خطا
+
+| کد | HTTP | توضیح |
+|----|------|-------|
+| `ERR_SUBSCRIPTION_REQUIRED` | 403 | Basic+ لازم است |
+| `ERR_PATIENT_NOT_FOUND` | 404 | پرونده پیدا نشد |
+| `ERR_SESSION_NOT_FOUND` | 404 | مراجعه پیدا نشد |
+| `ERR_SERVICE_ITEM_NOT_FOUND` | 404 | زیربخش سرویس پیدا نشد |