استخدام Cursor Canvas للتخطيط البصري للمشاريع

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

ما هو Cursor Canvas؟

Canvas هو مساحة عمل بصرية حيث يمكنك:

• رسم مخططات البنية بالمربعات والأسهم والتعليقات التوضيحية
• ربط عناصر الكود عن طريق سحب الملفات أو الدوال أو الأصناف إلى اللوحة
• تخطيط الميزات بصريًا قبل كتابة أي كود
• المشاركة مع فريقك عن طريق نشر لوحات Canvas كروابط مستقلة
• إضافة تعليقات توضيحية على القرارات بالملاحظات ومهام TODO ومبررات التصميم

الفرق الرئيسي عن الأدوات الخارجية مثل Miro أو Figma هو أن Canvas مدرك للسياق. عندما تضع مكوّنًا على اللوحة، فإنه يعرف مسار الملف الفعلي والصادرات والتبعيات الخاصة بذلك المكوّن.

المتطلبات الأساسية

• Cursor إصدار 0.42 أو أحدث (تم تقديم Canvas في أواخر عام 2024)
• مجلد مشروع مفتوح في Cursor (يعمل Canvas ضمن سياق المشروع)
• حساب Cursor لميزات النشر (الطبقة المجانية كافية)

إنشاء لوحة Canvas الأولى

الخطوة 1: فتح محرر Canvas

هناك ثلاث طرق لفتح لوحة Canvas جديدة:

1. لوحة الأوامر: Cmd/Ctrl + Shift + P واكتب Canvas: New Canvas
2. الشريط الجانبي: انقر على أيقونة Canvas في شريط النشاط (الشريط الجانبي الأيسر)
3. اختصار لوحة المفاتيح: Cmd/Ctrl + Shift + C (قابل للتهيئة في الإعدادات)

الخطوة 2: إضافة عناصر إلى اللوحة

ابدأ بلوحة فارغة. يمكنك إضافة أنواع العناصر التالية:

العنصر	طريقة الإضافة	الغرض
عقدة ملف	اسحب ملفًا من المستكشف	يعرض الملف وعلاقاته
عقدة دالة	انقر بزر الماوس الأيمن على دالة > "Add to Canvas"	تصور مخطط استدعاءات الدوال
مربع نص	انقر نقرًا مزدوجًا على مساحة فارغة في اللوحة	أضف ملاحظات أو تسميات أو قرارات
شكل	انقر على أداة الأشكال في شريط الأدوات	ارسم مربعات أو دوائر أو أسهم
صورة	اسحب ملف صورة أو الصق من الحافظة	أدرج لقطات شاشة أو نماذج أولية

الخطوة 3: ربط العناصر

ارسم أسهم بين العناصر لإظهار العلاقات:

1. مرر المؤشر فوق عنصر حتى تظهر نقاط الاتصال
2. انقر واسحب من نقطة اتصال إلى عنصر آخر
3. اترك لإنشاء اتصال
4. اختياريًا، أضف تسمية للاتصال (مثل "imports" أو "calls" أو "extends")

الخطوة 4: حفظ اللوحة

يتم حفظ لوحات Canvas كملفات .canvas في مشروعك:

my-project/
  .cursor/
    canvases/
      architecture-overview.canvas
      feature-auth-flow.canvas
      sprint-planning.canvas

تلميح

سمِّ لوحات Canvas بأسماء وصفية. ملفات Canvas قابلة للتحكم في الإصدارات، بحيث يمكن لفريقك تتبع تطور المخططات بمرور الوقت. أضف مجلد canvases/ إلى مستودعك وقم بإيداعها مع الكود الخاص بك.

نشر Canvas

ينشئ نشر لوحة Canvas رابطًا قابلًا للمشاركة يمكن لأي شخص عرضه في متصفح، حتى دون تثبيت Cursor. هذا مفيد لمشاركة قرارات البنية المعمارية مع أصحاب المصلحة أو لتهيئة أعضاء الفريق الجدد.

كيفية النشر

