---
name: run-prompt
description: اجرای یک فایل پرامپت .md به صورت گام‌به‌گام و ایمن. هر قابلیت را جداگانه پیاده‌سازی، تست و مستند می‌کند. استفاده کن وقتی کاربر می‌گوید "اجرای پرامپت"، "پرامپت را اجرا کن"، "run prompt"، یا مسیر یک فایل .md می‌دهد.
---

## نحوه دریافت ورودی

اگر کاربر مسیر فایل داد → آن را بخوان.
اگر فایل مشخص نشد → بپرس: «مسیر فایل پرامپت .md را وارد کنید»

---

## قبل از شروع — تحلیل پرامپت و ساخت Todo

۱. فایل پرامپت را کامل بخوان  
۲. مستندات موجود را بررسی کن: `docs/api/`  
۳. کد مرتبط در `src/` و `assets/admin/` را مرور کن  
۴. لیست قابلیت‌ها را از پرامپت استخراج کن  
۵. **با `TodoWrite` یک todo کامل بساز** — یک آیتم به ازای هر قابلیت  
۶. به کاربر نمایش بده:

```
📋 قابلیت‌های شناسایی‌شده:
  ۱. [نام قابلیت اول]
  ۲. [نام قابلیت دوم]
  ...

🚀 شروع با قابلیت ۱ — آیا ادامه دهم؟
```

---

## قوانین اجرا (اجباری — هیچ استثنایی ندارد)

### ۱. Todo — ستون فقرات اجرا

**در ابتدای هر اجرا** یک todo کامل با `TodoWrite` بساز:
- یک آیتم به ازای هر قابلیت با وضعیت `pending`
- آیتم‌های زیر-مجموعه اضافه کن اگر قابلیت چند بخش مستقل دارد

**در طول اجرا:**
- هر قابلیت را که شروع می‌کنی → وضعیتش را `in_progress` کن
- هر قابلیت را که تست و تأیید شد → فوری `completed` کن
- هرگز دو آیتم را همزمان `in_progress` نگذار
- اگر خطا داری که قابلیت را block کرده → یک آیتم `in_progress` باقی بماند تا رفع شود

**نمونه todo اولیه:**
```
[ ] قابلیت ۱: Stats Bar backend endpoint
[ ] قابلیت ۲: Stats Bar frontend component  
[ ] قابلیت ۳: PersianCalendar popup
[ ] قابلیت ۴: AppointmentStatusDropdown
[ ] قابلیت ۵: بازطراحی AppointmentsPage
```

### ۲. یک قابلیت در هر مرحله
- هرگز دو قابلیت را همزمان پیاده‌سازی نکن
- هرگز بدون تأیید موفقیت مرحله قبل به مرحله بعد نرو

### ۳. ترتیب اجرای هر قابلیت

```
① تحلیل      ② طراحی      ③ پیاده‌سازی      ④ تست      ⑤ رفع خطا      ⑥ مستندسازی      ⑦ Todo + گزارش
```

### ۴. سازگاری با پروژه
- همه تغییرات باید با Symfony 7 + React 19 سازگار باشند
- از الگوهای موجود پروژه پیروی کن (BaseController، TanStack Query، Zod، ...)
- اگر Entity تغییر کرد: `doctrine:migrations:diff` و `doctrine:migrations:migrate` اجرا کن
- اگر API تغییر کرد: همه بخش‌های وابسته (frontend types، api calls، ...) را اصلاح کن

### ۵. اصول کدنویسی
- SOLID و Clean Code
- هیچ کامنت غیرضروری اضافه نکن
- نام‌گذاری معنادار
- error handling فقط در boundaries واقعی (نه defensive programming اضافی)

---

## روند اجرای هر قابلیت

### مرحله ① — تحلیل

قبل از هر چیز:
- فایل‌های مرتبط را بخوان
- endpoint های موجود را بررسی کن: `php bin/console debug:router | grep api`
- Entity های مرتبط را شناسایی کن
- اگر سوال یا ابهامی هست → همین‌جا بپرس، نه وسط پیاده‌سازی

### مرحله ② — طراحی

قبل از کدنویسی، طرح کوتاه را توضیح بده:
- چه فایل‌هایی ایجاد/تغییر می‌کنند
- چه API endpoint هایی اضافه/تغییر می‌کنند
- چه migration لازم است (اگر Entity تغییر کرد)

### مرحله ③ — پیاده‌سازی

- قابلیت را در todo روی `in_progress` بگذار
- **Backend اول**: Entity → Migration → Repository → Service → Controller
- **Frontend بعد**: Types → API call → Component → Route
- یک فایل در هر Edit/Write — نه bulk

### مرحله ④ — تست

بعد از هر قابلیت این چک‌لیست را اجرا کن:

