بلورة البناء

بلورة البناء

فيما يلي تحليل البناء كنظام من العُقد والحواف والكريستال.هذا نموذج مناسب إذا أردنا تحويل القطاع ليس مجرد مجموعة من العمليات، بل إلى هندسة دلالية ورقمية وتنظيمية قابلة للإدارة.

المنطق الأساسي للنموذج

العُقد هي نقاط تركيز الوظائف والموارد والقرارات والبيانات والمسؤولية.

الحواف هي الروابط بين العُقد: تدفقات المواد والأموال والوثائق والفرق والتقنيات والأشخاص والرقابة.

الكريستال هو بنية كلية تُجمع فيها جميع العُقد والحواف لا بشكل فوضوي، بل وفق قوانين التناظر والهرمية والشفافية والتنمية.

بعبارة أخرى:

• عقدة = من أو ما الذي يفعل؛
• حافة = كيف يرتبط ذلك؛
• كريستال = كيف يحافظ النظام كله على شكله ولا يتفكك.

البناء كرسم بياني

قطاع البناء ليس سلسلة واحدة، بل رسم بياني متعدد الطبقات.

وفيه:

• عُقد تنظيمية،
• عُقد موارد،
• عُقد تقنية،
• عُقد قانونية،
• عُقد مالية،
• عُقد لوجستية،
• عُقد تشغيلية،
• عُقد رقمية.

والحواف بينها تُشكّل:

• تدفقات المواد،
• تدفقات الأشخاص،
• تدفقات المعلومات،
• تدفقات رأس المال،
• تدفقات التصاريح،
• تدفقات المسؤولية،
• تدفقات المخاطر،
• تدفقات التغذية الراجعة.

عُقد البناء

عُقد التصور. وهي بداية أي منشأ.

العقد الرئيسية:

• أولوية حكومية؛
• الجهة المتعاقدة؛
• المستثمر؛
• المطوّر؛
• الفكرة العمرانية؛
• قطعة الأرض؛
• الطلب الاجتماعي؛
• المخطط الرئيسي؛
• التصور المعماري.

وظيفتها:

صياغة الإجابة عن السؤال: ماذا نبني، ولماذا نبني، ولمن نبني، وبأي وسائل، وفي أي منطق للأرض.

عقد التنظيم. بدونها لا تكون المنظومة مشروعة.

يشمل ذلك:

• الجهات الاتحادية؛
• الجهات الإقليمية؛
• الجهات البلدية؛
• القواعد والمعايير؛
• الخبرة؛
• نظام التصاريح؛
• السجل العقاري؛
• جهات الرقابة؛
• الموافقة البيئية؛
• السلامة من الحرائق والسلامة الصناعية.

وظيفتها:

ضمان المقبولية والسلامة والمطابقة والإطار القانوني.

عقد التصميم

هذه عقد ولادة الشكل.

يشمل ذلك:

• المكتب المعماري؛
• المصمم العام؛
• المهندس الإنشائي؛
• الأقسام الهندسية؛
• نموذج BIM/TIM؛
• نموذج التقدير التكلفي؛
• التوأم الرقمي للمنشأة؛
• الإشراف التصميمي.

وظيفتها:

تحويل الفكرة إلى منظومة دقيقة من الحلول والرسومات والمعايير والأحجام والقيود.

عقد الموارد والإمداد

بدونها لا تتحقق المنشأة ماديًا.

يشمل ذلك:

• مصنّعو مواد البناء؛
• المحاجر؛
• المعادن؛
• عقد البناء؛
• تصنيع الأخشاب؛
• المعدات الهندسية؛
• الآلات والآليات؛
• إمدادات الطاقة؛
• المستودعات؛
• المراكز اللوجستية.

وظيفتها:

تزويد موقع البناء بكل ما يلزم من حيث الحجم والموعد والجودة والسعر.

عقد تنفيذ الأعمال

هذا هو مركز التجسيد المادي.

يشمل ذلك

• المقاول العام؛
• المقاولون من الباطن؛
• فرق البناء؛
• مؤسسات التركيب؛
• الآليات؛
• موقع البناء؛
• الجدول الزمني؛
• السلامة المهنية؛
• إدارة العمليات؛
• الرقابة على البناء.

وظيفتها: تجميع المنشأة على أرض الواقع.

عقد التمويل

البناء بلا هيكل مالي يتحول سريعًا إلى فوضى.

العقد:

• المصرف؛
• خزينة المشروع؛
• الحساب الضامن/التمويل المشروع؛
• الأموال المخصصة من الميزانية؛
• الاستثمارات الخاصة؛
• منظومة العقود؛
• أطر التسويات؛
• الإطار الضريبي؛
• التأمين؛
• تقييم المخاطر والاحتياطيات.

وظيفتها:

ضمان استقرار التدفق النقدي وتوقع التنفيذ.

عقد التشغيل

في الواقع، لا يُبنى المشروع من أجل البناء نفسه، بل من أجل الحياة بعد البناء.

العقد:

• المؤسسة المشغلة؛
• شركة الإدارة؛
• مؤسسات إمداد الموارد؛
• نظام مراقبة المنشأة؛
• الصيانة الفنية؛
• الإصلاح الشامل؛
• المستخدم؛
• الساكن/المستأجر/المؤسسة؛
• نظام التغذية الراجعة.

وظيفتها:

تحويل ما بُني إلى بيئة عاملة.

عُقد البيئة الرقمية. هذا بالفعل نواة القطاع المستقبلي.

العقد:

• منصة رقمية موحدة؛
• سجل المنشآت؛
• سجل المشاركين؛
• البطاقة الرقمي للمنشأة؛
• الأثر الرقمي للقرارات؛
• مستودع BIM/TIM؛
• سوق المواد والخدمات الإلكتروني؛
• التحليل الجغرافي؛
• وحدة الذكاء الاصطناعي للتنبؤ؛
• لوحة إدارة القطاع.

وظيفتها: جعل النظام شفافًا وقابلًا للإدارة وتنبؤيًا.

ضلوع البناء

