admin/PRODUCTION_READINESS_PLAN.md

برنامه آمادگی Production فرانت‌اند قبیله

این سند برنامه اجرایی رسیدن از وضعیت فعلی به انتشار عمومی مطمئن است. ترتیب مراحل الزام‌آور است: هر مرحله باید معیارهای پذیرش خود را پاس کند تا مرحله بعد آغاز شود.

تعریف Done نهایی

نسخه زمانی Production-ready محسوب می‌شود که:

• pipeline استاندارد و Docker build روی checkout تمیز، تکرارپذیر و کاملاً سبز باشد.
• lint هیچ error یا warning نداشته باشد.
• مسیرهای auth، booking، payment و authorization تست E2E پایدار داشته باشند.
• refresh token در JavaScript و localStorage قابل دسترس نباشد.
• کنترل‌های XSS، CSRF، CSP و upload در فرانت و بک‌اند تأیید شده باشند.
• accessibility، Core Web Vitals و مرورگرهای هدف از budgetهای تعریف‌شده عبور نکنند.
• خطاها و شاخص‌های عملیاتی قابل مشاهده باشند و rollback آزمایش شده باشد.
• smoke test محیط staging و production به‌صورت خودکار اجرا شود.

۱. تثبیت pipeline و کیفیت پایه — Release blocker

هدف

یک فرمان واحد باید تمام قرارداد API، typeها، lint، تست و production build را بدون وابستگی به state محلی بررسی کند.

کارها

1. رفع خطای TypeScript تولید OpenAPI در booking service بک‌اند.
2. یکسان‌سازی فرمان‌های:
   • generate:api
   • typecheck
   • lint
   • test
   • build
   • check
3. رفع تمام warningهای ESLint و فعال کردن مجدد --max-warnings 0.
4. تعیین سیاست روشن برای کد generated و جلوگیری از lint دستی آن.
5. ثابت کردن نسخه Node و pnpm در local، Docker و CI.
6. افزودن CI با cache کنترل‌شده و اجرای build روی checkout تمیز.
7. افزودن کنترل تغییر OpenAPI تا generated client قدیمی merge نشود.

معیار پذیرش

pnpm install --frozen-lockfile
pnpm check
pnpm build

هر سه فرمان باید با exit code صفر اجرا شوند و working tree پس از build تغییر نکند.

۲. تست مسیرهای حیاتی — Release blocker

هدف

شکست flowهای مالی و session پیش از deploy شناسایی شود.

کارها

1. unit test برای route policy، response normalization، validation و error mapping.
2. component test برای فرم‌های OTP، booking CTA، payment state و modalهای حساس.
3. راه‌اندازی Playwright با fixture و data factory ایزوله.
4. E2E سناریوهای:
   • درخواست OTP، ورود، تکمیل پروفایل و logout
   • refresh موفق، refresh هم‌زمان و session منقضی
   • دسترسی guest/user/admin به routeها
   • ایجاد، ویرایش و انتشار رویداد
   • رزرو، جلوگیری از double-submit و انقضای رزرو
   • پرداخت موفق، ناموفق، callback و retry
   • لغو، refund و waitlist
   • chat، notification و unread count
5. اجرای تست‌ها در CI با artifact شامل trace و screenshot شکست.

معیار پذیرش

• تمام تست‌های مسیر بحرانی پایدار و مستقل باشند.
• تست flaky پذیرفته نیست؛ retry نباید خطای واقعی را مخفی کند.
• coverage منطق حساس حداقل ۸۰٪ branch باشد؛ برای JSX عدد سراسری تحمیل نمی‌شود.

۳. سخت‌سازی امنیت — Release blocker

هدف

کاهش ریسک سرقت session، XSS، CSRF و upload مخرب.

کارها

1. انتقال refresh token به cookie با HttpOnly، Secure و SameSite مناسب.
2. حذف refresh token از localStorage و کد client.
3. rotation و reuse detection در بک‌اند و revoke واقعی session هنگام logout.
4. تعیین مدل CSRF و پیاده‌سازی token/origin validation متناسب با cookie auth.
5. تعریف CSP سازگار با API، WebSocket، map، image و file server.
6. افزودن HSTS، Referrer-Policy، Permissions-Policy، nosniff و frame-ancestors.
7. sanitize قطعی HTML تولیدشده توسط editor در مرز backend.
8. اعتبارسنجی server-side نوع، حجم، extension و محتوای upload.
9. dependency audit، secret scan و جلوگیری از log شدن OTP/token/PII.

معیار پذیرش

• refresh token از DevTools JavaScript قابل خواندن نباشد.
• تست‌های session rotation، CSRF و XSS پاس شوند.
• security headers روی پاسخ production تأیید شوند.
• یافته Critical/High باز در ممیزی امنیتی وجود نداشته باشد.

۴. refactor معماری و DRY

