MMD
2747f9d4bb
The PM panel (PmPanelPage -> iframe /pm/) needs the project-management platform served at /pm/ on the ERP domain. Source: org repo Aramesh/PM, branch feature/project-management-platform. Update via: git subtree pull --prefix=pm aramesh-pm feature/project-management-platform --squash
175 lines
14 KiB
Markdown
175 lines
14 KiB
Markdown
# راهنمای جامع معماری و مدل داده پایگاه‌داده سیستم مدیریت پروژه عمرانی (Construction PM)
|
|
|
|
> **دستورالعمل برای هوش مصنوعی (AI Prompt / Context):**
|
|
> این سند، مشخصات دقیق معماری، موجودیت‌ها (Entities)، فیلدها، روابط و قواعد تجاری یک سیستم بومی مدیریت پروژه عمرانی (Construction Project Management) است.
|
|
> لطفاً این راهنما را مطالعه کرده و بر اساس آن، ساختار سیستم، نحوه ذخیره‌سازی داده‌ها، جریان کار (Workflow) و روابط میان جداول را برای کاربر تحلیل و تشریح نما.
|
|
|
|
---
|
|
|
|
## ۱. نمای کلی سیستم و فناوری‌ها (Architecture Overview)
|
|
|
|
- **ماهیت سامانه:** پلتفرم یکپارچه و بومی مدیریت پروژه‌های عمرانی و ساختمانی (Native Construction PM Platform).
|
|
- **لایه‌های نرم‌افزاری:**
|
|
- **فرانت‌اند:** React + TypeScript + TailwindCSS + TanStack Query (رابط کاربری مدرن با پشتیبانی تقویم شمسی و نمودار گانت تعاملی).
|
|
- **بک‌اند:** Python 3.10+ با فریم‌ورک FastAPI و SQLAlchemy 2.0 (Async ORM با درایور aiosqlite / asyncpg).
|
|
- **پایگاه‌داده:** SQLite / PostgreSQL با ساختار کاملاً رابطه‌ای (Relational) و فیلدهای ساخت‌یافته JSON.
|
|
- **شناسه‌های یکتا (Primary Keys):** تمامی جداول از کلیدهای اصلی ۱۰۰٪ بومی از نوع `UUID v4` استفاده می‌کنند. هیچ‌گونه شناسه یا وابستگی به سیستم‌های قدیمی (Legacy) وجود ندارد.
|
|
- **منطق تاریخ‌ها:** تاریخ‌ها در پایگاه‌داده به صورت استاندارد میلادی (`Date` و `DateTime`) ذخیره می‌شوند و تبدیل‌های شمسی به‌صورت لایه‌ای و لحظه‌ای برای نمایش به کاربر انجام می‌گیرد.
|
|
|
|
---
|
|
|
|
## ۲. نمودار رابطه موجودیت‌ها (ERD)
|
|
|
|
```mermaid
|
|
erDiagram
|
|
PROJECTS ||--o{ TASKS : "شامل می‌شود (1:N)"
|
|
PROJECTS ||--o{ PROJECT_MEMBERS : "تخصیص اعضا (1:N)"
|
|
PM_USERS ||--o{ PROJECT_MEMBERS : "عضویت کاربر (1:N)"
|
|
PM_USERS ||--o{ PROJECT_ASSIGNMENTS : "دسترسی پروژه (1:N)"
|
|
PROJECTS ||--o{ PROJECT_ASSIGNMENTS : "محدوده دسترسی (1:N)"
|
|
PM_USERS ||--o{ TASKS : "مسئول وظیفه (Assignee)"
|
|
|
|
TASKS ||--o{ TASKS : "ساختار درختی WBS (والد/فرزند)"
|
|
TASKS ||--o{ TASK_RELATIONS : "وظیفه پیش‌نیاز (from_task)"
|
|
TASKS ||--o{ TASK_RELATIONS : "وظیفه پس‌نیاز (to_task)"
|
|
PROJECTS ||--o{ TASK_RELATIONS : "روابط گانت پروژه"
|
|
|
|
TASKS ||--o{ TASK_QC_DEFINITIONS : "چک‌لیست‌های کنترلی"
|
|
TASK_QC_DEFINITIONS ||--o{ TASK_QC_QUESTIONS : "آیتم‌های کنترلی"
|
|
TASK_QC_QUESTIONS ||--o{ TASK_QC_RESULTS : "تاریخچه بازرسی‌ها"
|
|
|
|
TASKS ||--o{ DEFECTS : "عیوب و عدم انطباق‌ها"
|
|
TASK_QC_QUESTIONS ||--o{ DEFECTS : "علت ریشه‌ای عیب (اختیاری)"
|
|
|
|
QC_TEMPLATES ||--o{ QC_QUESTIONS : "قالب‌های عمومی بازرسی"
|
|
```
|
|
|
|
---
|
|
|
|
## ۳. شرح تفصیلی جداول و موجودیت‌ها (Data Dictionary)
|
|
|
|
### ۱. جدول پروژه‌ها (`projects`)
|
|
موجودیت ریشه سامانه که اطلاعات اصلی کارگاه‌های عمرانی را نگهداری می‌کند.
|
|
|
|
| نام فیلد | نوع داده | کلید / ایندکس | توضیحات |
|
|
|---|---|---|---|
|
|
| `id` | `UUID` | **PK** | شناسه یکتای پروژه |
|
|
| `name` | `VARCHAR(255)` | Index | نام پروژه (مانند «پروژه برج بهارستان») |
|
|
| `description` | `TEXT` | - | شرح پروژه، الزامات و مشخصات فنی |
|
|
| `location` | `VARCHAR(255)` | - | موقعیت جغرافیایی / نشانی کارگاه |
|
|
| `project_manager` | `VARCHAR(255)` | - | نام مدیر یا سرپرست کارگاه |
|
|
| `status` | `VARCHAR(32)` | Index | وضعیت: `PLANNED`, `ACTIVE`, `ON_HOLD`, `COMPLETED`, `CANCELLED` |
|
|
| `planned_start` | `DATE` | - | تاریخ شروع مصوب (محاسبه و تجمیع خودکار از کمترین تاریخ شروع تسک‌ها) |
|
|
| `planned_end` | `DATE` | - | تاریخ پایان مصوب (محاسبه و تجمیع خودکار از بیشترین تاریخ پایان تسک‌ها) |
|
|
| `actual_start` | `DATE` | - | تاریخ شروع واقعی (محاسبه خودکار از زمان آغاز اولین تسک) |
|
|
| `actual_end` | `DATE` | - | تاریخ پایان واقعی (محاسبه خودکار با اتمام ۱۰۰٪ تمام تسک‌ها) |
|
|
| `progress` | `FLOAT` | - | درصد پیشرفت فیزیکی پروژه (میانگین وزنی درصد پیشرفت تسک‌ها از ۰ تا ۱۰۰) |
|
|
| `created_at` | `TIMESTAMP` | - | زمان ثبت رکورد |
|
|
| `updated_at` | `TIMESTAMP` | - | زمان آخرین ویرایش رکورد |
|
|
|
|
---
|
|
|
|
### ۲. جدول وظایف و فعالیت‌ها (`tasks`)
|
|
اصلی‌ترین موجودیت سامانه برای ساختار شکست کار (WBS)، گانت، تخصیص منابع و کنترل کیفی.
|
|
|
|
| نام فیلد | نوع داده | کلید / ایندکس | توضیحات |
|
|
|---|---|---|---|
|
|
| `id` | `UUID` | **PK** | شناسه یکتای وظیفه |
|
|
| `project_id` | `UUID` | **FK** -> `projects.id` | پروژه‌ای که وظیفه به آن تعلق دارد (Cascade Delete) |
|
|
| `parent_id` | `UUID` (Nullable) | **FK** -> `tasks.id` | والد در ساختار درختی WBS با عمق نامحدود (فاز ➔ فعالیت ➔ زیرتسک) |
|
|
| `title` | `VARCHAR(512)` | - | عنوان وظیفه (مانند «بتن‌ریزی سقف طبقه ۲») |
|
|
| `description` | `TEXT` | - | مشخصات و الزامات کار |
|
|
| `status` | `VARCHAR(32)` | Index | وضعیت: `TODO`, `IN_PROGRESS`, `BLOCKED`, `COMPLETED`, `CANCELLED` |
|
|
| `priority` | `VARCHAR(32)` | - | اولویت: `low`, `medium`, `high`, `urgent` |
|
|
| `assignee_id` | `UUID` (Nullable) | **FK** -> `pm_users.id` | کاربر سیستم مسئول اجرای وظیفه |
|
|
| `assignee_name` | `VARCHAR(255)` | - | نام متنی کاربر جهت نمایش سریع |
|
|
| `planned_start` | `DATE` | - | تاریخ شروع برنامه‌ریزی‌شده |
|
|
| `planned_end` | `DATE` | - | تاریخ پایان برنامه‌ریزی‌شده |
|
|
| `actual_start` | `DATE` (Nullable) | - | شروع واقعی (ثبت خودکار هنگام تغییر پیشرفت به بیشتر از صفر) |
|
|
| `actual_end` | `DATE` (Nullable) | - | پایان واقعی (ثبت خودکار در زمان تکمیل ۱۰۰٪) |
|
|
| `duration` | `INTEGER` | - | مدت زمان برآورد شده بر حسب روز کاری |
|
|
| `progress` | `INTEGER` | - | درصد پیشرفت واقعی از ۰ تا ۱۰۰ |
|
|
| `qc_status` | `VARCHAR(32)` | - | وضعیت کنترل کیفی: `none`, `pre_qc_pending`, `pre_qc_failed`, `ready`, `exec_qc_pending`, `in_progress`, `qc_failed_rework`, `final_passed` |
|
|
| `human_resources` | `JSON` | - | لیست نقش‌ها و نفرات: `[{"role": "آرماتوربند", "count": 4}]` |
|
|
| `materials` | `JSON` | - | لیست مصالح و تجهیزات/ماشین‌آلات: `[{"name": "سیمان تیپ ۲", "unit": "تن", "specifications": ["عیار ۳۵۰"], "count": 10}, {"name": "تاور کرین", "unit": "دستگاه", "specifications": ["ظرفیت ۸ تن"], "count": 1}]` |
|
|
| `created_at` | `TIMESTAMP` | - | تاریخ ایجاد رکورد |
|
|
| `updated_at` | `TIMESTAMP` | - | تاریخ آخرین به‌روزرسانی |
|
|
|
|
---
|
|
|
|
### ۳. جدول روابط وابستگی و گانت (`task_relations`)
|
|
پایه‌گذار روش مسیر بحرانی (CPM Scheduling) و شبکه فعالیت‌های گانت.
|
|
|
|
| نام فیلد | نوع داده | کلید / ایندکس | توضیحات |
|
|
|---|---|---|---|
|
|
| `id` | `UUID` | **PK** | شناسه رابطه |
|
|
| `project_id` | `UUID` | **FK** -> `projects.id` | پروژه مربوطه |
|
|
| `from_task_id` | `UUID` | **FK** -> `tasks.id` | فعالیت پیش‌نیاز (Predecessor) |
|
|
| `to_task_id` | `UUID` | **FK** -> `tasks.id` | فعالیت وابسته / پس‌نیاز (Successor) |
|
|
| `relation_type` | `VARCHAR(8)` | - | نوع وابستگی: `FS` (پایان به شروع)، `SS` (شروع به شروع)، `FF` (پایان به پایان)، `SF` (شروع به پایان) |
|
|
| `lag_days` | `INTEGER` | - | فاصله زمانی مجاز (تاخیر یا تقدم) بر حسب روز |
|
|
| `created_at` | `TIMESTAMP` | - | زمان ثبت رابطه |
|
|
|
|
*محدودیت (Constraint):* زوج `(from_task_id, to_task_id)` یکتا بوده و از ایجاد حلقه (Cycle) در الگوریتم CPM جلوگیری می‌شود.
|
|
|
|
---
|
|
|
|
### ۴. حوزه کنترل کیفیت و بازرسی فنی (QC Domain)
|
|
|
|
این بخش تضمین می‌کند کلیه اقدامات اجرایی کارگاه دارای تاییدیه‌های استاندارد باشند:
|
|
|
|
#### الف) قالب‌های سراسری بازرسی (`qc_templates` و `qc_questions`)
|
|
- **`qc_templates`:** کتابخانه فرم‌های استاندارد کیفی (مثلاً قالب بازرسی بتن‌ریزی، قالب سفت‌کاری).
|
|
- **`qc_questions`:** سوالات و ضوابط کنترلی در سه فاز اجرایی:
|
|
- `pre`: پیش از اجرا (آمادگی کارگاه، تایید نقشه‌ها، مصالح ورودی).
|
|
- `during`: حین اجرا (دمای بتن، ویبره مناسب، ایمنی).
|
|
- `after`: پس از اجرا (عمل‌آوری، مقاومت فشاری نمونه‌ها).
|
|
|
|
#### ب) فرم‌های کیفی اختصاص‌یافته به وظایف (`task_qc_definitions` و `task_qc_questions`)
|
|
- با تخصیص چک‌لیست به یک تسک، یک نسخه مستقل از قالب بر روی وظیفه ایجاد می‌شود تا هرگونه تغییر روی قالب سراسری به تاریخچه بازرسی‌های ثبت‌شده آسیب نزند.
|
|
|
|
#### ج) نتایج و تاریخچه بازرسی (`task_qc_results`)
|
|
- سیستم ثبت پیوسته (Append-Only Log) بدون امکان حذف؛ هر ارزیابی بازرس شامل:
|
|
- `question_id`: شناسه آیتم بازرسی.
|
|
- `answer`: پاسخ بازرس (`pass` تایید، `fail` عدم انطباق، `na` عدم کاربرد).
|
|
- `comment`: توضیحات فنی و نواقص مشاهده‌شده.
|
|
- `evaluated_by`: نام بازرس ناظر.
|
|
- `evaluated_at`: زمان دقیق بازرسی.
|
|
|
|
#### د) جدول عیوب و عدم انطباق‌ها (`defects`)
|
|
- ثبت رخدادهای نامنطبق در جریان اجرای کار:
|
|
- `id` (UUID - PK): شناسه عیب.
|
|
- `task_id` (UUID - FK -> `tasks.id`): وظیفه مربوطه.
|
|
- `question_id` (UUID - FK اختیاری): سوال بازرسی که منجر به رد شدن شده است.
|
|
- `title`: عنوان عدم انطباق (مثلاً: «کرموشدگی بتن ستون جنوبی»).
|
|
- `description`: شرح دقیق ایراد.
|
|
- `severity`: درجه شدت عیب (`minor`, `medium`, `major`, `critical`).
|
|
- `status`: وضعیت رفع (`open`, `in_progress`, `resolved`).
|
|
- `corrective_action`: دستور اقدام اصلاحی صادرشده توسط مهندس ناظر.
|
|
- `resolution_notes`: شرح نحوه رفع عیب.
|
|
- `photo_path`: مسیر ذخیره تصویر مستند عیب در سرور.
|
|
- `resolved_at`: زمان تایید رفع عیب.
|
|
|
|
---
|
|
|
|
### ۵. احراز هویت و دسترسی‌ها (`pm_users`, `project_members`, `project_assignments`)
|
|
|
|
- **`pm_users`:** کاربران سازمانی سیستم (`username`, `password_hash`, `display_name`, `role`).
|
|
- نقش‌های سیستمی: `project_manager` (دسترسی نامحدود به تمام پروژه‌ها)، `project_supervisor` (دسترسی محدود به پروژه‌های مشخص).
|
|
- **`project_members`:** اعضای منتسب به هر پروژه با نقش کارگاهی:
|
|
- `role`: `project_manager`, `site_engineer`, `qc_inspector`, `member`.
|
|
- **`project_assignments`:** جدول دامنه دسترسی برای ناظران و سرپرستان دارای دسترسی محدود (Scoped Roles).
|
|
|
|
---
|
|
|
|
## ۴. قواعد و منطق‌های تجاری نهفته در سیستم (Business Invariants)
|
|
|
|
1. **گیتینگ کنترل کیفی (QC Gating Rule):**
|
|
اگر وظیفه‌ای دارای چک‌لیست بازرسی فاز `pre` (پیش از اجرا) باشد، تا زمانی که تمامی این سوالات وضعیت `pass` یا `na` دریافت نکنند، سیستم اجازه شروع کار (`IN_PROGRESS`) و افزایش پیشرفت را نمی‌دهد.
|
|
2. **محاسبات پیش‌بینی مسیر بحرانی (CPM Logic):**
|
|
محاسبات زمان‌بندی با عبور رفت و برگشت (Forward & Backward Pass) تاریخ‌های زودهنگام و دیرهنگام را استخراج کرده و فعالیت‌های با شناوری صفر (`Total Float = 0`) را به عنوان مسیر بحرانی مشخص می‌کند.
|
|
3. **چرخه حیات خودکار تاریخ‌های واقعی:**
|
|
با اولین تغییر در پیشرفت تسک (`progress > 0`)، فیلد `actual_start` به تاریخ جاری تنظیم می‌گردد. با رسیدن پیشرفت به `100%`، فیلد `actual_end` تنظیم و وضعیت وظیفه خودکار به `COMPLETED` تغییر می‌یابد.
|
|
4. **تجمیع پروژه (Rollup Logic):**
|
|
تاریخ شروع، پایان و درصد پیشرفت فیزیکی کل پروژه همواره حاصل تجمیع و میانگین‌گیری پویای وظایف موجود در پروژه است.
|