تخطي إلى المحتوى الرئيسي

بنية منشئ المواقع

يُعرض كل موقع كنيسة يخدمه B1App من شجرة محتوى تضم الصفحات والأقسام والعناصر، وتُخزَّن في ContentApi ويُحرَّر بصريًا في B1Admin. تُستخدم مكتبة مكوّنات مشتركة واحدة لعرض كلٍّ من معاينة المحرر والموقع المنشور، ويحدد كتالوج أنواع العناصر ما يمكن أن يظهر في الصفحة، ويمكن لخدمة ذكاء اصطناعي منفصلة أن تولّد شجرة المحتوى أو تعيد كتابتها. توضح هذه الصفحة المنظومة كاملة: عقد العناصر في @churchapps/helpers، ومسار العرض، وعناصر بيانات الكنيسة، والأدوات المصغّرة على مستوى الموقع، وطبقة المدونة، والصفحات المقيّدة بالوصول، وتحسين محركات البحث، وتوليد الذكاء الاصطناعي، والنماذج التفاعلية.

نظرة عامة​

┌──────────────────────────────┐             ┌─────────────────────────────────────────┐
│ B1Admin — editor │ │ Api — /content module (ContentApi) │
│ ContentEditor · SectionEdit │ POST /… │ │
│ ElementEdit · PageLinkEdit │ ──────────▶ │ pages ─ sections ─ elements blocks │
│ SiteWidgetsEdit · Blog │ │ posts redirects settings styles │
└──────────┬───────────────────┘ └───────────────┬─────────────────────────┘
│ │ GET /content/pages/:churchId/tree?url=…
│ shared render pipeline ▼ (anon, JWT honored)
│ ┌───────────────────────────────┐ ┌─────────────────────────────────┐
└──▶│ @churchapps/helpers │◀──│ B1App — public site (Next.js) │
│ ElementTypes.ts (catalog) │ │ Zone → Section → Element │
│ @churchapps/apphelper │ │ + widgets, JSON-LD, sitemap, │
│ ElementRegistry, renderers │ │ redirects, branded 404 │
│ SectionDivider, widgets │ └───────────────┬─────────────────┘
└───────────────────────────────┘ │ church-data elements
┌──────────────────────────────┐ ▼
│ AskApi — /website/* (AI) │ ┌─────────────────────────────────────────┐
│ generateSite · rewriteSection│ │ /giving/funds/public/…/total │
│ generateAltText · metaDesc │ │ /membership/groupmembers/public/… │
│ returns JSON; B1Admin saves │ │ /attendance/servicetimes/public/… │
└──────────────────────────────┘ └─────────────────────────────────────────┘

تنطبق ثلاث قواعد على المنظومة كلها:

  1. شجرة واحدة، ومُعرِضان. الصفحة هي شجرة pages → sections → elements حيث يحمل كل عقدة إعداداتها في كائن JSON باسم answers. تعرض مكوّنات apphelper نفسها المحرر بالسحب والإفلات في B1Admin والموقع العام المُعرَض على الخادم في B1App، ولا يوجد "تنسيق نشر" منفصل.
  2. العقد تعيش في @churchapps/helpers. ملف ElementTypes.ts هو الكتالوج الوحيد لأنواع العناصر، وتُحلّ المُعرِضات عبر سجلّ في apphelper، وتعيش نماذج المحرر في B1Admin. إضافة نوع عنصر جديد تعني تعديل الأماكن الثلاثة بهذا الترتيب.
  3. الموقع العام يقرأ نقاط نهاية مجهولة. كل ما يحتاجه B1App — شجرة الصفحة، والإعدادات، ومقالات المدونة، وعمليات إعادة التوجيه، ونقاط نهاية بيانات الكنيسة في الوحدات الأخرى — متاح للعموم. المصادقة اختيارية: رمز JWT على نقطة نهاية الشجرة المجهولة يفتح الصفحات الخاصة بالأعضاء فقط، ولا يتغير أي شيء آخر.

شجرة المحتوى​

تملك وحدة المحتوى (Api/src/modules/content) بيانات المنشئ:

الجدولالدور
pagesصفحة واحدة لكل عنوان URL: url وtitle وlayout، إضافةً إلى visibility/groupIds (تقييد الوصول) وmetaDescription (تحسين محركات البحث)
sectionsشرائط أفقية داخل الصفحة (أو ضمن كتلة): الخلفية ولون النص، وحقل answersJSON الذي يحمل التنسيق إضافةً إلى إعدادات أشكال الفواصل dividerTop/dividerBottom
elementsقطع المحتوى داخل القسم: elementType وanswersJSON، ويمكن تداخلها في أنواع التخطيط (صف/عمود، دوّار)
blocksمجموعات أقسام/عناصر قابلة لإعادة الاستخدام (كتل التذييل، وكتل العناصر) تُشارَك بين الصفحات
postsمقالات مدونة مستقلة (انظر المدونة)
redirectsأزواج fromPath → toPath لكل كنيسة، بحد أقصى 200 (انظر تحسين محركات البحث)
settingsإعدادات الكنيسة بصيغة مفتاح-قيمة؛ الصفوف المعلَّمة public تُقدَّم للعموم وتحمل إعدادات الأدوات المصغّرة والتحليلات

تعود شجرة الصفحة الكاملة لعنوان URL واحد من استدعاء مجهول واحد — GET /content/pages/:churchId/tree?url=/about — وهي ما يُعرَض منه B1App على الخادم. أما طلبات المحرر فتجلب بالمعرّف وتحتفظ بالمعرّفات الداخلية.

عقد العنصر​

الكتالوج (@churchapps/helpers)​

يُعرّف الملف Packages/helpers/src/ElementTypes.ts كل نوع عنصر بوصفه ElementTypeDefinition: elementType وlabel وcategory وschemaVersion وdefaults، وanswersSchema بأسلوب JSON Schema لإجاباته. تتسم الدالة validateElementAnswers() بالتساهل عن قصد؛ فالأنواع غير المعروفة والمفاتيح الزائدة تمر، فلا يتعطل المحتوى القديم عند تحديث الكتالوج. تُرفَق 35 نوعًا حاليًا:

الفئةأنواع العناصر
التخطيط (6)row, column, box, carousel, whiteSpace, block
المحتوى (11)text, textWithPhoto, card, faq, iconFeature, testimonial, socialIcons, countdown, stats, table, buttonLink
الوسائط (4)image, gallery, video, map
الكنيسة (12)logo, sermons, stream, donation, donateLink, form, calendar, groupList, groups, campaignProgress, staffGrid, serviceTimes
متقدم (2)rawHTML, iframe

يُعد عنصر sermons الأكثر قابلية للتهيئة بين أنواع الكنيسة: تختار إجابة layout بين browse (المتصفح الكامل القديم) وgrid وlist وfeaturedLatest، وتُحسّن playlistId وitemCount وshowTitles وshowDates التخطيطات غير المتصفحة.

للعنصر rawHTML إجابتان: rawHTML (الترميز) وjavascript. الأكواد البرمجية المُدرجة عبر innerHTML لا تُنفَّذ أبدًا، لذا يُعيد RawHTMLElement إنشاء كل عقدة <script> في الترميز بوصفها عنصرًا جديدًا. تُعامَل هذه العقد غير المُدرجة بواسطة المحلل على أنها موثوقة بموجب strict-dynamic في سياسة CSP. إذا بدأت إجابة javascript بالرمز < (مقتطف من مورّد ملصوق مع وسوم <script>)، فتُحلَّل كترميز وتُعامَل بالطريقة نفسها. وإلا فإنها تُنفَّذ كنص برمجي مضمَّن عادي. تُنبّه B1Admin إلى عنوان URL مجرد في خانة JavaScript، لأن الرابط المنفرد يُنفَّذ كنص برمجي فارغ لا يفعل شيئًا. لا يعرض العنصر map أي شيء، ولا يحمّل نص خرائط Google البرمجي، عندما لا يكون مفتاح واجهة برمجة الخرائط مُهيّأً.

المُعرِضات (@churchapps/apphelper)​

تعيش المُعرِضات في Packages/apphelper/src/website/components/elementTypes/، بمكوّن واحد لكل نوع، وتُحلّ عبر ElementRegistry.ts — وهو خريطة من طبقتين يسجّل فيها Element.tsx المُعرِض الافتراضي لجميع الأنواع الـ35 (registerDefaultElementRenderer)، ويستطيع التطبيق المضيف تجاوز أيٍّ منها أثناء التشغيل (registerElementRenderer) دون تفريع الحزمة.

نماذج المحرر (B1Admin)​

تعيش نماذج إعدادات كل نوع في المحرر ضمن B1Admin/src/site/admin/elements/ — إذ يوجّه ElementEdit.tsx إلى مكوّن مخصص (GalleryEdit وTestimonialEdit وStatsEdit …) أو إلى بانٍ مُضمَّن للحقول لكل نوع. النسخة الموجهة للذكاء الاصطناعي من هذا الكتالوج هي أداة describe_page_builder في خادم MCP الخاص بالواجهة البرمجية (انظر خادم MCP).

يستخدم معاينة المحرر السمة Theme نفسها الموجودة في الموقع المنشور، والتي تضبط متغيّرات CSS الخاصة --headingFont و--bodyFont من الأنماط العامة للكنيسة. يطبّق B1App هذه المتغيرات عبر pages.css، وهو ملف لا يستطيع B1Admin استيراده، لذا يحقن ContentEditor.tsx الملف EDITOR_PAGE_FONT_CSS (src/site/admin/editorCss.ts) لتطبيقها على نص .page والعناوين h1–h6. ودون ذلك كانت المعاينة تعرض العناوين بخط الإدارة.

فواصل أشكال الأقسام​

يمكن للأقسام أن تحمل فواصل زخرفية على أي حافة. يعيش الإعداد في answersJSON الخاص بالقسم ككائنين dividerTop / dividerBottom — بالشكل { shape, color, height, flip } حيث تكون shape إحدى القيم wave, waves, slant, curve, triangle, peaks. يشحن apphelper المكوّن SectionDivider والدالة المساعدة parseDividerConfig()؛ وتحلّل مُعرِضات الأقسام في التطبيقين (B1App/src/components/Section.tsx وB1Admin/src/site/admin/Section.tsx) الإجابات وتركّب الفاصل، ويوفّر SectionEdit.tsx في B1Admin واجهة الاختيار. تشحن الحزم اللبنة الأساسية فقط، أما ربطها على مستوى القسم فهو مسؤولية التطبيقات المستهلكة.

عناصر بيانات الكنيسة​

ثلاثة أنواع عناصر تعرض بيانات الكنيسة الحية بدلًا من المحتوى المكتوب. يبقى عزل الوحدات قائمًا — إذ يستدعي كل عنصر نقطة النهاية العامة الخاصة بالوحدة المالكة مباشرةً من المتصفح:

العنصرنقطة النهايةملاحظات
campaignProgressGET /giving/funds/public/:churchId/:fundId/totalيعيد { fundId, totalAmount, donationCount }، مع نافذة اختيارية ?startDate=&endDate=؛ ويقارنها العنصر بإجابة goalAmount الخاصة به
staffGridGET /membership/groupmembers/public/:churchId/:groupIdاختياري فقط: يجب أن تكون المجموعة مضبوطة على publicRoster (القيمة الافتراضية معطّلة). الإسقاط مُصمَّم بأقل قدر ممكن عن قصد — personId وdisplayName وleader والصورة — دون أي حقول اتصال أو ديموغرافية
serviceTimesGET /attendance/servicetimes/public/:churchIdيعيد الشجرة: الحرم ← الخدمة ← الوقت؛ ويُصدر مُعرِض apphelper بأفضل جهد JSON-LD من نوع Event بمفردات schema.org انطلاقًا منها (تعيد الواجهة البرمجية بيانات عادية)
تحذير

الحقل publicRoster هو بوابة الخصوصية للعنصر staffGrid. لا توسّع إسقاط أعضاء المجموعة العام أبدًا، ولا تتجاوز العلم؛ فنقطة نهاية الكشف مجهولة عن قصد، وقائمة الحقول الدنيا هي خاصية الأمان.

عنصر التقويم وصفحات الفعاليات​

إجابات عنصر calendar هي calendarType (group | curated) وcalendarId وdisplay (month، وهي الافتراضية، أو upcoming) وtag. يتجاوز B1App مُعرِض apphelper في src/components/Element.tsx باستخدام registerElementRenderer("calendar", …):

  • display: "upcoming" يعرض UpcomingEventsElement الخاص بـB1App: يحمّل GET /content/events/public/group/:churchId/:groupId أو GET /content/curatedEvents/public/calendar/:churchId/:curatedCalendarId، ويوسّع التكرارات عبر buildOccurrences() (src/helpers/EventOccurrences.ts، بحالة واحدة لكل فعالية خلال سنة)، ويعرض أول 12 منها كبلاطات صور (events.photoUrl، وإلا يُعرض العنوان على اللون الداكن للسمة) تربط بـ/events/{id}، مع قائمة اشتراك لخلاصة ICS الخاصة بالتقويم.
  • display: "month" يعرض CalendarElement من apphelper مع استدعاء eventUrl. يقوم GroupCalendar / CuratedCalendar ← EventCalendar / CuratedEventCalendar بالانتقال إلى ذلك العنوان عند النقر بدلًا من فتح نافذة التفاصيل (لا يمرّر B1Admin الحقل eventUrl، لذا يحتفظ تقويم الإدارة بنافذته).
  • tag يُرشّح كلا العرضين عبر EventHelper.hasTag() (من @churchapps/helpers): مطابقة غير حساسة لحالة الأحرف مع الحقل events.tags المفصول بفواصل؛ والقيمة الفارغة تعرض كل شيء. يختار انضمام التقويم المنسَّق e.tags كي تحمل الفعاليات المنسَّقة وسومها.

تربط الفعاليات المنسَّقة عبر realEventId (eventPageId())، لذا يسمّي عنوان URL دائمًا الفعالية الأساسية. المسار /{sdSlug}/events/[eventId] مسار مخصص (وليس جزءًا من مسار المنشئ): يحمّل GET /content/events/public/:churchId/:id — الذي يعيد null للفعاليات المعلّقة أو المرفوضة وللفعاليات الخاصة دون تسجيل — ويضيف roomNames من حجوزات الغرف غير المرفوضة — ويعرض EventPageContent (صورة رئيسية، ووصف بصيغة markdown، وشريط جانبي للتوقيت والمكان، وزر Register for this Event عندما تكون registrationEnabled، ورابط Add to my calendar إلى GET /content/events/public/:churchId/:id/ical)، ويستخدم الصورة كصورة Open Graph، ويصدر JSON-LD من نوع Event للحالة التالية عبر EventPageJsonLd. تعيد الفعالية غير المعروفة أو المخفية خطأ 404 حقيقيًا.

الأدوات المصغّرة على مستوى الموقع​

تظهر أداتان على كل صفحة عامة خارج الشجرة: AnnouncementBanner (شريط علوي قابل للإغلاق في أعلى الصفحة) وLauncher (مركز إجراءات عائم لروابط بنمط العطاء/الزيارة/المشاهدة). يشحن كلا المكوّنين ودوال parse*Config() المساعدة في apphelper. تُضبط الأداتان عبر صفين من إعدادات الموقع العامة، بالمفتاحين announcementBanner وlauncher، ويكتبهما SiteWidgetsEdit في B1Admin (في صفحة المظهر)، ويقرأهما التخطيط العام لـB1App عبر GET /content/settings/public/:churchId. تتعامل الواجهة البرمجية مع هذه الإعدادات كأزواج مفتاح-قيمة غير شفافة؛ وأسماء المفاتيح اتفاق اصطلاحي بين التطبيقين.

المدونة​

المدونة نوع محتوى مستقل، وليست طبقة فوق صفحات المنشئ. يحمل صف posts المقالة كاملة: title وslug وexcerpt وcontent (نص بصيغة markdown) وauthorId وphotoUrl وpublishDate وcategory وtags. واجهة العرض العامة (كلها مجهولة، عبر PostController):

المسارالغرض
GET /content/posts/public/:churchIdالمقالات المنشورة، قابلة للترشيح بـ?category=&tag=، ومقسّمة على صفحات
GET /content/posts/public/:churchId/categoriesالفئات المتميزة عبر المقالات المنشورة
GET /content/posts/public/:churchId/slug/:slugمقالة منشورة واحدة
GET /content/posts/rss/:churchId?siteUrl=خلاصة RSS 2.0، بعنوان اسم الكنيسة، مع فئة لكل عنصر ووصف يتكوّن من المقتطف أو المحتوى

تُعدّ المقالة "منشورة" بمجرد ضبط publishDate وتجاوزه الوقت الحالي؛ أما publishDate في المستقبل فيعني مقالة مجدولة (مخفية للعموم، وتظهر في الإدارة بشارة Scheduled). تُثري نقاط نهاية القراءة كل مقالة بالحقل authorName، يُحلّ من authorId عبر بوابة وحدة العضوية. عند غياب المقتطف يُستخدم المحتوى منزوع الـmarkdown (نحو 160 حرفًا) في بطاقات القوائم وأوصاف الميتا وخلاصة RSS. يقدّم B1App المسار /{sdSlug}/blog — وهو قائمة تحريرية (ترويسة في الوسط تصبح اسم الفئة أو الوسم النشط عند الترشيح، وصف من شرائح الفئات للترشيح، وصفوف مقالات بصورة مصغّرة على اليسار مع أسماء الكتّاب والمقتطفات) مع إعلان خلاصة RSS كرابط بديل — والمسار /{sdSlug}/blog/[postSlug]، وهو مسار مخصص (وليس خط أنابيب Zone/Section) بترويسة في الوسط (عنوان فئة صغير، والعنوان، واسم الكاتب، وخط تمييز باللون الأساسي)، وصورة رئيسية بنسبة 16:9 بعرض الحاوية، ونص markdown في عمود قراءة بعرض نحو 720 بكسل، وشرائح الوسوم في تذييل المقالة، وشريط "More in {category}" للمقالات ذات الصلة، وJSON-LD من نوع BlogPosting يتضمن الكاتب. تُنسَّق الصفحتان بالكامل عبر رموز السمة، فتتوارث لوحة ألوان كل كنيسة. تُدرج عناوين المدونة في خريطة الموقع sitemap الخاصة بكل كنيسة. تُدار واجهة التأليف في B1Admin (Site → Blog) عبر نافذة لتحرير المقالات: محرر markdown مع زر تبديل المعاينة، ومنتقي صور من المعرض مقصوص بنسبة 16:9، ومنتقي للكاتب (يختار المستخدم المحرِّر افتراضيًا)، وإكمال تلقائي للفئات مبني على الفئات الموجودة، والتحقق من تكرار الـslug، ومفتاح للنشر؛ وتربط الصفوف المنشورة إلى المقالة الحية، وتذكّر الصفحة المشرفين بإضافة رابط /blog إلى التنقل. تُترك التعليقات لخدمات الطرف الثالث: إعداد الموقع العام blogFooterHtml على مستوى الكنيسة (يُحرَّر في Below Every Post في صفحة المدونة، ويظهر فقط عبر Settings→Edit) يُعرض أسفل كل مقالة بواسطة BlogFooterEmbed في B1App، الذي يعيد إنشاء وسوم <script> بحيث تُنفَّذ بموجب 'strict-dynamic' ويشغّلها بالترتيب (ينتهي تحميل src الخارجي قبل تشغيل النص البرمجي المضمَّن التالي)، لأن مقتطفات المورّدين تحمّل مكتبة ثم تستدعيها.

الصفحات الخاصة بالأعضاء فقط​

يعيد pages.visibility استخدام تعداد روابط التنقل — everyone (الافتراضية) وvisitors وmembers وstaff وteam وgroups (مع groupIds) — لكن بوصفه بوابة وصول صارمة، وليس مرشّحًا للتنقل (PageVisibilityHelper.canViewPage). يسير التدفق كالتالي:

  1. تتحقق نقطة نهاية الشجرة المجهولة من الرؤية عند الجلب بعنوان URL. يتلقى الزوار المجهولون لصفحة مقيّدة الاستجابة { restricted: true, visibility } بدلًا من المحتوى — فلا تتسرب الشجرة أبدًا.
  2. لا تزال نقطة النهاية تحترم رمز JWT: يتحقق CustomAuthProvider من ترويسة Authorization في كل طلب، بما في ذلك المسارات المجهولة، فيُحَلّ طلب العضو المصادَق نفسه إلى الصفحة نفسها بشكل طبيعي.
  3. يعرض B1App الصفحة RestrictedPage عند استجابة restricted: يستعيد الجلسة من بيانات الاعتماد المخزّنة، ويعيد جلب الشجرة برمز JWT ويعرضها — أو يعرض بوابة تسجيل دخول مع returnUrl عند غياب الجلسة.
معلومة

تتفاوت دقة البوابة حسب المستوى: يفحص groups الحقل groupIds في الرمز مقابل قائمة الصفحة، ويفحص staff الحقل membershipStatus، أما members وteam فيسمحان حاليًا لأي مستخدم مصادَق من الكنيسة. اعتبر groups الخيار الأكثر صرامة.

تحسين محركات البحث والاكتشاف​

كل هذا عرض يتم من جهة B1App فوق بيانات ContentApi — فالواجهة تخزّن، والتطبيق يُصدر:

الموضوعطريقة العمل
أوصاف الميتايمرّ pages.metaDescription (بحد 300 حرف) عبر MetaHelper.getMetaData() إلى Metadata في Next.js (الوصف وOpen Graph) على كل مسار يعرضه المنشئ. تتضمن إعدادات الصفحة في B1Admin زر Generate بالذكاء الاصطناعي (انظر أدناه)
عمليات إعادة التوجيهصفوف redirects لكل كنيسة تُدار في /content/redirects (الصلاحية content.edit، وحد 200 صف، ومسارات مُطبَّعة). عند ما سيكون خطأ 404، يحلّ مسار الصفحة في B1App المسار عبر GET /content/redirects/public/:churchId ويصدر إعادة توجيه HTTP 308 عبر permanentRedirect في Next؛ أما المسارات غير المطابقة فتنتقل إلى notFound()
صفحة 404 بهوية الكنيسةيعرض not-found.tsx المكوّن BrandedNotFound بشعار الكنيسة واسمها وسمتها بدلًا من خطأ عام. تعيد المسارات غير المعروفة /register/[eventId] و/events/[eventId] و/stream/[pageSlug] و/volunteer/[planId] خطأ 404 حقيقيًا، وكذلك النطاقات الفرعية غير المعروفة وأسماء الصفحات المشوّهة (انظر توجيه المواقع وتعدد المواقع)
البيانات المنظمةJSON-LD من نوع BlogPosting للمقالات؛ وVideoObject لصفحات الخطب الفردية (/{sdSlug}/sermons/[sermonId]) وللصفحات التي تحتوي على عنصر sermons؛ وEvent من عناصر التقويم والفعاليات على صفحات المنشئ وعلى كل صفحة /{sdSlug}/events/[eventId] (الحالة التالية، مع صورة الفعالية بوصفها image)؛ وEvent بمفردات schema.org من عنصر serviceTimes
صفحات الخطبتحصل كل خطبة عامة على صفحة قابلة للفهرسة في /sermons/[sermonId] مع بيانات وصفية كاملة — لم تعد الخطب محبوسة داخل عنصر المتصفح على جانب العميل
التحليلاتيحقن مفتاح الإعداد العام ga4MeasurementId (يُدار بجانب عمليات إعادة التوجيه في B1Admin) وسم gtag من GA4 لكل كنيسة عبر next/script. يرسل تطبيق B1 (/{sdSlug}/mobile) مشاهدات صفحاته إلى هذا المعرّف أيضًا، إلى جانب وسم ChurchApps الخاص به، عندما يكون معرّفًا صالحًا يبدأ بـG- (تبقى معرّفات حاويات GTM على الموقع فقط). يحمل كل استدعاء gtag('config') القيمة display_mode إما installed أو browser، استنادًا إلى navigator.standalone أو استعلام الوسائط (display-mode: standalone) (B1App/src/helpers/mobileAnalytics.ts)
خريطة الموقع والخلاصاتيتضمن مسار sitemap.xml لكل كنيسة صفحات المنشئ وعناوين المدونة و50 صفحة خطبة حديثة (مع <lastmod> من تاريخ نشر كل خطبة). ويدرج أيضًا الصفحات المدمجة /sermons و/groups و/volunteer عندما يكون لها محتوى (المجموعات العامة، وخطط التسجيل للتطوع)، ما لم تستبدلها عملية إعادة توجيه محفوظة. يُستبعد / عندما لا تملك الكنيسة صفحة رئيسية، لأن / عندها يعيد التوجيه إلى /mobile غير المسموح به. تعلن قائمة المدونة عن خلاصة RSS
إمكانية الوصولتعرض الواجهة العامة رابط تخطٍّ يستهدف المعلم <main id="main-content"> في كل غلاف تخطيط

توليد الذكاء الاصطناعي (AskApi)​

يعمل توليد الصفحات والمواقع في AskApi، وهي خدمة منفصلة، تحت المتحكّم /website. تُصادق على الطلبات بالرمز CustomAuthProvider JWT نفسه المستخدم في كل شيء آخر، وهي عديمة الحالة فيما يخص المحتوى: تعيد كل نقطة نهاية JSON، ويحفظ المستدعي (B1Admin) النتيجة عبر ContentApi (ينشئ POST /content/pages/importTree صفحة مع شجرة الأقسام والعناصر المتداخلة كاملةً في استدعاء واحد؛ ويُدرج دائمًا تحت كنيسة المستدعي ويتجاهل المعرّفات في الجسم).

توليد الصفحات (planPage ← writePage)​

يستخدم قالب "AI" للصفحة في AddPageModal في B1Admin خط أنابيب منخفض التكلفة (AskApi/src/helpers/SiteGenHelper.ts) مبني على قاعدة واحدة: لا يُصدر أي نموذج JSON خاص بالمنشئ. يقسّم نموذجان العمل عبر بوابة Vercel AI (طلبات HTTP عادية، ومفتاح SSM في /{env}/aiGatewayApiKey أو AI_GATEWAY_API_KEY):

  • JEV (typesafe-ai/jev) — نموذج قرار مُكتَب الأنواع يُعيد الخيارات والدرجات والقيم المنطقية مع الاحتمالات، لكنه لا يستطيع كتابة النصوص. يختار كل قسم بالترتيب من مكتبة قوالب ثابتة، ويسجّل التخطيطات، ويتحقق من صحة النصوص، ويختار الصور المجانية والأيقونات. تكلف المدخلات نحو 0.04 دولار لكل مليون رمز والمخرجات مجانية، فتكلف نحو 90 استدعاءً لكل صفحة جزءًا من السنت.
  • نموذج دردشة صغير (GPT-4.1 mini افتراضيًا) — يملأ الخانات النصية المسماة ذات الحد الأقصى للطول في القوالب المختارة. الكاتب ثابت واحد، ويمكن تجاوزه بمتغيّر البيئة SITEGEN_COPY_MODEL (أي معرّف نموذج دردشة على البوابة، مثل anthropic/claude-haiku-4.5). في مقارنة عمياء جانبًا إلى جانب على ثلاث كنائس، بدا Claude Haiku 4.5 أدفأ قليلًا، لكن GPT-4.1 mini كان قريبًا منه، وأرخص بنحو أربع مرات وأسرع، لذلك هو الافتراضي. تكلف الصفحة الكاملة بالتخطيطات الثلاثة نحو 1.3 سنت، ونحو 80% منها للكاتب.
المرحلةنقطة النهايةما يحدث
1POST /website/planPageيصنّف نوع الصفحة (رئيسية، زيارة، عن الكنيسة…)، ثم يأخذ 10 تخطيطات مرشحة من احتمالات JEV لكل جولة (البطل + عدد الأقسام ← كل قسم ← الختام)، ويزيل التكرار، ويطلب من JEV تسجيل كل منها من حيث الملاءمة والتدفق والفجوات، ويعيد أفضل 3 إلى جانب نبرة الكتابة وsuggestedStyle (لوحة الألوان والخطوط). تطرح المرشحات التي تشترك في الأقسام نفسها حتى الآن السؤال نفسه على JEV، لذلك تُحفَظ الجولات بالبادئة. يُسجَّل أفضل درجة أقل من 6 بوصفها lowLayoutScore — وهذا السجل هو قائمة القوالب التي تستحق الإضافة. نحو 2 ثانية
2POST /website/writePage (استدعاء واحد لكل مرشح)يملأ الكاتب نصوص الخانات بقسمين لكل استدعاء، بالتوازي، ويعيد خمسة عناوين رئيسية يختار JEV من بينها؛ ويتحقق JEV من صحة كل قسم؛ والأقسام التي تفشل، أو تستخدم عبارة جاهزة، أو تعيد سرد قسم سابق (تسلسلات مشتركة من 4 كلمات، يتحقق منها الكود) تُعاد كتابتها بالتوازي مع ذكر السبب المحدد؛ ويزيل تنظيف برمجي الجمل التي تحتوي على عبارات مواقع الكنائس الجاهزة (ما لم يستخدمها وصف الكنيسة نفسه)؛ ويختار JEV موضوعات الصور والأيقونات وفاصل شكل البطل، ويسجّل النتيجة. يعيد شجرة أقسام جاهزة للحفظ ودرجةً. نحو 6–9 ثوانٍ
3POST /content/pages/importTreeتكتب B1Admin التخطيط الأعلى ترتيبًا فقط (الثاني احتياطي إذا فشلت الكتابة)، وتحفظه وتفتح المعاينة (نحو 10 ثوانٍ بعد الحفظ)

كل مرحلة طلب مستقل، حتى تبقى كل استدعاءات ضمن حد 29 ثانية لبوابة API Gateway. القوالب في SiteGenHelper.buildTree أشجار أقسام وعناصر ثابتة من الكتالوج (text وrow/column وcard وiconFeature وfaq وtable وtestimonial وtextWithPhoto وbox وmap وsermons) وتشير إلى رموز السمة (var(--accent) وvar(--lightAccent) …)، فترث الصفحات المولّدة إعدادات المظهر الحالية للكنيسة. تعني إضافة قالب قسم إضافة قائمة خاناته إلى SECTIONS وشجرته إلى buildTree؛ ويمرّ اختبار الوحدة على كل قالب ويتحقق من شجرته.

المدخلات. لا يجوز أن تذكر النصوص حقائق إلا من مصدرين: ما كتبه المستخدم، وchurchContext.facts — وهي سجلات تجمعها B1Admin قبل التخطيط (أوقات الخدمة العامة وأسماء المجموعات العامة، إضافةً إلى اسم الكنيسة وعنوانها). تضبط الأعلام نفسها القوالب المعتمدة على البيانات: يعرض times عنصر serviceTimes الحي عندما تحتفظ الكنيسة بأوقات الخدمة في B1 (وإلا فجدول مكتوب)، ولا يُعرض groups وcountdown إلا عند وجود بيانات خلفهما. تُجرى استدعاءات JEV بشكل متحوّط — يُطلق نسخة مكررة بعد 1.5 ثانية وتفوز أول إجابة — لأن البوابة تتعثر أحيانًا، والاستدعاءات شبه مجانية.

البقاء على الموضوع. موضوع طلب المستخدم هو موضوع الصفحة، وليس خلفية عن الكنيسة. يصنّف planPage الطلب (home وvisit وabout وministries وgive وcontact وevent وtopic)، وبالنسبة لصفحات event وtopic لا تُعرض قوالب الكنيسة العامة (ملاحظة الراعي، والخطب، والخدمات، والمجموعات، وأثر المجتمع، وأوقات الأسبوع والعد التنازلي، والبطل بالفيديو) أصلًا، بينما تُعرض details (متى / أين / ماذا تحضر) وeventCountdown بتاريخ محدد. يسجّل الحكمان ملاءمة المحتوى للموضوع. تمرّر B1Admin الحقل pageType من الخطة إلى كل استدعاء writePage.

صفحات كاملة من طلبات قصيرة. تتكون الصفحات من ثلاثة إلى ستة أقسام وسطى، بخانات طول سخية، مع سطر تمهيدي في أقسام البطاقات، وقسم أسئلة شائعة من خمسة أسئلة، وتوسّع مرحلة الإصلاح أي قسم يعود هزيلًا. يتم التوليد بنقرة واحدة: لا توجد أسئلة متابعة. وعندما يغفل الطلب تفصيلًا عاديًا تحتاجه الصفحة الكاملة (وقت البدء، أو القاعة، أو ما يُحضر، أو كيفية التسجيل)، يملأه الكاتب باختيار معقول ومتواضع تستطيع الكنيسة تعديله. ولأن الأقسام تُكتب بالتوازي، تُحسم هذه الفجوات مرة واحدة في planPage (assumedDetails، باستدعاء كاتب صغير واحد يعمل بالتوازي مع أخذ عينات التخطيط)، ويعاد تمريرها إلى كل استدعاء writePage عبر churchContext.assumedDetails، فلا يمكن لقسم أن يقول 5:00 بينما يقول آخر 5:30. يصلح JEV أي قسم يتعارض مع الطلب، أو مع سجلات الكنيسة، أو مع هذه التفاصيل المحسومة. لا تُعرض التفاصيل المحسومة في الواجهة؛ تراجع الكنيسة الصفحة وتعدّلها كأي صفحة أخرى. وهناك أشياء لا تُختلق أبدًا: أسماء الأشخاص، وأرقام الهواتف، وعناوين البريد الإلكتروني والويب، والأسعار، والإحصاءات، وتاريخ الكنيسة، والاقتباسات المنسوبة إلى أشخاص، ويوم الأسبوع لتاريخ لم يحدد الطلب يومه.

المرئيات. لا تسمّي القوالب صورها أو أيقوناتها. بل تترك خانات مفتوحة، ويمر مسار عام واحد (visualSlots ← pickVisuals ← applyVisuals في SiteGenHelper) عبر الشجرة المكتملة ويملأ كل خانة: خلفية قسم أو مدخل معرض معلَّم بـauto:photo، وauto:icon، وauto:divider للبطل، ومن دون أي علامة، أي عنصر textWithPhoto أو card أو image يكون حقل photo فيه فارغًا. يختار JEV كل صورة من النص المجاور لها (صورة البطاقة من عنوانها ونصها، والخلفية من نص القسم)، دون تكرار أي موضوع في الصفحة الواحدة. لذلك يحصل أي قالب جديد على الصور تلقائيًا. الصور موضوعات بحث في Pexels تُصدر بوصفها عناصر نائبة pexels:<term> تحلّها B1Admin عبر POST /content/stock/search؛ والعميل الذي لا يرسل resolvesPhotos يحصل على صورة بطل مدمجة وأشرطة لونية مسطحة وبطاقات بلا صور. لا توجد عمدًا موضوعات لصور الأشخاص، ولا يحمل قالب الراعي أي صورة: يجب ألا يحل غريب من المخزون محل شخص حقيقي أبدًا. بالنسبة للكنيسة التي لا تملك صفحات بعد، تطبق B1Admin suggestedStyle على الأنماط العامة؛ أما المواقع القائمة فتحتفظ بمظهرها.

نقاط النهاية الأخرى​

معلومة

يبقى زر إعادة كتابة SectionToolbar وزر Generate Site في قائمة الصفحات في B1Admin معلَّقين من جهة العميل. لا تزال نقاط نهاية AskApi أدناه تستجيب؛ الواجهة فقط مخفية.

نقطة النهايةالغرض
POST /website/generatePageOutline ← generateSectionتدفق الصفحة الأصلي من خطوتين (المخطط، ثم استدعاء LLM واحد لكل قسم يُصدر JSON للعناصر). استبدلته B1Admin بـplanPage/writePage بسبب التكلفة؛ وتبقى لمستهلكي الواجهة البرمجية
POST /website/generateSiteتوليد الموقع كاملًا. مصمم على مرحلتين عمدًا: يعيد الاستدعاء planOnly: true خطة الصفحات المتعددة فقط (استدعاء نموذج سريع واحد)، ثم يطلب العميل المحتوى الكامل — فتبقى كل الطلبات ضمن مهلة Lambda/API-Gateway
POST /website/rewriteSectionإعادة كتابة تحافظ على البنية: لا يحق للنموذج إلا تغيير الإجابات التي تحمل نصوصًا. تُقارن بصمة بنية متكررة (المعرّفات + الأنواع + الترتيب) قبل التعديل وبعده؛ وأي عدم تطابق يعيد القسم الأصلي مع fallback: true بدلًا من بنية تالفة
POST /website/generateAltTextاستدعاء رؤية على حتى 20 رابط صورة؛ يعيد نصًا بديلًا موجزًا (بحد 125 حرفًا، مع إزالة بادئات "photo of")
POST /website/generateMetaDescriptionوصف ميتا واحد لمحركات البحث (بحد 155 حرفًا) من النص الظاهر للصفحة — مرتبط بزر Generate في إعدادات الصفحة في B1Admin

توجد تعليمات هذه النقاط كملفات markdown تحت AskApi/config/instructions/، بما فيها كتالوج العناصر الذي يولّد النموذج منه. ويحافظ مبدآن تصميميان على صدق الكتالوج: يمرّر العميل availableElementTypes في كل طلب (يجب أن يستخدم الطلب الأنواع الموجودة في هذه القائمة فقط — ولا يُثبّت الخادم المجموعة الكاملة)، وتحمل أداة MCP describe_page_builder في الواجهة البرمجية الدليل نفسه لوكلاء الذكاء الاصطناعي الذين يعملون عبر MCP. النماذج هي Anthropic Claude عبر OpenRouter — 3.5 Haiku لمحتوى الأقسام (زمن الاستجابة)، و3.5 Sonnet للمخططات وخطط المواقع والرؤية — مع احتياطي من OpenAI عند عدم ضبط مفتاح OpenRouter.

النماذج التفاعلية​

اكتسبت النماذج (وحدة العضوية) وضعًا تفاعليًا موجّهًا لصفحات بطاقات الاتصال. تقود أربعة أعمدة في forms هذا الوضع: displayMode (standard | conversational)، وautoCreatePerson، وfollowUpSubject، وfollowUpBody.

  • العرض — يتحول FormSubmissionEdit في apphelper إلى المكوّن ConversationalForm (سؤال واحد في كل مرة) عندما تكون displayMode هي conversational؛ وتمرّر صفحة النموذج في B1App الوضع. حمولة الإرسال نفسها في الحالتين.
  • إنشاء الشخص تلقائيًا — عند الإرسال مع ضبط autoCreatePerson، تُزيل ConversationalFormHelper.findOrCreatePerson التكرار بالبريد الإلكتروني (دون حساسية لحالة الأحرف)، وإلا ينشئ أسرة وشخصًا مع membershipStatus: "Guest"، ثم يربط الإرسال بهذا الشخص.
  • بريد المتابعة — عند ضبط الموضوع والنص، يتلقى المرسل بريدًا إلكترونيًا من قالب (مع الرموز {firstName} / {churchName}) عبر المسار القائم للبريد المعاملاتي (TransactionalEmailHelper)، وليس عبر ملخص الإشعارات أبدًا. وكلا الأثرين غير قاتل: فالفشل لا يُفقد الإرسال أبدًا.

تُضبط الحقول الأربعة عبر الواجهة البرمجية حاليًا؛ ولا يعرضها محرر النماذج في B1Admin بعد.

ذاكرة التخزين المؤقت للموقع العام​

يخزّن مسار العرض العام في B1App عمليات الجلب المرتبطة بالكنيسة مؤقتًا (next: { revalidate: 300, tags: [sdSlug] } في الإنتاج؛ و0 في التطوير)، لذا قد تبقى صفحة حية قديمة حتى خمس دقائق بعد كتابة في ContentApi. يُسقط POST /api/revalidate/{sdSlug} في B1App التخزين المؤقت مبكرًا عبر استدعاء revalidateTag(sdSlug)>، وهو الطريقة الوحيدة لذلك.

يكتب على هذا التخزين جهتان:

  1. B1Admin — يرسل clearSiteCache() في B1Admin/src/site/siteCache.ts طلب POST بعد حفظ المحرر. ويفضّل النطاق الفرعي للموقع النشط (يجب أن يبطل موقع ثانوي وسم ذلك الموقع، لا وسم الكنيسة الافتراضي).
  2. Api — تُطلق تعديلات المحتوى التي لا تمر عبر B1Admin أبدًا (مفاتيح API، وMCP، والذكاء الاصطناعي) SiteCacheHelper.bump(churchId) من متحكمات المحتوى. تحلّ المساعدة النطاق الفرعي للكنيسة عبر SubDomainHelper وترسل POST إلى {b1AppRoot}/api/revalidate/{sd}. تُبتلع الإخفاقات حتى لا يُفشل B1App غير القابل للوصول أي حفظ.

المتحكمات التي تطلق التحديث: الصفحات (الحفظ، والحذف، والنسخ، والنشر، والتراجع، وإلغاء النشر، والقالب المؤقت للذكاء الاصطناعي)، والأقسام، والعناصر، والكتل، والروابط، والأنماط العامة، والمقالات، وعمليات إعادة التوجيه. يكون b1AppRoot في التطوير http://{subdomain}.localtest.me:3301؛ وفي التجريبي والإنتاج https://{subdomain}.b1.church.

صفحات ذات صلة​