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