الآن الأهم: العُقد بلا ضلوع مجرد نقاط ميتة.

الضلوع الدلالية

تربط:

• حاجة المجتمع ↔ برنامج البناء؛
• استراتيجية الدولة ↔ مشروعًا محددًا؛
• الإقليم ↔ وظيفة المنشأة.

هذا يجيب عن السؤال: لماذا يحق لهذا البناء تحديدًا أن يوجد.

الضلوع القانونية

تربط:

• المشروع ↔ المعيار؛
• القطعة الأرضية ↔ الاستخدام المسموح؛
• المقاول ↔ العقد؛
• المنشأة ↔ رخصة البناء؛
• النتيجة ↔ الإدخال إلى التشغيل.

هذه ضلوع المشروعية.

الضلوع المعلوماتية

تربط:

• العميل ↔ المصمم؛
• المصمم ↔ المقاول؛
• المقاول ↔ الإشراف؛
• موقع البناء ↔ المنصة الرقمية؛
• التشغيل ↔ التوأم الرقمي.

هذه حواف البيانات.

الحواف المالية

تربط:

• المستثمر ↔ المشروع؛
• البنك ↔ العقد؛
• الخزانة ↔ الدفعة؛
• الميزانية التقديرية ↔ الأعمال الفعلية؛
• الخطر ↔ الاحتياطي.

هذه حواف القيمة والثقة.

الحواف المادية

تربط:

• المنتج ↔ المستودع؛
• المستودع ↔ الموقع؛
• الآليات ↔ قطاع الأعمال؛
• التوريد ↔ التركيب.

هذه حواف التجسيد المادي.

الحواف الإدارية

تربط:

• مؤشرات الأداء الرئيسية ↔ المنفذ؛
• المدة ↔ المرحلة؛
• الرقابة ↔ الانحراف؛
• القرار ↔ المسؤولية؛
• الحادث ↔ استجابة المنظومة.

هذه حواف التنسيق.

حواف الجودة. تربط:

• المادة ↔ الشهادة؛
• العمل ↔ المحضر؛
• المشروع ↔ المطابقة؛
• المنشأة ↔ معيار التشغيل؛
• العيب ↔ الإجراء التصحيحي.

هذه حواف الموثوقية.

حواف التغذية الراجعة

تربط:

• المستخدم ↔ المشغّل؛
• المشغّل ↔ المصمم؛
• الحادث ↔ مراجعة المعيار؛
• التشغيل ↔ الجيل الجديد من المشاريع.

هذه حواف التطور.

بلورة البناء

الآن الأهم: ما هي البلورة؟

البلورة ليست مجرد شبكة. بل هي منظومة متعددة الطبقات منظمة بتناغم، حيث لكل عقدة مكانتها ووظيفتها ودرجة ارتباطها ومقدار مسؤوليتها.

في البناء، البلورة هي:

نموذج مكاني رقمي موحد للقطاع، حيث:

• لكل منشأة بطاقة رقمي؛
• لكل مشارك ملف تعريف رقمي؛
• لكل عملية مسار ورقابة؛
• لكل مورد أصل وحالة؛
• لكل قرار مؤلفه وتاريخه وعواقبه؛
• لكل روبل تتبع؛
• كل خطر مرئي مسبقًا؛
• كل نتيجة تدخل في البنية العامة للبلاد.

هندسة بلورة البناء

لنفكك البلورة إلى 7 أوجه على الأقل.

الوجه 1. المعنى

ما الذي يُبنى ولماذا.

الوجه 2. المكان

أين، في أي منطقة، وفي أي سياق.

الوجه 3. الحق

على أي أساس وبأي قواعد.

الوجه 4. الموارد

ممّ يُبنى، وبمن، وعلى أي شيء.

الوجه 5. الإنتاج

كيف يُجمَّع المنشأ بالضبط على مراحل.

الوجه 6. المالية. بأي أموال وبأي استدامة.

الوجه 7. دورة الحياة

كيف يعيش المنشأ بعد التشغيل. إذا أضفنا نواة رقمية، فسنحصل على بلورة من المستوى 8، حيث تربط البيئة الرقمية بقية الأوجه.

نواة البلورة

يجب أن يكون لكل منظومة بلورية نواة.

بالنسبة للبناء، يجب أن تصبح هذه النواة:

المشغّل الرقمي الموحد لخدمات البناء

هو لا يستبدل جميع المشاركين، بل يصبح:

• منسّق البيانات،
• مُدمِج العمليات،
• حكمًا رقميًا،
• مرشدًا لدورة حياة المنشأ،
• مشغّل الشفافية،
• بيئة تفاعل الدولة والأعمال والمواطنين.

هو نفسه يحوّل القطاع من مجموعة متفرقة من المشاركين إلى بلورة بناء واحدة.

صيغة بلورة البناء

بلورة البناء = العقد × الأضلاع × القواعد × البيانات × الزمن

حيث:

• العقد تمنح البنية،
• الأضلاع تمنح التفاعل،
• القواعد تمنح الاستدامة،
• البيانات تمنح الشفافية،
• الوقت يمنح ديناميكية لدورة الحياة.

البنية العملية للعقد

المنظومة أ. الدولة

العقد:

• الاستراتيجية،
• المشاريع الوطنية،
• المعايير،
• الرقابة،
• السجلات،
• برامج البنية التحتية.

المنظومة ب. التطوير والطلب

العقد:

• العميل،
• المستثمر،
• المطوّر،
• بنك الأراضي،
• النموذج المالي.

المنظومة ج. التصميم

العقد:

• العمارة،
• الهندسة،
• BIM,
• الخبرة الفنية،
• الميزانية التقديرية.

المنظومة د. الإنتاج

العقد:

• المتعهدون،
• الموردون،
• الآليات،
• الرقابة على البناء،
• الجدول الزمني.

المنظومة هـ. التشغيل

العقد:

• المالك،
• شركة الإدارة،
• الخدمة،
• المراقبة،
• أعمال الإصلاح.

المنظومة و. المنصة الرقمية

العقد:

