ERP/README.md

# ERP & PM Integrated Platform — Dockerized
## سامانه یکپارچه تدارکات، انبارداری، مدیریت پروژه (PM) و ربات هوشمند

مجموعه نرم‌افزاری یکپارچه و خودکفا (Self-contained) شامل تمامی سرویس‌ها، ماژول‌ها و تنظیمات زیرساختی مورد نیاز برای اجرا در محیط توسعه و عملیات:

| سرویس | نام کانتینر | فناوری / کاربرد | پورت در دسترس |
|---|---|---|---|
| **postgres** | `procurement-postgres` | PostgreSQL 18 (دیتابیس مشترک `procurement` + `casdoor`) | `5455:5432` |
| **minio** | `procurement-minio` | MinIO Object Storage (S3-compatible) برای فایل‌ها و پیش‌فاکتورها | `9000` (API), `9001` (کنسول) |
| **casdoor** | `procurement-casdoor` | ارائه‌دهنده متمرکز هویت سازمانی (OIDC Provider) | `8080:8000` |
| **api** | `procurement-api` | بک‌اند اصلی تدارکات و انبار (FastAPI + Asyncpg) | `8000:8000` |
| **frontend** | `procurement-frontend` | فرانت‌اند وب ERP (React 19 + Vite + Tailwind) | سرو از طریق Traefik روی پورت `80` |
| **pm-api** | `pm-api` | بک‌اند بومی مدیریت پروژه ساخت (FastAPI + Python 3.12) | درون‌شبکه‌ای (زیرمسیر `/pm/api`) |
| **pm-frontend** | `pm-frontend` | فرانت‌اند پلتفرم PM (React 19 + تقویم شمسی + گانت + QC) | سرو از طریق Traefik روی `/pm` |
| **bot** | `procurement-bot` | ربات هوشمند بله با پردازش صوت و متن (DeepSeek LLM + STT) | ارتباط Long-polling با Bale |
| **db-backup** | `procurement-db-backup` | پشتیبان‌گیری خودکار زمان‌بندی‌شده از هر دو پایگاه داده | کانتینر دوره‌ای در پس‌زمینه |
| **traefik** | `procurement-traefik` | ریورس پروکسی و مدیریت ترافیک لایه لبه (Traefik v3) | `80` (HTTP), `443` (HTTPS) |

---

## 🌐 معماری شبکه و هدایت ترافیک (Traefik Edge Routing)

```text
                                  ┌────────────────────────┐
                                  │   Browser / Client     │
                                  └───────────┬────────────┘
                                              │ :80 / :443
                                              ▼
                                  ┌────────────────────────┐
                                  │    Traefik v3 (Edge)   │
                                  └───────────┬────────────┘
                                              │
         ┌────────────────────────────────────┼───────────────────────────────────┐
         │                                    │                                   │
         ▼ (Host: localhost)                  ▼ (PathPrefix: /pm)                 ▼ (Host: api.localhost)
┌───────────────────────┐            ┌───────────────────────┐           ┌───────────────────────┐
│   frontend (React)    │            │ pm-frontend / pm-api  │           │   api (FastAPI Core)  │
│  /api/* Proxy ───────┼────────────┼───────────────────────┼──────────►│  /api/v1/*            │
└───────────────────────┘            └───────────────────────┘           └───────────┬───────────┘
         │                                                                           │
         ├────────────────────────────────────┬──────────────────────────────────────┤
         ▼                                    ▼                                      ▼
┌───────────────────────┐            ┌───────────────────────┐           ┌───────────────────────┐
│  Casdoor OIDC (:8080) │            │   MinIO S3 (:9000)    │           │ PostgreSQL 18 (:5455) │
│  Host: auth.localhost │            │ Host: s3 / storage    │           │ procurement + casdoor │
└───────────────────────┘            └───────────────────────┘           └───────────────────────┘
                                              ▲
                                              │ ثبت پیش‌نویس استعلام
                                     ┌────────┴──────────────┐
                                     │ bot (Bale AI Agent)   │
                                     └───────────────────────┘
```

