# نصب ClaimManager روی دامنه و cPanel

## علت مشکل تصویر

دامنه فهرست فایل‌های public_html را نشان می‌دهد، نه برنامه را. این پروژه TanStack Start / React / Nitro با سرور Node.js 24 و SQLite داخلی Node است. خروجی اجرایی `.output/server/index.mjs` است و صرف آپلود سورس، افزودن index.html یا تغییر php.ini سرور آن را اجرا نمی‌کند. پوشهٔ `public` یا `.output/public` به‌تنهایی نسخهٔ کامل قابل اجرا نیست.

این تحویل اصلاح مسیر راه‌اندازی و بسته‌بندی است، نه بازنویسی محصول یا تأیید آمادگی Enterprise. قابلیت‌های نسخهٔ قبلی حفظ شده‌اند.

## ۱. ابتدا انتشار سورس را متوقف کنید

- از فایل‌ها و هر دادهٔ واقعی نسخهٔ پشتیبان بگیرید؛ public_html را کورکورانه پاک نکنید.
- در cPanel گزینهٔ نمایش فایل‌های مخفی را فعال کنید. کلیدها، `.env`، دیتابیس و بکاپ نباید در Document Root عمومی باشند.
- تا تکمیل جابه‌جایی، از میزبان بخواهید Directory Listing و دسترسی عمومی به سورس را ببندد. فایل `deploy/emergency-lockdown.htaccess` نمونهٔ انسداد کامل موقت برای Apache 2.4 است؛ باید با تنظیمات موجود ادغام شود، ممکن است روی همهٔ میزبان‌ها مجاز نباشد، و پیش از فعال‌سازی سرویس باید قواعد انسداد آن برداشته شود. این فایل راه‌انداز Node نیست.
- اگر قبلاً فایل حاوی کلید یا گذرواژه در مسیر عمومی بوده است، آن اعتبارنامه‌ها را عوض کنید. خاموش کردن فهرست پوشه به‌تنهایی مانع دسترسی مستقیم به فایل‌های شناخته‌شده نمی‌شود.

## ۲. قابلیت هاست را بررسی کنید

وجود cPanel به‌تنهایی کافی نیست. میزبان باید تمام موارد زیر را فراهم کند:

1. Node.js **24.x** همراه ماژول `node:sqlite`؛ نسخه‌های 18، 20 و 22 با این بسته پشتیبانی نمی‌شوند.
2. اجرای دائمی برنامه، راه‌اندازی مجدد و reverse proxy دامنه به برنامه؛ مثلاً Passenger سازگار یا Application Manager.
3. مسیر خصوصی قابل نوشتن و پایدار برای SQLite/WAL و اسناد؛ نه پوشهٔ عمومی و نه فضای موقت.
4. HTTPS معتبر و اجازهٔ استفاده از SQLite روی فایل‌سیستم محلی.

برای ارسال به پشتیبانی:

«برنامهٔ من Node.js 24، Nitro node-server، پورت TCP و ماژول داخلی node:sqlite لازم دارد. آیا امکان اجرای دائمی آن از پوشه‌ای خارج از public_html، با startup file برابر app.cjs و reverse proxy دامنه و HTTPS وجود دارد؟ آیا SQLite/WAL روی فضای پایدار محلی مجاز است؟»

اگر پاسخ منفی است: VPS یا میزبانی Node سازگار لازم است. با .htaccess، PHP یا آپلود ZIP نمی‌توان این محدودیت را برطرف کرد. سازگاری Passenger هر میزبان باید توسط همان میزبان تأیید و روی هاست آزموده شود.

## ۳. نصب با Setup Node.js App / Application Manager

نام فیلدها در پنل‌های مختلف متفاوت است:

