From a1d3442b9bffdca6ac7dded3f60474545da43c7b Mon Sep 17 00:00:00 2001
From: hamed <15238-genius.ha@users.noreply.drupalcode.org>
Date: Sun, 14 Jun 2026 20:43:59 +0330
Subject: [PATCH] Refactor PRD documentation: Remove outdated pre_prd.md and
 create comprehensive prd.md for ClinicPro Phase 2, detailing new features,
 requirements, and API endpoints. Add initial pre_prd.md for settings and
 staff management.

---
 {PRD => docs/PRD}/prd.md     | 48 +++++++++++++++++++++++-------------
 {PRD => docs/PRD}/pre_prd.md |  0
 2 files changed, 31 insertions(+), 17 deletions(-)
 rename {PRD => docs/PRD}/prd.md (89%)
 rename {PRD => docs/PRD}/pre_prd.md (100%)

diff --git a/PRD/prd.md b/docs/PRD/prd.md
similarity index 89%
rename from PRD/prd.md
rename to docs/PRD/prd.md
index 33c68aa4..d5cd67ef 100644
--- a/PRD/prd.md
+++ b/docs/PRD/prd.md
@@ -91,15 +91,23 @@ ClinicStaff:
 | 2 | Professional | ۵ منشی + پرونده بیمار + مدیریت سرویس‌ها |
 
 #### دوره‌های اشتراک (مثال)
-| دوره | مدت (ماه) | قیمت Basic | قیمت Professional |
-|------|-----------|-----------|------------------|
-| ۱ ماهه | 1 | ادمین تعیین می‌کند | ادمین تعیین می‌کند |
-| ۳ ماهه | 3 | ادمین تعیین می‌کند | ادمین تعیین می‌کند |
-| ۶ ماهه | 6 | ادمین تعیین می‌کند | ادمین تعیین می‌کند |
-| ۱۲ ماهه | 12 | ادمین تعیین می‌کند | ادمین تعیین می‌کند |
+| دوره | مدت (ماه) | نوع | قیمت |
+|------|-----------|-----|------|
+| تریال | 1 | trial — رایگان | ۰ ریال |
+| ۱ ماهه | 1 | paid | ادمین تعیین می‌کند |
+| ۳ ماهه | 3 | paid | ادمین تعیین می‌کند |
+| ۶ ماهه | 6 | paid | ادمین تعیین می‌کند |
+| ۱۲ ماهه | 12 | paid | ادمین تعیین می‌کند |
 
 > ادمین می‌تواند دوره‌های دلخواه اضافه، ویرایش یا غیرفعال کند.
 
+#### دوره تریال
+- تریال فقط برای پنل **Basic** فعال است
+- هر کلینیک/دکتر فقط **یک بار** می‌تواند از تریال استفاده کند (بررسی در `ClinicSubscription`)
+- تریال نیازی به پرداخت ندارد — مستقیم فعال می‌شود
+- ادمین می‌تواند تریال را به‌طور کلی فعال/غیرفعال کند (`trial_enabled` در SiteConfig)
+- بعد از انقضای تریال، سیستم به پنل Free بازمی‌گردد (نه حذف داده)
+
 #### نیازمندی‌های کارکردی
 - **F2.1** — ادمین برای هر ترکیب (پنل × دوره) یک قیمت تعریف می‌کند
 - **F2.2** — ادمین می‌تواند دوره‌های جدید اضافه کند (مثلاً ۲ ماهه) یا دوره‌ای را غیرفعال کند
@@ -109,6 +117,8 @@ ClinicStaff:
 - **F2.6** — gate: `hasFeature('patient_records')` — بررسی اشتراک فعال و expired نبودن
 - **F2.7** — گزارش فروش پنل‌ها در داشبورد ادمین (تعداد، درآمد، بر اساس دوره و سطح)
 - **F2.8** — نمایش تاریخ انقضا و هشدار ۷ روز قبل به کلینیک/دکتر
