توسعه محلی Frontend وب

این راهنما برای Developer وب است. Backend باید روی http://127.0.0.1:8080 فعال باشد و Node/npm با نسخه ثبت‌شده Repository اجرا شوند.

راه‌اندازی

Copy-Item .env.example .env.local
npm ci
npm run dev

سپس http://localhost:3000 باز می‌شود. npm ci فقط Lockfile را مصرف می‌کند و تغییر ناخواسته Dependency Resolution ایجاد نمی‌کند.

Configuration

API_BASE_URL=http://127.0.0.1:8080
BACKEND_REQUEST_TIMEOUT_MS=5000

هر دو مقدار Server-only هستند. Prefix برابر NEXT_PUBLIC_ آن‌ها را وارد Client Bundle می‌کند و برای Secret یا Backend URL خصوصی مجاز نیست. Frontend Secret پایدار در Browser ندارد.

کنترل کیفیت

npm run typecheck
npm run lint
npm run test:coverage
npm audit --audit-level=high
$env:DEPLOYMENT_VERSION='local-verify'
npm run build

کنترل	هدف
Typecheck	جلوگیری از Drift Type و Import نامعتبر
Lint	قواعد Next.js، React و TanStack Query
Test Coverage	Behavior، Error و Boundaryهای فعلی
Audit	Advisoryهای High و Critical
Production Build	Server/Client Boundary، CSP و Standalone Output

Debug شبکه

• Liveness Frontend: http://localhost:3000/api/health/live
• Readiness Backend از BFF: http://localhost:3000/api/health/ready
• Health مستقیم Backend: http://127.0.0.1:8080/readyz

اگر Liveness موفق و Readiness ناموفق است، Next.js سالم ولی Backend یا Config اتصال آن در دسترس نیست. Timeout را برای پنهان‌کردن مشکل شبکه بی‌دلیل افزایش ندهید.

معیار پایان تغییر

• Loading، Empty، Error، Offline و Success مرتبط Test شده‌اند.
• Keyboard و Focus بررسی شده‌اند.
• داده Tenant قبلی پس از Switch باقی نمی‌ماند.
• Secret یا PII وارد Client Bundle، Log یا Snapshot نشده است.
• Typecheck، Lint، Test، Audit، Build و git diff --check موفق هستند.