- ZIP را خارج از public_html، مثلاً داخل `~/apps/`، Extract کنید.
- مسیر واقعی برنامه باید به پوشه‌ای برسد که **app.cjs** و **.output** داخل آن هستند، نه پوشهٔ والد آن‌ها.
- Node version: **24.x**
- Mode: **Production**
- Application root: مثلاً `apps/ClaimManager_v2`، نسبت به home حساب؛ مسیر واقعی را از File Manager بردارید.
- Application URL: دامنهٔ انتخاب‌شده در ریشهٔ `/`؛ نصب زیرمسیر در این تحویل آزموده نشده است.
- Startup file: **app.cjs**. اگر پنل این نام را نمی‌پذیرد یا اجرای CommonJS را محدود کرده، پیش از تغییر فایل‌ها از پشتیبانی روش سازگار را بپرسید.
- در `.env` خصوصی یا بخش Environment Variables، مقادیر زیر را تنظیم کنید. متغیرهای محیطی پنل بر فایل `.env` تقدم دارند؛ مقادیر متناقض تعریف نکنید.

```dotenv
NODE_ENV=production
APP_ORIGIN=https://claimanagerapp.ir
COOKIE_SECURE=true
ADMIN_EMAIL=YOUR_REAL_ADMIN_EMAIL
ADMIN_PASSWORD=YOUR_UNIQUE_LONG_PASSWORD
```

- APP_ORIGIN باید دقیقاً origin نهایی مرورگر باشد؛ اگر از www استفاده می‌کنید همان را ثبت کنید. تمام درخواست‌های HTTP را در وب‌سرور به HTTPS هدایت کنید.
- ADMIN_PASSWORD باید تصادفی، یکتا و حداقل ۱۲ نویسه باشد. مقادیر نمونه را عیناً استفاده نکنید و گذرواژه را در چت نفرستید.
- DATA_DIR را به مسیر **مطلق خصوصی و قابل نوشتن** اختصاص دهید. مثال: `/home/YOUR_CPANEL_USER/claimmanager-data`؛ نام حساب واقعی را جایگزین کنید.
- REPORTS_DIR و RAW_DIR و PROCESSED_DIR را نیز داخل همین مسیر خصوصی قرار دهید، به‌ترتیب در `markdown`، `ingest/raw` و `ingest/processed`.
- HOST/PORT را مطابق پشتیبانی میزبان تنظیم کنید. راه‌انداز در نبود مقدار از `127.0.0.1:3000` استفاده می‌کند؛ آن را خودسرانه جایگزین PORT تزریق‌شدهٔ پنل نکنید. این خروجی Nitro پورت TCP عددی می‌خواهد و اجرای آن با socket-path در PORT پشتیبانی نمی‌شود.
- پوشهٔ `.output` مخفی است؛ حتماً پس از Extract وجود آن را بررسی کنید. وابستگی‌های اجرای اصلی در آن bundle شده‌اند؛ برای اجرای خروجی آماده نیاز به npm install نیست. برای تغییر سورس/ساخت مجدد، بخش توسعه را ببینید.
- برنامه را Start/Restart کنید. لاگ باید بررسی‌های PASS را نشان دهد. FAIL را رفع کنید؛ با غیرفعال‌کردن کنترل امنیتی از آن عبور نکنید.
- `/readyz` را باز کنید؛ باید `status: ready` بدهد. `/healthz` فقط زنده‌بودن فرایند را نشان می‌دهد و به‌تنهایی کافی نیست.
- صفحهٔ `/auth/login` و سپس `/workspace` را باز کنید. یک پروژهٔ آزمایشی، سند و گزارش بسازید؛ برنامه را Restart کنید و ماندگاری را بررسی کنید.
- پس از ساخته‌شدن مدیر اولیه، ADMIN_PASSWORD را از تنظیمات دائمی حذف کنید و Restart کنید؛ حساب از دیتابیس خوانده می‌شود. حذف DATA_DIR حساب‌ها و اسناد را از بین می‌برد.

اگر همچنان Index of / دیده می‌شود، reverse proxy دامنه به برنامه وصل نشده یا Application URL اشتباه است. اگر 503 است، لاگ Node و وضعیت preflight را بررسی کنید. اگر ورود 403 می‌دهد، origin و دامنه/HTTPS را کنترل کنید. اگر پس از ورود دوباره به صفحهٔ ورود می‌روید، HTTPS، کوکی Secure و دامنه را بررسی کنید.