1. افتح لوحة Canvas التي تريد نشرها
2. انقر على زر Publish في شريط الأدوات العلوي الأيمن
3. اختر مستوى الرؤية:
   • خاص - فقط الأشخاص الذين لديهم الرابط وحساب Cursor يمكنهم العرض
   • غير مدرج - أي شخص لديه الرابط يمكنه العرض (لا يتطلب حسابًا)
   • عام - قابل للاكتشاف والعرض من قبل أي شخص
4. انقر على Publish
5. انسخ عنوان URL الذي تم إنشاؤه وشاركه

كيف يعمل النشر داخليًا

عند نشر لوحة Canvas، يقوم Cursor بـ:

1. تحويل اللوحة إلى تنسيق محمول
2. رفعه إلى التخزين السحابي الخاص بـ Cursor
3. إنشاء مفتاح مشروع فريد للنسخة المنشورة
4. إرجاع عنوان URL يحتوي على ذلك المفتاح

warning

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

إدارة مفتاح المشروع

كل لوحة Canvas، سواء كانت محلية أو منشورة، مرتبطة بمفتاح مشروع. فهم كيفية عمل مفاتيح المشروع أمر ضروري لاستكشاف أخطاء النشر وإصلاحها.

ما هو مفتاح المشروع؟

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

مشكلة مفتاح المشروع المؤقت لكل تشغيل

يبلغ مستخدمو المنتدى بشكل متكرر أن نشر لوحة Canvas يفشل مع رسالة "لم يتم العثور على ملف Canvas". السبب الجذري هو أن Cursor ينشئ مفتاح مشروع مؤقتًا عند كل تشغيل عندما لا يعثر على مفتاح دائم.

إليك ما يحدث:

1. تفتح Cursor، وتقوم بتعيين مفتاح مشروع مؤقت مثل tmp_abc123
2. تنشئ وتعمل على لوحة Canvas مرتبطة بـ tmp_abc123
3. تنقر على Publish
4. يبحث نقطة نهاية النشر عن اللوحة باستخدام مفتاح المشروع الحالي
5. إذا تغير المفتاح (لأنه تم إعادة تشغيل Cursor)، يفشل البحث
6. ترى "لم يتم العثور على ملف Canvas"

إصلاح مشكلة مفتاح المشروع

الحل 1: إنشاء مفتاح مشروع دائم

أضف ملف .cursor/project.json إلى جذر مشروعك:

{
  "projectKey": "persistent-key-my-project-2024",
  "projectName": "My Project",
  "createdAt": "2024-01-15T10:00:00Z"
}

يضمن هذا بقاء مفتاح المشروع مستقرًا عبر عمليات إعادة تشغيل Cursor.

تلميح

استخدم مفتاح مشروع وصفيًا وفريدًا. لا تستخدم قيمًا عامة مثل project1 أو test. إذا كان لمشروعين على جهازك نفس المفتاح، فقد تتعارض عمليات البحث عن لوحات Canvas، وسيفشل النشر بشكل متقطع.

الحل 2: إعادة ربط اللوحة

إذا كان لديك بالفعل لوحة بمفتاح مؤقت قديم:

1. أغلق اللوحة في Cursor
2. افتح ملف .canvas في محرر نصوص
3. ابحث عن حقل projectKey
4. حدّثه ليطابق مفتاحك الدائم
5. احفظ وأعد الفتح في Cursor
6. حاول النشر مرة أخرى

ملف .canvas مبني على JSON، والقسم ذو الصلة يبدو كالتالي:

{
  "version": "1.0",
  "projectKey": "tmp_abc123",
  "elements": [...],
  "connections": [...]
}

غيّر tmp_abc123 إلى مفتاحك الدائم.

الحل 3: مسح ذاكرة التخزين المؤقت لـ Canvas

إذا لم تعمل الحلول أعلاه، فقد تكون ذاكرة التخزين المؤقت المحلية لـ Canvas تالفة:

