دليل المطارات

أنشئ دليل مطارات حقيقيًا ومعولمًا على Profound CMS: نمط عنوان URL واحد يعرض صفحة لكل مطار، بـ 35 لغة. أنت تكتب شيفرة Next.js وتبني بنية نظام إدارة المحتوى يدويًا؛ يتولى Claude Code (عبر Profound MCP) ثلاث مهام — توليد بيانات المطارات، ربط نظام التصميم، وتوليد مكونات React الأربعة. ثلاثة أجزاء: الإعداد، البناء، الإنتاج.

شاهد الدليل المرئي الكامل.

ما الذي ستبنيه

• ~50 سجل مطار، لكل منها عنوان URL خاص به.
• مسار براميتري واحد /{language}/{airport_code}.
• أربعة عناصر واجهة — شريط التصفح، العنوان الرئيسي، المتن، التذييل — يتم عرضها بواسطة cms-renderer.
• بيانات CMS حية من خلال ربط CEL.
• جميع اللغات الـ35، تُترجم بنقرة واحدة.
• نشر على Vercel مع معاينة حية وتحرير في مكانه.

المتطلبات المسبقة

• Bun ≥ 1.3 — curl -fsSL https://bun.sh/install | bash
• Claude Code متصل بـ Profound MCP (الجزء 1).
• حساب Profound CMS.
• للجزء 3: GitHub CLI (gh) بتسجيل دخول، وحساب Vercel مرتبط بـ GitHub.

كيف تتكامل الأمور

• المكونات تحدد شكل المحتوى. حقل Route Slug يجعل المكون قابلًا للتوجيه؛ ووسم UI Element يجعله قابلاً للوضع على صفحة؛ المكونات النظامية (مثل language) تأتي مدمجة مسبقًا.
• المتغيرات هي المحتوى (JFK، SFO، LAX...).
• عناصر واجهة المستخدم هي أقسام الصفحة، تُملأ عبر CEL — سكربت داخل القالب من Profound، يُقيَّم عند العرض.
• المسار البراميتري يربط عنوان URL بمتغير مع مجموعة من عناصر واجهة المستخدم.
• تطبيق Next.js الخاص بك يعرض كل ذلك عبر حزمة cms-renderer باستخدام مفتاح واجهة برمجة التطبيقات للقراءة.

الجزء 1 — الإعداد

الحالة النهائية: حوالي 50 مطارًا في CMS، التطبيق موصول لقراءتها، ونظام التصميم في مكانه.

1. أنشئ الموقع

سجل في Profound (مصادقة WorkOS) وأنشئ موقعًا باسم airports. انسخ شيئين: معرّف الموقع (UUID في عنوان URL للإدارة) ومفتاح API لطبقة القراءة من Deployments → Create API key. التطبيق يقرأ فقط، لذا مفتاح القراءة يكفي.

2. جهّز التطبيق ووصلْه

bunx create-profound-next airports
cd airports

أضف بيانات الاعتماد إلى .env.local:

PROFOUND_API_KEY=<your read key>
NEXT_PUBLIC_PROFOUND_WEBSITE_ID=<your website id>
NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_BUNNY_CDN_URL=https://cms-profound.b-cdn.net

شغّل bun dev وافتح localhost:3000 للتأكد من الاتصال.

3. أنشئ مكون airport

في لوحة الإدارة، انتقل إلى Components → Create new component وسمّه airport. أضف ستة حقول: code، name، city، country (نص) وlatitude، longitude (رقم). وسم الحقل code كحقل Route Slug واضبط الحالة على Active. اترك كل الحقول اختيارية؛ لا تضف وسم عنصر واجهة.

مكون airport — ستة حقول، مع تعيين code كحقل Route Slug.

4. اسحب المكون إلى المخططات

bun run generate-schemas

يكتب هذا airportSchema (Zod) وAirport (نوع) في generated/cms-schemas.ts، ويؤكد صلاحية بيانات اعتمادك.

5. زوّد البيانات عبر MCP

وصّل MCP وصدّق:

claude mcp add --transport http Profound http://107.21.107.99:8081/mcp

يُجري الخادم المصادقة عبر OAuth (WorkOS). في Claude Code، شغّل /mcp، اختر Profound، وأكمل تسجيل الدخول في المتصفح — سيطالبك Claude Code تلقائيًا أول مرة يُستدعى فيها أداة Profound. بمجرد أن يُظهر /mcp أن Profound متصل، وجّه طلبًا إلى Claude:

أنشئ خمسين مطارًا حقيقيًا — رموز IATA الصحيحة، الأسماء، المدن، البلدان، والإحداثيات. احفظها كـ JSON في مجلد data، تحقق منها مقابل مكون airport، ثم أنشئ كل واحدة كوثيقة منشورة عبر Profound MCP، بالتوازي.

افتح airport → Variants للتأكد من وجود حوالي 50 مطارًا منشورًا. التطبيق يقرأ عبر مفتاح API؛ MCP يكتب عبر جلسة WorkOS الخاصة به.

حوالي 50 مطارًا، تمت زراعتها كمتغيرات منشورة.

6. أضف نظام تصميم

يأتي الهيكل الأساسي بدون تنسيق. ضع ملف DESIGN.md (كتلة @theme لـ Tailwind v4 بالإضافة إلى التوكنات) في جذر المشروع — يمكنك إنشاء واحد بنفسك، أو تنزيله من refero.design. ثم وجّه طلبًا إلى Claude:

اقرأ DESIGN.md. اضبط Tailwind v4 ووصل السمة والخطوط. استخدم next/font للخطوط، وليس استيراد Google وقت التشغيل. تنسيق فقط — لا صفحات ولا مكونات بعد.

تأكد من أن src/app/globals.css يحتوي على @import "tailwindcss"; بالإضافة إلى كتلة @theme، وأن localhost:3000 يُظهر التوكنات.

الجزء 2 — البناء

ابنِ طبقة العرض: عناصر الواجهة، مكونات React، المسار، ربط CEL، والترجمة.

1. عرّف مكونات عناصر الواجهة الأربعة

في لوحة الإدارة، أنشئ مكونًا جديدًا أربع مرات (بدون Route Slug). لكل واحد، أضف الحقول كـ نص ما لم يُذكر خلاف ذلك، واضبط الحالة على Active، وأضف وسم UI Element في Settings → Tags:

• nav → brand
• headline → title, subtitle
• body → code, city, country, latitude (رقم), longitude (رقم)
• footer → text

يجب أن يكون body.latitude وbody.longitude من نوع رقم ليتطابقا مع مكون المطار.

كل عنصر واجهة مستخدم هو مكون منفصل — هنا body، مضبوط على Active مع وسم UI Element.

جميع عناصر الواجهة الأربعة إلى جانب مكون airport.

2. أعد توليد الأنواع

bun run generate-schemas

3. أنشئ مكونات React وسجّلها

وجّه طلبًا إلى Claude:

أنشئ أربعة مكونات React — nav، headline، body، footer — داخل components/. كل منها يستقبل خاصية content واحدة من نوع BlockComponentProps<T> من cms-renderer/lib/types، حيث T هو النوع المُولد للعنصر، ويقرأ حقوله من content. سجّل المكونات الأربعة في سجل المسار الجامع باسم المكون. نسّقها باستخدام نظام التصميم لدينا، ولكن كمكوناتنا الخاصة — لا تنسخ تخطيط الموقع المصدر. شريط التصفح: العلامة التجارية على اليسار. العنوان الرئيسي: اسم المطار مع سطر فرعي code · city, country. المتن: لوحة تفاصيل تحتوي على الرمز، المدينة، البلد، والإحداثيات. التذييل: سطر ثابت واحد. تخطيط وتنسيق فقط.

يُنشئ Claude المكونات الأربعة ويملأ السجل في src/app/[...slug]/page.tsx:

const registry = { nav: Nav, headline: Headline, body: Body, footer: Footer };

قاعدتان: يقرأ كل مكون حقوله من content (ليس كخصائص منفصلة)، ويجب أن تتطابق مفاتيح السجل مع أسماء مكونات CMS تمامًا — أي عدم تطابق سيجعل العرض فارغًا.

4. أنشئ المسار البراميتري

في لوحة الإدارة، اذهب إلى Pages → Create page واضبط النمط على /{airport_code}. ضمن Dynamic Segment Mappings، اربط airport_code → مكون airport, وحقل slug هو code. احفظ — ستنتقل إلى Page Builder. تأكد من أن /JFK يعمل.

5. أضف عناصر الواجهة، اربط CEL، وانشر

إضافة عنصر واجهة إلى الصفحة من علامة التبويب Custom.

عناصر الواجهة الأربعة مضافة إلى ربط JFK في Page Builder.

1. اختر ربط JFK → Add UI Element → علامة التبويب Custom → أضف nav، headline، body، footer بالترتيب. يقوم Profound بنسخ المجموعة إلى كل ربط مطار.