## ۴. مسیر VPS با reverse proxy

Node.js 24 را به‌صورت سیستمی نصب و یک کاربر سرویس کم‌دسترسی ایجاد کنید. سورس را خارج از ریشهٔ Nginx/Apache، مثلاً در `/opt/claimmanager` قرار دهید.

```bash
cd /opt/claimmanager
cp .env.example .env
chmod 600 .env
# فایل .env را با اطلاعات واقعی و مسیر خصوصی داده تکمیل کنید.
node --env-file=.env scripts/doctor.mjs
node app.cjs
```

- پس از تست دستی، از `deploy/claimmanager.service` برای اجرای دائمی استفاده کنید. User/Group و WorkingDirectory و ExecStart و مسیر قابل نوشتن باید با سرور واقعی شما منطبق باشند.
- ExecStart نمونه `/usr/bin/node` است؛ مسیر Node 24 واقعی را کنترل کنید. با ProtectHome=true، نصب Node زیر home/nvm در دسترس سرویس نخواهد بود.
- `deploy/nginx.conf` قطعهٔ تنظیمات برای افزودن داخل server block دارای TLS است، نه کانفیگ کامل nginx. گواهی و انتقال HTTP به HTTPS باید جداگانه تنظیم شوند.
- پورت Node را عمومی نکنید؛ Nginx/Apache به `127.0.0.1:3000` متصل شود. فقط پورت‌های لازم مانند 443 را باز کنید.
- اجرای Docker نیز فایل‌های قبلی Dockerfile و compose.yaml را دارد، ولی build کانتینر و نصب روی VPS واقعی در این بررسی انجام نشده‌اند.

## ۵. توسعه و ساخت مجدد

روی دستگاه دارای Node 24 و اینترنت، از داخل پوشهٔ سورس:

```bash
npm ci
npm run check:all
npm run lint
npm run build
npm run test:deployment
```

`node_modules` عمداً داخل ZIP نیست؛ package-lock.json برای نصب تکرارپذیر موجود است. برای اجرای معمولی خروجی ساخته‌شده از `node app.cjs` یا `npm start` استفاده کنید، نه npm run dev و نه vite preview.

## ۶. بکاپ و بازیابی

```bash
node --env-file=.env scripts/backup.mjs /PATH/TO/PRIVATE/BACKUPS
```

بکاپ اسکریپت فقط snapshot دیتابیس SQLite است. فایل‌های جانبی اسناد و گزارش‌ها، تنظیمات و اسرار باید با سیاست جداگانه پشتیبان‌گیری شوند. نسخهٔ رمزگذاری‌شده خارج از همین هاست نگه دارید و زمان‌بندی و retention را خودتان تنظیم کنید. برای بازیابی، ابتدا سرویس را متوقف کنید، از دادهٔ فعلی snapshot بگیرید، integrity بکاپ را کنترل و فایل‌ها را در مسیر خصوصی با مالکیت صحیح برگردانید؛ فایل‌های WAL/SHM قبلی را بدون برنامهٔ بازیابی با دیتابیس جایگزین مخلوط نکنید. تمرین بازیابی واقعی روی یک محیط جداگانه الزامی است.

## محدودیت مهم

این نرم‌افزار همان پایلوت تک‌سازمانی است. وجود نام Enterprise در نام بسته به معنای SSO/MFA، جداسازی چندسازمانی، HA، لاگ ضد دستکاری، ممیزی مستقل امنیتی یا ظرفیت بار اثبات‌شده نیست. فعال‌سازی مدل ابری/محلی و OCR واقعی به تنظیمات و آزمون مستقل نیاز دارد. نتایج حقوقی/مالی باید توسط متخصص بازبینی شوند. هیچ کلید یا حساب واقعی در این بسته قرار ندارد.