feat: add Figma token mapping and guidelines for project implementation

2026-07-13 10:57:20 +03:30
parent 43e057040f
commit 9d8de9bc33
2 changed files with 262 additions and 0 deletions
@@ -0,0 +1,122 @@
+---
+name: figma-to-feature
+description: وقتی کاربر یک لینک figma.com/design با node-id می‌دهد، صفحه را تحلیل
+  کن، نیازهای فرانت‌اند و بک‌اند را استخراج کن و پس از تأیید پیاده‌سازی کن.
+---
+
+## بخش ۰ — زبان (قبل از هر کاری)
+- ورودی من فارسی است. منظور را استخراج کن، نه ترجمه‌ی لغوی.
+- متن را به یک normalized English spec تبدیل کن با فیلدهای:
+  Goal / Scope (in-out) / Constraints / Acceptance criteria / Ambiguities
+- اصطلاحات فینگلیش (کامپوننت، اندپوینت، باتن) اصطلاح فنی‌اند، ترجمه نکن.
+- اسم متغیر، مسیر فایل، اسم کامپوننت و هر چیز داخل بک‌تیک را عیناً حفظ کن.
+- spec انگلیسی + خلاصه‌ی برداشتت به فارسی را نشانم بده و منتظر تأیید بمان.
+  اگر Ambiguities خالی نبود، سؤال‌ها را بپرس. بدون تأیید، کد ننویس.
+- خروجی: کد/کامنت/داکیومنت/کامیت انگلیسی. گفت‌وگو با من فارسی.
+  رشته‌های UI فارسی و از فایل i18n پروژه — هاردکد ممنوع.
+
+## بخش ۱ — استخراج از فیگما
+- fileKey و node-id را از URL دربیاور.
+- get_design_context → ساختار و لِی‌اوت
+- get_variable_defs → رنگ/اسپیسینگ/تایپوگرافی
+- get_screenshot → مرجع تطبیق بصری
+- download_assets → آیکون و تصاویر
+- توکن‌های فیگما را با mapping.md به متغیرهای واقعی پروژه نگاشت کن.
+
+## بخش ۲ — ممیزی کدبیس (اجباری، قبل از هر تحلیلی)
+
+هر بار که یک لینک صفحه می‌گیری، باید هم بک‌اند و هم فرانت‌اند را واقعاً بگردی.
+حدس زدن ممنوع؛ فقط چیزی که با Grep/Read در کد دیدی.
+
+### الف) ممیزی بک‌اند
+- routes/controllers را بگرد: کدام اندپوینت‌ها مرتبط با این صفحه از قبل وجود دارند؟
+- مدل‌ها و اسکیمای دیتابیس: کدام جدول/فیلد لازم است و از قبل هست؟
+- سرویس‌ها و validationها و middleware مرتبط
+- برای هر مورد بنویس: مسیر فایل + شماره خط
+
+### ب) ممیزی فرانت‌اند
+- کامپوننت‌های design system که می‌شود reuse کرد (با مسیر فایل)
+- روت مربوطه هست یا نه
+- hook/service/state موجود برای این داده
+- فایل i18n: کلیدهای متنی این صفحه از قبل هستند؟
+- برای هر مورد بنویس: مسیر فایل + شماره خط
+
+### ج) خروجی ممیزی — این جدول را بده
+| مورد | لایه | وضعیت | فایل | اقدام |
+|------|------|-------|------|-------|
+| نام دقیق | Frontend/Backend | ✅ موجود / ✏️ نیاز به ادیت / 🆕 جدید | مسیر:خط | یک جمله |
+
+### د) مبهم‌ها
+هر چیزی که از دیزاین معلوم نیست: empty state، حالت خطا، لودینگ، pagination،
+دسترسی/نقش کاربر، اعتبارسنجی فیلدها. لیست کن و بپرس.
+
+منتظر تأیید من بمان.
+
+---
+
+## بخش ۳ — TODO List (اجباری)
+
+بعد از تأیید ممیزی، با ابزار TodoWrite یک TODO بساز. قواعد:
+
+- ترتیب حتماً: **Backend → Frontend → i18n → تست → تطبیق بصری**
+  (فرانت را قبل از آماده شدن اندپوینت نساز.)
+- هر آیتم اتمیک و قابل تست باشد. آیتم مبهم مثل «صفحه را بساز» ممنوع.
+- هر آیتم TODO باید تست خودش را هم شامل شود، نه یک آیتم «تست» در آخر.
+- ساختار پیشنهادی:
+  1. [BE] مایگریشن/مدل X — + تست
+  2. [BE] توسعه‌ی اندپوینت Y (یا ساخت جدید، اگر توجیه شد) — + integration test
+  3. [FE] service/hook برای فراخوانی Y — + unit test
+  4. [FE] کامپوننت A (presentational) — + تست رندر
+  5. [FE] کامپوننت B (تعاملی) — + تست تعامل
+  6. [FE] مونتاژ صفحه و روت
+  7. [i18n] کلیدهای متنی فارسی
+  8. [QA] اجرای کل تست‌ها
+  9. [QA] مقایسه با اسکرین‌شات فیگما و اصلاح اختلاف‌ها
+
+TODO را قبل از شروع نشانم بده.
+
+---
+
+## بخش ۴ — اجرا، مرحله به مرحله
+
+- **همیشه فقط یک آیتم in_progress باشد.** موازی‌کاری ممنوع.
+- ترتیب TODO را رعایت کن؛ از روی آیتم‌ها نپر.
+- بعد از هر آیتم: تستش را اجرا کن. **آیتم بدون تست سبز، completed علامت نمی‌خورد.**
+- بعد از هر آیتم یک خط فارسی گزارش بده: چه ساختی، کدام فایل، تست سبز شد یا نه.
+- اگر وسط کار به چیزی برخوردی که در ممیزی ندیده بودی (اندپوینت پنهان، کامپوننت
+  مشابه، تضاد با SOLID) → **توقف کن**، TODO را به‌روز کن، و از من تأیید بگیر.
+  خودسرانه scope را عوض نکن.
+- در آخر: خروجی را با اسکرین‌شات فیگما مقایسه کن، اختلاف‌ها را لیست و اصلاح کن،
+  و کل تست‌ها را یک بار دیگر اجرا کن.
+
+## قواعد الزامی — بدون استثنا
+
+### ۱. SOLID
+- SRP: هر کامپوننت/کلاس یک مسئولیت. کامپوننتی که هم fetch می‌کند هم رندر می‌کند
+  باید به hook/service + کامپوننت presentational شکسته شود.
+- OCP: رفتار جدید با prop/strategy، نه if/else تو در تو در کد موجود.
+- LSP: هر پیاده‌سازی جایگزین قرارداد اینترفیس را کامل رعایت کند.
+- ISP: props و اینترفیس بزرگ ممنوع؛ به قراردادهای کوچک بشکن.
+- DIP: UI و لایه‌ی بیزنس مستقیم به axios/fetch/ORM وابسته نشوند.
+اگر SOLID با ساختار فعلی تضاد داشت، توقف کن و بپرس؛ خودسرانه بازنویسی نکن.
+
+### ۲. API جدید — آخرین گزینه
+1. کل لایه‌ی routes/controllers را بگرد.
+2. اگر اندپوینتی با یک پارامتر یا فیلد اضافه کافی است → همان را
+   backward-compatible توسعه بده.
+3. فقط اگر هیچ اندپوینتی نبود، جدید بساز.
+در جدول تحلیل برای هر نیاز بنویس: «موجود X» / «توسعه‌ی X» / «جدید — چون این‌ها
+را بررسی کردم و کافی نبودند: [...]». بدون این توجیه، اندپوینت جدید نساز.
+
+### ۳. مستندسازی — دقیق و مختصر
+- هر تابع/کامپوننت عمومی: بلاک کوتاه (چه می‌کند، ورودی، خروجی، خطاها).
+- هر اندپوینت: متد، مسیر، payload، response، کدهای خطا — در همان فرمت
+  مستندات فعلی پروژه.
+- کامنت بدیهی ممنوع. «چرا» را بنویس، نه «چه».
+
+### ۴. تست — بدون تست کار تمام نیست
+- منطق بیزنس/سرویس/هوک: unit test با حالت موفق + خطا + مرزی.
+- اندپوینت جدید یا توسعه‌یافته: integration test.
+- کامپوننت تعاملی: تست رندر + تست تعامل.
+- از فریم‌ورک تست موجود پروژه استفاده کن.
+- تست‌ها را اجرا کن و خروجی سبز را نشان بده.