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)
┌────────────────────────┐
│ 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) │
└───────────────────────┘
📁 ساختار پوشه‌ها و اجزای مخزن
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.
- دسترسی به مشاهده یا ویرایش تسک‌ها، چارت گانت، ثبت عیوب و فرم‌های QC در
۲. قوانین و نقش سرپرست پروژه (supervisor)
- کاربرانی با نقش
supervisorتنها در صورتی مجاز به ورود به سامانه هستند که حداقل یک پروژه در جدولuser_project_membersیاprojects.pm_user_idبه آن‌ها منتسب شده باشد. در غیر این صورت، پیام عدم تخصیص پروژه نمایش داده شده و اجازه ورود نخواهند داشت.
🚀 راهنمای سریع راه‌اندازی محیط توسعه (Docker)
پیش‌نیازها
- Docker Desktop (ویندوز) یا Docker Engine + Docker Compose Plugin (لینوکس)
- حداقل ۴ گیگابایت فضای خالی دیسک و اتصال اینترنت برای بارگیری ایمیج‌های اولیه
دستورات اجرا
# ۱. رفتن به پوشه پروژه و ساخت/اجرای کانتینرها
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)
ربات پیام‌رسان بله به عنوان یک سرویس اختصاصی درون شبکه فعال است:
- پیام صوتی یا متنی فرستاده شده از طریق هوش مصنوعی (DeepSeek NLU) و تبدیل صوت به متن پردازش می‌شود.
- قلم‌ها، متریال‌ها، پروژه‌ها و تامین‌کنندگان به صورت فازی جستجو و شناسایی می‌شوند.
- پیش‌نویس در جدول
bot_draftsذخیره شده و شناسه پیش‌نویس تولید می‌شود. - کاربر می‌تواند با زدن دکمه روی بله یا مراجعه به لینک مستقیم:
http://localhost/wizard?draft=<UUID>اطلاعات استخراج‌شده را در ویزارد فرانت‌اند مرور، تکمیل و نهایی کند. - راهنمای تکمیلی تنظیم توکن در bot/docs/SETUP.md قرار دارد.
🔄 انتقال بین‌کارگاهی کالاها (project_transfers)
سامانه دارای سیستم ردیابی انتقال متریال بین کارگاه‌هاست:
- ثبت انتقال از طریق صفحه «تغییر موجودی» با نوع
انتقال بین کارگاهی. - وضعیت‌های انتقال:
در حال انتقال (in_transit)،تحویل‌شده (received)ولغوشده (cancelled). - کارگاه مقصد از طریق زبانه «انتقالات ورودی» در صفحه «کالاهای در راه» اقلام ارسالی را دریافت و به انبارهای خود تخصیص می‌دهد.
🛠️ عملیات نگهداری و دیپلوی در سرور (Operations)
- دیپلوی خودکار: سرور با هر Push به برنچ
productionاز طریق وب‌هوک اختصاصی به صورت خودکار بیلد و بالا می‌آید. راهنمای کامل: docs/OPERATIONS.md. - پشتیبان‌گیری پایگاه داده: سرویس
db-backupبه صورت روزانه از هر دو پایگاه دادهprocurementوcasdoorفایل‌های.dumpتولید و در پوشهbackups/نگهداری می‌کند. - مانیتورینگ و مشاهده‌پذیری: ابزارهای Prometheus، لاگ‌های Loki و ردیابی خطاهای GlitchTip در پوشه monitoring/ سازمان‌دهی شده‌اند.