clinicpro/.claude/skills/run-prompt/SKILL.md

name, description

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

قبل از شروع، فایل .claude/guidelines.md را بخوان و همهٔ بخش‌های آن را اعمال کن (اگر روت جلسه workspace است: clinicpro/.claude/guidelines.md). آن فایل «چگونه کار کردن» (درک مسئله، todo، تعریف «تمام شد»، مستندات، SOLID، رفتار تحلیل‌گر، چک‌لیست پایانی §۷) را تعیین می‌کند؛ این skill فقط قواعد stack، دستورهای تست و مسیرها را دارد. در تناقض با متن پرامپت، guidelines برنده است — مگر کاربر صریحاً خلافش را بگوید.

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

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

---

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

۱. فایل پرامپت را کامل بخوان ۲. مستندات موجود را بررسی کن: docs/api/ ۳. کد واقعیِ مرتبط در src/ و assets/admin/ را بخوان — هیچ فرضی از حافظه ۴. نقد پرامپت (guidelines §۶): اگر راه‌حل پرامپت اشتباه، ناقص یا پرریسک است، همین‌جا صریح و با دلیل بگو و منتظر تعیین تکلیف بمان. اجرای بی‌چون‌وچرای پرامپت غلط، خطای agent است. ۵. لیست قابلیت‌ها را استخراج کن؛ اگر پرامپت «معیار پذیرش» ندارد، خودت برای هر قابلیت بساز (موفق + خطا + مرزی) و به کاربر نشان بده ۶. با TodoWrite todo کامل بساز — یک آیتم قابل‌تست به ازای هر قابلیت ۷. به کاربر نمایش بده — تحلیل با بازگویی مسئله و معیار پذیرش تمام می‌شود، نه فقط لیست قابلیت‌ها:

🧭 بازگویی مسئله: مشکل X است؛ رفتار درست Y؛ محدودهٔ تغییر فایل‌های Z.
📋 قابلیت‌ها + معیار پذیرش:
  ۱. [نام] — ✅ [موفق] / ❌ [خطا] / ⚠️ [مرزی]
  ۲. ...
⚠️ ایرادهای پرامپت (اگر هست): ...

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

---

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

۱. Todo — ستون فقرات اجرا (guidelines §۲)

در ابتدای هر اجرا یک todo کامل با TodoWrite بساز:

• یک آیتم به ازای هر قابلیت با وضعیت pending
• هر آیتم قابل تست با خروجی مشخص («endpoint X با response Y کار می‌کند»)، نه فعل مبهم («بررسی سیستم نوبت»)
• آیتم‌های زیر-مجموعه اضافه کن اگر قابلیت چند بخش مستقل دارد

در طول اجرا:

• هر قابلیت را که شروع می‌کنی → in_progress؛ در هر لحظه فقط یک آیتم in_progress
• آیتم فقط وقتی completed می‌شود که هر سه انجام شده باشد: پیاده‌سازی + تست سبز + مستندات به‌روز
• اگر خطا داری که قابلیت را block کرده → یک آیتم in_progress باقی بماند تا رفع شود
• کشف کار جدید وسط اجرا (باگ جانبی، وابستگی پنهان) → آیتم جدید به todo + اطلاع به کاربر؛ انجام بی‌صدا ممنوع

۲. یک قابلیت در هر مرحله

• هرگز دو قابلیت را همزمان پیاده‌سازی نکن
• هرگز بدون تأیید موفقیت مرحله قبل به مرحله بعد نرو — خطا یعنی توقف کامل

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

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

۴. سازگاری با پروژه

• همه تغییرات باید با Symfony 7 + React 19 سازگار باشند
• از الگوهای موجود پروژه پیروی کن (BaseController، TanStack Query، Zod، ...)
• اگر Entity تغییر کرد: doctrine:migrations:diff و doctrine:migrations:migrate اجرا کن
• اگر قرارداد API تغییر کرد: همه کلاینت‌های وابسته را اصلاح کن — admin frontend (types، api calls) و اگر endpoint عمومی است، مصرف آن در nobat724_front/services/ را دستی دنبال کن؛ این تغییرات در build خطا نمی‌دهند و در رانتایم می‌شکنند. نتیجه بررسی را گزارش بده.

۵. اصول کدنویسی (تفصیل در guidelines §۵)

• SOLID: Controller نازک، منطق در Service، کوئری در Repository؛ رفتار جدید با extension نه if روی نوع؛ وابستگی با constructor injection نه new
• سبک کد جدید = سبک فایل‌های مشابه موجود در پروژه
• هیچ کامنت بدیهی؛ نام‌گذاری معنادار؛ هیچ abstraction بدون مصرفِ الان
• error handling فقط در boundaries واقعی (Controller، فراخوانی API، I/O)

