ERP/DATABASE_GUIDE.md

راهنمای جامع معماری و مدل داده پایگاه‌داده سیستم مدیریت پروژه عمرانی (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)

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): تاریخ شروع، پایان و درصد پیشرفت فیزیکی کل پروژه همواره حاصل تجمیع و میانگین‌گیری پویای وظایف موجود در پروژه است.