<div dir="rtl">

# راهنمای دیپلوی روی Liara

این پروژه دو سرویسِ مستقل دارد که جدا دیپلوی می‌شوند:

1. **بک‌اند (API + اسکرپرها)** → پلتفرم **Docker** لیارا (به‌خاطر Playwright/Chromium) + **دیسکِ پایدار** برای SQLite و گزارش‌ها.
2. **فرانت‌اند (TanStack Start)** → پلتفرم **Node** لیارا، یا کلودفلر (تارگتِ پیش‌فرضِ بیلد).
3. **پنل ادمین (`:8001`)** → عمومی نکن؛ فقط لوکال/SSH/VPN.

> قبل از شروع: `npm i -g @liara/cli` و `liara login`.

---

## گام ۱ — بک‌اند روی Liara (Docker)

آرتیفکت‌ها از قبل ساخته شده‌اند: `backend/Dockerfile`، `backend/requirements.txt`، `backend/liara.json`.

```powershell
# ۱) ساخت برنامه (یک‌بار) — پلتفرم docker
liara app:create --name didvan-api --platform docker

# ۲) ساخت دیسکِ پایدار برای دیتابیس + گزارش‌ها (روی /data مونت می‌شود)
liara disk:create --app didvan-api --name data --size 5   # گیگابایت دلخواه

# ۳) تنظیم متغیرهای محیطی (حتماً قبل از دیپلوی)
liara env:set --app didvan-api `
  DB_PATH=/data/asianmetal.db `
  REPORTS_DIR=/data/reports `
  ADMIN_PASSWORD=یک‌رمزِ‌خیلی‌قوی `
  ASIANMETAL_TOKEN=توکنِ‌تازهٔ‌منبع `
  ALLOWED_ORIGINS=https://didvan.example.com `
  COOKIE_SECURE=1 `
  COOKIE_SAMESITE=none

# ۴) دیپلوی از داخل پوشهٔ backend
cd backend
liara deploy --app didvan-api --port 8000
```

نکته‌ها:
- `liara.json` داخلِ `backend/` پلتفرم/پورت/دیسک را تعریف کرده؛ پس `liara deploy` را از همان پوشه بزن.
- Chromium در خودِ image نصب می‌شود (`playwright install --with-deps chromium`) → بیلدِ اول کند است. پلنِ حداقل **۱GB RAM**.
- بعد از دیپلوی، آدرسِ بک‌اند مثلاً می‌شود `https://didvan-api.liara.run`.

### آپلودِ آرشیو گزارش‌ها (PDFها)
گزارش‌ها (~۵۰۰۰ فایل) باید روی دیسک باشند. بعد از اولین دیپلوی، از پنل لیارا (بخش دیسک/فایل‌منیجر) یا با ابزارِ لیارا فایل‌ها را در `/data/reports` بریز، با همان ساختار `<منبع> - <دسته>/<file>.pdf`. اگر حجم زیاد است، گزینهٔ بهترْ **آبجکت‌استوریجِ S3‌ای لیارا** است (نیازمندِ تغییر `reports.py` برای خواندن از S3).

---

## گام ۲ — فرانت‌اند

فرانت با URLِ بک‌اند کار می‌کند؛ متغیرِ بیلد را ست کن:

```
VITE_API_BASE=https://didvan-api.liara.run
```

(در حالت dev این خالی می‌ماند و از پراکسیِ Vite استفاده می‌شود — چیزی خراب نمی‌شود.)

پروژه برای لیارا تنظیم شده تا خروجیِ **سرورِ Node** بدهد (در `vite.config.ts` ⇠ `nitro: { preset: "node-server" }`). بیلد، `.output/server/index.mjs` می‌سازد و اسکریپتِ `start` (در `package.json`) آن را اجرا می‌کند. کانفیگ در `liara.json`ِ ریشه (پلتفرم node، پورت 3000) است.

```powershell
# از ریشهٔ پروژه
liara app:create --name didvan --platform node
liara env:set --app didvan VITE_API_BASE=https://didvan-api.liara.run
liara deploy --app didvan
```

لیارا هنگام دیپلوی `npm install` → `npm run build` → `npm start` (یعنی `node .output/server/index.mjs`) را اجرا می‌کند؛ سرورِ Nitro روی متغیرِ `PORT` که لیارا می‌دهد گوش می‌دهد. (تست‌شده: سرور بوت می‌شود و صفحات را سرو می‌کند.)

---

## گام ۳ — کوکیِ ورود (مهم)

ورود با **کوکیِ نشستِ httpOnly** کار می‌کند. بسته به اینکه فرانت و بک‌اند هم‌دامنه‌اند یا نه:

| حالت | تنظیمات بک‌اند |
|---|---|
| **هم‌دامنه** (توصیه‌شده) | `COOKIE_SAMESITE=lax` ، `COOKIE_SECURE=1` |
| **دامنهٔ جدا** (فرانت و API فرق دارند) | `COOKIE_SAMESITE=none` ، `COOKIE_SECURE=1` ، و `ALLOWED_ORIGINS=https://<دامنهٔ فرانت>` |

فرانت همهٔ درخواست‌های احراز را با `credentials:"include"` می‌زند (از قبل انجام شده). CORS هم با `allow_credentials=True` تنظیم شده.

---

## چک‌لیستِ قبل از انتشار

- [ ] توکنِ قدیمیِ منبعِ داده را **باطل** کن (در git history لو رفته) و مقدارِ تازه را در `ASIANMETAL_TOKEN` بگذار.
- [ ] `ADMIN_PASSWORD` قوی (بدونش پنل ادمین بالا نمی‌آید).
- [ ] `COOKIE_SECURE=1` روی HTTPS.
- [ ] `ALLOWED_ORIGINS` دقیقاً دامنهٔ فرانت (نه `*`).
- [ ] `DB_PATH` و `REPORTS_DIR` روی دیسکِ `/data`.
- [ ] پنل ادمین (`:8001`) عمومی نشود.
- [ ] `__pycache__` از گیت پاک شود: `git rm -r --cached backend/__pycache__`.
- [ ] (اختیاری ولی بهتر) مهاجرت SQLite → **PostgreSQLِ مدیریت‌شدهٔ لیارا** برای پایداری/مقیاس.

---

## یادآوریِ معماری
- اسکرپرها داخلِ پروسهٔ بک‌اند (FastAPI lifespan) اجرا می‌شوند؛ تا پروسه بالا باشد کار می‌کنند. ری‌استارت، کشِ حافظه را پاک می‌کند ولی از DB دوباره seed می‌شود.
- جزئیات کامل سیستم در `README.md`.

</div>