بناء مشروع نظامي إدارة المجمعات ومبيعات الوحدات السكنية

المواصفات الكاملة للمشروع — نظامي إدارة المجمعات ومبيعات الوحدات السكنية

1. مقدمة عامة

المشروع يتكون من نظامين منفصلين، كل منهما يمكن تفعيله بشكل مستقل، مع إمكانية الربط بينهما:

النظام A — إدارة المجمع السكني (Property & Community Management)

النظام B — مبيعات الوحدات السكنية وإدارة العقود والأقساط (Sales & Installment Management)

المنصات المستهدفة:

Web (Desktop / Admin)

Android App

iOS App

الهدف: إنشاء نظامين متكاملين قابلين للتعديل، مع إمكانيات التوسعة المستقبلية، وحفظ أفضل ممارسات البرمجة لتسهيل صيانة الكود وتطويره لاحقًا.

2. المتطلبات العامة المشتركة

2.1 البنية التقنية

Backend: Modular Monolith أو Microservices (REST/GraphQL)

Database: PostgreSQL (علاقات) + Redis (Cache/Locks)

Storage: S3-compatible لتخزين الملفات والعقود والصور

Authentication: OAuth2 / JWT، دعم 2FA

Realtime: WebSockets / Server-Sent Events للتنبيهات اللحظية

CI/CD: GitHub Actions / GitLab CI

Containerization: Docker + Kubernetes (اختياري)

Logging & Monitoring: ELK / Grafana + Prometheus

2.2 الأمن

TLS لكل الاتصالات

تشفير البيانات الحساسة (PII)

سياسات صلاحيات دقيقة (RBAC + ACL)

حماية ضد CSRF/XSS/SQLi

سجل تدقيق لجميع العمليات الحساسة

2.3 الأداء والتوافر

SLA: 99.9% uptime

Cache للبيانات الثابتة

نسخ احتياطية يومية واستراتيجية استرجاع (RPO/RTO)

Load Testing: دعم 1000 concurrent users على الأقل

2.4 توجيهات الجودة البرمجية

Backend: Node.js (NestJS) / Python (Django/DRF) / Java (Spring Boot)

Frontend Web: React + TypeScript

Mobile: Flutter أو React Native (كود مشترك)

معايير: ESLint/Prettier, Type checking, Unit & Integration Tests ≥70%

Documentation: OpenAPI/Swagger لكل API، README لكل خدمة، ARCHITECTURE.md

2.5 قابلية التعديل والتوسعة

تصميم Modular لكل نطاق وظيفي

دعم Feature Flags لتفعيل/تعطيل المميزات

Plugin System / Adapters لتكامل بوابات الدفع أو خدمات طرف ثالث

Configuration over Code: المعادلات، الرسوم، القوالب، جداول الدفع قابلة للتعديل عبر الواجهة

Event-driven architecture لربط الخدمات بدون تداخل

Formula Engine مع معادلات قابلة للتعديل من واجهة الإدارة

2.6 توثيق الكود

docstrings لكل Function/Class

توضيح المدخلات/المخرجات والآثار الجانبية

ملفات ARCHITECTURE.md وDATA_MODEL.md وAPI_GUIDE.md

أمثلة تشغيلية وقوالب للـ Dev environment

Type Definitions واضحة لجميع DTOs

3. النظام A — إدارة المجمعات السكنية

3.1 الفكرة العامة

نظام شامل لإدارة المجمعات/العمارات السكنية:

إدارة السكان

إدارة الوحدات

العقود السكنية

الفواتير

الدفع الإلكتروني

خدمات الحراسة والنظافة والصيانة

إدارة الصلاحيات والتقارير

3.2 إدارة الوحدات والسكان

تعريف الوحدة: رقم، نوع، مساحة، عدد غرف، الطابق، الخدمات، الحالة

بيانات السكان: مالك/مستأجر، أفراد الأسرة، مستندات، بيانات الاتصال، العقود المرتبطة، الفواتير السابقة، سجل السكن

3.3 العقود السكنية

أنواع العقود: إيجار، ملكية، تجديد، إنهاء عقد مبكر مع غرامة

محرر قوالب العقود

تعبئة بيانات تلقائية

توقيع إلكتروني

حفظ نسخة PDF

إدارة الإصدارات Versioning

ربط العقد بالفواتير والخدمات