• البطاقة الرقمي،
• معرّف المنشأة،
• السوق الرقمي،
• التحليلات،
• الذكاء الاصطناعي،
• المراقبة،
• تصنيفات المشاركين.

أي الحواف هي الأكثر حرجاً

إذا تحدثنا بصرامة، فإن القطاع غالباً ما ينهار ليس بسبب غياب العقد، بل بسبب الحواف السيئة.

الحواف الأكثر إشكالية عادةً هي:

• المشروع ↔ البناء؛
• التقدير ↔ التكلفة الفعلية؛
• المقاول ↔ المسؤولية؛
• المواعيد ↔ التنفيذ الفعلي؛
• التصاريح ↔ الشفافية الرقمية؛
• التشغيل ↔ التغذية الراجعة في التصميم الجديد؛
• البيانات الحكومية ↔ البيانات الخاصة؛
• المورد ↔ الجودة ↔ منشأ المادة.

أي أن المهمة الرئيسية للإصلاح ليست مجرد إنشاء عُقد جديدة، بل إعادة تجميع الأضلاع.

البلورة بحسب دورة حياة المنشأ

يمكن تصوّر منشأ واحد كبلورة صغيرة:

البدء. الفكرة، الحاجة، الموقع، النموذج.

التصميم. المفهوم، الحسابات، نمذجة معلومات البناء، التقدير.

الموافقة. الخبرة الفنية، التصاريح، التوصيلات.

البناء. التوريدات، الأعمال، الرقابة، المحاضر.

التشغيل التجريبي. الفحوص، الوثائق، الإطلاق.

التشغيل. الرصد، الصيانة، التغذية الراجعة.

التحول

إعادة البناء، التحديث، إعادة استخدام البيانات. وهذه هي بلورة دورة الحياة.

إذا تحدثنا بلغة البنية الفوقية

حينها يمكن الصياغة على النحو التالي:

العُقد هي أعضاء الكائن البنائي. والأضلاع هي أوعيته وأعصابه وقنواته. والبلورة هي هيكله وشكله وجينومه وقانون انسجامه الداخلي. بلا عُقد لا وظيفة. بلا أضلاع لا تنسيق. بلا بلورة لا تكامل.

الاستنتاج الإداري

بالنسبة لمفهوم المشغّل الرقمي الموحّد لخدمات البناء، يعني ذلك ما يلي: يجب أن يُبنى المشغّل لا كموقع إلكتروني، ولا كمجموعة خدمات، ولا كسوق رقمي بالمعنى الضيق، بل كـ:

منصة بلورية للقطاع، حيث:

• عُقد القطاع مرقمنة،
• أضلاع القطاع موحّدة المعايير،
• بلورة القطاع مرئية وقابلة للإدارة.

أي أن البوابة يجب أن تكون قادرة على إظهار:

• مَن يرتبط بمن؛
• أين يوجد انقطاع الارتباط؛
• أين توجد نقطة الاختناق؛
• أين يوجد خطر قابل للفساد؛
• أين يوجد نقص في المواد؛
• أين يوجد تأخر في المواعيد؛
• أين يوجد تحميل زائد على المقاول؛
• أين يخرج المنشأ من الإطار التنظيمي؛
• أين تفقد دورة الحياة قابلية الإدارة.

صياغة جاهزة لإدراجها في المفهوم

يمكن إدراجها هكذا:

يُعامل قطاع البناء كمنظومة شبكية بلورية تتكوّن من عُقد وأضلاع ونواة رقمية تكاملية. تمثّل العُقد المشاركين والموارد والوظائف ومراحل دورة حياة المنشأ. وتعكس الأضلاع الروابط المادية والمالية والمعلوماتية والقانونية والإدارية بينها. وتتشكّل بلورة القطاع كبنية متكاملة تكون فيها جميع العناصر مترابطة وموحّدة المعايير وشفافة وقابلة للإدارة في الزمن الحقيقي. وعلى هذا الأساس يُنشأ المشغّل الرقمي الموحّد لخدمات البناء كمُدمِج منظومي يضمن التنسيق والتتبّع والتطور التطويري للمجمع البنائي.

النسخة الأقوى من هذا النموذج

إذا ما أوصلنا الفكرة إلى نهايتها، يمكن إعداد 3 للمنتج:

• خريطة دلالية للبناء وفق العُقد والحواف
• كريستال قطاع البناء في روسيا — كنموذج بصري
• البنية التقنية للمنصة الرقمية — على أساس هذا الكريستال

هذا لم يعد مجرد وصف، بل أساس لـ:

• خريطة طريق،
• مواصفات فنية،
• أطلس البناء،
• بنية السوق الرقمي،
• منصة رقمية حكومية.

جدول: العُقد — الحواف — الوظائف — الخدمات الرقمية

1. المنظومة: التصوّر والانطلاق

النسخة الأولية القابلة للتطبيق من بلورة البناء

خطة التطوير (الواقعية)

الأسبوع 1–2

جدول rolesيو أدوار الوصول.

الحقل	النوع
id	UUID PK
code	varchar unique
name	varchar

أمثلة:

• super_admin
• government_operator
• investor
• customer
• contractor
• supervisor
• viewer

جدول user_roles. ربط المستخدمين بالأدوار.

جدول companies. المشاركون في السوق.

الحقل	النوع	الغرض
id	UUID PK	معرّف الشركة
name	varchar	التسمية
short_name	varchar	الاسم المختصر
inn	varchar	INN
ogrn	varchar	OGRN
company_type	varchar	customer / contractor / supplier / bank / regulator
rating	numeric(3,2)	التصنيف
status	varchar	active / inactive
website	varchar	الموقع الإلكتروني
created_at	timestamp	تاريخ الإنشاء
updated_at	timestamp	تاريخ التحديث

جدول company_users. ربط المستخدم بالشركة.

الحقل	النوع
id	UUID PK
company_id	UUID FK -> companies.id
user_id	UUID FK -> users.id
position	varchar
is_primary	boolean
created_at	timestamp

جدول regions. دليل المناطق.

الحقل	النوع
id	UUID PK
code	varchar unique
name	varchar