---

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

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

قبل از هر چیز:

• فایل‌های مرتبط را بخوان
• endpoint های موجود را بررسی کن: php bin/console debug:router | grep api — API جدید فقط وقتی هیچ موجودی، حتی با توسعه، کافی نباشد
• Entity های مرتبط را شناسایی کن
• ابهام = توقف: سوال را همین‌جا بپرس، نه وسط پیاده‌سازی

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

قبل از کدنویسی، طرح کوتاه را توضیح بده:

• چه فایل‌هایی ایجاد/تغییر می‌کنند
• چه API endpoint هایی اضافه/تغییر می‌کنند
• چه migration لازم است (اگر Entity تغییر کرد)

اگر بیش از یک راه‌حل جدی وجود دارد: مزایا، معایب، ریسک و حداقل یک گزینهٔ جایگزین را مقایسه کن و دلیل انتخاب را بنویس (guidelines §۶). قبل از ساختن چیز جدید: اول بگرد، بعد توسعه بده، در آخر بساز — و دلیلش را بنویس.

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

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

مرحله ④ — تست

Definition of Done: syntax/build سبز و پوشش سه سناریوی معیار پذیرش (موفق، خطا، مرزی). دستورهای زیر حداقل‌اند نه سقف — اگر قابلیت منطق دارد، همان منطق را واقعاً اجرا کن (curl به endpoint با داده و توکن واقعی، نه فقط php -l). اگر پرامپت «نحوه تست» داده، همان را اجرا کن.

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

# تست واقعی endpoint — سه سناریو:
#   ✅ curl با توکن معتبر و داده واقعی → response مطابق معیار پذیرش
#   ❌ بدون توکن / بدون permission / ورودی نامعتبر → status و error code درست
#   ⚠️ حالت مرزی معیار پذیرش

اگر frontend تغییر کرد، TypeScript errors را بررسی کن:

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 با JSON واقعی از اجرای واقعی (خروجی curl مرحله تست، نه دست‌ساز)
4. تمام status codes و error codes
5. اگر پارامتر query داشت → همه را مستند کن

مرحله ⑦ — چک‌لیست + Todo + گزارش

۱. چک‌لیست پایان قابلیت — guidelines §۷ را کامل مرور کن؛ فقط اگر همهٔ آیتم‌ها تیک خورد، ادامه بده ۲. آیتم todo را completed کن با TodoWrite ۳. گزارش کوتاه نمایش بده:

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

معیار پذیرش: ✅ موفق / ❌ خطا / ⚠️ مرزی — هر سه تست شد (نتیجه واقعی، نه ادعا)
فایل‌های تغییر یافته:
  • src/...
  • assets/admin/...
  • docs/api/...
مستندات: docs/api/... به‌روز شد | نیاز نداشت (دلیل)

📊 پیشرفت کلی:
  ✅ قابلیت ۱: [نام] — تکمیل
  ⏳ قابلیت ۲: [نام] — در صف
  ...
─────────────────────────────────
▶ قابلیت بعدی: [شماره] — [نام]
آیا ادامه دهم؟

در گزارش، بین واقعیت (خروجی تست واقعی)، فرضیه و حدس تفاوت بگذار و برچسبش را مشخص کن؛ اگر چیزی تست نشده، همان را بگو — قطعی جا نزن.

---

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

Backend

• همه controller ها از BaseController ارث می‌برند
• پاسخ‌ها: $this->success($data) | $this->paginated(...) | $this->error(...)
• خطاها با AppException(ErrorCodes::ERR_XXX)؛ کدها و پیام فارسی در src/Shared/Constant/ErrorCodes.php
• لیست‌های 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

→ guidelines.md خوانده شد
→ فایل پرامپت را می‌خوانم...
→ کد مرتبط را می‌خوانم و پرامپت را نقد می‌کنم...

🧭 بازگویی مسئله: صفحه نوبت‌ها آمار روز و تغییر وضعیت inline ندارد؛ رفتار درست، toolbar با آمار و تقویم شمسی است؛ محدوده AppointmentsPage + یک endpoint آمار.
📋 قابلیت‌ها + معیار پذیرش:
  ۱. Stats Bar (backend + frontend) — ✅ آمار امروز درست / ❌ بدون توکن 401 / ⚠️ روز بدون نوبت → صفر
  ۲. تقویم شمسی Popup — ✅/❌/⚠️ ...
  ۳. بازطراحی Toolbar با date navigator — ...
  ۴. نمای جدولی با inline status change — ...

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