3.4 الخدمات والفواتير

خدمات: كهرباء، ماء، إنترنت، حراسة، نظافة، صيانة

إنشاء فواتير دورية أو استثنائية

معادلات احتساب مرنة

إشعارات تلقائية عند إصدار الفاتورة

لوحة حسابات للسكان

3.5 الدفع الإلكتروني

دعم بوابات الدفع

دفع كامل أو جزئي

إشعارات الدفع الفورية

Webhooks للتحديث التلقائي

سجل الدفع قابل للتصدير

3.6 إدارة الحراسة والزوار

تسجيل دخول وخروج الزوار

التقاط صور الهوية

تسجيل Offline للحراس

إشعارات للتجاوزات

3.7 إدارة الصيانة

إنشاء طلب صيانة

تحديد الأولوية

رفع الصور والفواتير

جدولة الفنيين

إشعارات للسكان

3.8 لوحة الإدارة

إدارة المجمعات والوحدات

إدارة المستخدمين والصلاحيات

إدارة العقود والخدمات والفواتير

تقارير مالية وصيانة وزيارات

إدارة المعادلات الحسابية

4. النظام B — مبيعات الوحدات السكنية

4.1 الفكرة العامة

نظام متخصص لإدارة بيع الوحدات:

حجز الوحدات

البيع

الأقساط

الخرائط التفاعلية

العقود

التحصيل

التمويل

نقل الملكية

4.2 إدارة الوحدات والخرائط

خريطة تفاعلية للوحدات: متاحة، محجوزة، مباعة

عرض معلومات الوحدة عند الضغط

تحديثات لحظية

4.3 الحجز والدفعات

حجز مؤقت مع مهلة دفع

دفع مبلغ الحجز إلكترونيًا

انتهاء الحجز تلقائيًا عند عدم الدفع

4.4 إدارة العقود

قوالب عقود: Initial, Final, Finance, Transfer

محرر قوالب ديناميكي

Versioning للعقود

توقيع إلكتروني

PDF generation

Approval workflow: Draft → Legal → Finance → Final → Signed

الربط مع جدول الأقساط والدفعات

4.5 الأقساط والدفعات

جدول سداد ديناميكي لكل عقد

دفع أولى، أقساط دورية

إعادة جدولة

partial payments

prepayment handling

ربط كل دفعة مع القيد المحاسبي

4.6 نقل الملكية

احتساب الرسوم

تحويل الأقساط المتبقية

إصدار عقد جديد وربط البيانات

4.7 التقارير والتحليلات

مالية: المبيعات، التحصيل، الأقساط المتأخرة، الأرباح

إدارية: الحجوزات، الوحدات المتاحة، النشاطات، أداء المسوقين

5. مميزات إضافية مقترحة

Multi-Tenant SaaS

Dynamic Pricing Engine

Document OCR & Auto-Fill

Two-way Bank Reconciliation

Role-based Dashboards

Offline-first Mobile Apps

Third-party Integrations (ERP, Accounting, SMS/WhatsApp)

Tenant Portal & Owner Portal

White-labeling

Audit & Compliance Module

Multi-currency & FX handling

6. التوثيق البرمجي والتعليمات للمبرمج

docstrings لكل Function/Class

توضيح المدخلات والمخرجات والآثار الجانبية

ملفات ARCHITECTURE.md وDATA_MODEL.md وAPI_GUIDE.md

أمثلة تشغيلية وقوالب للـ Dev environment

Type Definitions واضحة لجميع DTOs

تعليمات التعليقات: TODO[ROLE-XYZ]: description، @deprecated

ملفات seed للبيانات التجريبية

Migration scripts مع rollback

README لكل Module

OpenAPI / Swagger لكل API

7. Acceptance Criteria / حالات قبول نهائية

فاتورة دورية: إنشاء الفواتير تلقائيًا عند تسجيل قراءة عداد، إرسال إشعارات، تسجيل الدفع.

بيع وحدة: تحويل الوحدة من available إلى sold في النظام B وoccupied في النظام A بعد استلام الدفعة الأولى.

توقيع العقد: ظهور PDF نهائي وتسجيل النسخة الموقعة رقمياً.

8. مستندات مرفقة للمبرمج

ER Diagram

OpenAPI / Postman collection

Wireframes / Figma (Dashboards, Sales map, Contract editor)

Sample contract template

Test cases CSV