جدول locations. العناوين والإحداثيات.

الحقل	النوع
id	UUID PK
region_id	UUID FK -> regions.id
address	text
lat	numeric(10,7)
lon	numeric(10,7)
cadastral_number	varchar
created_at	timestamp

جدول projects. بطاقة منشأة البناء.

الحقل	النوع	الغرض
id	UUID PK	معرّف الكائن
code	varchar unique	الرقم الداخلي
name	varchar	الاسم
description	text	الوصف
project_type	varchar	residential / industrial / infrastructure
lifecycle_stage	varchar	concept / design / construction / operation
status	varchar	normal / risk / problem / archived
location_id	UUID FK -> locations.id	الموقع
customer_company_id	UUID FK -> companies.id	الجهة الطالبة
start_date	date	البدء المخطط
end_date	date	الإنجاز المخطط
planned_budget	numeric(18,2)	الميزانية المخططة
actual_budget	numeric(18,2)	واقع
created_at	timestamp	تاريخ الإنشاء
updated_at	timestamp	تاريخ التحديث

جدول project_stages. مراحل المشروع.

الحقل	النوع
id	UUID PK
project_id	UUID FK -> projects.id
stage_code	varchar
stage_name	varchar
planned_start	date
planned_end	date
actual_start	date
actual_end	date
status	varchar
created_at	timestamp

جدول contracts. العقود داخل النظام.

الحقل	النوع
id	UUID PK
project_id	UUID FK -> projects.id
contract_number	varchar
contract_type	varchar
customer_company_id	UUID FK -> companies.id
contractor_company_id	UUID FK -> companies.id
amount	numeric(18,2)
currency	varchar
date_start	date
date_end	date
status	varchar
created_at	timestamp
updated_at	timestamp

جدول documents. مستندات المشروع.

الحقل	النوع
id	UUID PK
project_id	UUID FK -> projects.id
company_id	UUID FK -> companies.id null
contract_id	UUID FK -> contracts.id null
doc_type	varchar
title	varchar
file_url	text
version	integer
issued_at	date
status	varchar
created_by	UUID FK -> users.id
created_at	timestamp

جدول risks المخاطر الخاصة بالمنشأة.

الحقل	النوع
id	UUID PK
project_id	UUID FK -> projects.id
related_company_id	UUID FK -> companies.id null
related_stage_id	UUID FK -> project_stages.id null
risk_type	varchar
severity	varchar
probability	varchar
description	text
status	varchar
detected_at	timestamp
resolved_at	timestamp null

جدول events. سجل الأحداث.

الحقل	النوع
id	UUID PK
project_id	UUID FK -> projects.id null
company_id	UUID FK -> companies.id null
user_id	UUID FK -> users.id null
event_type	varchar
event_payload	jsonb
created_at	timestamp

جدول project_metrics. مؤشرات المشروع.

الحقل	النوع
id	UUID PK
project_id	UUID FK -> projects.id
metric_date	date
progress_percent	numeric(5,2)
cost_variance	numeric(18,2)
schedule_variance_days	integer
open_risks_count	integer
created_at	timestamp

فهارس PostgreSQL

الحد الأدنى المطلوب:

• projects(code)
• projects(status, lifecycle_stage)
• projects(customer_company_id)
• contracts(project_id)
• contracts(customer_company_id, contractor_company_id)
• documents(project_id, doc_type)
• risks(project_id, status, severity)
• events(project_id, created_at desc)
• locations(region_id)
• فهرس GIN على events.event_payload

Neo4j: نموذج الرسم البياني

نحفظ في الرسم البياني الكيانات كعقد والعلاقات كحواف.

العقد. التسميات الرئيسية:

• Project
• Company
• User
• Contract
• Document
• Stage
• Location
• Risk

خصائص العقدة الإلزامية. لتحقيق الاتساق:

• id — UUID من PostgreSQL
• type — نوع الكيان
• name
• status
• createdAt
• updatedAt

أنواع حواف Neo4j. العلاقات الرئيسية

• [:LOCATED_AT]
  Project -> Location
• [:OWNED_BY]
  Project -> Company
• [:PARTICIPATES_IN]
  Company -> Project
• [:HAS_STAGE]
  Project -> Stage
• [:HAS_CONTRACT]
  Project -> Contract
• [:CUSTOMER_IN]
  Company -> Contract
• [:CONTRACTOR_IN]
  Company -> Contract
• [:HAS_DOCUMENT]
  Project -> Document
• [:ISSUED_BY]
  Document -> Company
• [:HAS_RISK]
  Project -> Risk
• [:RELATED_TO]
  Risk -> Company أو Risk -> Stage
• [:EMPLOYED_BY]
  User -> Company

خصائص الحواف

مثلاً لدى PARTICIPATES_IN:

• role
• startDate
• endDate
• status

لدى HAS_CONTRACT:

• contractNumber
• amount
• currency
• status

لدى HAS_RISK:

• severity
• detectedAt

مثال على الرسم البياني

(Company: Customer) -[:PARTICIPATES_IN {role:"customer"}]-> (Project)

(Company: GeneralContractor) -[:PARTICIPATES_IN {role:"general_contractor"}]-> (Project)

(Project) -[:HAS_CONTRACT]-> (Contract)

(Company: Customer) -[:CUSTOMER_IN]-> (Contract)

(Company: GeneralContractor) -[:CONTRACTOR_IN]-> (Contract)

(Project) -[:HAS_STAGE]-> (Stage: Construction)

(Project) -[:HAS_RISK {severity:"high"}]-> (Risk)

(Project) -[:LOCATED_AT]-> (Location)

معمارية API

تكفي REST API v1 للنسخة الأولية. يمكن لاحقاً إضافة GraphQL للشاشات المعقدة للرسم البياني.

القواعد العامة لـ API

البادئة الأساسية

/api/v1

الصيغة

{

  "data": {},

  "meta": {},

  "error": null

}

خطأ

