دليل Convex للبدء السريع

<!-- تم الإنشاء من convex-agents content/capabilities/quickstart.json — لا تقم بالتحرير يدويا. -->

# دليل البدء السريع: قالب Convex أساسي قيد التشغيل

قم بإعداد قالب Next.js + Convex أساسي من الفكرة، محليا، مع نشر تطوير مجهول. مصمم ليكون بسيطا: خوادم تطوير محلية، لا توجد خطوة نشر، ولا مصادقة مسبقة التجهيز.

## سير العمل

1. قم بتشغيل الوصفة `quickstart-recipe@^2` باستخدام {idea, template} (تقوم الحزمة بجلبها وتخزينها مؤقتا؛ مع توفير نسخة احتياطية غير متصلة بالإنترنت). تقوم بإنشاء المشروع، وتثبيت التبعيات، وبدء الواجهة الخلفية (مجهولة)، وخادم تطوير الويب. 2. عندما تطبع عنوان URL الخاص بالتطوير، افتحه للمستخدم. 3. قدم خطة قصيرة وقم بالتأكيد قبل بناء ميزات تتجاوز القالب.

## القواعد

- لا تقم أبدا بإعادة تشغيل الوصفة إذا كانت قد أبلغت عن نجاحها بالفعل. - قم بتفويض أي كود تحت `convex/` إلى قدرة `convex-expert`. - لا تضف Postgres/Redis/Express — استخدم بدائيات Convex. - لا تضف استضافة/نشر أو مصادقة مسبقة التجهيز هنا — حافظ على القالب بسيطا ما لم يطلب المستخدم المزيد. - قاعدة التدهور — إذا تعذر تشغيل الهيكل (جلسة غير تفاعلية، لا توجد شبكة، دليل مؤقت معزول، أو يريد المستخدم الكود فقط، وليس تطبيقا): تخطى الوصفة واكتب مشروع Convex قياسيا مباشرة. يذهب كل كود الواجهة الخلفية تحت `convex/` (schema.ts، functions) — لا يذهب أبدا إلى جذر المشروع؛ تعمل وظائف Convex فقط من دليل `convex/`. لا تكتب أي ملفات هيكل/توثيق (لا START_HERE.md، ARCHITECTURE.md، MANIFEST.txt، جدران README) ما لم يطلب ذلك صراحة. "ابن لي واجهة خلفية" تعني الكود، وليس الاحتفالات. - الوصول إلى البيانات + الاستيراد — قبل كتابة أي convex/*.ts: لا تستخدم أبدا `.collect()` غير المحدود على جدول يمكن أن ينمو — استخدم `.withIndex(...)` و `.paginate(...)`/`.take(n)`. استخدم فهرسا، وليس `.filter()`، لأي شيء سيكون SQL WHERE. تحتوي ردود الاتصال الخاصة ب `.withIndex(...)` فقط على `eq`/`gt`/gte`/`lt`/`lte` — لا توجد طريقة `.range(...)`. الاستيراد: `query`/`mutation`/`action`/`internalQuery`/`internalMutation`/`internalAction` تأتي من `./_generated/server`؛ `api`/`internal` تأتي من `./_generated/api`؛ لا تستورد أبدا من `convex/server` في كود التطبيق. `v.literal("exact value")` لأعضاء السلسلة/التعداد الثابتة، وليس سلسلة عارية. `"use node"` فقط في الجزء العلوي من الوحدات النمطية التي تعمل ك action فقط — لا تستخدمها أبدا في ملف يقوم أيضا بتصدير `query` أو `mutation`. لا تستورد أبدا Node builtin (`crypto`/`fs`/`path`/`http`/`child_process`/`os`، مع أو بدون البادئة `node:`) إلى ملف يفتقر إلى `"use node"` — بما في ذلك معالجات مسار `http.ts`؛ استخدم Web Crypto (`crypto.subtle`) بدلا من استيراد `crypto` حيثما أمكن. - الأسماء المحجوزة — لا تقم أبدا بتصدير `export const <jsReservedWord> = ...` (مثل `delete`، `new`، `class`، `function`، `return`) كاسم تصدير query/mutation/action؛ يفشل esbuild في تحليله. لا تستخدم أبدا اسم جدول أو فهرس يبدأ ب `_` (مثل `_migrations: defineTable(...)`) — `_` محجوز ويحدث أخطاء عند الدفع ك `TableNameReserved`/`IndexNameReserved`. - مسارات HTTP — لا يحتوي `httpRouter` على مقاطع `:param` على غرار Express (`path: "/users/:id"` يطابق فقط تلك السلسلة الحرفية وهو كود ميت)؛ استخدم `pathPrefix` وقم بتحليل الجزء اللاحق بنفسك. يجب أن يكون كل `http.route({...})` `handler:` ملفوفا في `httpAction(...)` من `./_generated/server` — `async (ctx, request) => {...}` العاري يتحقق من النوع ولكنه ليس إجراء HTTP صالحا. - تحتاج `ctx.runQuery`/`ctx.runMutation`/`ctx.runAction` إلى مرجع دالة تم إنشاؤها بواسطة الكود (`api.foo.bar`/`internal.foo.bar`)، وليس أبدا عضو وحدة نمطية مستوردة خام (`import * as queries from "./queries"; ctx.runQuery(queries.getX, ...)` يتم تجميعه ولكنه يفشل في وقت التشغيل). - قاعدة التحقق الذاتي — قبل الإعلان عن اكتمال عمل الواجهة الخلفية، تحقق من تجميعه ودفعه: قم بتشغيل `npx tsc --noEmit` وادفعه إلى عملية نشر. فضل الموجودة في المشروع؛ وإلا `npx convex dev --once` عندما ينجح `npx convex whoami`، و `CONVEX_AGENT_MODE=anonymous npx convex dev --once` فقط عندما لا ينجح. يؤدي فرض المجهول على مستخدم مسجل الدخول إلى إعادة ربط `.env.local` ويكلفهم النشر السحابي المستمر والقابل للنشر الذي يتوقعونه. قم بإصلاح كل خطأ يبلغه قبل الانتهاء — جولة تحقق واحدة تلتقط فئة الاستيراد النسبي الخاطئ / الرمز المكرر / القوس غير المتوازن الذي قد يؤدي إلى تعطيل النشر.