Архітектура конструктора сайтів
Кожен сайт церкви, що обслуговується B1App, відтворюється з дерева контенту (сторінки, секції, елементи), яке зберігається в ContentApi і редагується візуально в B1Admin. Одна спільна бібліотека компонентів відтворює і попередній перегляд редактора, і живий сайт. Один каталог типів елементів визначає, що може з’явитися на сторінці, а окремий сервіс ШІ може створювати або переписувати це дерево. Ця сторінка описує весь стек: контракт елементів у @churchapps/helpers, конвеєр відтворення, елементи з даними церкви, віджети для всього сайту, шар блогу, сторінки з обмеженим доступом, SEO, генерацію за допомогою ШІ та розмовні форми.
Огляд
┌──────────────────────────────┐ ┌─────────────────────────────────────────┐
│ 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/… │
└──────────────────────────────┘ └─────────────────────────────────────────┘
Три правила діють у всьому стеку:
- Одне дерево, два рендерери. Сторінка — це дерево
pages → sections → elements, де кожен вузол зберігає свої налаштування у вигляді JSON-блобаanswers. Ті самі компоненти apphelper відтворюють редактор drag-and-drop у B1Admin і серверно відтворений публічний сайт у B1App. Окремого «формату публікації» немає. - Контракт розміщено в
@churchapps/helpers.ElementTypes.ts— єдиний каталог типів елементів. Рендерери розв’язуються через реєстр в apphelper, а форми редактора розташовані в B1Admin. Додавання типу елемента вимагає змін у всіх трьох місцях, саме в такому порядку. - Публічний сайт читає анонімні ендпоінти. Усе, що потрібно B1App, є публічним: дерево сторінок, налаштування, дописи блогу, редіректи та ендпоінти даних церкви в інших модулях. Автентифікація необов’язкова. JWT на анонімному ендпоінті дерева відкриває сторінки лише для учасників, а більше нічого не змінюється.
Дерево контенту
Модуль контенту (Api/src/modules/content) зберігає дані конструктора:
| Таблиця | Роль |
|---|---|
pages | Одна сторінка на URL: url, title, layout, а також visibility/groupIds (обмеження доступу) та metaDescription (SEO) |
sections | Горизонтальні смуги на сторінці (або в блоці): фон, колір тексту та answersJSON, що містить стилізацію та конфігурації фігурних роздільників dividerTop/dividerBottom |
elements | Елементи контенту всередині секції: elementType + answersJSON. Для типів макета (row/column, carousel) можуть вкладатися один в один |
blocks | Повторно використовувані групи секцій/елементів (блоки футера, блоки елементів), спільні для сторінок |
posts | Окремі дописи блогу (див. Блог) |
redirects | Пари fromPath → toPath для кожної церкви, обмежені 200 записами (див. SEO) |
settings | Налаштування церкви у форматі ключ-значення. Рядки з позначкою public віддаються анонімно і містять конфігурацію віджетів та аналітики |
Усе дерево для однієї URL повертається одним анонімним викликом, GET /content/pages/:churchId/tree?url=/about, з якого B1App виконує серверне відтворення. Запити редактора натомість отримують дані за id і зберігають внутрішні id.
Контракт елементів
Каталог (@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 уточнюють макети, відмінні від browse.
Елемент rawHTML має дві відповіді: rawHTML (розмітка) і javascript. Скрипти, вставлені через innerHTML, ніколи не виконуються, тому RawHTMLElement створює кожен вузол <script> у розмітці заново, як новий елемент. Такі вузли, не вставлені парсером, довіряються за політикою strict-dynamic у CSP. Відповідь javascript, що починається з < (фрагмент від постачальника, вставлений разом із тегами <script>), розбирається як розмітка і обробляється так само. В іншому разі вона виконується як звичайний вбудований скрипт. B1Admin позначає голе посилання в полі JavaScript, оскільки саме по собі посилання виконується як скрипт, що нічого не робить. Елемент map нічого не відображає і не завантажує скрипт Google Maps, якщо не налаштовано ключ API Maps.
Рендерери (@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, …) або вбудованому конструктору полів для кожного типу. Дзеркало цього каталогу для ШІ — інструмент API MCP describe_page_builder (див. Сервер 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(). Компоненти Section в обох застосунках (B1App/src/components/Section.tsx, B1Admin/src/site/admin/Section.tsx) розбирають відповіді й монтують роздільник, а SectionEdit.tsx у B1Admin надає інтерфейс вибору. Пакети постачають лише будівельний блок. Підключення на рівні секції є завданням застосунків-споживачів.
Елементи з даними церкви
Три типи елементів відтворюють живі дані церкви, а не авторський контент. Обмеження модулів збережено: кожен із них викликає публічний ендпоінт відповідного модуля безпосередньо з браузера:
| Елемент | Ендпоінт | Примітки |
|---|---|---|
campaignProgress | GET /giving/funds/public/:churchId/:fundId/total | Повертає { fundId, totalAmount, donationCount }, необов’язкове вікно ?startDate=&endDate=. Елемент порівнює це зі своєю відповіддю goalAmount |
staffGrid | GET /membership/groupmembers/public/:churchId/:groupId | Лише за бажанням: у групи має бути встановлено publicRoster (типово вимкнено). Проєкція навмисно мінімальна: personId, displayName, leader, фото. Контактних чи демографічних полів немає |
serviceTimes | GET /attendance/servicetimes/public/:churchId | Повертає дерево кампус → служіння → час. Рендерер apphelper на його основі генерує JSON-LD Event зі schema.org за принципом «найкращих зусиль» (API повертає звичайні дані) |
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/{id}, а меню «Підписатися» дає доступ до ICS-стрічки календаря.display: "month"відтворюєCalendarElementз apphelper з callbackeventUrl.GroupCalendar/CuratedCalendar→EventCalendar/CuratedEventCalendarпісля натискання переходять за цією URL, а не відкривають діалогове вікно з деталями. 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, бічну панель «Коли/Де», кнопку Зареєструватися на цю подію (якщо registrationEnabled) і посилання Додати до мого календаря на GET /content/events/public/:churchId/:id/ical. Фото використовується як зображення Open Graph, а EventPageJsonLd виводить JSON-LD Event для наступного входження. Невідома або прихована подія повертає справжню помилку 404.
Віджети для всього сайту
Два віджети відтворюються на кожній публічній сторінці, а не всередині дерева: AnnouncementBanner (закривана смуга у верхній частині сторінки) та Launcher (плаваючий центр дій для посилань у стилі «пожертвувати / відвідати / дивитися»). Обидва компоненти та їхні допоміжні функції parse*Config() постачаються в apphelper. Конфігурація — це два публічні рядки налаштувань із ключами announcementBanner і launcher. Їх записує SiteWidgetsEdit в B1Admin (на сторінці Вигляд), а публічний макет B1App читає через GET /content/settings/public/:churchId. API трактує їх як непрозорі пари ключ-значення. Назви ключів — домовленість між двома застосунками.
Блог
Блог — окремий тип контенту, а не шар поверх сторінок конструктора. Рядок 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 означає запланований допис: він прихований для публіки і позначений міткою «Заплановано» в адмінці. Endpoint-и читання доповнюють кожен допис полем authorName, яке визначається за authorId через шлюз модуля членства. Якщо анотації немає, у картках списку, метаописах і RSS використовується вміст без розмітки markdown (близько 160 символів). B1App віддає /{sdSlug}/blog: редакційний список (центрований заголовок, який стає назвою активної категорії чи тега під час фільтрації, рядок фільтрів-чіпів за категоріями, рядки дописів із мініатюрою зліва, автором і анотацією). Стрічка RSS оголошена як альтернативне посилання. Також B1App віддає /{sdSlug}/blog/[postSlug], окремий маршрут (не конвеєр Zone/Section) із центрованим заголовком (категорія, заголовок, автор, акцентна лінія основного кольору), героєм 16:9 на ширину контейнера, текстом у markdown у колонці близько 720 пікселів, чіпами тегів у підвалі статті, стрічкою пов’язаних дописів «Більше в {category}» і JSON-LD BlogPosting, що включає автора. Обидві сторінки повністю стилізуються з токенів теми, тож успадковують палітру кожної церкви. URL блогу включено до карти сайту кожної церкви.
Інтерфейс авторства в B1Admin (Сайт → Блог) редагує дописи в діалоговому вікні: редактор markdown із перемикачем попереднього перегляду, вибір зображення з галереї з обрізкою 16:9, вибір автора (типово користувач, що редагує), автодоповнення категорій на основі вже наявних, перевірку повторюваних slug і перемикач публікації. Опубліковані рядки посилаються на живий допис, а сторінка спонукає адміністраторів додати посилання /blog у навігацію. Коментарі залишаються за сторонніми сервісами. Загальноцерковий публічний параметр blogFooterHtml (редагується в розділі Під кожним дописом на сторінці блогу, видно лише в Налаштування → Редагувати) відтворюється під кожним дописом компонентом B1App BlogFooterEmbed. Він заново створює теги <script>, щоб вони виконувалися за політикою 'strict-dynamic', і запускає їх по порядку: зовнішній src завершує завантаження до виконання наступного вбудованого скрипта. Це потрібно, бо скрипти від постачальників спочатку завантажують бібліотеку, а потім викликають її.
Сторінки лише для учасників
pages.visibility використовує той самий перелік, що й посилання навігації: everyone (типово), visitors, members, staff, team, groups (з groupIds). Але він працює як жорсткий контроль доступу, а не фільтр навігації (PageVisibilityHelper.canViewPage). Процес такий:
- Анонімний ендпоінт дерева перевіряє видимість для запитів за URL. Анонімні виклики обмеженої сторінки отримують
{ restricted: true, visibility }замість вмісту, тож дерево ніколи нічого не витікає. - Ендпоінт і далі враховує JWT.
CustomAuthProviderперевіряє заголовокAuthorizationу кожному запиті, включно з анонімними маршрутами, тож запит автентифікованого учасника за тією самою URL виконується нормально. - B1App відтворює
RestrictedPageу разі відповідіrestricted. Він відновлює сесію зі збережених облікових даних, повторно запитує дерево з JWT і відтворює його. Якщо сесії немає, він показує екран входу зreturnUrl.
Рівень деталізації залежить від рівня. groups перевіряє groupIds з токена зі списком сторінки, а staff перевіряє membershipStatus. Але members і team наразі пропускають будь-якого автентифікованого користувача церкви. Вважайте groups суворішим варіантом.
SEO та віднаходження
Усе це — відтворення на боці B1App поверх даних ContentApi: API зберігає, застосунок видає.
| Аспект | Як це працює |
|---|---|
| Метаописи | pages.metaDescription (≤300 символів) передається через MetaHelper.getMetaData() у Metadata Next.js (опис + Open Graph) на кожному маршруті, відтвореному конструктором. Налаштування сторінки в B1Admin містять кнопку «Згенерувати» на основі ШІ (див. нижче) |
| Редіректи | Рядки 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, так само як невідомі піддомени та некоректні slug сторінок (див. Маршрутизація сайтів та мультисайтовість) |
| Структуровані дані | 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) також надсилає перегляди сторінок на цей ID разом із тегом ChurchApps, якщо це дійсний ідентифікатор G-. Ідентифікатори контейнерів GTM залишаються лише для сайту. Кожен виклик gtag('config') містить display_mode зі значенням installed або browser, що визначається за navigator.standalone або медіазапитом (display-mode: standalone) (B1App/src/helpers/mobileAnalytics.ts) |
| Карта сайту та стрічки | Маршрут sitemap.xml для кожної церкви включає сторінки конструктора, URL блогу та 50 найновіших сторінок проповідей (з <lastmod> із дати публікації кожної проповіді). Він також перелічує вбудовані сторінки /sermons, /groups і /volunteer, якщо вони мають вміст (публічні групи, плани волонтерства), якщо тільки збережений редірект не замінює цей шлях. / виключається, якщо в церкви немає домашньої сторінки, оскільки тоді / перенаправляє на заборонений /mobile. Сторінка списку блогу рекламує стрічку RSS |
| Доступність | Публічна оболонка відтворює посилання для пропуску, що вказує на орієнтир <main id="main-content">, у кожній обгортці макета |
Генерація ШІ (AskApi)
Генерація сторінок і сайтів виконується в AskApi, окремому сервісі під контролером /website. Він автентифікується тим самим JWT CustomAuthProvider, що й усе інше, і є безстановим щодо контенту: кожен ендпоінт повертає JSON, а викликач (B1Admin) зберігає результат через ContentApi. Наприклад, POST /content/pages/importTree створює сторінку з повним вкладеним деревом секцій і елементів одним викликом. Він завжди вставляє сторінку під церкву викликача й ігнорує id у тілі запиту.
Генерація сторінок (planPage → writePage)
Шаблон сторінки «AI» у AddPageModal B1Admin використовує недорогий конвеєр (AskApi/src/helpers/SiteGenHelper.ts), побудований на одному правилі: жодна модель ніколи не видає JSON конструктора. Дві моделі розподіляють роботу через Vercel AI Gateway (звичайний 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 був близьким, приблизно у 4 рази дешевшим і швидшим, тож він є типовим. Повна сторінка з усіма трьома макетами коштує близько 1,3 цента, з яких близько 80% припадає на автора тексту.
| Етап | Ендпоінт | Що відбувається |
|---|---|---|
| 1 | POST /website/planPage | Класифікує тип сторінки (home, visit, about…), потім вибирає 10 кандидатів-макетів з імовірностей JEV для кожного раунду (hero + кількість секцій → кожна секція → завершальна), видаляє дублікати й доручає JEV оцінити кожен за відповідністю, потоком і прогалинами. Повертає топ-3 разом із голосом письма та suggestedStyle (палітра + шрифти). Кандидати, що мають однакові секції до цього моменту, ставлять JEV ідентичне запитання, тому раунди мемоїзуються за префіксом. Найкраща оцінка нижче 6 записується як lowLayoutScore. Цей журнал є чергою шаблонів, які варто додати. ~2 с |
| 2 | POST /website/writePage (один виклик на кандидата) | Автор заповнює текст слотів по дві секції за виклик, паралельно, і повертає п’ять заголовків hero, з яких JEV обирає. JEV перевіряє факти в кожній секції. Секції, які не пройшли перевірку, використовують стокову фразу або переповідають попередню секцію (спільні послідовності з 4 слів перевіряються кодом), переписуються паралельно з конкретною причиною. Очищення коду видаляє речення зі стоковими фразами сайтів церков (якщо тільки власний опис церкви не використовує їх). JEV обирає теми фото, іконки та фігурний роздільник hero і оцінює результат. Повертає готове до збереження дерево секцій та оцінку. ~6–9 с |
| 3 | POST /content/pages/importTree | B1Admin записує лише макет з найвищим рейтингом (наступний за ним є запасним варіантом, якщо запис не вдався), зберігає його та відкриває попередній перегляд (~10 с після збереження) |
Кожен етап — окремий запит, щоб кожен виклик залишався в межах ліміту API Gateway 29 секунд. Шаблони в 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.
Повні сторінки з коротких запитів. Сторінки мають від трьох до шести основних секцій, щедру довжину слотів, вступний рядок на картках-секціях і FAQ з п’ятьма запитаннями. Етап відновлення розширює будь-яку секцію, що вийшла замалою. Генерація здійснюється одним кліком, уточнювальних запитань немає. Коли запит не містить звичайної деталі, потрібної для повної сторінки (час початку, кімната, що взяти з собою, як зареєструватися), автор заповнює її правдоподібним, скромним варіантом, який церква може відредагувати. Оскільки секції пишуться паралельно, ці прогалини вирішуються один раз у planPage (assumedDetails, один невеликий виклик автора, що виконується разом із вибіркою макетів). Далі вони передаються в кожен виклик writePage через churchContext.assumedDetails, тож одна секція не може сказати 5:00, а інша 5:30. JEV виправляє будь-яку секцію, що суперечить запиту, записам церкви або цим вирішеним деталям. Вирішені деталі в інтерфейсі не показуються. Церква переглядає та редагує сторінку, як і будь-яку іншу. Деякі речі ніколи не вигадуються: імена людей, номери телефонів, адреси електронної пошти та вебсайтів, ціни, статистика, історія церкви, цитати, приписані людям, і день тижня для дати, для якої запит його не вказав.
Візуали. Шаблони ніколи не називають свої фото чи іконки. Вони залишають слоти відкритими. Один загальний прохід (visualSlots → pickVisuals → applyVisuals у SiteGenHelper) обходить готове дерево та заповнює кожен слот: фон секції або запис галереї з позначкою auto:photo, auto:icon, фігурний роздільник hero auto:divider, а також будь-який textWithPhoto, card або image без жодної позначки, якщо його photo порожнє. JEV обирає кожне зображення з тексту поруч: фото картки з її заголовка й тексту, фон з тексту секції. Тема на сторінці не повторюється. Тож новий шаблон отримує фото безкоштовно. Фото — це пошукові теми Pexels, що надсилаються як заповнювачі pexels:<term>, які B1Admin розв’язує через POST /content/stock/search. Клієнт, який не надсилає resolvesPhotos, отримує вбудоване зображення hero, суцільні кольорові смуги та картки без фото. Навмисно немає тем з портретами, а шаблон пастора не містить фото: випадковий незнайомець ніколи не повинен замінювати справжню людину. Для церкви без сторінок B1Admin застосовує suggestedStyle до глобальних стилів. Наявні сайти зберігають свій вигляд.
Інші ендпоінти
Кнопка переписування SectionToolbar і кнопка «Generate Site» у списку сторінок B1Admin залишаються закоментованими на боці клієнта. Ендпоінти AskApi нижче все ще відповідають. Приховано лише цей інтерфейс.
| Ендпоінт | Призначення |
|---|---|
POST /website/generatePageOutline → generateSection | Початковий двоетапний процес сторінок (план, потім один виклик LLM на секцію, що видає JSON елементів). Замінений у B1Admin на planPage/writePage через вартість і збережений для споживачів API |
POST /website/generateSite | Генерація всього сайту. Двофазна за задумом: виклик з planOnly: true повертає лише багатосторінковий план (один швидкий виклик моделі). Потім клієнт запитує повний вміст, і кожен запит залишається в межах тайм-ауту Lambda/API Gateway |
POST /website/rewriteSection | Переписування зі збереженням структури: модель може змінювати лише відповіді з текстом. Рекурсивна сигнатура структури (id + типи + порядок) порівнюється до й після. Будь-яка невідповідність повертає початкову секцію з fallback: true замість пошкодженої структури |
POST /website/generateAltText | Візуальний виклик для до 20 URL зображень. Повертає стислий альтернативний текст (≤125 символів, префікси «photo of» видалено) |
POST /website/generateMetaDescription | Один SEO-метаопис (≤155 символів) на основі тексту сторінки. Підключений до кнопки «Згенерувати» в налаштуваннях сторінки B1Admin |
Промпти для цих ендпоінтів — це файли markdown у AskApi/config/instructions/, зокрема каталог елементів, з якого генерує модель. Два принципи дизайну тримають каталог чесним. По-перше, клієнт передає availableElementTypes у кожному запиті: промпт може використовувати лише типи з цього списку, а сервер ніколи не прописує повний набір жорстко. По-друге, інструмент API MCP describe_page_builder містить той самий посібник для агентів ШІ, які працюють через MCP. Моделі — Anthropic Claude через OpenRouter: 3.5 Haiku для вмісту секцій (через затримку), 3.5 Sonnet для планів, структур сайтів і візуального аналізу. Коли ключ OpenRouter не налаштовано, використовується резервний варіант OpenAI.
Розмовні форми
Форми (модуль членства) отримали розмовний режим, орієнтований на сторінки у стилі картки контакту. Чотири стовпці в forms керують ним: displayMode (standard | conversational), autoCreatePerson, followUpSubject, followUpBody.
- Відтворення:
FormSubmissionEditз apphelper перемикається на компонентConversationalForm(одне запитання за раз), колиdisplayModeмає значенняconversational. Сторінка форми B1App передає цей режим далі. Структура надісланих даних в обох випадках однакова. - Автоматичне створення особи: під час надсилання з увімкненим
autoCreatePersonConversationalFormHelper.findOrCreatePersonусуває дублікати за електронною поштою (без урахування регістру). Інакше він створює домогосподарство та особу зmembershipStatus: "Guest", потім прив’язує надсилання до цієї особи. - Супровідний лист: якщо задано тему та текст, відправник отримує лист за шаблоном (з токенами
{firstName}/{churchName}) через наявний транзакційний шлях (TransactionalEmailHelper). Дайджест сповіщень не використовується. Обидва побічні ефекти не є критичними: збій ніколи не призводить до втрати надсилання.
Наразі ці чотири поля встановлюються через API. Редактор форм B1Admin ще не надає до них доступу.
Кеш публічного сайту
Шлях публічного відтворення B1App кешує запити, позначені тегом церкви (next: { revalidate: 300, tags: [sdSlug] } у продакшені, 0 у dev). Тому жива сторінка може залишатися застарілою до п’яти хвилин після запису в ContentApi. POST /api/revalidate/{sdSlug} у B1App викликає revalidateTag(sdSlug) і є єдиним способом скинути цей кеш раніше.
Двоє авторів звертаються до нього:
- B1Admin:
clearSiteCache()уB1Admin/src/site/siteCache.tsвиконує POST після збереження в редакторі. Вона надає перевагу піддомену активного сайту. Допоміжний сайт має скидати саме той тег, а не типовий тег церкви. - Api: зміни контенту, які не проходять через B1Admin (ключі API, MCP, ШІ), запускають
SiteCacheHelper.bump(churchId)з контролерів контенту. Помічник визначає піддомен церкви черезSubDomainHelperі виконує POST на{b1AppRoot}/api/revalidate/{sd}. Помилки ігноруються, щоб недоступний B1App не міг спричинити збій збереження.
Контролери, що виконують bump: сторінки (збереження, видалення, дублювання, публікація, скасування змін, зняття з публікації, тимчасова сторінка ШІ), секції, елементи, блоки, посилання, глобальні стилі, дописи та редіректи. Dev b1AppRoot — http://{subdomain}.localtest.me:3301. Demo і prod використовують https://{subdomain}.b1.church.
Пов’язані сторінки
- Маршрутизація сайтів та мультисайтовість: як запит визначає церкву та сайт і як маршрутизуються власні домени
- Ендпоінти контенту: повний REST-інтерфейс для сторінок, секцій, елементів, блоків, дописів, редіректів і налаштувань
- AppHelper: npm-пакет, що постачає рендерери, реєстр, роздільники та віджети
- Сервер MCP: зокрема інструмент-посібник
describe_page_builder - Редактор сторінок (для кінцевих користувачів): документація редактора для персоналу