+- **F2.9** — تریال Basic: فعال‌سازی رایگان یک‌بار — endpoint جداگانه `POST /api/v1/subscription/trial`
+- **F2.10** — بررسی استفاده قبلی از تریال قبل از فعال‌سازی (`used_trial: bool` روی entity)
 
 #### موجودیت‌های جدید مورد نیاز
 ```
@@ -124,9 +134,10 @@ SubscriptionPlan:
 SubscriptionPeriod:
   - id, uuid
   - plan_id (FK → subscription_plans)
-  - label: string (مثال: "۶ ماهه", "سالانه")
+  - label: string (مثال: "۶ ماهه", "تریال ۱ ماهه")
   - duration_months: int (1, 3, 6, 12, ...)
-  - price_rials: int (قیمت این دوره برای این پنل)
+  - price_rials: int (0 برای تریال)
+  - is_trial: bool (default: false — فقط یک دوره trial در Basic)
   - active: bool
   - sort_order: int (ترتیب نمایش)
   - created_at, updated_at
@@ -137,7 +148,8 @@ ClinicSubscription:
   - entity_id: int
   - plan_id (FK → subscription_plans)
   - period_id (FK → subscription_periods)
-  - payment_id (FK → payments, nullable)
+  - payment_id (FK → payments, nullable — برای تریال null است)
+  - is_trial: bool (کپی از period — برای گزارش راحت‌تر)
   - starts_at: int (Unix timestamp)
   - expires_at: int (Unix timestamp — null = بی‌نهایت برای Free)
   - created_at
@@ -150,25 +162,27 @@ ClinicSubscription:
 #### API endpoints
 | Method | Path | Permission |
 |--------|------|-----------|
-| `GET` | `/api/v1/subscription/plans` | public — لیست پنل‌ها با دوره‌ها و قیمت‌ها |
-| `GET` | `/api/v1/subscription/my` | clinic/doctor — اشتراک فعال + تاریخ انقضا |
+| `GET` | `/api/v1/subscription/plans` | public — لیست پنل‌ها با دوره‌ها، قیمت‌ها و دوره تریال |
+| `GET` | `/api/v1/subscription/my` | clinic/doctor — اشتراک فعال + تاریخ انقضا + `used_trial` |
+| `POST` | `/api/v1/subscription/trial` | clinic/doctor — فعال‌سازی تریال Basic (رایگان، یک‌بار) |
 | `POST` | `/api/v1/subscription-payment` | clinic/doctor — `{ period_uuid }` |
 | `GET` | `/api/v1/admin/subscription/plans` | admin — مدیریت پنل‌ها |
 | `POST` | `/api/v1/admin/subscription/plan` | admin |
 | `PATCH` | `/api/v1/admin/subscription/plan/{uuid}` | admin |
 | `POST` | `/api/v1/admin/subscription/period` | admin — افزودن دوره جدید |
-| `PATCH` | `/api/v1/admin/subscription/period/{uuid}` | admin — ویرایش قیمت/مدت |
+| `PATCH` | `/api/v1/admin/subscription/period/{uuid}` | admin — ویرایش قیمت/مدت/تریال |
 | `DELETE` | `/api/v1/admin/subscription/period/{uuid}` | admin — غیرفعال‌سازی |
-| `GET` | `/api/v1/admin/subscription/report` | admin — گزارش فروش |
+| `GET` | `/api/v1/admin/subscription/report` | admin — گزارش فروش + تعداد تریال‌های فعال‌شده |
 
 #### Frontend
 - صفحه کلینیک/دکتر: `SubscriptionPage.tsx`
-  - نمایش پنل فعال + تاریخ انقضا (شمسی)
-  - جدول مقایسه پنل‌ها با انتخاب دوره (مثل toggle ماهانه/سالانه)
+  - اگر `used_trial = false`: بنر «۱ ماه رایگان امتحان کنید» با دکمه فعال‌سازی تریال
+  - نمایش پنل فعال + تاریخ انقضا (شمسی) + badge «تریال» اگر is_trial باشد
+  - جدول مقایسه پنل‌ها با انتخاب دوره (toggle)
   - دکمه خرید → redirect به gateway
 - صفحه ادمین: `AdminSubscriptionPage.tsx`
-  - تب «پنل‌ها»: ویرایش قیمت دوره‌ها (DataTable با inline edit)
-  - تب «گزارش»: فروش بر اساس بازه زمانی، سطح، دوره
+  - تب «پنل‌ها»: ویرایش قیمت دوره‌ها + مشخص کردن کدام دوره تریال است
+  - تب «گزارش»: فروش + تریال‌ها بر اساس بازه زمانی
 
 ---
 
diff --git a/PRD/pre_prd.md b/docs/PRD/pre_prd.md
similarity index 100%
rename from PRD/pre_prd.md
rename to docs/PRD/pre_prd.md