docs: update root, bot, and pm README files for integrated ERP architecture

2026-10-19 11:09:58 +03:30
parent 707e40e840
commit 264c7cc906
3 changed files with 240 additions and 490 deletions
@@ -1,91 +1,59 @@
-# PM — سامانه یکپارچه مدیریت پروژه‌های ساخت و کنترل کیفیت
+# PM — سامانه یکپارچه مدیریت پروژه‌های ساخت و کنترل کیفیت (Aramesh PM)

-اپلیکیشن موبایل‌محور و تحت وب برای مدیریت جامع پروژه‌های عمرانی و ساخت: مدیریت سلسله‌مراتب فعالیت‌ها (WBS)، زمان‌بندی و گانت چارت، مسیر بحرانی (CPM)، سیستم پیشرفته کنترل کیفیت (QC)، مدیریت مصالح و انبار (با اتصال به ERP) و داشبورد عملیاتی روزانه.
+پلتفرم تخصصی مدیریت پروژه‌های عمرانی، کنترل کیفیت و زمان‌بندی کارگاهی که به صورت وندور شده و یکپارچه در کنار سامانه ERP قرار دارد.

 ---

-## دسترسی سریع
+## 🏗️ نحوه استقرار و دسترسی در سامانه ERP

-| سامانه | آدرس شبکه محلی | آدرس محلی سیستم |
-|---|---|---|
-| **PM (وب + نمای موبایل)** | http://192.168.1.103:8083 | http://localhost:8083 |
-| **PM API Health** | http://192.168.1.103:8083/api/v1/health | http://localhost:8083/api/v1/health |
+پلتفرم PM در استک یکپارچه پروژه از دو سرویس داکر تشکیل شده است:
+* **`pm-backend` (`pm-api`):** وب‌سرویس پایتون مبتنی بر FastAPI روی شبکه داخلی استک.
+* **`pm-frontend` (`pm-frontend`):** اپلیکیشن کلاینت React با سرور داخلی Nginx که از طریق ریورس‌پروکسی Traefik زیر مسیر `/pm` قرار گرفته است.

-**ورود پیش‌فرض:** `admin` / `pm123456` (قابل تغییر از طریق فایل `.env`)
+### راه‌های دسترسی:
+1. **از داخل رابط کاربری ERP:** با ورود به حساب کاربری (نقش‌های مجاز یا پنل PM) و انتخاب منوی **«مدیریت پروژه (PM)»** در آدرس `/panel/pm` (به صورت آی‌فریم روان با سشن یکپارچه).
+2. **دسترسی مستقیم مرورگر:** در آدرس `http://localhost/pm` (یا دامنه عملیاتی با پسوند `/pm/`).

 ---

-## معماری سامانه
+## 🗄️ پایگاه داده و احراز هویت مشترک

-```
-PM Frontend (React 19, Tailwind CSS, تقویم شمسی, نمای موبایل و دسکتاپ)
-        │ /api/v1
-        ▼
-PM Backend (FastAPI, Python 3.12, SQLAlchemy 2.0 Async)
-        │
-        ├── Projects & Tasks Engine (سلسله‌مراتب نامحدود WBS، زمان‌بندی CPM، گانت)
-        ├── QC Module (قالب‌های سراسری، تعریف‌های مستقل تسک، چک‌لیست، ثبت عیوب)
-        ├── Materials & Resources (تخصیص نیروی انسانی، ماشین‌آلات، مصالح و رزرو انبار)
-        ├── ERP Integration (استعلام موجودی کاتالوگ و انبارهای پروژه)
-        └── PM Postgres (ذخیره‌سازی بومی داده‌ها با پشتیبانی از JSONB و UUID)
-```
+* **پایگاه‌داده مشترک:** سرویس PM مستقیماً به همان دیتابیس `procurement` در کانتینر Postgres متصل می‌شود. جداول اختصاصی PM (`pm_projects`, `pm_tasks`, `pm_qc_*`, `pm_defects`, ...) در زمان بوت اولیه به صورت خودکار و بدون تداخل با جداول تدارکات ایجاد می‌شوند (`schema_sync.py`).
+* **احراز هویت یکپارچه (SSO):** ورود با همان حساب کاربری Casdoor انجام شده و سطح دسترسی پنل PM (`user_panels.pm`) کنترل می‌شود.

 ---

-## مالکیت داده
+## ⚙️ قابلیت‌های اصلی پلتفرم PM