{

  "data": null,

  "meta": {},

  "error": {

    "code": "PROJECT_NOT_FOUND",

    "message": "Project not found"

  }

التخويل Authorization: Bearer <token>

Auth API. POST /auth/login. تسجيل الدخول.

Request

{

  "email": "user@example.com",

  "password": "secret"

}

Response

{

  "data": {

    "accessToken": "jwt",

    "refreshToken": "jwt",

    "user": {

      "id": "uuid",

      "fullName": "إيفان بيتروف",

      "email": "user@example.com",

      "roles": ["customer"]

    }

  },

  "meta": {},

  "error": null

}

POST /auth/refresh. تحديث الرمز.

GET /auth/me. ملف تعريف المستخدم الحالي.

واجهة برمجة تطبيقات الشركات

GET /companies. قائمة الشركات. المعاملات:

• search
• companyType
• status
• page
• limit

POST /companies. إنشاء شركة.

Request

{

  "name": "شركة سترويغراد ذات المسؤولية المحدودة",

  "shortName": "سترويغراد",

  "inn": "1234567890",

  "ogrn": "1234567890123",

  "companyType": "contractor",

  "website": "https://example.com"

}

GET /companies/{id}. بطاقة الشركة.

PATCH /companies/{id}. تحديث الشركة.

GET /companies/{id}/projects. مشاريع الشركة.

GET /companies/{id}/relations. روابط الشركة في الرسم البياني.

Response

{

  "data": {

    "nodes": [

      { "id": "c1", "type": "company", "name": "شركة سترويغراد ذات المسؤولية المحدودة" },

      { "id": "p1", "type": "project", "name": "مجمع سيفر السكني" }

    ],

    "edges": [

      {

        "from": "c1",

        "to": "p1",

        "type": "PARTICIPATES_IN",

        "role": "contractor",

        "status": "active"

      }

    ]

  },

  "meta": {},

  "error": null

}

واجهة برمجة تطبيقات المشاريع

GET /projects. قائمة المشاريع. المرشحات:

• status
• lifecycleStage
• regionId
• customerCompanyId
• search
• page
• limit

POST /projects. إنشاء مشروع.

Request

{

  "name": "مجمع سيفر السكني"،

  "description": "مجمع سكني متعدد الوظائف"،

  "projectType": "residential",

  "lifecycleStage": "design",

  "status": "normal",

  "location": {

    "regionId": "uuid",

    "address": "سانت بطرسبرغ، ..."،

    "lat": 59.93,

    "lon": 30.31,

    "cadastralNumber": "78:00:0000000:1234"

  },

  "customerCompanyId": "uuid",

  "startDate": "2026-04-01",

  "endDate": "2028-10-31",

  "plannedBudget": 2500000000

}

GET /projects/{id}. بطاقة المشروع.

PATCH /projects/{id}. تحديث المشروع.

GET /projects/{id}/graph. نقطة النهاية الرئيسية للحد الأدنى القابل للتطبيق. تعيد عقد وحواف الكائن.

Response

{

  "data": {

    "project": {

      "id": "uuid",

      "name": "مجمع سيفر السكني"،

      "status": "risk",

      "lifecycleStage": "construction"

    },

    "nodes": [

      { "id": "p1", "type": "project", "name": "مجمع سيفر السكني", "status": "risk" },

      { "id": "c1", "type": "company", "name": "العميل ديفيلوبمنت", "status": "active" },

      { "id": "c2", "type": "company", "name": "المقاول العام 1", "status": "active" },

      { "id": "r1", "type": "risk", "name": "تأخر المواعيد", "status": "open" }

    ],

    "edges": [

      { "from": "c1", "to": "p1", "type": "PARTICIPATES_IN", "role": "customer", "status": "active" },

      { "from": "c2", "to": "p1", "type": "PARTICIPATES_IN", "role": "general_contractor", "status": "active" },

      { "from": "p1", "to": "r1", "type": "HAS_RISK", "severity": "high" }

    ]

  },

  "meta": {},

  "error": null

}

GET /projects/{id}/timeline. سجل التغييرات والأحداث.

GET /projects/{id}/metrics. مقاييس المشروع.

GET /projects/{id}/risks. قائمة المخاطر.

POST /projects/{id}/risks. إنشاء خطر.

GET /projects/{id}/documents. مستندات المشروع.

POST /projects/{id}/documents. تحميل مستند.

GET /projects/{id}/companies. المشاركون في المشروع.

POST /projects/{id}/companies. إضافة مشارك إلى المشروع.

Request

{

  "companyId": "uuid",

  "role": "supplier",

  "startDate": "2026-05-01",

  "status": "active"

}

واجهة برمجة تطبيقات مراحل المشروع

GET /projects/{id}/stages. قائمة المراحل.

POST /projects/{id}/stages. إنشاء مرحلة.

PATCH /projects/{id}/stages/{stageId}. تحديث المرحلة.

واجهة برمجة تطبيقات العقود

GET /contracts. قائمة العقود. المرشحات:

• projectId
• customerCompanyId
• contractorCompanyId
• status

POST /contracts. إنشاء عقد.

Request

{

  "projectId": "uuid",

  "contractNumber": "C-2026-001",

  "contractType": "general_contract",

  "customerCompanyId": "uuid",

  "contractorCompanyId": "uuid",

  "amount": 1500000000,

  "currency": "RUB",

  "dateStart": "2026-04-10",

  "dateEnd": "2027-12-20",

  "status": "active"

}

GET /contracts/{id}. بطاقة العقد.

PATCH /contracts/{id}. تحديث عقد.

واجهة برمجة تطبيقات المخاطر

GET /risks. القائمة العامة للمخاطر. المرشحات:

• projectId
• severity
• status
• relatedCompanyId

POST /risks. إنشاء خطر.

PATCH /risks/{id}. تعديل خطر.

POST /risks/{id}/resolve. إغلاق خطر.

واجهة برمجة تطبيقات المستندات

GET /documents/{id}. البيانات الوصفية للمستند.

GET /documents/{id}/download تنزيل الملف.

واجهة برمجة تطبيقات الرسم البياني. هذه خدمة منفصلة لأنها قلب النظام.

GET /graph/projects/{id}

الرسم البياني للمشروع.

GET /graph/companies/{id}

الرسم البياني للشركة.

POST /graph/query

استعلام بحثي أو تحليلي إلى الرسم البياني. بالنسبة إلى MVP من الأفضل الاقتصار على استعلامات قالبية بدلا من إتاحة Cypher حر.

Request

{

  "queryType": "project_neighbors",

  "entityId": "uuid",

  "depth": 2

}

GET /graph/search. البحث عن الكيانات في الرسم البياني:

• q
• type

واجهة برمجة تطبيقات التحليلات

GET /analytics/dashboard

المؤشرات المجمعة:

• عدد المشاريع
• عدد المشاريع الإشكالية
• عدد المخاطر المفتوحة
• عدد الشركات النشطة

GET /analytics/projects/status-summary

ملخص حسب حالات المشاريع.

GET /analytics/companies/top-contractors

أفضل المتعاقدين حسب عدد المشاريع.

GET /analytics/risks/hotspots

أين تتركز أكبر قدر من المخاطر.

واجهة برمجة تطبيقات الأحداث

GET /events

سجل الأحداث. المرشحات:

• projectId
• companyId
• eventType
• from
• to

التقسيم إلى خدمات. بالنسبة إلى MVP تكفي 5 خدمات.

auth-service

• login
• refresh
• me
• users
• roles

directory-service

• companies
• regions
• locations

project-service

• projects
• stages
• contracts
• documents
• risks
• metrics
• events

graph-service

• graph endpoints
• sync from PostgreSQL to Neo4j
• graph queries

analytics-service

• dashboards
• summaries
• alerts

مزامنة PostgreSQL وNeo4j

هذه نقطة مهمة. مصدر الحقيقة للبطاقات هو PostgreSQL. مصدر الحقيقة للعلاقات والمسارات هو Neo4j.

النهج. بعد إنشاء الكيان أو تحديثه في PostgreSQL:

• نكتب سجلا في events
• ننشر حدثا
• يقوم graph-service بتحديث الرسم البياني

أمثلة على الأحداث:

• project.created
• project.updated
• company.added_to_project
• contract.created
• risk.created

أدنى حد من DTO

CreateProjectDto

{

  "name": "string",

  "description": "string",

  "projectType": "residential",

  "lifecycleStage": "design",

  "status": "normal",

  "customerCompanyId": "uuid",

  "startDate": "2026-04-01",

  "endDate": "2027-12-31",

  "plannedBudget": 1000000

}

AddCompanyToProjectDto

{

  "companyId": "uuid",

  "role": "contractor",

  "startDate": "2026-04-01",

  "endDate": null,

  "status": "active"

}

CreateRiskDto

{

  "projectId": "uuid",

  "relatedCompanyId": "uuid",

  "riskType": "deadline_delay",

  "severity": "high",

  "probability": "medium",

  "description": "تأخر عن الجدول الزمني بمقدار 21 يوم"

}

ما يجب إنجازه بالضرورة في الإصدار الأول

بدون هذا سيكون MVP فارغا:

إلزامي

• projects
• companies
• contracts
• risks
• events
• GET /projects/{id}/graph
• GET /companies/{id}/relations

يمكن تأجيله

• وثائق معقدة
• تحليلات موسعة
• IoT
• مستودع BIM
• سوق إلكتروني

الحزمة الموصى بها مباشرة لهذا المخطط

Backend

• NestJS
• PostgreSQL
• Prisma أو TypeORM
• Neo4j
• Redis للتخزين المؤقت وقوائم الانتظار
• Swagger/OpenAPI للتوثيق

Frontend

• Next.js
• React Query
• Cytoscape.js للرسم البياني
• Tailwind CSS أو MUI

Infra

• Docker
• Docker Compose للنسخة الأولية
• Nginx
• مستودع متوافق مع S3 للوثائق

هيكل المستودع

/crystal-construction

  /apps

    /api-gateway

    /auth-service

    /directory-service

    /project-service

    /graph-service

    /analytics-service

    /web-client

  /packages

    /shared-types

    /shared-utils

    /ui

  /infra

    /docker

    /nginx

    /db

  /docs

    openapi.yaml

    database-schema.md

    graph-model.md

الترتيب الأصح للبناء

• تشغيل خدمة المصادقة auth-service
• تشغيل خدمة الدليل directory-service
• إنشاء خدمة المشاريع project-service
• إنشاء خدمة الرسم البياني graph-service
• ربط واجهة المستخدم بـ GET /projects/{id}/graph
• إضافة المخاطر والأحداث
• إضافة لوحة المعلومات dashboard

يجب أن تجيب النسخة الأولية MVP على 4 سؤالاً:

• ما هذا الكائن؟
• من يرتبط به؟
• أين الخطر؟
• ماذا يحدث الآن؟

إذا كانت واجهة API وقاعدة البيانات توفران ذلك، فلديك بالفعل نواة عاملة لبلورة البناء.

1. مسودة OpenAPI

فيما يلي هيكل مختصر لكنه عامل لمواصفة OpenAPI 3.1 للنسخة الأولية MVP.

openapi: 3.1.0

info:

  title: Crystal Construction API

  version: 1.0.0

  description: واجهة API للنسخة الأولية لمنصة "بلورة البناء"

servers:

  - url: https://api.crystal-construction.local/api/v1

tags:

  - name: Auth

  - name: Companies

  - name: Projects

  - name: Contracts

  - name: Risks

  - name: Graph

  - name: Analytics

paths:

  /auth/login:

    post:

      tags: [Auth]

      summary: دخول المستخدم

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/LoginRequest'

      responses:

        '200':

          description: دخول ناجح

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/AuthResponse'

  /auth/me:

    get:

      tags: [Auth]

      summary: الملف الشخصي للمستخدم الحالي

      security:

        - bearerAuth: []

      responses:

        '200':

          description: الملف الشخصي للمستخدم

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/UserProfileResponse'

  /companies:

    get:

      tags: [Companies]

      summary: قائمة الشركات

      security:

        - bearerAuth: []

      parameters:

        - in: query

          name: search

          schema: { type: string }

        - in: query

          name: companyType

          schema: { type: string }

        - in: query

          name: status

          schema: { type: string }

        - in: query

          name: page

          schema: { type: integer, minimum: 1, default: 1 }

        - in: query

          name: limit

          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }

      responses:

        '200':

          description: قائمة الشركات

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/CompanyListResponse'

    post:

      tags: [Companies]

      summary: إنشاء شركة

      security:

        - bearerAuth: []

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/CreateCompanyRequest'

      responses:

        '201':

          description: تم إنشاء الشركة

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/CompanyResponse'

  /companies/{id}:

    get:

      tags: [Companies]

      summary: بطاقة الشركة

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

      responses:

        '200':

          description: بيانات الشركة

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/CompanyResponse'

    patch:

      tags: [Companies]

      summary: تحديث الشركة

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/UpdateCompanyRequest'

      responses:

        '200':

          description: تم تحديث الشركة

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/CompanyResponse'

  /companies/{id}/relations:

    get:

      tags: [Graph]

      الملخص: مخطط علاقات الشركة

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

        - in: query

          name: depth

          schema: { type: integer, minimum: 1, maximum: 3, default: 1 }

      responses:

        '200':

          الوصف: مخطط الشركة

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/GraphResponse'

  /projects:

    get:

      tags: [Projects]

      الملخص: قائمة المشاريع

      security:

        - bearerAuth: []

      parameters:

        - in: query

          name: status

          schema: { type: string }

        - in: query

          name: lifecycleStage

          schema: { type: string }

        - in: query

          name: regionId

          schema: { type: string, format: uuid }

        - in: query

          name: customerCompanyId

          schema: { type: string, format: uuid }

        - in: query

          name: search

          schema: { type: string }

        - in: query

          name: page

          schema: { type: integer, default: 1 }

        - in: query

          name: limit

          schema: { type: integer, default: 20 }

      responses:

        '200':

          الوصف: قائمة المشاريع

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ProjectListResponse'

    post:

      tags: [Projects]

      الملخص: إنشاء مشروع

      security:

        - bearerAuth: []

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/CreateProjectRequest'

      responses:

        '201':

          الوصف: تم إنشاء المشروع

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ProjectResponse'

  /projects/{id}:

    get:

      tags: [Projects]

      الملخص: بطاقة المشروع

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

      responses:

        '200':

          الوصف: بيانات المشروع

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ProjectResponse'

    patch:

      tags: [Projects]

      الملخص: تحديث المشروع

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/UpdateProjectRequest'

      responses:

        '200':

          الوصف: تم تحديث المشروع

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ProjectResponse'

  /projects/{id}/graph:

    get:

      tags: [Graph]

      الملخص: مخطط المشروع

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

        - in: query

          name: depth

          schema: { type: integer, minimum: 1, maximum: 3, default: 2 }

      responses:

        '200':

          الوصف: مخطط المشروع

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ProjectGraphResponse'

  /projects/{id}/companies:

    post:

      tags: [Projects]

      الملخص: إضافة مشارك إلى المشروع

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/AddCompanyToProjectRequest'

      responses:

        '201':

          الوصف: تمت إضافة المشارك

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/OperationResponse'

  /contracts:

    get:

      tags: [Contracts]

      الملخص: قائمة العقود

      security:

        - bearerAuth: []

      parameters:

        - in: query

          name: projectId

          schema: { type: string, format: uuid }

        - in: query

          name: customerCompanyId

          schema: { type: string, format: uuid }

        - in: query

          name: contractorCompanyId

          schema: { type: string, format: uuid }

        - in: query

          name: status

          schema: { type: string }

      responses:

        '200':

          الوصف: قائمة العقود

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ContractListResponse'

    post:

      tags: [Contracts]

      الملخص: إنشاء عقد

      security:

        - bearerAuth: []

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/CreateContractRequest'

      responses:

        '201':

          الوصف: تم إنشاء العقد

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ContractResponse'

  /risks:

    get:

      tags: [Risks]

      الملخص: قائمة المخاطر

      security:

        - bearerAuth: []

      parameters:

        - in: query

          name: projectId

          schema: { type: string, format: uuid }

        - in: query

          name: severity

          schema: { type: string }

        - in: query

          name: status

          schema: { type: string }

      responses:

        '200':

          الوصف: قائمة المخاطر

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/RiskListResponse'

    post:

      tags: [Risks]

      الملخص: إنشاء خطر

      security:

        - bearerAuth: []

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/CreateRiskRequest'

      responses:

        '201':

          الوصف: تم إنشاء الخطر

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/RiskResponse'

  /risks/{id}/resolve:

    post:

      tags: [Risks]

      الملخص: إغلاق الخطر

      security:

        - bearerAuth: []

      parameters:

        - $ref: '#/components/parameters/IdPath'

      responses:

        '200':

          الوصف: تم إغلاق الخطر

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/RiskResponse'

  /analytics/dashboard:

    get:

      tags: [Analytics]

      الملخص: لوحة معلومات MVP

      security:

        - bearerAuth: []

      responses:

        '200':

          الوصف: تحليلات مجمعة

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/DashboardResponse'