1. أغلق Cursor
2. انتقل إلى دليل ذاكرة التخزين المؤقت لـ Cursor:
   • macOS: ~/Library/Application Support/Cursor/canvas-cache/
   • Windows: %APPDATA%/Cursor/canvas-cache/
   • Linux: ~/.config/Cursor/canvas-cache/
3. احذف محتويات مجلد canvas-cache
4. أعد فتح Cursor
5. أعد فتح ملف اللوحة الخاص بك
6. حاول النشر مرة أخرى

warning

مسح ذاكرة التخزين المؤقت لـ Canvas لن يحذف ملفات .canvas الخاصة بك (تلك موجودة في مشروعك). إنه يزيل فقط جداول البحث المؤقتة التي تعيّن مفاتيح المشروع إلى البيانات الوصفية للوحة Canvas. يتم الحفاظ على محتوى اللوحة الفعلي.

Canvas المستقل مقابل تطبيق Glass App

يتوفر Canvas في سياقين داخل نظام Cursor البيئي، وهناك اختلافات مهمة.

Canvas المستقل (Cursor IDE)

هذه هي اللوحة التي تصل إليها من داخل محرر Cursor:

• تعيش في دليل .cursor/canvases/ الخاص بك
• مرتبطة مباشرة بمشروعك المفتوح
• يمكنك سحب الملفات من المستكشف إلى اللوحة
• تستخدم مفتاح المشروع من .cursor/project.json
• الأفضل لـ: المخططات الموجهة للمطورين، وتخطيط البنية المعمارية، وتخطيط الكود

Canvas في تطبيق Glass App

Glass هو تطبيق بصري مستقل من Cursor (منفصل عن IDE). Canvas داخل Glass:

• يعيش في مساحة التخزين الخاصة بـ Glass، وليس دليل المشروع الخاص بك
• يمكن ربطه بمشروع ولكنه يعمل بشكل مستقل
• لديه مساحة أسماء مختلفة لمفاتيح المشروع
• يدعم عناصر بصرية أكثر ثراءً (الرسوم المتحركة، والمكونات التفاعلية)
• الأفضل لـ: العروض التقديمية، وعروض أصحاب المصلحة، والمشاركة عبر الفرق

الاختلافات الرئيسية

الميزة	Canvas المستقل	Canvas في تطبيق Glass App
موقع التخزين	.cursor/canvases/	التخزين السحابي لـ Glass
مصدر مفتاح المشروع	.cursor/project.json	إعدادات مشروع Glass
السحب والإفلات للملفات	نعم، من المستكشف	لا، يجب الاستيراد
التعاون في الوقت الفعلي	لا	نعم
نطاق النشر	حساب Cursor	مساحة عمل Glass
التحرير دون اتصال	نعم	لا (يتطلب اتصالًا)

تلميح

إذا كنت تعمل بشكل أساسي في Cursor IDE، فاستخدم Canvas المستقل لتخطيط التطوير. استخدم Canvas في تطبيق Glass App عندما تحتاج إلى التقديم لأصحاب المصلحة غير التقنيين أو التعاون في الوقت الفعلي. الاثنان غير قابلين للتبديل، ومحاولة استخدام Canvas في Glass لمهام تخطيط الكود ستكون محبطة لأنه لا يمكنه الإشارة إلى الملفات المباشرة.

الترحيل بين Canvas المستقل و Glass

يمكنك تصدير لوحة Canvas مستقلة واستيرادها إلى Glass:

1. افتح اللوحة في Cursor
2. انقر على Export > Export as Glass-compatible
3. احفظ ملف .glass-canvas
4. افتح Glass
5. انقر على Import وحدد الملف

لاحظ أن المراجع في اللوحة المصدّرة سيتم تحويلها إلى مراجع ثابتة (لن تتحدث إذا تغير الكود الأساسي).

تصميم سير العمل البصري

Canvas ليس فقط لمخططات البنية. إنها مساحة عمل بصرية للأغراض العامة. فيما يلي أنماط سير العمل الشائعة.

سير عمل تخطيط الميزات