---

## 📁 ساختار پوشه‌ها و اجزای مخزن

```text
ERP/
├── docker-compose.yml          ← پیکربندی اصلی اجرای کامل تمام سرویس‌های استک
├── docker-compose.prod.yml     ← لایه تنظیمات عملیاتی (Let's Encrypt و دامنه‌های رسمی)
├── docker-compose.coolify.yml  ← پیکربندی سازگار با استقرار بر روی Coolify
├── start.ps1                   ← اسکریپت هلپر پاورشل برای ساخت و اجرا
├── mc.cmd                      ← ابزار خط فرمان MinIO Client برای مدیریت باکت‌ها
├── README.md                   ← همین سند راهنما
├── backend/                    ← سرویس بک‌اند اصلی تدارکات و انبار (procurement-api)
│   ├── app/
│   │   ├── db/                 ← اتصال دیتابیس و توابع راه‌اندازی اسکیمای خودکار (init_db.py)
│   │   ├── models/             ← مدل‌های پایگاه‌داده (procurement, inventory, catalog)
│   │   ├── routers/            ← اندپوینت‌های API v1 (quotes, inventory, users, drafts, ...)
│   │   ├── schemas/            ← مدل‌های اعتبارسنجی Pydantic
│   │   ├── services/           ← منطق بیزینس (انبارداری، استعلام‌ها، ذخیره‌سازی، ...)
│   │   ├── utils/              ← ابزارهای امنیتی، خطایابی، ریت‌لیمیت
│   │   ├── auth.py             ← تایید توکن Casdoor و تفکیک دسترسی‌ها
│   │   ├── config.py           ← متغیرهای پیکربندی
│   │   └── main.py             ← اسمبلی برنامه FastAPI و میدل‌ورها
│   └── tools/                  ← اسکریپت‌های سیدینگ (seed_casdoor.py) و تست‌های دود (Smoke)
├── frontend/                   ← وب‌اپلیکیشن اصلی ERP (procurement-frontend)
│   ├── src/
│   │   ├── components/         ← کامپوننت‌های مشترک، لایه‌بندی و سوییچر پنل‌ها
│   │   ├── pages/
│   │   │   ├── Admin/          ← پنل مدیریت سامانه و همگام‌سازی کاربران
│   │   │   ├── Auth/           ← صفحه ورود و احراز هویت
│   │   │   ├── Dashboard/      ← کارتابل استعلام‌ها و تصمیم‌گیری خرید
│   │   │   ├── Inventory/      ← انبارداری (موجودی، ورود کالا، انتقال کارگاهی، کنترل روزانه)
│   │   │   ├── Organization/   ← ماتریس دسترسی پنل‌ها و انتساب پروژه‌ها
│   │   │   ├── Projects/       ← مدیریت پروژه‌های عمرانی
│   │   │   ├── Suppliers/      ← دسته‌بندی موضوعی و فهرست تأمین‌کنندگان
│   │   │   ├── Units/          ← سیستم کاتالوگ متریال‌ها، تامین‌کنندگان و ضرایب تبدیل
│   │   │   └── Wizard/         ← ویزارد مرحله‌ای ثبت استعلام (با اتصال مستقیم به پیش‌نویس ربات)
│   │   ├── store/              ← مدیریت وضعیت با Zustand
│   │   └── App.tsx             ← درخت روت‌ها، گیت‌های امنیتی پنل‌ها و نقش‌ها
├── pm/                         ← پلتفرم مدیریت پروژه و کنترل کیفیت (پلتفرم آرامش)
│   ├── backend/                ← بک‌اند مستقل PM (FastAPI, CPM Engine, QC Service)
│   ├── frontend/               ← فرانت‌اند PM (گانت چارت شمسی، WBS، ثبت عیوب و بازرسی)
│   ├── sql/                    ← اسکیما و اسکریپت‌های اختصاصی پایگاه داده PM
│   └── API_CONTRACT.md         ← قرارداد کامل اندپوینت‌های PM
├── bot/                        ← ایجنت هوشمند بله برای ثبت صوتی/متنی استعلام‌ها
│   ├── app/                    ← کلاینت Bale، پردازشگر STT صوتی، استخراج NLU با DeepSeek
│   ├── docs/SETUP.md           ← راهنمای راه‌اندازی و اتصال توکن بله
│   └── requirements.txt
├── monitoring/                 ← استک مانیتورینگ، متریک‌ها و لاگ‌ها (پرومتئوس، گرافانا، لوکی)
├── infra/                      ← تنظیمات وب‌هوک دیپلوی خودکار و کانفیگ‌های داینامیک Traefik
├── sql/
│   ├── migration.sql           ← اسکریپت اولیه پایه دیتابیس
│   └── 02-casdoor-db.sql       ← اسکریپت راه‌اندازی دیتابیس هویت Casdoor
└── tests/                      ← تست‌های یکپارچگی NLU و ویزارد استعلام
```

