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
14 KiB
14 KiB
راهنمای جامع معماری و مدل داده پایگاه‌داده سیستم مدیریت پروژه عمرانی (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)
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)
- گیتینگ کنترل کیفی (QC Gating Rule):
اگر وظیفه‌ای دارای چک‌لیست بازرسی فاز
pre(پیش از اجرا) باشد، تا زمانی که تمامی این سوالات وضعیتpassیاnaدریافت نکنند، سیستم اجازه شروع کار (IN_PROGRESS) و افزایش پیشرفت را نمی‌دهد. - محاسبات پیش‌بینی مسیر بحرانی (CPM Logic):
محاسبات زمان‌بندی با عبور رفت و برگشت (Forward & Backward Pass) تاریخ‌های زودهنگام و دیرهنگام را استخراج کرده و فعالیت‌های با شناوری صفر (
Total Float = 0) را به عنوان مسیر بحرانی مشخص می‌کند. - چرخه حیات خودکار تاریخ‌های واقعی:
با اولین تغییر در پیشرفت تسک (
progress > 0)، فیلدactual_startبه تاریخ جاری تنظیم می‌گردد. با رسیدن پیشرفت به100%، فیلدactual_endتنظیم و وضعیت وظیفه خودکار بهCOMPLETEDتغییر می‌یابد. - تجمیع پروژه (Rollup Logic): تاریخ شروع، پایان و درصد پیشرفت فیزیکی کل پروژه همواره حاصل تجمیع و میانگین‌گیری پویای وظایف موجود در پروژه است.