1. أنشئ لوحة باسم feature-[name]-plan.canvas
2. أضف مربعات نص لمتطلبات الميزة
3. أضف عقد ملفات للملفات التي سيتم تعديلها
4. ارسم أسهمًا توضح تدفق البيانات
5. أضف مربعات نص TODO للأسئلة المفتوحة
6. شارك اللوحة مع الفريق قبل التنفيذ
7. استخدم اللوحة كمرجع أثناء التنفيذ

سير عمل مراجعة الكود

1. أنشئ لوحة لطلب السحب (PR) قيد المراجعة
2. اسحب الملفات المتغيرة إلى اللوحة
3. ارسم مخطط استدعاءات الدوال المتغيرة
4. أضف تعليقات توضيحية للمشكلات المحتملة بمربعات نص حمراء
5. انشر اللوحة وأضف رابطها في وصف طلب السحب

سير عمل التهيئة

1. أنشئ ملف project-architecture.canvas
2. أضف نقاط الدخول الرئيسية (مثل index.ts، app.tsx)
3. أضف الوحدات والخدمات الأساسية
4. ارسم مخطط التبعيات
5. أضف تعليقات توضيحية تشرح مسؤولية كل وحدة
6. انشر كرابط غير مدرج
7. شارك مع أعضاء الفريق الجدد في يومهم الأول

تلميح

اجعل لوحات Canvas للتهيئة عالية المستوى. اللوحة التي تحتوي على 200 عقدة أصعب في الفهم من قراءة الكود مباشرة. اهدف إلى 10-20 عنصرًا توضح الصورة الكبيرة، ودع الموظفين الجدد يتعمقون في الكود للتفاصيل.

ميزات Canvas المتقدمة

الاتصالات المدركة للكود

عندما تضيف دالة أو صنفًا إلى اللوحة، يمكن لـ Canvas اكتشاف تبعياتها تلقائيًا وعرض إضافتها:

1. انقر بزر الماوس الأيمن على عقدة دالة
2. حدد Show Dependencies
3. يسرد Canvas جميع الدوال والوحدات والأنواع التي تستخدمها الدالة
4. انقر على أي تبعية لإضافتها إلى اللوحة مع اتصال مرسوم تلقائيًا

قوالب Canvas

أنشئ قوالب Canvas قابلة لإعادة الاستخدام لأنواع المخططات الشائعة:

{
  "version": "1.0",
  "template": "microservice-architecture",
  "elements": [
    {"type": "text", "label": "API Gateway", "x": 400, "y": 50},
    {"type": "text", "label": "Auth Service", "x": 200, "y": 200},
    {"type": "text", "label": "User Service", "x": 600, "y": 200},
    {"type": "text", "label": "Database", "x": 400, "y": 350}
  ],
  "connections": [
    {"from": 0, "to": 1, "label": "routes to"},
    {"from": 0, "to": 2, "label": "routes to"},
    {"from": 1, "to": 3, "label": "reads/writes"},
    {"from": 2, "to": 3, "label": "reads/writes"}
  ]
}

احفظ هذا كملف .cursor/canvases/templates/microservice.canvas واستخدم Canvas: New from Template لإنشاء نسخة منه.

تضمين لوحات Canvas في الوثائق

يمكنك تضمين روابط لوحات Canvas المنشورة في وثائق مشروعك:

## Architecture Overview

