# سامانه تحویل کالای بازرگانی ماندگار

سامانه‌ای مستقل، فارسی و RTL برای مدیریت زنجیرهٔ «فاکتور مالی → تأیید مدیر تأمین → صف انبار → تحویل/لغو/برگشت/تحویل مجدد» با نگهداری نسخه‌های تغییرناپذیر، مغایرت، ممیزی و گزارش Excel.

## قابلیت‌های اصلی

- سه نقش پیش‌فرض: مدیر کل، مدیر تأمین و انباردار با RBAC ریزدانه.
- ثبت فاکتور دستی با یا بدون ردیف کالا و ورود امن فایل‌های `xlsx`/`xlsm` بدون اجرای ماکرو یا فرمول.
- نسخه‌بندی مالی تغییرناپذیر، تشخیص تغییر، مغایرت دستی/مالی و بیش‌تحویلی.
- تحویل کامل یا جزئی، جلوگیری تراکنشی از بیش‌تحویلی، کلید idempotency و رویدادهای append-only.
- صف بلادرنگ WebSocket، اعلان داخلی و Web Push اختیاری.
- تاریخ و بازهٔ جلالی با محاسبه در منطقهٔ زمانی `Asia/Tehran`.
- خروجی Excel چهاربخشی، RTL، فیلترپذیر و دارای رنگ وضعیت.
- ظاهر واکنش‌گرا، تم روشن/تیره، فونت Vazirmatn و هویت بصری ماندگار.
- PostgreSQL در production، Redis برای session/pub-sub، worker پایگاه‌داده‌ای و scheduler بازیابی job.

## پشته و معماری

این نسخه یک monolith ماژولار TypeScript روی Node.js 24 و Express 5 است. SSR با EJS، تعامل سبک با Alpine.js و Tailwind CSS 4 انجام می‌شود. پایگاه محلی PGlite است و همان SQL مهاجرت‌ها در PostgreSQL production اجرا می‌شود. جزئیات استقرار در [راهنمای استقرار](docs/DEPLOYMENT_FA.md) آمده است.

## اجرای سریع توسعه

پیش‌نیاز: Node.js 24 و pnpm 10.

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

رمز حساب‌های نمونه فقط یک بار هنگام `pnpm seed` نمایش داده می‌شود و در اولین ورود باید تغییر کند. برای ایجاد مدیر واقعی از این فرمان استفاده کنید:

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

نشانی پیش‌فرض: `http://localhost:3000`؛ سلامت: `/health/live` و `/health/ready`.

## کنترل کیفیت

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

آزمون E2E یک پایگاه مجزای `storage/e2e-pglite` می‌سازد و گردش واقعی هر سه نقش را اجرا می‌کند. اطلاعات سنجش تحویل در [VALIDATION_FA.md](docs/VALIDATION_FA.md) ثبت شده است.

## راهنماها

- [نصب محلی](docs/INSTALLATION_FA.md)
- [استقرار production، HTTPS، backup و rollback](docs/DEPLOYMENT_FA.md)
- [راهنمای کاربران و نقش‌ها](docs/USER_GUIDE_FA.md)
- [ورود فایل مالی](docs/EXCEL_IMPORT_FA.md)
- [ممیزی، پشتیبان‌گیری و بازیابی](docs/AUDIT_RECOVERY_FA.md)
- [نتیجهٔ اعتبارسنجی](docs/VALIDATION_FA.md)

## نکات امنیتی

ثبت‌نام عمومی وجود ندارد. رمزها با Argon2id ذخیره می‌شوند، session پس از ورود بازتولید و با تغییر/reset رمز ابطال می‌شود، CSRF و rate limit فعال است، cookie production امن و SameSite=Strict است، و CSP اجرای handlerهای inline را منع می‌کند. فایل‌های مالی به کمک magic bytes، پسوند، MIME، اندازه و checksum کنترل می‌شوند؛ فرمول‌ها پذیرفته نمی‌شوند و هیچ ماکرویی اجرا نمی‌شود.

## مجوز و مالکیت

این مخزن برای استفادهٔ داخلی بازرگانی ماندگار آماده شده است. پیش از انتشار عمومی، سیاست مجوز سازمان را به آن اضافه کنید.