components:

  securitySchemes:

    bearerAuth:

      type: http

      scheme: bearer

      bearerFormat: JWT

  parameters:

    IdPath:

      in: path

      name: id

      required: true

      schema:

        type: string

        format: uuid

  schemas:

    ApiError:

      type: object

      properties:

        code: { type: string }

        message: { type: string }

      required: [code, message]

    LoginRequest:

      type: object

      properties:

        email: { type: string, format: email }

        password: { type: string }

      required: [email, password]

    AuthUser:

      type: object

      properties:

        id: { type: string, format: uuid }

        fullName: { type: string }

        email: { type: string, format: email }

        roles:

          type: array

          items: { type: string }

      required: [id, fullName, email, roles]

    AuthResponse:

      type: object

      properties:

        data:

          type: object

          properties:

            accessToken: { type: string }

            refreshToken: { type: string }

            user:

              $ref: '#/components/schemas/AuthUser'

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    UserProfileResponse:

      type: object

      properties:

        data:

          $ref: '#/components/schemas/AuthUser'

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    Company:

      type: object

      properties:

        id: { type: string, format: uuid }

        name: { type: string }

        shortName: { type: string }

        inn: { type: string }

        ogrn: { type: string }

        companyType: { type: string }

        rating: { type: number }

        status: { type: string }

        website: { type: string, nullable: true }

      required: [id, name, companyType, status]

    CreateCompanyRequest:

      type: object

      properties:

        name: { type: string }

        shortName: { type: string }

        inn: { type: string }

        ogrn: { type: string }

        companyType: { type: string }

        website: { type: string }

      required: [name, inn, ogrn, companyType]

    UpdateCompanyRequest:

      type: object

      properties:

        name: { type: string }

        shortName: { type: string }

        companyType: { type: string }

        rating: { type: number }

        status: { type: string }

        website: { type: string }

    CompanyResponse:

      type: object

      properties:

        data:

          $ref: '#/components/schemas/Company'

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    CompanyListResponse:

      type: object

      properties:

        data:

          type: array

          items:

            $ref: '#/components/schemas/Company'

        meta:

          type: object

          properties:

            page: { type: integer }

            limit: { type: integer }

            total: { type: integer }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    LocationInput:

      type: object

      properties:

        regionId: { type: string, format: uuid }

        address: { type: string }

        lat: { type: number }

        lon: { type: number }

        cadastralNumber: { type: string }

      required: [regionId, address]

    Project:

      type: object

      properties:

        id: { type: string, format: uuid }

        code: { type: string }

        name: { type: string }

        description: { type: string, nullable: true }

        projectType: { type: string }

        lifecycleStage: { type: string }

        status: { type: string }

        customerCompanyId: { type: string, format: uuid }

        startDate: { type: string, format: date, nullable: true }

        endDate: { type: string, format: date, nullable: true }

        plannedBudget: { type: number, nullable: true }

        actualBudget: { type: number, nullable: true }

      required: [id, name, projectType, lifecycleStage, status]

    CreateProjectRequest:

      type: object

      properties:

        name: { type: string }

        description: { type: string }

        projectType: { type: string }

        lifecycleStage: { type: string }

        status: { type: string }

        location:

          $ref: '#/components/schemas/LocationInput'

        customerCompanyId: { type: string, format: uuid }

        startDate: { type: string, format: date }

        endDate: { type: string, format: date }

        plannedBudget: { type: number }

      required:

        - name

        - projectType

        - lifecycleStage

        - status

        - location

        - customerCompanyId

    UpdateProjectRequest:

      type: object

      properties:

        name: { type: string }

        description: { type: string }

        lifecycleStage: { type: string }

        status: { type: string }

        actualBudget: { type: number }

        endDate: { type: string, format: date }

    ProjectResponse:

      type: object

      properties:

        data:

          $ref: '#/components/schemas/Project'

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    ProjectListResponse:

      type: object

      properties:

        data:

          type: array

          items:

            $ref: '#/components/schemas/Project'

        meta:

          type: object

          properties:

            page: { type: integer }

            limit: { type: integer }

            total: { type: integer }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    GraphNode:

      type: object

      properties:

        id: { type: string }

        type: { type: string }

        name: { type: string }

        status: { type: string, nullable: true }

        metadata:

          type: object

          additionalProperties: true

      required: [id, type, name]

    GraphEdge:

      type: object

      properties:

        from: { type: string }

        to: { type: string }

        type: { type: string }

        role: { type: string, nullable: true }

        status: { type: string, nullable: true }

        metadata:

          type: object

          additionalProperties: true

      required: [from, to, type]

    GraphResponse:

      type: object

      properties:

        data:

          type: object

          properties:

            nodes:

              type: array

              items: { $ref: '#/components/schemas/GraphNode' }

            edges:

              type: array

              items: { $ref: '#/components/schemas/GraphEdge' }

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    ProjectGraphResponse:

      type: object

      properties:

        data:

          type: object

          properties:

            project:

              $ref: '#/components/schemas/Project'

            nodes:

              type: array

              items: { $ref: '#/components/schemas/GraphNode' }

            edges:

              type: array

              items: { $ref: '#/components/schemas/GraphEdge' }

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    CreateContractRequest:

      type: object

      properties:

        projectId: { type: string, format: uuid }

        contractNumber: { type: string }

        contractType: { type: string }

        customerCompanyId: { type: string, format: uuid }

        contractorCompanyId: { type: string, format: uuid }

        amount: { type: number }

        currency: { type: string }

        dateStart: { type: string, format: date }

        dateEnd: { type: string, format: date }

        status: { type: string }

      required:

        - projectId

        - contractNumber

        - contractType

        - customerCompanyId

        - contractorCompanyId

        - amount

        - currency

        - status

    Contract:

      type: object

      properties:

        id: { type: string, format: uuid }

        projectId: { type: string, format: uuid }

        contractNumber: { type: string }

        contractType: { type: string }

        customerCompanyId: { type: string, format: uuid }

        contractorCompanyId: { type: string, format: uuid }

        amount: { type: number }

        currency: { type: string }

        status: { type: string }

      required: [id, projectId, contractNumber, contractType, amount, currency, status]

    ContractResponse:

      type: object

      properties:

        data:

          $ref: '#/components/schemas/Contract'

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    ContractListResponse:

      type: object

      properties:

        data:

          type: array

          items: { $ref: '#/components/schemas/Contract' }

        meta: { type: object }

        error:

          oneOf:

            - $ref: '#/components/schemas/ApiError'

            - { type: 'null' }

    CreateRiskRequest:

      type: object

      properties:

        projectId: { type: string, format: uuid }

        relatedCompanyId: { type: string, format: uuid, nullable: true }

        riskType: { type: string }

        severity: { type: string }

        probability: { type: string }

        description: { type: string }

      required: [projectId, riskType, severity, probability, description]

    Risk:

      type: object

      properties:

        id: { type: string, format: uuid }

        projectId: { type: string, format: uuid }

        relatedCompanyId: { type: string, format