See our [visual architecture diagram](https://canvas.cursor.sh/c/persistent-key-my-project-2024/architecture-overview) for the full system map.

Key components:
- API Gateway handles routing
- Auth Service manages JWT verification
- User Service handles profile CRUD

استكشاف الأخطاء الشائعة وإصلاحها

المشكلة: "لم يتم العثور على ملف Canvas" عند النشر

هذا هو الخطأ الأكثر شيوعًا. اتبع خطوات استكشاف أخطاء مفتاح المشروع أعلاه. إذا لم تحل تلك المشكلة:

1. تحقق من أن ملف .canvas موجود على القرص
2. تأكد من أن الملف غير مفتوح في تطبيق آخر (قفل الملف)
3. تأكد من أن لديك أذونات الكتابة على دليل .cursor/canvases/
4. تحقق من اتصالك بالإنترنت (يتطلب النشر الرفع إلى السحابة)

المشكلة: تختفي عناصر Canvas بعد إعادة التشغيل

السبب: يشير ملف اللوحة إلى العناصر بمعرفات داخلية قد تتغير إذا تغيرت بنية الكود الأساسية (مثل إعادة تسمية ملف أو حذفه).

الإصلاح:

1. افتح اللوحة
2. انقر على أي عنصر متبقٍ
3. استخدم Reconnect to file لإعادة ربطه بمسار الملف الحالي
4. أعد إضافة أي عناصر مفقودة

المشكلة: يعرض رابط النشر صفحة فارغة

السبب: مفتاح المشروع في عنوان URL المنشور لا يطابق أي لوحة Canvas مخزنة.

الإصلاح: أعد نشر اللوحة بعد التأكد من تعيين مفتاح مشروع دائم. الروابط القديمة من لوحات بمفاتيح مؤقتة لن يتم حلها.

المشكلة: تدهور أداء Canvas

السبب: اللوحات الكبيرة التي تحتوي على أكثر من 100 عنصر يمكن أن تبطئ العرض.

الإصلاح:

1. قسّم اللوحات الكبيرة إلى لوحات أصغر متعددة
2. استخدم ميزة Collapse لمجموعات العناصر
3. أزل الاتصالات غير المستخدمة
4. تجنب إضافة أدلة كاملة كعقد واحدة (استخدم ملفات فردية بدلًا من ذلك)

warning

لا تضف node_modules/ أو الأدلة الكبيرة الأخرى إلى لوحة Canvas. كل ملف يصبح عقدة منفصلة، والدليل الذي يحتوي على 10,000 ملف سيجعل Cursor غير مستجيب. أضف دائمًا ملفات أو دوال محددة، وليس مجلدات كاملة.

أفضل الممارسات

إبقاء لوحات Canvas مركزة

يجب أن تجيب لوحة Canvas واحدة على سؤال واحد. بدلًا من لوحة "كل شيء" واحدة، أنشئ:

• data-flow.canvas - كيف تنتقل البيانات عبر النظام
• auth-architecture.canvas - تدفق المصادقة والتفويض
• deployment-topology.canvas - البنية التحتية وخريطة النشر
• sprint-3-plan.canvas - الخطة البصرية للسبرنت الحالي

التحكم في إصدارات لوحات Canvas

ملفات .canvas مبنية على نص JSON. أودعها في مستودعك:

git add .cursor/canvases/
git commit -m "docs: update architecture canvas for new auth flow"

يمنحك هذا تاريخًا لكيفية تطور بنيتك المعمارية ويتيح لأعضاء الفريق مراجعة تغييرات المخطط من خلال طلبات السحب.

صيانة Canvas المنتظمة

في كل سبرنت، راجع لوحات Canvas الخاصة بك:

• احذف المخططات القديمة
• حدّث البنى المعمارية المتغيرة
• أزل الإشارات إلى الملفات المحذوفة
• أعد نشر أي لوحة يتم مشاركتها خارجيًا

الخلاصة

يحوّل Cursor Canvas تخطيط المشروع من نشاط منفصل إلى سير عمل بصري متكامل. خطأ "لم يتم العثور على ملف Canvas"، وهو المشكلة الأكثر شيوعًا التي يواجهها المستخدمون، ينبع من آلية مفتاح المشروع المؤقت لكل تشغيل ويتم حله بالكامل عن طريق إنشاء مفتاح مشروع دائم في .cursor/project.json. فهم الاختلافات بين Canvas المستقل و Canvas في تطبيق Glass App يضمن استخدامك للأداة المناسبة لكل سياق، بينما اتباع أنماط سير العمل البصري في هذا الدليل سيجعل تخطيطك أكثر فعالية وبنيتك المعمارية أكثر قابلية للتواصل.