2. املأ كل حقل. القيم الثابتة (علامة شريط التصفح، نص التذييل): اكتبها مباشرة. القيم الديناميكية: انتقل إلى الوضع الديناميكي واكتب CEL. الاستعلام المشترك هو documents.get("airport", meta.params.airport_code).

   الحقل	قيمة CEL
   headline.title	documents.get("airport", meta.params.airport_code).name
   headline.subtitle	documents.get("airport", meta.params.airport_code).code + " · " + documents.get("airport", meta.params.airport_code).city + ", " + documents.get("airport", meta.params.airport_code).country
   body.code / body.city / body.country	documents.get("airport", meta.params.airport_code).<field>
   body.latitude / body.longitude	documents.get("airport", meta.params.airport_code).latitude (و.longitude)
   nav.brand, footer.text	سلاسل ثابتة

3. انشر الصفحة (أعلى اليمين).

6. تحقق باللغة الإنجليزية

افتح localhost:3000/JFK، ثم /SFO، /LAX — نفس القالب، ولكن مطار مختلف.

الصفحة النهائية تعرض بيانات JFK، بالإنجليزية.

7. التدويل

1. ترجم المكونات أولًا. في لوحة الإدارة، افتح كل مكون (أي مكون — لا يلزم أن يكون عنصر واجهة) وانقر Translate → Submit. يترجم Profound المحتوى إلى جميع اللغات الـ35 دفعة واحدة، بما في ذلك القيم الثابتة. افعل ذلك قبل تعديل المسار أو لمس أي CEL.

   

   Translate → Submit يرسل المكون إلى جميع اللغات الـ35 دفعة واحدة.

2. أضف بُعد اللغة. في Pages، غيّر النمط إلى /{language}/{airport_code}. أضف Dynamic Segment Mapping لـ language → مكون النظام المدمج language، حقل slug هو code. احفظ وتأكد من أن /en/JFK يعمل.

   

   إضافة المقطع {language} إلى المسار.

3. وجّه كل حقل قابل للترجمة إلى الجلب المترجم. تدويل الصفحة يعني تبديل كل حقل يعتمد على اللغة — ليس العنوان فقط — من documents.get(...) إلى documents.translated("airport", meta.params.airport_code, meta.params.language):

   الحقل	CEL المترجم
   headline.title	documents.translated("airport", meta.params.airport_code, meta.params.language).name
   headline.subtitle	documents.get("airport", meta.params.airport_code).code + " · " + documents.translated("airport", meta.params.airport_code, meta.params.language).city + ", " + documents.translated("airport", meta.params.airport_code, meta.params.language).country
   body.city / body.country	documents.translated("airport", meta.params.airport_code, meta.params.language).city (و.country)

   اترك رمز IATA والإحداثيات على documents.get — فهما متماثلان في كل اللغات. يتم تغطية nav.brand وfooter.text بالفعل عبر ترجمة المكون في الخطوة 1.

عند اكتمال الخطوات الثلاث، ستُعرض /fr/SFO، /de/SFO، وغيرها مترجمة بالكامل.

الجزء 3 — الإنتاج

1. انشر: GitHub، ثم Vercel

ادفع إلى GitHub:

git init
git add -A
git commit -m "Airport directory"
gh repo create airports --public --source=. --push

استورد إلى Vercel: Add New → Project → استورد مستودع airports. أضف متغيرات البيئة — PROFOUND_API_KEY، NEXT_PUBLIC_PROFOUND_WEBSITE_ID، NEXT_PUBLIC_CMS_API_URL، وبشكل اختياري NEXT_PUBLIC_BUNNY_CDN_URL — ثم Deploy. زر /en/JFK و/fr/SFO. كل git push لاحق يعيد النشر.

2. المعاينة الحية والتحرير في المكان

كلاهما يأتي مع الهيكل الأساسي.

• المعاينة الحية: يقوم <Refresher> في layout.tsx بتحديث الصفحة التي تعاينها عند التحرير والحفظ في لوحة الإدارة — بلا إعادة نشر.
• التحرير في المكان: أضف ?edit_mode=true إلى أي عنوان URL (مثل …/en/JFK?edit_mode=true) للحصول على تراكبات التحرير. الزوار العموميون يرون الصفحة النظيفة.

?edit_mode=true يُظهر تراكب المحرر على الصفحة الحية.

هذا هو البناء

خمسون مطارًا، 35 لغة، في وضع عمل — موصوفة مرة واحدة ومملوءة بالبيانات: مسار واحد، أربعة مكونات React، وعدد قليل من روابط CEL. نظام إدارة المحتوى يحتفظ بالمحتوى، شيفرتك تعرضه، وCEL يربط بينهما.