---

## 🔐 سیستم احراز هویت، ماتریس پنل‌ها و کنترل دسترسی (RBAC)

سامانه از سیستم احراز هویت **Casdoor OIDC** بهره می‌برد؛ ورود به صورت In-Page بوده و توکن JWT صادر شده توسط بک‌اند با JWKS اعتبارسنجی می‌شود.

مدل دسترسی سامانه بر پایه **پنل‌ها (`user_panels`)** بازطراحی شده است:

### ۱. لایه‌های دسترسی پنل‌ها
* **پنل تدارکات (`procurement`):**
  * `full`: دسترسی کامل به کارتابل استعلام‌ها، تایید یا رد پیشنهادها، تامین‌کنندگان و قیمت‌ها.
  * `limited`: فقط امکان ثبت استعلام جدید در ویزارد برای پروژه‌های منتسب به کاربر (کاربر پس از ورود مستقیماً به `/wizard` یا `/requester` هدایت می‌شود).
* **پنل انبارداری (`inventory`):**
  * `full`: مشاهده موجودی همه انبارها، رهگیری «کالاهای در راه» و کارتابل تایید رسید.
  * `limited`: فقط مشاهده و مدیریت انبارهای پروژه‌های تحت عضویت، همراه با دسترسی به ثبت تغییر موجودی کارگاهی (`/inventory/change`).
* **پنل مدیریت پروژه (`pm`):**
  * دسترسی به مشاهده یا ویرایش تسک‌ها، چارت گانت، ثبت عیوب و فرم‌های QC در `/panel/pm`.

### ۲. قوانین و نقش سرپرست پروژه (`supervisor`)
* کاربرانی با نقش `supervisor` تنها در صورتی مجاز به ورود به سامانه هستند که حداقل یک پروژه در جدول `user_project_members` یا `projects.pm_user_id` به آن‌ها منتسب شده باشد. در غیر این صورت، پیام عدم تخصیص پروژه نمایش داده شده و اجازه ورود نخواهند داشت.

---

## 🚀 راهنمای سریع راه‌اندازی محیط توسعه (Docker)

### پیش‌نیازها
* Docker Desktop (ویندوز) یا Docker Engine + Docker Compose Plugin (لینوکس)
* حداقل ۴ گیگابایت فضای خالی دیسک و اتصال اینترنت برای بارگیری ایمیج‌های اولیه

### دستورات اجرا

```powershell
# ۱. رفتن به پوشه پروژه و ساخت/اجرای کانتینرها
docker compose up -d --build

# ۲. بررسی وضعیت سلامت سرویس‌ها
docker compose ps
```

