# راهنمای نصب محلی

## پیش‌نیازها

- Node.js نسخهٔ 24 یا جدیدتر و pnpm 10.
- Windows 10/11 با PowerShell یا Linux جدید.
- برای حالت سبک توسعه PostgreSQL لازم نیست؛ PGlite داده را در `storage/pglite` نگه می‌دارد.
- Redis در توسعه اختیاری است؛ در production اجباری است.

## Windows PowerShell

```powershell
Copy-Item .env.example .env
pnpm install
pnpm migrate
pnpm seed
pnpm dev
```

## Linux/macOS

```bash
cp .env.example .env
pnpm install
pnpm migrate
pnpm seed
pnpm dev
```

در `.env` توسعه این مقادیر مناسب‌اند:

```dotenv
NODE_ENV=development
DATABASE_DRIVER=pglite
PGLITE_DATA_DIR=storage/pglite
REDIS_REQUIRED=false
SECURE_COOKIES=false
SEED_DEMO_USERS=true
```

برای کلیدهای توسعه نیز رشته‌های تصادفی حداقل ۳۲ کاراکتری تعیین کنید. فایل `.env` را commit نکنید.

## ایجاد حساب مدیر

اگر `seed` حساب نمونه ساخته باشد، رمز فقط در همان اجرای اول چاپ می‌شود. برای یک مدیر جدید:

```bash
pnpm bootstrap:admin -- admin "مدیر سامانه"
```

نام کاربری، رمز موقت یک‌بارنمایش و اجبار تغییر رمز ایجاد می‌شود. در محیط توسعه، reset اضطراری یک حساب موجود با فرمان زیر ممکن است؛ این فرمان در production عمداً غیرفعال است:

```bash
pnpm dev:credentials -- admin
```

## build و اجرای مشابه production

```bash
pnpm build
pnpm start
```

فرایندهای پس‌زمینه در دو terminal جدا:

```bash
pnpm worker
pnpm scheduler
```

## تست‌ها

```bash
pnpm lint
pnpm typecheck
pnpm test
pnpm exec playwright install chromium
pnpm test:e2e
```

پایگاه E2E از پایگاه توسعه جداست. در صورت نیاز می‌توانید پوشهٔ `storage/e2e-pglite` را فقط وقتی هیچ تستی فعال نیست حذف کنید.

## عیب‌یابی اولیه

- `health/live` فقط زنده‌بودن process را نشان می‌دهد؛ `health/ready` اتصال پایگاه را هم بررسی می‌کند.
- اگر Redis در توسعه در دسترس نباشد، هشدار ثبت می‌شود و session حافظه‌ای/بلادرنگ تک‌نمونه فعال می‌ماند.
- خطای تولید دربارهٔ `SECURE_COOKIES` یا `REDIS_REQUIRED` intentional است؛ تنظیم ناامن در production پذیرفته نمی‌شود.
- اگر login پس از تغییر دامنه loop شد، `APP_URL`، HTTPS، `TRUST_PROXY=1` و header `X-Forwarded-Proto` را بررسی کنید.