129 lines
8.3 KiB
Markdown
129 lines
8.3 KiB
Markdown
---
|
||
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 را عوض نکن.
|
||
- در آخر: خروجی را با اسکرینشات فیگما مقایسه کن، اختلافها را لیست و اصلاح کن،
|
||
و کل تستها را یک بار دیگر اجرا کن.
|
||
|
||
## بخش ۵ — بستن کار (به همین ترتیب)
|
||
|
||
1. **اول کدها را commit کن.** وقتی همهٔ تستها سبز شد، تغییرات را با یک پیام
|
||
انگلیسی معنادار commit کن (طبق Conventional Commits). قبل از graphify commit
|
||
کن، نه بعدش.
|
||
2. **بعد graphify را بهروز کن:** `graphify update .` — تا گراف با کد جدید همگام
|
||
شود. این مرحله فقط پس از commitِ موفق اجرا میشود.
|
||
|
||
### ۱. 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.
|
||
- کامپوننت تعاملی: تست رندر + تست تعامل.
|
||
- از فریمورک تست موجود پروژه استفاده کن.
|
||
- تستها را اجرا کن و خروجی سبز را نشان بده.
|