هدف

کاهش coupling و امکان تغییر featureها بدون regression گسترده.

کارها

1. شکستن PaginatedList به:
   • query/state hook
   • table renderer
   • filter controls
   • pagination
   • export action
2. شکستن Input به کنترل‌های typed مجزا و API ترکیبی مشترک.
3. انتقال business logic از pageها به feature hook/service.
4. حذف تبدیل‌های تکراری response و type assertionهای ناامن.
5. تعریف الگوی واحد data fetching شامل cache، retry، abort و invalidation.
6. محدود کردن Contextهای global و انتقال providerها به نزدیک‌ترین layout مصرف‌کننده.
7. انتقال محتوای غیرتعاملی و public fetching به Server Component.

معیار پذیرش

• رفتار قبلی با component/E2E test حفظ شود.
• فایل‌های feature عادی ترجیحاً زیر ۳۰۰ خط باشند.
• cycle در import graph و duplicate business rule وجود نداشته باشد.

۵. error handling، accessibility و UX مرزی

هدف

کاربر در خطا، کندی شبکه، keyboard navigation و deviceهای مختلف مسیر قابل فهم داشته باشد.

کارها

1. مدل خطای واحد برای validation، network، auth، permission و server.
2. error boundary سطح route و feature با retry و request ID.
3. حالت‌های loading، skeleton، empty، offline، timeout و retry برای تمام صفحات.
4. جلوگیری از double-submit و تعریف optimistic update فقط در عملیات امن.
5. حفظ filter/page هنگام back navigation.
6. keyboard navigation، focus trap/restore، label، description و live region.
7. بررسی contrast، reduced motion، zoom و screen reader.
8. اجرای axe در component و E2E test.

معیار پذیرش

• axe در مسیرهای اصلی violation بحرانی/جدی نداشته باشد.
• تمام flowهای اصلی فقط با keyboard قابل انجام باشند.
• هر درخواست async حالت loading، error و retry مشخص داشته باشد.

۶. performance و مرزبندی Next.js

هدف

کاهش JavaScript سمت client و دستیابی پایدار به Core Web Vitals مناسب.

کارها

1. تحلیل bundle و تعیین budget برای routeهای اصلی.
2. dynamic import برای editor، map، chart، QR و کتابخانه‌های سنگین.
3. استفاده درست از next/image و تعیین sizes/priority.
4. کاهش client boundary و providerهای root.
5. cache/revalidation صحیح صفحات عمومی SEO.
6. حذف hydration و renderهای غیرضروری.
7. ثبت Web Vitals واقعی و اصلاح براساس داده production.

معیار پذیرش

• p75 موبایل: LCP ≤ 2.5s، INP ≤ 200ms و CLS ≤ 0.1.
• budget تعریف‌شده bundle در CI enforce شود.
• route عمومی بدون نیاز، client-side data fetching نداشته باشد.

۷. عملیات Production و PWA

هدف

انتشار قابل مشاهده، قابل rollback و قابل پشتیبانی باشد.

کارها

1. Docker image کوچک، reproducible و non-root با health check.
2. جداسازی config و secret محیط‌های dev/staging/production.
3. error monitoring با source map خصوصی و release tag.
4. داشبورد Web Vitals، خطاهای API/WebSocket و نرخ شکست login/payment.
5. alert با threshold و runbook مشخص.
6. smoke test خودکار پس از deploy.
7. canary یا rollout تدریجی و rollback آزمایش‌شده.
8. سیاست cache Service Worker؛ عدم cache داده خصوصی.
9. update flow نسخه PWA، offline fallback و تست push روی device واقعی.

معیار پذیرش

• deploy و rollback در staging عملاً تمرین شده باشند.
• خطای عمدی client با release و source map در monitoring دیده شود.
• smoke test پس از deploy خودکار و blocking باشد.

۸. ممیزی نهایی و Release gate

کارها

1. تست Chrome، Firefox، Safari و مرورگر Android هدف.
2. تست موبایل واقعی روی شبکه کند و قطع/وصل شبکه.
3. load test flowهای auth، discovery، booking و payment callback.
4. ممیزی امنیتی و accessibility مستقل.
5. اجرای restore/rollback drill.
6. انتشار محدود beta و بررسی telemetry قبل از rollout کامل.

معیار پذیرش

• هیچ issue با شدت Critical یا High باز نباشد.
• issueهای Medium پذیرفته‌شده owner و deadline داشته باشند.
• Product، Engineering و Operations چک‌لیست release را تأیید کنند.

ترتیب تحویل

هر مرحله در یک تغییر قابل review تحویل می‌شود. گزارش هر مرحله شامل فایل‌های تغییرکرده، تصمیم‌های معماری، فرمان‌های راستی‌آزمایی، ریسک‌های باقی‌مانده و مرحله بعد خواهد بود.