عقد الموقع

عقد الموقع هو الاتفاق بين شيفرة موقعك وAtlas. يسرد ما هو موجود في موقعك وما يجوز للمحررين تغييره. وهو لا يحتوي على أي شيفرة قابلة للتنفيذ: أوصاف وحقول مضبوطة الأنواع فقط.

احتفظ به في مستودعك (مثل atlas/contract.bundle.json) وأدِر إصداراته مع شيفرتك.

دورة الحياة

1. يقوم مطور، أو وكيل ذكاء اصطناعي عبر MCP، بالتحقق من الحزمة واقتراحها.
2. يراجعها مسؤول الموقع ويفعّلها (أو يرفضها) في Studio ضمن Site setup.
3. يبلّغ موقعك عن بصمة الحزمة التي يعرضها (POST /deployments). ويعرض Studio ما إذا كانت الشيفرة والعقد متزامنين.

البصمة هي تجزئة SHA-256 لصيغة JSON القانونية للحزمة، لذا يجب أن تطابق الحزمة في مستودعك تلك التي اقترحتها تمامًا.

البنية العليا

المفتاح	المحتويات
contractVersion	دائمًا 1.0.0 لهذه الصيغة
bundleVersion	إصدارك الخاص لهذه الحزمة، مثل 1.4.0
site	key وdisplayName وruntimes (node وcloudflare-workers) وlocales (الافتراضية والمدعومة والتي تُكتب من اليمين إلى اليسار) وstaticRoutes التي تملكها شيفرتك
tokens	الألوان وأنماط الخطوط والتباعد التي يجوز للمحررين الاختيار منها
motion	إعدادات حركة مسماة تنفذها شيفرتك، مع سلوك تقليل الحركة
mediaProfiles	أحجام الصور ونسبها ونسخها المسموح بها
components	حتى 300 مكوّن، لكل منها معرّف مؤهّل وإصدار ونوع وحقول
collections	أنواع المحتوى المتكرر، مع الحقول وحقلي العنوان والـ slug وقواعد التفرد
pageTypes	حتى 100 نوع صفحة: نمط المسار، ومجموعة مرتبطة اختيارية، والمناطق، وقواعد SEO
globals	محتوى مشترك مثل site-header وsite-footer

مكوّن (مختصر)

{
  "id": "acme.home.hero",
  "version": "1.0.0",
  "kind": "section",
  "label": "Home hero",
  "fields": [
    { "key": "heading", "type": "text", "label": "Heading", "required": true, "maxLength": 80 },
    { "key": "intro", "type": "longText", "label": "Intro", "maxLength": 400 },
    { "key": "image", "type": "asset", "label": "Image", "profile": "hero" },
    { "key": "cta", "type": "link", "label": "Button" }
  ]
}

نوع صفحة (مختصر)

{
  "key": "industry-landing",
  "version": "1.0.0",
  "label": "Industry landing",
  "route": { "pattern": "/industries/{entry.slug}" },
  "entry": { "collection": "industries", "mode": "one-page-per-entry" },
  "regions": [
    {
      "key": "hero",
      "reorder": "locked",
      "sections": [
        {
          "key": "hero",
          "component": { "id": "acme.industry.hero", "versionRange": "^1.0.0" },
          "presence": "required",
          "bind": { "headline": "entry.headline", "image": "entry.image" }
        }
      ]
    },
    {
      "key": "body",
      "reorder": "within-region",
      "min": 1,
      "max": 20,
      "insertable": ["acme.text", "acme.faq"]
    }
  ]
}

تحدد المناطق ما يستطيع المحررون فعله: يمكن أن تكون الأقسام required أو default أو optional؛ ويمكن أن تكون المناطق مقفلة أو قابلة لإعادة الترتيب، مع حد أدنى وأقصى لعدد الأقسام وقائمة بالمكوّنات القابلة للإدراج. ويمكن ربط الحقول بعنصر الصفحة، فتُنشأ صفحة واحدة لكل منتج أو قطاع من المجموعة.

أنواع الحقول

النوع	الاستخدام	الحدود
text	نص قصير من سطر واحد	حتى 500 حرف
longText	فقرات، دون تنسيق	حتى 10,000 حرف
richText	نص منسق، بملف تعريف basic أو article	منظَّم، وليس HTML خامًا أبدًا
number	أرقام مع نطاق اختياري
boolean	تشغيل/إيقاف
select	واحد من قائمة ثابتة	حتى 100 خيار
date	تاريخ
link	مسار داخلي أو، إن سُمح، عنوان URL خارجي
asset	صورة أو صور ضمن ملف تعريف وسائط	حتى 50 لكل حقل
reference	رابط إلى عناصر مجموعة	حتى 200 لكل حقل
list	مجموعة حقول متكررة	حتى 200 عنصر، 40 حقلًا لكل منها
group	حقول تُجمع معًا	حتى 40 حقلًا
table	صفوف وأعمدة مضبوطة الأنواع	حتى 12 عمودًا، 200 صف
token	أحد رموز التصميم لديك (لون، نمط خط، تباعد)
icon	أحد مجموعات الأيقونات المسماة التي توفرها شيفرتك	حتى 200 خيار

يمكن تعليم الحقول بـ required وlocalized. ويمكن أن يضم المكوّن أو المجموعة ما يصل إلى 80 حقلًا.