docs: document React architecture and enforce migration checks in CI

2026-10-28 12:53:12 +03:30
parent 55d4123fe5
commit fbfa8d011d
16 changed files with 762 additions and 45 deletions
@@ -0,0 +1,48 @@
+# قرارداد تحویل تسک به Agent
+
+## متن شروع پیشنهادی
+
+> ابتدا docs/README.md و سندهای مرتبط با این تسک را بخوان. سپس کد فعلی و git status را بررسی کن؛ مستندات snapshot هستند و ممکن است پس از commit مبنا تغییر کرده باشند. رفتار فعلی، تصمیم محصول و پیشنهادهای آینده را یکی نگیر. فقط محدودهٔ این تسک را پیاده کن و مدارک تست، محدودیت و مستندات به‌روز را تحویل بده.
+
+## قالب آمادهٔ تسک
+
+```text
+عنوان:
+هدف کاربر و مسئله:
+مراجع docs و شناسهٔ بک‌لاگ:
+رفتار فعلی و مراحل بازتولید:
+رفتار مطلوب (تصمیم صاحب بازی):
+دامنهٔ تغییر / فایل‌های احتمالی:
+خارج از دامنه:
+قواعدی که باید حفظ شوند:
+معیار پذیرش قابل مشاهده:
+سناریوهای خطا و مرزها:
+تست خودکار مرتبط:
+تست دستی desktop/mobile/GPS/offline در صورت نیاز:
+نیاز به asset یا دادهٔ بیرونی:
+خروجی مورد انتظار (کد، سند، نتیجهٔ تست، تصویر در صورت نیاز):
+مجوز commit/push/deploy و remote مقصد، اگر خواسته شده:
+```
+
+## چک‌لیست Agent
+
+1. دستورهای AGENTS/RTK قابل اعمال و وضعیت تغییرات کاربر را بخوان؛ remote و branch را فرض نکن.
+2. منبع حقیقت تسک را مشخص کن: اقتصاد game-state/scoring؛ مکان locations؛ نمایش main/style؛ حسگر realworld/ar؛ انتشار workflow/compose.
+3. قبل از تغییر، تست مربوط و مسیر وابستگی را بفهم. برای bug ابتدا failing regression معنادار بساز؛ برای متن صرف تست تقلیدی نساز.
+4. تغییر را با دامنهٔ کوچک انجام بده. محاسبهٔ قیمت یا شرط مأموریت را در UI دوباره تعریف نکن.
+5. مقدار پول قبل/پس، busy، تراکنش یکتا، mode، timer و رفتار لغو را در تسک‌های مرتبط حفظ کن.
+6. تست مرتبط و build را اجرا کن؛ برای GPU/permissions/offline از تست Node نتیجهٔ بصری استنتاج نکن.
+7. سند مرتبط را هم اصلاح کن؛ قابلیت آینده را «انجام‌شده» علامت نزن مگر معیار پذیرش محقق شده باشد.
+8. نتیجه را با فایل‌ها، شواهد، ریسک/محدودیت و عملیات واقعاً انجام‌شده گزارش کن.
+
+## نمونهٔ تسک مستقل
+
+عنوان: بازیابی UI پس از بسته‌شدن دستگاه در مرحلهٔ پرداخت (R01).
+
+معیار پذیرش: در ۱۳:۲۹:۵۹ از مدرسه پرداخت را شروع کن، قبل swipe ساعت از ۱۳:۳۰ بگذرد؛ پول/خرید تغییر نکنند، پیام بسته‌بودن نمایش داده شود، پنل گیر نکند، کنترل حرکت برگردد و کاربر دستگاه دیگری انتخاب کند. لغو عادی و خرید موفق/برداشت یک‌باره همچنان پاس باشند. تغییر به حفظ ساعت پرداخت تنها با تصمیم صریح محصول انجام شود.
+
+این نمونه پیشنهاد است و اجرای آن با ساخت این سند مجاز/انجام‌شده تلقی نمی‌شود.
+
+## دستورهای مخزن و توصیف فناوری
+
+در پایان این بررسی یک فایل AGENTS.md با دستورهای عمومی React/Next.js در workspace دیده شد. آن فایل از تغییرات این نوبت نیست. Agent توسعه باید نسخهٔ حاضر آن را پیش از کار بخواند و دستورهای قابل اعمال را رعایت کند؛ توصیف فناوری در این اسناد گزارش وضعیت واقعی کد است، نه جایگزین AGENTS یا مجوز مهاجرت به React/Redux/Tailwind. انتخاب زبان/UI برای توسعهٔ بعدی و هر تعارض عملی باید در همان تسک روشن شود. برای این تسک مستندسازی، زبان برنامه و کتابخانهٔ رابط تغییر نکرده‌اند.