Архитектура конструктора сайтов
Каждый сайт церкви, который обслуживает B1App, отображается из дерева контента — страниц, разделов и элементов, — которое хранится в ContentApi и редактируется визуально в B1Admin. Одна общая библиотека компонентов отображает и предпросмотр редактора, и живой сайт; один каталог типов элементов определяет, что может появиться на странице, а отдельный сервис ИИ может создать или переписать это дерево. На этой странице описан весь стек: контракт элементов в @churchapps/helpers, конвейер рендеринга, элементы с данными церкви, виджеты всего сайта, слой блога, страницы с ограничением доступа, SEO, генерация ИИ и диалоговые формы.
Обзор
┌──────────────────────────────┐ ┌─────────────────────────────────────────┐
│ B1Admin — редактор │ │ Api — модуль /content (ContentApi) │
│ ContentEditor · SectionEdit │ POST /… │ │
│ ElementEdit · PageLinkEdit │ ──────────▶ │ pages ─ sections ─ elements blocks │
│ SiteWidgetsEdit · Blog │ │ posts redirects settings styles │
└──────────┬───────────────────┘ └───────────────┬─────────────────────────┘
│ │ GET /content/pages/:churchId/tree?url=…
│ общий конвейер рендеринга ▼ (анонимно, JWT учитывается)
│ ┌───────────────────────────────┐ ┌─────────────────────────────────┐
└──▶│ @churchapps/helpers │◀──│ B1App — публичный сайт (Next.js)│
│ ElementTypes.ts (каталог) │ │ Zone → Section → Element │
│ @churchapps/apphelper │ │ + виджеты, JSON-LD, sitemap, │
│ ElementRegistry, рендереры │ │ редиректы, брендированная 404 │
│ SectionDivider, виджеты │ └───────────────┬─────────────────┘
└───────────────────────────────┘ │ элементы с данными церкви
┌──────────────────────────────┐ ▼
│ AskApi — /website/* (ИИ) │ ┌─────────────────────────────────────────┐
│ generateSite · rewriteSection│ │ /giving/funds/public/…/total │
│ generateAltText · metaDesc │ │ /membership/groupmembers/public/… │
│ возвращает JSON; B1Admin сохраняет │ │ /attendance/servicetimes/public/… │
└──────────────────────────────┘ └─────────────────────────────────────────┘
Три правила действуют во всём стеке:
- Одно дерево, два рендерера. Страница — это дерево
pages → sections → elements, где каждый узел хранит свои настройки в виде JSON-поляanswers. Одни и те же компоненты apphelper отображают редактор с перетаскиванием в 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 типов:
| Категория | Типы элементов |
|---|---|
| layout (6) | row, column, box, carousel, whiteSpace, block |
| content (11) | text, textWithPhoto, card, faq, iconFeature, testimonial, socialIcons, countdown, stats, table, buttonLink |
| media (4) | image, gallery, video, map |
| church (12) | logo, sermons, stream, donation, donateLink, form, calendar, groupList, groups, campaignProgress, staffGrid, serviceTimes |
| advanced (2) | rawHTML, iframe |
Элемент sermons — самый настраиваемый из церковных типов: ответ layout выбирает browse (прежний полный обозреватель), grid, list или featuredLatest, а playlistId, itemCount, showTitles и showDates уточняют макеты, отличные от browse.
У элемента rawHTML два ответа: rawHTML (разметка) и javascript. Скрипты, вставленные через innerHTML, никогда не выполняются, поэтому RawHTMLElement пересоздаёт каждый узел <script> в разметке как новый элемент. Эти узлы, не вставленные парсером, считаются доверенными по политике CSP strict-dynamic. Ответ javascript, который начинается с < (фрагмент поставщика, вставленный вместе с тегами <script>), разбирается как разметка и обрабатывается так же. В остальных случаях он выполняется как обычный встроенный скрипт. B1Admin помечает голый URL в поле JavaScript, так как одиночный URL выполняется как пустой скрипт. Элемент map ничего не выводит и не загружает скрипт Google Maps, если не настроен ключ Maps API.
Рендереры (@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, …) или на построитель полей для каждого типа. Аналог этого каталога для ИИ — инструмент MCP describe_page_builder в API (см. 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.photoUrl, а при отсутствии фото — название на тёмном цвете темы), ведущих на/events/{id}, с меню Subscribe для ICS-ленты календаря.display: "month"отображаетCalendarElementиз apphelper с обратным вызовомeventUrl.GroupCalendar/CuratedCalendar→EventCalendar/CuratedEventCalendarтогда переходят по этому URL при нажатии вместо открытия диалога с подробностями (B1Admin не передаётeventUrl, поэтому административный календарь сохраняет диалог).tagфильтрует оба варианта черезEventHelper.hasTag()(@churchapps/helpers): регистронезависимое совпадение со спискомevents.tagsчерез запятую; пустое значение показывает всё. Соединение curated-календаря выбираетe.tags, поэтому у событий из curated-календарей есть теги.
События из curated-календарей ссылаются через realEventId (eventPageId()), поэтому URL всегда указывает на исходное событие. /{sdSlug}/events/[eventId] — отдельный маршрут (не конвейер конструктора): он загружает GET /content/events/public/:churchId/:id — который возвращает null для событий в ожидании или отклонённых и для приватных событий без регистрации, а также добавляет roomNames из бронирований комнат, не отклонённых ранее, — рендерит EventPageContent (фото-шапка, описание в markdown, боковая колонка When/Where, 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 (на странице Appearance), а публичная разметка 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 — это запланированная запись (скрыта публично, в админке показывается с чипом Scheduled). Эндпоинты чтения дополняют каждую запись полем authorName, которое разрешается из authorId через шлюз модуля membership. Отсутствующая выдержка заменяется содержимым без разметки (~160 символов) в карточках списка, метаописаниях и RSS. B1App отдаёт /{sdSlug}/blog — редакционный список (заголовок по центру, который становится названием активной категории или тега при фильтрации, ряд фильтров-чипов категорий, строки записей с миниатюрой слева, подписями авторов и выдержками), с лентой RSS, объявленной как альтернативная ссылка, — и /{sdSlug}/blog/[postSlug], отдельный маршрут (не конвейер Zone/Section) с заголовком по центру (надстрочный текст категории, название, подпись автора, акцентная линия основного цвета), 16:9-изображением-шапкой на ширину контейнера, текстом в markdown в колонке чтения шириной ~720px, чипами тегов в конце статьи, полосой "More in {category}" с похожими записями и JSON-LD BlogPosting, включающим автора. Обе страницы оформляются исключительно через токены темы, поэтому наследуют палитру каждой церкви. URL блога входят в sitemap церкви. Интерфейс авторинга B1Admin (Site → Blog) редактирует записи в диалоге: редактор markdown с переключателем предпросмотра, выбор изображения галереи с обрезкой 16:9, выбор автора среди людей (по умолчанию редактирующий пользователь), автодополнение категорий по существующим, проверка дубликатов slug и переключатель публикации; опубликованные строки ведут на живую запись, а страница подсказывает администратору добавить ссылку /blog в навигацию. Комментарии оставляются сторонним сервисам: общая для церкви публичная настройка blogFooterHtml (редактируется в Below Every Post на странице Blog, видна только при Settings→Edit) выводится под каждой записью компонентом BlogFooterEmbed из B1App, который пересоздаёт теги <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 символов) попадает в Metadata Next.js (description и Open Graph) через MetaHelper.getMetaData() на каждом маршруте, отрисованном конструктором. В настройках страницы 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, как и неизвестные поддомены и некорректные 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, если это корректный ID G- (ID контейнеров GTM остаются только для сайта). Каждый gtag('config') несёт display_mode со значением installed или browser, исходя из navigator.standalone или медиазапроса (display-mode: standalone) (B1App/src/helpers/mobileAnalytics.ts) |
| Sitemap и ленты | Маршрут sitemap.xml для каждой церкви включает страницы конструктора, URL блога и 50 самых свежих страниц проповедей (с <lastmod> из даты публикации проповеди). Также перечисляются встроенные страницы /sermons, /groups и /volunteer, когда у них есть содержимое (публичные группы, планы записи), если только сохранённый редирект не заменяет этот путь. / исключается, когда у церкви нет домашней страницы, поскольку тогда / перенаправляет на запрещённый /mobile. Список блога объявляет ленту RSS |
| Доступность | Публичная оболочка выводит ссылку пропуска на ориентир <main id="main-content"> в каждой обёртке макета |
Генерация ИИ (AskApi)
Генерация страниц и сайтов работает в AskApi — отдельном сервисе под контроллером /website. Он аутентифицируется тем же CustomAuthProvider JWT, что и всё остальное, и не хранит контент: каждый эндпоинт возвращает 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 | Классифицирует тип страницы (главная, визит, о нас…), затем выбирает 10 кандидатов макета из вероятностей JEV по раундам (герой + число разделов → каждый раздел → завершение), убирает дубликаты, просит JEV оценить каждый по соответствию, потоку и пробелам, и возвращает три лучших плюс голос письма и suggestedStyle (палитра + шрифты). Кандидаты с одинаковыми разделами до текущего момента задают JEV одинаковый вопрос, поэтому раунды мемоизируются по префиксу. Лучшая оценка ниже 6 записывается как lowLayoutScore — этот журнал и есть очередь шаблонов, которые стоит добавить. ~2 с |
| 2 | POST /website/writePage (один вызов на кандидата) | Пишущая модель заполняет текст слотов по два раздела за вызов, параллельно, и возвращает пять заголовков героя, из которых JEV выбирает один; JEV проверяет факты в каждом разделе; разделы, которые не прошли проверку, используют шаблонную фразу или пересказывают более ранний раздел (общие последовательности из 4 слов, проверяемые в коде), переписываются параллельно с указанием конкретной причины; очистка кода убирает предложения с шаблонными фразами церковных сайтов (если только собственное описание церкви не использует их); JEV выбирает предметы фото, значки и разделитель-фигуру героя и оценивает результат. Возвращает готовое к сохранению дерево разделов и оценку. ~6–9 с |
| 3 | POST /content/pages/importTree | B1Admin записывает только макет с лучшим рангом (вторая по рангу — запасной вариант, если запись не удалась), сохраняет его и открывает предпросмотр (~10 с после Save) |
Каждая фаза — это отдельный запрос, поэтому каждый вызов укладывается в лимит 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.
Полные страницы из коротких запросов. Страницы имеют от трёх до шести средних разделов, щедрую длину слотов, вводную строку в карточных разделах и FAQ из пяти вопросов, а проход исправления расширяет любой раздел, который вернулся слишком кратким. Генерация выполняется одним нажатием: уточняющих вопросов нет. Когда запрос не содержит обычной детали, которая нужна полной странице (время начала, помещение, что взять с собой, как записаться), пишущая модель заполняет её правдоподобным и скромным выбором, который церковь может изменить. Поскольку разделы пишутся параллельно, эти пробелы решаются один раз в planPage (assumedDetails, один небольшой вызов пишущей модели, который выполняется параллельно с выбором макетов) и передаются обратно в каждый вызов writePage через churchContext.assumedDetails, так что один раздел не может сказать 5:00, а другой — 5:30. JEV исправляет любой раздел, который противоречит запросу, записям церкви или этим решённым деталям. Решённые детали не показываются в интерфейсе; церковь проверяет и редактирует страницу, как и любую другую. Некоторые вещи никогда не выдумываются: имена людей, телефоны, email и веб-адреса, цены, статистика, история церкви, цитаты, приписанные людям, и день недели для даты, которую запрос не сопровождал днём недели.
Визуалы. Шаблоны никогда не называют свои фото и значки. Они оставляют открытые слоты, а один общий проход (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 из-за стоимости; сохранён для потребителей 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 символов) по текстовому содержимому страницы — подключено к кнопке Generate в настройках страницы B1Admin |
Промпты этих эндпоинтов — это файлы markdown в AskApi/config/instructions/, включая каталог элементов, из которого генерирует модель. Два принципа делают каталог честным: клиент передаёт availableElementTypes в каждом запросе (промпт может использовать только типы из этого списка — сервер никогда не задаёт полный набор в коде), а инструмент MCP describe_page_builder в API содержит то же руководство для ИИ-агентов, работающих через MCP. Модели — Anthropic Claude через OpenRouter: 3.5 Haiku для содержимого разделов (задержка), 3.5 Sonnet для планов, планов сайтов и визуальных задач — с резервом в виде OpenAI, если ключ OpenRouter не настроен.
Диалоговые формы
Формы (модуль membership) получили диалоговый режим, ориентированный на страницы в стиле connect-card. Четыре столбца в forms управляют им: displayMode (standard | conversational), autoCreatePerson, followUpSubject, followUpBody.
- Отображение —
FormSubmissionEditиз apphelper переключается на компонентConversationalForm(один вопрос за раз), когдаdisplayModeравенconversational; страница формы B1App передаёт режим дальше. Полезная нагрузка отправки одинаковая в обоих режимах. - Автосоздание человека — при отправке с
autoCreatePersonConversationalFormHelper.findOrCreatePersonубирает дубликаты по email (без учёта регистра), а иначе создаёт домохозяйство и человека соmembershipStatus: "Guest", затем связывает отправку с этим человеком. - Письмо с последующим сообщением — когда заданы тема и текст, отправитель получает письмо по шаблону (с метками
{firstName}/{churchName}) через существующий транзакционный путь (TransactionalEmailHelper), но никогда через дайджест уведомлений. Оба побочных эффекта не фатальны: сбой никогда не теряет отправку.
Эти четыре поля сейчас задаются через API; редактор форм B1Admin их пока не показывает.
Кеш публичного сайта
Путь публичного рендеринга B1App кеширует выборки, помеченные церковью (next: { revalidate: 300, tags: [sdSlug] } в продакшне; 0 в разработке), поэтому живая страница может устареть на пять минут после записи в 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 не мог сорвать сохранение.
Контроллеры, которые вызывают сброс: страницы (сохранение, удаление, дублирование, публикация, отмена черновика, снятие с публикации, временный ИИ), разделы, элементы, блоки, ссылки, глобальные стили, записи и редиректы. b1AppRoot в разработке — http://{subdomain}.localtest.me:3301; в демо и продакшне — https://{subdomain}.b1.church.
Связанные страницы
- Маршрутизация сайта и несколько сайтов — как запрос сопоставляется с церковью и сайтом и как работают пользовательские домены
- Эндпоинты Content — полный REST-интерфейс для страниц, разделов, элементов, блоков, записей, редиректов и настроек
- AppHelper — npm-пакет, который поставляет рендереры, реестр, разделители и виджеты
- MCP-сервер — включая инструмент-руководство
describe_page_builder - Редактор страниц (для пользователей) — документация редактора для сотрудников