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 نشود.

### معیار پذیرش

```bash
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 تحویل می‌شود. گزارش هر مرحله شامل فایل‌های تغییرکرده، تصمیم‌های معماری، فرمان‌های راستی‌آزمایی، ریسک‌های باقی‌مانده و مرحله بعد خواهد بود.