-| حوزه داده | متولی و مالک | توضیحات |
-|---|---|---|
-| پروژه‌ها، فعالیت‌ها، وابستگی‌ها، مایلستون‌ها | **PM Platform** | مدیریت کامل در دیتابیس بومی PM |
-| چک‌لیست‌ها و کنترل کیفیت (QC) | **PM Platform** | پیش از اجرا، حین اجرا و پس از اجرا |
-| ثبت عیوب و اقدامات اصلاحی | **PM Platform** | الصاق تصویر، شدت عیب، پیگیری رفع |
-| کاتالوگ مصالح و موجودی واقعی انبار | **ERP** | استعلام برخط موجودی از طریق API |
-| رزرو مصالح و درخواست‌های خرید | **PM Platform** | رزرو نرم بدون دستکاری انبار تا زمان تأیید |
+### ۱. مدیریت زمان‌بندی و شکست کار (WBS & CPM Engine)
+* ساختار شکست کار با عمق نامحدود (فاز، بخش، فعالیت، زیرفعالیت).
+* روابط وابستگی چهارگانه بین فعالیت‌ها (`FS`, `SS`, `FF`, `SF`) به همراه زمان وقفه (Lag).
+* محاسبه خودکار مسیر بحرانی (Critical Path Method) و شناوری کل فعالیت‌ها.
+* گانت چارت شمسی و تعریف مایلستون‌های کلیدی پروژه.
+
+### ۲. چرخه سه‌مرحله‌ای کنترل کیفیت (QC Module)
+* **قالب‌های عمومی بازرسی (QC Templates):** تعریف چک‌لیست‌های استاندارد کیفیت برای انواع فعالیت‌های ساختمانی.
+* **مراحل ارزیابی:**
+  * **پیش از اجرا (`pre`):** دروازه ورود به تسک؛ تا زمان تایید این مرحله، پیشرفت تسک نمی‌تواند بیشتر از ۰٪ شود.
+  * **حین اجرا (`during`):** ثبت بازرسی‌های فنی حین عملیات اجرایی.
+  * **پس از اجرا (`after`):** کنترل نهایی؛ تا زمان تایید تمامی سوالات الزامی، پیشرفت تسک اجازه ۱۰۰٪ شدن ندارد.
+* **ثبت و پیگیری عیوب (Defects):** ثبت عیوب همراه با تصاویر، سطح بحرانی بودن و لزوم بازرسی مجدد پس از اقدامات اصلاحی.
+
+### ۳. مدیریت منابع و اتصال به انبار کارگاه
+* امکان تخصیص متریال و ثبت رزرو نرم با استعلام موجودی واقعی انبارهای متناظر در ERP.

 ---

-## قابلیت‌های کلیدی
-
-### ۱. مدیریت زمان‌بندی و گانت چارت (CPM Engine)
- ایجاد پروژه‌ها با کدهای اختصاصی و تیم پروژه
- ساختار شکست کار (WBS) در عمق‌های نامحدود (فاز، بخش، فعالیت، زیرفعالیت)
- وابستگی‌های چهارگانه بین فعالیت‌ها (`FS`, `SS`, `FF`, `SF`) همراه با روزهای تأخیر (Lag)
- محاسبه خودکار مسیر بحرانی (Critical Path) و شناوری کل فعالیت‌ها
- تعریف مایلستون‌ها و نقاط عطف کلیدی پروژه
-
-### ۲. چرخه سه‌مرحله‌ای کنترل کیفیت (QC)
- **مراحل ارزیابی:** پیش از اجرا (`pre`) · حین اجرا (`during`) · پس از اجرا (`after`)
- **قوانین دروازه‌ای سرور:**
-  - فعالیت تا زمان تأیید الزامات پیش از اجرا اجازه شروع (پیشرفت > ۰) ندارد.
-  - فعالیت تا زمان پاس شدن همه الزامات الزامی اجازه رسیدن به ۱۰۰٪ ندارد.
- ثبت عیوب همراه با تصاویر و الزام به بازرسی مجدد پس از اصلاح.
-
-### ۳. مدیریت منابع و ارتباط با ERP
- تخصیص نفرات، ماشین‌آلات و مصالح به تفکیک فعالیت
- اتصال پروژه به پروژه متناظر در ERP جهت استعلام موجودی انبارهای کارگاه
- رزرو نرم مصالح جهت جلوگیری از تداخل مصرف در بخش‌های مختلف پروژه
-
-### ۴. تقویم و تاریخ‌های شمسی
- تقویم بومی جلالی بدون خطا و با رعایت روزهای کاری
- ثبت و نمایش روان تاریخ‌ها در رابط کاربری به زبان فارسی
-
---
-
-## راه‌اندازی و اجرا
-
-اجرای آسان با اسکریپت پاورشل یا داکر کامپوز:
+## 🧪 اجرای آزمایشی مستقل (Standalone Dev)

+در صورت تمایل به اجرای مستقل پلتفرم PM برای تست‌های ایزوله:
 ```powershell
-# اجرای خودکار از پوشه PM:
+# از درون پوشه pm:
 powershell -ExecutionPolicy Bypass -File .\start.ps1
 ```
-
-یا مستقیماً با داکر:
-```powershell
-docker compose up -d --build
-```
+این حالت روی پورت محلی `8083` به صورت ایزوله اجرا خواهد شد.

 ---

-## قرارداد API
-مستندات کامل اندپوینت‌ها: [`API_CONTRACT.md`](API_CONTRACT.md)
+## 📑 قرارداد و مستندات API
+قرارداد جامع اندپوینت‌ها و نمونه پیام‌ها در فایل [API_CONTRACT.md](API_CONTRACT.md) و راهنمای تفصیلی ساختار جداول در [DATABASE_GUIDE.md](DATABASE_GUIDE.md) مستند شده است.