تمام سرویس‌ها باید وضعیت `Up` و دیتابیس وضعیت `(healthy)` را نشان دهند.

### درگاه‌ها و آدرس‌های محلی

| بخش | آدرس محلی | توضیحات |
|---|---|---|
| **رابط کاربری ERP** | http://localhost | داشبورد اصلی سامانه |
| **پلتفرم PM** | http://localhost/pm | مدیریت پروژه و کنترل کیفیت (قابل دسترس در `/panel/pm`) |
| **مستندات API (Swagger)** | http://localhost:8000/docs | مستندات تعاملی اندپوینت‌های تدارکات |
| **سلامت API** | http://localhost:8000/health/ready | بررسی اتصال دیتابیس، Casdoor و MinIO |
| **کنسول MinIO** | http://localhost:9001 | نام کاربری و رمز پیش‌فرض: `minioadmin` / `minioadmin` |
| **کنسول Casdoor** | http://localhost:8080 | نام کاربری و رمز اولیه: `admin` / `123` |
| **پایگاه داده PostgreSQL** | `localhost:5455` | نام دیتابیس: `procurement`، کاربر: `postgres` |

---

## 🤖 ربات هوشمند بله (`procurement-bot`)

ربات پیام‌رسان بله به عنوان یک سرویس اختصاصی درون شبکه فعال است:
1. پیام صوتی یا متنی فرستاده شده از طریق هوش مصنوعی (DeepSeek NLU) و تبدیل صوت به متن پردازش می‌شود.
2. قلم‌ها، متریال‌ها، پروژه‌ها و تامین‌کنندگان به صورت فازی جستجو و شناسایی می‌شوند.
3. پیش‌نویس در جدول `bot_drafts` ذخیره شده و شناسه پیش‌نویس تولید می‌شود.
4. کاربر می‌تواند با زدن دکمه روی بله یا مراجعه به لینک مستقیم:
   `http://localhost/wizard?draft=<UUID>`
   اطلاعات استخراج‌شده را در ویزارد فرانت‌اند مرور، تکمیل و نهایی کند.
5. راهنمای تکمیلی تنظیم توکن در [bot/docs/SETUP.md](file:///c:/Users/Reza/Desktop/v1.6/bot/docs/SETUP.md) قرار دارد.

---

## 🔄 انتقال بین‌کارگاهی کالاها (`project_transfers`)

سامانه دارای سیستم ردیابی انتقال متریال بین کارگاه‌هاست:
* ثبت انتقال از طریق صفحه «تغییر موجودی» با نوع `انتقال بین کارگاهی`.
* وضعیت‌های انتقال: `در حال انتقال (in_transit)`، `تحویل‌شده (received)` و `لغوشده (cancelled)`.
* کارگاه مقصد از طریق زبانه «انتقالات ورودی» در صفحه «کالاهای در راه» اقلام ارسالی را دریافت و به انبارهای خود تخصیص می‌دهد.

---

## 🛠️ عملیات نگهداری و دیپلوی در سرور (Operations)

* **دیپلوی خودکار:** سرور با هر Push به برنچ `production` از طریق وب‌هوک اختصاصی به صورت خودکار بیلد و بالا می‌آید. راهنمای کامل: [docs/OPERATIONS.md](file:///c:/Users/Reza/Desktop/v1.6/docs/OPERATIONS.md).
* **پشتیبان‌گیری پایگاه داده:** سرویس `db-backup` به صورت روزانه از هر دو پایگاه داده `procurement` و `casdoor` فایل‌های `.dump` تولید و در پوشه `backups/` نگهداری می‌کند.
* **مانیتورینگ و مشاهده‌پذیری:** ابزارهای Prometheus، لاگ‌های Loki و ردیابی خطاهای GlitchTip در پوشه [monitoring/](file:///c:/Users/Reza/Desktop/v1.6/monitoring/README.md) سازمان‌دهی شده‌اند.