# AI CRM · عقارات `01 · ai-crm · Delivered` Agent إنتاجي للـ AI مع tool API بأسلوب MCP من 19 endpoint، audit trail، وتسليم للمشغل. يؤهل leads العقار، يجري research للمشاريع، ويحجز viewings. **النطاق:** Solo · 7 أسابيع **الدور:** منصة full-stack مع Telegram agent مستقل **الفيديو:** [YouTube](https://www.youtube.com/watch?v=9FXcuA0-ars) · [RuTube](https://rutube.ru/video/private/581c7da02de2ce044aace99ed51fa0d8/?p=FQ-B4a3j63xJK0f8lzC8UQ) ## شرح الفيديو AI agent إنتاجي يدير محادثات العملاء في Telegram بينما يشرف المشغلون من admin panel محدد الصلاحيات — لوحة Kanban، تقويم، تأهيل الـ leads، research عميق للمشاريع، حجز viewings، وتسليم للمشغل. كل نداء AI يتتبع: التوكنز والتكلفة تظهر لكل عميل، بشكل منفصل بين المساعد الذي يحادث العميل والمساعد الذي يساعد المشغل. نظام CRM مدعوم بالذكاء الاصطناعي لوكالات العقار: العملاء يكلمون مساعد AI داخل تيليجرام، وفريقك يشوف كل شيء مرتب في مكان واحد. لوحة التحكم تعرض الصفقات، العملاء المحتملين، وضغط العمل على الفريق. ولوحة الكانبان تدير البايبلاين كامل: اسحب الكرت من مرحلة لمرحلة، والنظام يحفظ التغييرات والتاريخ تلقائياً. كل كرت يظهر على التقويم أيضاً. فلتر حسب المشغّل أو اللوحة، بدّل بين الشهر، الأسبوع أو اليوم، وافتح أي حدث لتشوف التفاصيل والكروت المرتبطة بذلك الموعد. ومن أي كرت تقدر تدخل مباشرة على المحادثة. الذكاء الاصطناعي يأهل العميل، يلقى المشاريع المناسبة، يسوي بحث عميق إذا احتاج، ويرسل كرت عقار تفاعلي داخل تيليجرام. العميل يتصفح الصور، الوحدات والتقارير بدون ما يطلع من التطبيق. ولما يكون جاهز، الـ AI يحجز له موعد معاينة، ويحفظ ملاحظة واضحة بالسياق للفريق. وإذا أحد من الفريق مسك المحادثة، الـ AI يتنحى ببساطة. المشغّلون عندهم أيضاً مساعد AI داخل النظام: اسأله عن أي عميل، ويرجع لك ملخص سريع ورد جاهز للإرسال، مبني على كامل سجل المحادثة. كل نداء AI يتتبع: التوكنز والتكلفة تظهر لكل عميل، بشكل منفصل بين المساعد اللي يكلم العميل والمساعد اللي يساعد المشغّل. والنظام يدعم الثيم الفاتح والداكن، مع مجموعة ألوان تمييز. --- ## السياق > المشغلون يديرون المكالمات والزيارات. والـ AI يدير الباقي. وكالات العقار التي تدير funnel عبر Telegram تستقبل inbound على مدار الساعة. الحجم يتجاوز قدرة فريق تشغيل صغير. آلاف المشاريع وعشرات آلاف الوحدات تتجاوز ما يمكن لأي شخص حفظه أثناء المحادثة. Chatbots الجاهزة ترد مرة بأسئلة شائعة ثم تتوقف؛ لا شيء ينقل المشتري من أول رسالة إلى موعد محجوز. الفصل ثابت: المشغلون يأخذون المكالمات والزيارات؛ وكل ما عدا ذلك — التأهيل، research عميق للمشروع والمنطقة، وجدولة حسب تقويم المشغل — يعمل بدونهم. ## حقائق | | | |---|---| | **النطاق** | 7 أسابيع solo | | **الأسطح** | CRM admin + Telegram WebApp (repo واحد · نقطتا دخول Vite) | | **الكتالوج** | آلاف المشاريع · عشرات آلاف الوحدات من GenieMap · raw_payload محفوظ | | **أدوات agent** | 19 endpoint داخلية + 5 callbacks · Bearer auth · envelope موحد | | **نموذج الصلاحيات** | 15 capability keys | | **الحالة** | تم التسليم · 20 pytest modules · structlog · respx | ## المعمارية ### دورة حياة الرسالة ```text 1 Client Telegram message │ 2 tg_bot │ POST /api/v1/conversations/messages/ [BOT_SHARED_TOKEN] ▼ 3 Backend (Django/DRF) │ upsert Conversation + Message[RECEIVED] │ Celery.dispatch_to_n8n_workflow.delay() ▼ 4 Celery worker │ POST {N8N_BASE_URL}/{webhook} [N8N_API_KEY] ▼ 5 n8n ──► LLM │ tool_call (projects-search, send-webapp, …) ▼ Agent Tools API [Bearer] │ data {data, meta, errors} ▼ LLM ──► final reply text │ 6 Backend ◄── callback /api/v1/integrations/n8n/ [N8N_CALLBACK_TOKEN] │ Message[AWAITING_CALLBACK → READY_TO_SEND] ▼ 7 Celery worker │ POST /bridge/send [TG_BRIDGE_TOKEN] ▼ 8 Telegram → Client Message[SENT] ``` **حالات الرسالة (7).** مسار خطي: RECEIVED → PROCESSING → AWAITING_CALLBACK → READY_TO_SEND → SENT. الفروع: AWAITING_OPERATOR إذا أوقف المشغل AI وسط المحادثة، وFAILED عند أي خطأ n8n. **لماذا bridge منفصل.** جلسة Telegram bot يملكها process واحد: tg_bot. Backend لا يفتح جلسة خاصة به؛ الإرسال للخارج يمر عبر HTTP bridge داخل نفس الحاوية. هكذا يبقى backend stateless تجاه Telegram. **أين يعيش AI.** داخل الخطوة 5 — n8n يملك LLM tool-loop. Backend يخدم callbacks وtool calls نفسها أثناء الحلقة. ### تخطيط المكونات ```text External tg_bot frontend (admin · webapp) ──────── ────── ─────────────────────────── Telegram ◄─────► aiogram + bridge React · Vite (×2 entries) │ │ BOT_SHARED ──┤ │ HTTPS · /api/v1 TG_BRIDGE ──┤ │ ▼ ▼ ┌───────────────────────────────────────────┐ │ Backend (Django · DRF · structlog) │ │ Single envelope: {data, meta, errors} │ └────┬─────────┬──────────┬─────────────────┘ │ │ │ ▼ ▼ ▼ Postgres 16 Redis 7 Celery worker + beat │ N8N_API_KEY ▼ n8n + n8n-worker (LLM tool-loops) │ N8N_CALLBACK_TOKEN ▼ Backend.callback ``` **تسع خدمات Docker.** postgres · redis · backend · celery · celery-beat · tg_bot · frontend · n8n · n8n-worker. n8n-worker منفذ منفصل يزيح flows الطويلة عن orchestrator. **Trust model.** كل cross-service call يحمل shared secret واضحا — bot bridge، n8n outbound، n8n callback، وagent-tool Bearer. لا توجد خدمة تثق بأخرى لمجرد أنها داخل نفس compose. **فصل frontend.** Repo Vite واحد، وHTML entryان: /admin للـ CRM و/webapp/:projectId لـ Telegram WebApp. المكونات وAPI client مشتركة؛ access control على نفس قواعد backend. ### نواة الدومين ```text CATALOG CONVERSATIONS ─────── ───────────── Project Conversation ├── Unit (×N) · status ├── ResearchBlock × 4 └── Message (×N, 7-state lifecycle) │ · core Note (manual + 3 system cards) │ · market & demand OperatorAssistantSession │ · legal & ops │ · dynamics & news ├── Amenity (×N) └── District (FK) KANBAN ────── USERS Board ───── └── Column User · capability strings └── Card · telegram_link └── Activity UserInvite CALENDAR GENIEMAP ──────── ──────── Calendar ProviderSyncLog ├── CalendarEvent · raw_payload preserved └── ScheduleRule · scheduled syncs ``` **37 models في 7 apps.** الدومين مفكك حسب bounded context: catalog · conversations · kanban · calendar · users · geniemap · auth. لا توجد god-table؛ كل entity له وظيفة واحدة. **Status enums لا bool flags.** كل دومين يحمل status enum خاصا به بدلا من parade من archived/is_active/is_draft. سطح قابل للإسقاط لكل دومين. **raw_payload محفوظ.** كل entity متزامن من GenieMap يحتفظ بالـ JSON الأصلي بجانب الأعمدة normalized. هذا يحمي من mapping drift ويجعل re-ingest رخيصا. ### Topologies الـ agent ![Four research-specialist agents (core, market & demand, legal & ops, dynamics & news), each on its own LLM, all sharing one web-search tool.](https://ilyadev.xyz/private/airea-n8n-specialists.png) *Specialists cluster, shared tool* ![A single chat agent wired to twelve tools — projects/districts search and research, calendar availability and create, send-webapp, admin-notify, context-save, user-note CRUD, web-search.](https://ilyadev.xyz/private/airea-n8n-omnimodel.png) *Omnimodel, twelve tools* **لماذا يعمل هذا.** الـ 19 endpoints مستقلة عن النموذج والـ orchestrator. تم اختبارها مع GPT وGemini فوق نفس tool API. ## قرارات هندسية رئيسية ### 01 · Capability overrides فوق role presets **القرار.** ثلاث role presets (OWNER · ADMIN · OPERATOR) تحدد مجموعة الصلاحيات الافتراضية؛ extra_capabilities وrevoked_capabilities لكل مستخدم تعطي overrides دقيقة. الفحص يمر عبر hasCapability() بدلا من role == "admin". **لماذا.** تركيبات المشغلين الواقعية لا تناسب enum من 3 أدوار — "dashboard نعم، user-management لا، AI-toggle نعم" حالة عادية. جدول roles فقط سينفجر؛ capabilities فقط تفقد default مريح. نموذج overrides يبقي الاثنين. **الكلفة.** طبقتان للتفكير عند debug access: preset + overrides. كان لا بد من hard-code للـ default role presets حتى تبقى UX مختصرة في onboarding. ### 02 · 19 أداة agent داخلية على Bearer + envelope موحد **القرار.** كل AI tool call يمر عبر /api/v1/agent/tools/... مع Bearer token خاص؛ وكل response يحمل نفس envelope: {data, meta, errors}. **لماذا.** n8n يعمل بلا user context — session auth لا يناسب. Bearer-edge يعطي LLM سطح minimum-privilege؛ شكل envelope واحد يجعل tool loop مستقرة. **الكلفة.** بعض endpoints مكررة حسب الجمهور (operator مقابل AI) — سطحان متوازيان بدلا من سطح واحد dual-auth. ### 03 · n8n لسطح no-code **القرار.** منطق agent يعيش في 4 n8n workflows؛ LLM tool-calls تتفرع إلى tool API الداخلي، وcallbacks تعود عبر webhook. **لماذا.** القيد كان وجود سطح no-code لتعديل agent-flow. n8n كان الخيار الواضح وقتها: شائع وناضج وله tool-calling وwebhooks. البديل — custom admin UI فوق tool-loop داخلي — كان سيضاعف نطاق MVP. **الكلفة.** Prompt ومنطق orchestration انقسما بين n8n flows وtool API الداخلي؛ n8n-worker خدمة منفصلة. الدرس اللاحق موجود في §06. ### 04 · Research كـ state machine من 4 blocks **القرار.** Research لكل مشروع ينقسم إلى 4 blocks: core، market & demand، legal & ops، dynamics & news، وكل block يدور EMPTY → PENDING → READY | FAILED. callbacks من n8n تعيد كل block عند اكتماله، والواجهة تعرض النتائج block-by-block. **لماذا.** تشغيل research عميق يستغرق دقائق؛ حبس LLM tool-loop سيجمد Telegram chat. UX حسب block يعرض نتائج جزئية بدلا من الانتظار الكامل. **الكلفة.** كل block له prompt ومصادر بحث خاصة — صيانة pipeline تكبر خطيا مع عدد blocks. ## التقنيات | | | |---|---| | **Backend** | Python · Django · DRF · Celery · structlog · aiogram | | **Frontend** | React · Vite · Tailwind 4 · Radix UI · MapLibre GL · react-router 7 | | **Infra** | PostgreSQL · Redis · Docker Compose | | **AI · orch.** | Gemini, OpenAI · n8n (model-agnostic) | | **Agent surface** | 19 tool endpoints داخلية + 5 callbacks · Bearer auth · {data, meta, errors} envelope | | **Scale** | 12 Django apps · 224 frontend modules · 20 pytest modules · ~56K LOC | ## الدروس والحالة ### ما سأحمله للأمام - Capability overrides فوق role presets — role أساسي يعطي default واضحا، وextra/revoked keys تغطي الحالات الطويلة بدون اختراع أدوار جديدة. - Envelope واحد `{data, meta, errors}` لكل API response — tool-loop مملة ومستقرة هي feature وليست bug. - UX operator console — kanban + chat + calendar في shell واحد، مع handoff بشري داخل نفس thread عند الطلب. - انضباط audit trail — X-Request-ID ممتد عبر structlog في كل cross-service hop. بدونه ينهار debugging لـ LLM tool-loop. ### ما سأغيره - اختيار Django كان reflex. السطح المستخدم فعليا — ORM وrouting وapp structure — بقي خفيفا، بينما DRF أضاف boilerplate حول كل endpoint، وclass-based permissions اصطدمت بنموذج capability strings. FastAPI + Pydantic + async SQLAlchemy كان أقرب لشكل API-only الذي انتهى إليه المشروع. - n8n لم يبرر وزنه — معظم تعديلات flow كانت في prompts أو tool API. اليوم سأشغل tool-loop داخلي وأبني UI رقيقة فقط حيث تحدث التعديلات فعلا. - 9 Docker services كثيرة على MVP. اليوم: n8n + n8n-worker يخرجان، celery-beat يندمج مع celery كperiodic، والـ frontend في production يصبح static files خلف backend. النتيجة 4 خدمات: postgres، redis، backend، celery. تم البناء والنشر والتسليم عند إغلاق engagement؛ code walkthrough عند الطلب. --- المصدر: https://ilyadev.xyz/cases/ai-crm (HTML) · /cases/ai-crm.ar.md (هذا الملف) التالي: 02 — Restaurant Stock AI Agent · مخزون المطاعم → https://ilyadev.xyz/cases/ai-warehouse.ar.md الفهرس: https://ilyadev.xyz/llms-ar.txt — قائمة دراسات الحالة الكاملة المؤلف: إليا كازانتسيف — https://ilyadev.xyz/index.ar.md