```bash
# PHP syntax
ddev exec php -l src/Path/To/ChangedFile.php

# Symfony cache (اگر route یا config تغییر کرد)
ddev exec php bin/console cache:clear

# Migration (اگر Entity تغییر کرد)
ddev exec php bin/console doctrine:migrations:diff --no-interaction
ddev exec php bin/console doctrine:migrations:migrate --no-interaction

# Frontend build
ddev exec yarn dev

# Route وجود دارد؟
ddev exec php bin/console debug:router | grep "new-route-name"
```

اگر frontend تغییر کرد، TypeScript errors را بررسی کن:
```bash
ddev exec npx tsc --noEmit --project tsconfig.json 2>&1 | head -30
```

### مرحله ⑤ — رفع خطا

- اگر خطا بود → **همین‌جا** رفع کن، به مرحله بعد نرو
- اگر خطا در فایل دیگری بود → آن را هم رفع کن
- بعد از رفع خطا → دوباره تست را اجرا کن

### مرحله ⑥ — مستندسازی

بعد از موفقیت تست، مستندات را به‌روزرسانی کن:

| تغییر | فایل مستندات |
|-------|-------------|
| `src/Auth/*` | `docs/api/auth.md` |
| `src/Doctor/*` | `docs/api/doctor.md` |
| `src/Clinic/*` | `docs/api/clinic.md` |
| `src/Appointment/Controller/AppointmentController.php` | `docs/api/appointment.md` |
| `src/Appointment/Controller/AppointmentSettings*` | `docs/api/appointment-settings.md` |
| `src/Payment/*` | `docs/api/payment.md` |
| `src/Admin/*` | `docs/api/admin.md` |
| `src/Secretary/*` | `docs/api/secretary.md` |
| `src/Representation/*` | `docs/api/representation.md` |
| `src/Blog/*` | `docs/api/blog.md` |
| `src/Rating/*` | `docs/api/rating.md` |
| `src/Settlement/*` | `docs/api/settlement.md` |
| `src/Sms/*` | `docs/api/sms.md` |

الزامات مستندسازی:
1. endpoint جدید با method، path، permission
2. Request body با تمام فیلدها و نوع داده
3. Response format با مثال واقعی JSON
4. تمام status codes و error codes
5. اگر پارامتر query داشت → همه را مستند کن

### مرحله ⑦ — Todo + گزارش

بعد از موفقیت تست و مستندسازی:

۱. **آیتم todo را `completed` کن** با `TodoWrite`  
۲. گزارش کوتاه نمایش بده:

```
✅ قابلیت [شماره]: [نام] — تکمیل شد

فایل‌های تغییر یافته:
  • src/...
  • assets/admin/...
  • docs/api/...

📊 پیشرفت کلی:
  ✅ قابلیت ۱: [نام] — تکمیل
  ✅ قابلیت ۲: [نام] — تکمیل
  ⏳ قابلیت ۳: [نام] — در صف
  ...

─────────────────────────────────
▶ قابلیت بعدی: [شماره] — [نام]
آیا ادامه دهم؟
```

---

## قوانین خاص این پروژه

### Backend
- همه controller ها از `BaseController` ارث می‌برند
- پاسخ‌ها: `$this->success($data)` | `$this->paginated(...)` | `$this->error(...)`
- لیست‌های admin از DQL array hydration (`.getArrayResult()`) استفاده کنند
- تاریخ‌ها Unix timestamp صحیح (نه DateTime object)
- بعد از هر تغییر Entity: حتماً migration بساز و اجرا کن

### Frontend
- داده‌های paginated: items از `data?.data`، total از `data?.meta?.totalRecords`
- داده‌های single resource: از `data?.data` (ممکن است double-nested باشد)
- Category API همیشه triple-nested: `data?.data?.data ?? []`
- JWT در `localStorage['clinicpro-auth']` → `state.token`
- همه تاریخ‌ها با `formatDate()` شمسی نمایش داده شوند (`fa-IR-u-ca-persian`)
- Form: React Hook Form + Zod resolver
- State management: TanStack Query v5 برای server state، Zustand برای client state

### CSS / UI
- از کلاس‌های موجود استفاده کن: `btn primary sm`، `badge green`، `card`، `toolbar`، `field`، `avatar`، `appt-status`، ...
- هیچ کتابخانه CSS جدید اضافه نکن مگر ضرورت قطعی داشته باشد
- RTL رعایت شود

---

## مثال اجرا

```
کاربر: /run-prompt .claude/prompt/appointments-redesign.md

→ فایل را می‌خوانم...
→ تحلیل می‌کنم...

📋 قابلیت‌های شناسایی‌شده:
  ۱. Stats Bar — آمار امروز (backend + frontend)
  ۲. تقویم شمسی Popup (PersianCalendar component)
  ۳. بازطراحی Toolbar با date navigator
  ۴. نمای جدولی با inline status change
  ۵. نمای زمانبندی (Schedule View)
  ۶. ثبت نوبت از slot خالی

🚀 شروع با قابلیت ۱ (Stats Bar) — آیا ادامه دهم؟
```