Регистрация (Check-Ins)
Регистрация — это одна система с тремя точками входа: приложение-киоск B1Checkin для станций с персоналом и для самообслуживания, самостоятельная регистрация внутри портала участника B1App и учёт посещаемости на стороне администратора в B1Admin. Все три записывают данные в один модуль посещаемости основного Api, а маршрутизация по классам полностью определяется группами — отдельной сущности «помещений» или «комнат» нет. Поверх этого работает слой безопасности детей: типы регистрации для каждого визита, серверные проверки вместимости и соотношения взрослых и детей, проверка возраста и класса на киоске, проверка доверенных лиц при выдаче ребёнка и оповещение родителей по SMS через провайдера текстовых сообщений церкви. На этой странице описаны модель данных, сценарии регистрации, слой безопасности и конвейер печати этикеток.
Обзор
┌──────────────────────────┐
│ B1Checkin (Expo kiosk) │──┐ ┌──────────────────────────────────────────────┐
│ поиск → домохозяйство → │ │ │ Api │
│ группы → завершение/печать │ HTTPS │ ┌─ модуль membership ─────────────────────┐ │
├──────────────────────────┤ ├───────▶ │ │ люди · домохозяйства · группы │ │
│ B1App (самостоятельная │──┤ │ └─────────────────────────────────────────┘ │
│ регистрация) │ │ │ ┌─ модуль attendance ─────────────────────┐ │
│ экран /mobile/checkin │ │ │ │ кампусы → службы → времена служений │ │
├──────────────────────────┤ │ │ │ groupServiceTimes (маршрутизация по классам) │
│ B1Admin (сотрудники) │──┘ │ │ sessions ← visitSessions → visits │ │
│ настройка · отчёты · │ │ │ labelTemplates │ │
│ редактор этикеток │ │ └─────────────────────────────────────────┘ │
└──────────────────────────┘ └──────────────────────────────────────────────┘
Путь печати этикеток (только киоск):
POST /attendance/visits/checkin ──▶ { securityCode, streaks }
└▶ LabelHelper (шаблоны этикеток или встроенный HTML-запасной вариант)
└▶ LabelRenderer → HTML-документ + встроенные SVG-штрихкоды
└▶ PrintUI: рендер в WebView → захват JPG через ViewShot
└▶ нативный модуль printer-helper → Brother QL / Zebra
| Поверхность | Репозиторий | Стек | Роль |
|---|---|---|---|
| Киоск | B1Checkin | Expo / React Native, маршрутизация файлов expo-router; сборки EAS для Android, Amazon Fire и iOS; OTA-обновления через expo-updates | Станция с персоналом или самообслуживания с печатью этикеток и проверенной выдачей ребёнка |
| Самостоятельная регистрация | B1App | Next.js (портал участника b1.church) | Вошедшие участники регистрируют своё домохозяйство с телефона; печати нет |
| Администрирование | B1Admin | React SPA | Настройка структуры служений, назначение групп на времена служений, дизайн этикеток, ручной учёт посещаемости, отчёты |
Все три используют одни и те же два модуля API через ApiHelper: MembershipApi (/membership) — для людей, домохозяйств и групп; AttendanceApi (/attendance) — для всего остального ниже.
Модель данных (Api/src/modules/attendance)
| Сущность / таблица | Ключевые поля | Значение |
|---|---|---|
campuses | name, address | Устарело — кампусы ведутся в модуле membership (/membership/campuses); копия в attendance заморожена только для чтения для старых читателей (models/Campus.ts) |
services | campusId, name | Регулярное собрание, например «Sunday Morning» (models/Service.ts) |
serviceTimes | serviceId, name, dayOfWeek, startTime, endTime, checkinOpenMinutes, checkinCloseMinutes | Временной слот внутри службы, например «9:00 AM» (models/ServiceTime.ts). Столбцы расписания необязательны (миграция tools/migrations/attendance/2026-10-10_service_time_schedule.ts) и определяют окно регистрации |
groupServiceTimes | groupId, serviceTimeId | Таблица связей: какие группы (классы) собираются в каких временах служений (models/GroupServiceTime.ts) |
sessions | groupId, serviceTimeId, sessionDate | Одно собрание одной группы в одну дату — создаётся лениво во время регистрации (models/Session.ts) |
visits | personId, serviceId, visitDate, checkinTime, securityCode, checkinType, checkedInById, checkoutTime, checkedOutBy, checkedOutById | Посещение одним человеком в одну дату (models/Visit.ts). checkinType — member / guest / volunteer (NULL = устаревший member), задаётся киоском и используется проверками вместимости и соотношения |
visitSessions | visitId, sessionId | На какие занятия распространяется визит — ребёнок, зарегистрированный на два времени служений, получает две строки (models/VisitSession.ts) |
labelTemplates | name, labelType (nametag/pickup), width, height, isDefault, content (блоки JSON) | Настраиваемые макеты этикеток (models/LabelTemplate.ts) |
Как сохраняется завершённая регистрация
VisitController.postCheckin (Api/src/modules/attendance/controllers/VisitController.ts) обрабатывает POST /attendance/visits/checkin?serviceId=&peopleIds=. Тело — это массив объектов Visit, каждый из которых содержит visitSessions, а вложенный session указывает только пару (serviceTimeId, groupId). Затем сервер:
- Проверяет вместимость и соотношения до любой записи.
evaluateGates()→CheckinGateHelper.evaluate()проверяет для каждой выбранной комнаты вместимость, вместимость для гостей, флаг закрытия и соотношение волонтёров к детям относительно текущей загрузки. postCheckin не транзакционный, поэтому проверка должна выполняться до первого сохранения — при жёстком нарушении возвращается 409 с названием комнаты (комнат) и ничего не сохраняется. См. Проверки вместимости и соотношения волонтёров. - Лениво определяет занятия.
getSessionId()находит или создаёт строкуsessionsдля(groupId, serviceTimeId, сегодня)— идентификаторы занятий кешируются в памяти процесса по дате. Для новых занятий отправляется вебхукsession.created. Цикл — это ожидаемыйfor..of: более ранний вариантforEach(async …)без ожидания гонялся с сохранением и записывал NULL в sessionId при создании первого занятия (исправлено; отмечено комментарием в коде у цикла). - Заменяет записи за день. Все существующие визиты этих людей на эту службу за сегодня удаляются вместе со своими visitSessions, затем сохраняется переданный набор. Повторная регистрация семьи — это поэтому идемпотентная операция «вот текущее состояние», а не добавление. Если передать
?checkDuplicates=true, сервер вернёт{ duplicates: [personId…] }без записи — так киоск предупреждает перед перезаписью. - Создаёт один код безопасности на пакет.
SecurityCodeHelper.generate()формирует 4-символьный код из алфавита23456789BCDFGHJKLMNPQRSTVWXYZ(без гласных и похожих символов, чтобы коды не складывались в слова и не читались с ошибками). Сервер повторяет генерацию при коллизии с открытыми визитами той же церкви за тот же день и проставляет код в каждый визит пакета. - Возвращает
{ streaks, securityCode }.streaksсопоставляет personId с числом последовательных недель посещения; киоск отмечает вехи (каждую пятую неделю) конфетти.
Каждый сохранённый визит также отправляет вебхук attendance.recorded. Чтение, GET /attendance/visits/checkin, возвращает визиты людей с их последней записанной даты — если это была прошлая неделя, идентификаторы удаляются, и клиент получает предзаполненную копию выбора комнат прошлой недели, которая сохранится как новые записи.
Выдача ребёнка (check-out)
Два эндпоинта завершают цикл (VisitController):
GET /attendance/visits/code/:code— сегодняшние визиты, ещё не отмеченные как выданные, с этим кодом безопасности и заполненными занятиями.POST /attendance/visits/checkout— тело{ visitIds, checkedOutBy?, checkedOutById? }; проставляетcheckoutTimeи того, кто забрал ребёнка, и отправляет вебхукattendance.checkoutна каждый визит.
Права: киоски аутентифицируются с attendance.checkin, которое даёт ровно поверхность регистрации, выдачи и шаблонов этикеток, плюс поиск домохозяйств, нужный киоску без people.view» (поиск по телефону или имени, члены домохозяйства в модели регистрации и список лиц для выдачи). SessionHelper.filterChurchesв B1Checkin предлагает только церкви, где у учётной записи естьAttendance/CheckinилиAttendance/Edit. Checkin больше не входит в права Everyone (роль null) (RoleHelperи миграция2026-11-01_remove_everyone_checkin), поэтому его нужно выдавать через настоящую роль; attendance.view/attendance.editпокрывают отчёты и ручной ввод; структура (службы, времена служений, назначения групп) требуетservices.edit. Самостоятельная регистрация участника (B1App) не требует никаких прав: любой аутентифицированный пользователь с привязанным человеком в церкви может вызывать GET/POST /attendance/visits/checkin, а сервер ограничивает передаваемые personIdсобственным домохозяйством вызывающего (иначе 403 — именно этот барьер не даёт читать чужиеsecurityCode). Членство и есть право доступа; видна ли функция участникам, определяется вкладками навигации B1App церкви. Остальные эндпоинты регистрации (code/:code, checkout, guardians, CheckinController`) остаются только для киоска и персонала.
Маршрутизация по классам через группы
Нигде в системе нет сущности «комнаты» или «классы». «Комната» — это группа членства с включённым trackAttendance, связанная с одним или несколькими временами служений через groupServiceTimes. Поля группы (в Api/src/modules/membership/models/Group.ts), которые определяют поведение киоска:
| Поле | Влияние |
|---|---|
trackAttendance | Группа участвует в учёте посещаемости; страница настройки в B1Admin помечает группы с trackAttendance без строки groupServiceTimes как неназначенные |
parentPickup | Помечает детскую комнату: регистрация в неё делает визит «детским» — печатается семейная этикетка для выдачи, а код безопасности помещается на бейдж |
printNametag | Печатать ли бейдж при регистрации в эту группу |
capacity / guestCapacity / checkinClosed | Ограничения вместимости комнаты и жёсткий переключатель «закрыто», которые проверяются на сервере (настраиваются в B1Admin в настройках группы в разделе «Check-In Capacity») |
volunteerRatio / minVolunteers | Соотношение детей к волонтёру и минимальное число волонтёров, применяются согласно общецерковной настройке ratioEnforcement |
minAgeMonths / maxAgeMonths / minGrade / maxGrade | Границы по возрасту и классу, которые вычисляются на киоске для выделения или затемнения комнат |
Каждый клиент денормализует данные одинаково (например, B1Checkin/app/services.tsx, B1App/src/app/[sdSlug]/mobile/components/screens/CheckinPage.tsx): параллельно загружаются GET /attendance/servicetimes?serviceId=, GET /attendance/groupservicetimes и GET /membership/groups, а затем для каждого времени служения собираются группы, строки groupServiceTimes которых указывают на него, в serviceTime.groups. Этот массив и показывает выбор комнаты, организованный по categoryName группы.
Назначения редактируются на странице группы в B1Admin (B1Admin/src/groups/components/ServiceTimesEdit.tsx — POST/DELETE /attendance/groupservicetimes), а всё дерево Кампус → Служба → Время служения → Группа визуализируется в B1Admin/src/attendance/components/AttendanceSetup.tsx через GET /attendance/attendancerecords/tree.
Поскольку группы — единственный источник истины, одно и то же членство в группе обеспечивает маршрутизацию на киоске, учёт посещаемости по спискам на страницах групп в B1Admin и отчёты о посещаемости. Назначение группы на время служения — единственный шаг, нужный, чтобы сделать её пунктом регистрации.
Безопасность детей
Типы регистрации
У каждого визита есть checkinType — member, guest или volunteer (NULL означает устаревший/member; миграция tools/migrations/attendance/2026-07-03_checkin_type.ts). Тип выбирается на стороне киоска: чипы Member / Guest / Volunteer в развёрнутой строке участника (B1Checkin/src/components/MemberServiceTimes.tsx), и проставляются на каждый ожидающий визит при завершении (app/checkinComplete.tsx, по умолчанию member). Сервер учитывает его в проверках: волонтёры засчитываются в покрытие соотношения, а не в вместимость, а гости — в guestCapacity.
Проверки вместимости и соотношения
CheckinGateHelper.evaluate() (Api/src/modules/attendance/helpers/CheckinGateHelper.ts) выполняется внутри postCheckin до любого сохранения (эндпоинт не транзакционный, поэтому корректность обеспечивается проверкой до записи). Он загружает текущую загрузку для каждой выбранной группы (VisitRepo.countActiveByGroupToday) и конфигурацию группы через шлюз модуля membership, затем классифицирует нарушения:
- Жёсткие (всегда блокируют):
checkinClosed,текущие + входящие > capacity, число гостей большеguestCapacity. Пакет отклоняется с409 { error: "capacity", groups: [{ groupId, groupName, reason }] }— киоск показывает название комнаты. - Соотношение (предупреждение или блокировка): входящие не-волонтёры в комнату, где
volunteers < minVolunteers, волонтёров нет совсем илиchildren > volunteers × volunteerRatio. Строгость задаётся настройкой церквиratioEnforcement("warn"по умолчанию /"block", редактируется в B1Admin в Manage Church → Check-In,CheckinSettingsEdit.tsx). В режиме предупреждения возвращается409 { warning: true, error: "ratio", … }, если клиент не повторит отправку сacknowledgeWarnings=true— это повторное подтверждение и есть переопределение, которое подтверждает сотрудник на киоске.
Окна регистрации по расписанию
Время служения может иметь необязательное недельное расписание (dayOfWeek от 0 до 6, где 0 — воскресенье, startTime/endTime в формате HH:mm, checkinOpenMinutes, checkinCloseMinutes), которое редактируется в форме времени служения в B1Admin Attendance → Setup (B1Admin/src/attendance/components/ServiceTimeEdit.tsx, «Check-in Schedule»). CheckinGateHelper.hasSchedule() считает время служения расписанным только тогда, когда заданы dayOfWeek и startTime; время без расписания никогда не ограничивается по времени. isServiceTimeOpen() вычисляет окно в местном настенном времени (DateHelper.toChurchTime). Часовой пояс определяется для каждого времени служения через CheckinTimeZoneHelper.load() (Api/src/modules/attendance/helpers/CheckinTimeZoneHelper.ts): сначала берётся timezone кампуса службы (service.campusId, через MembershipModuleGateway.loadCampusTimeZones), затем timeZone церкви (задаётся в B1Admin в Church Information), затем первый не удалённый кампус с заданным timezone (loadCampusTimeZone), и только потом America/New_York. Кампус идёт первым, потому что многим церквям при миграции в поле церкви был проставлен America/New_York. Списки и операции отправки ниже определяют часовой пояс одинаково. Окно идёт от checkinOpenMinutes до начала до checkinCloseMinutes после окончания (или после начала, если окончания нет), учитывая окна, переходящие через полночь или границу недели.
Окно соблюдается в двух местах:
- Список:
GET /attendance/servicetimesдобавляет каждой строке вычисленный булев флагcheckinOpen. Самостоятельная регистрация B1App (CheckinPage.tsx) и выбор служения в B1Checkin (app/services.tsx) оставляют все времена. Когда все времена службы закрыты, они показывают ближайшее открытие («Check-in opens Sun 9:30 AM.» в B1App, «Check-in for this service opens Sun 9:30 AM.» в B1Checkin, изCheckinHelper.opensLabel/ServiceTimeHelper.getOpensLabel), а если время открытия вычислить нельзя — «Check-in isn't open for this service right now.» (на киоске есть кнопка «Назад», чтобы выбрать другую службу). В остальных случаях закрытые времена отображаются как невыбираемая строка «Closed» / «Closed · opens 9:30 AM». Экран домохозяйства в B1Checkin (MemberServiceTimes.tsx) пересчитывает открытость в реальном времени по часам устройства с помощьюServiceTimeHelper.isCheckinOpen()(часовой пояс устройства, а не церкви), поэтому киоск, оставленный работать, открывается и закрывается вовремя, а на закрытом времени, которое человек уже занял, показывает «Kids Room 1 · Checked in» (название группы). - Отправка: внутри
evaluateGates(), до оценки вместимости и соотношения,findClosedServiceTimeGroups()отклоняет пакет с409 { error: "notOpen", groups: [{ groupId, groupName, reason: "notOpen" }] }, если время служения какого-либо целевого занятия вне окна. Поскольку существующие визиты домохозяйства за сегодня повторно отправляются при каждой регистрации, занятия, которые человек уже занимает (personId|sessionIdв существующих визитах), этот барьер пропускают, так что добавление более позднего открытого времени служения не отклоняется только потому, что более раннее окно закрылось. B1Checkin показывает это на экране жёсткого барьера с причиной «check-in isn't open right now» (нарушения вместимости по-прежнему показывают «room is full or closed»).
Соответствие по возрасту и классу (на стороне киоска)
Соответствие комнаты — это рекомендательный интерфейс, который вычисляется на киоске, а не принудительно на сервере. B1Checkin/src/helpers/EligibilityHelper.ts сравнивает дату рождения и класс человека с minAgeMonths/maxAgeMonths/minGrade/maxGrade группы (порядок классов: PreK, K, 1–12, Graduated) и возвращает eligible / ineligible / unknown — отсутствие данных даёт unknown и никогда не скрывает комнату. Возраст и класс вычисляются на дату перехода по классам церкви (настройка gradePromotionDate, формат "MM-DD", редактируется в B1Admin/src/settings/components/GradePromotionSettingsEdit.tsx); киоск получает её из GET /attendance/checkin/settings, а resolveAsOfDate выбирает ближайшее вхождение, которое не позже сегодня. Выбор комнаты подсвечивает подходящие комнаты и затемняет неподходящие; чтобы выбрать затемнённую комнату, нужно подтверждение сотрудника.
Выдача с проверкой доверенных лиц
Люди, которые могут забрать ребёнка, — это сущность membership на уровне домохозяйства: householdPickupPeople (Api/src/modules/membership/models/HouseholdPickupPerson.ts — householdId, необязательный personId, name, photoUrl, relationship, status trusted / notAuthorized, notes). CRUD: GET /membership/householdpickup/:householdId (любой аутентифицированный пользователь церкви, поэтому киоски могут его читать), а POST / DELETE ограничены правом people.edit. Сотрудники управляют списком в карточке Pickup на странице человека (B1Admin/src/people/components/PickupPeople.tsx) — фото, степень родства и чип статуса Trusted / Not Authorized.
При выдаче (B1Checkin/app/checkout.tsx) киоск загружает список лиц для выдачи домохозяйства: записи trusted отображаются как карточки, которые можно нажать, рядом с сеткой фото взрослых членов домохозяйства, а свободно введённое имя «Other» сравнивается нечётким способом (расстояние Левенштейна, src/helpers/PickupMatchHelper.ts) с записями notAuthorized — совпадение блокирует выдачу с предупреждающим листом и кнопкой сотрудника Override. Переопределение фиксируется в самом визите: отправляется checkedOutBy со значением "OVERRIDE: {name}" через обычный POST /attendance/visits/checkout, поэтому оно попадает в запись посещаемости и вебхук attendance.checkout, а не в отдельную таблицу аудита.
Вызов родителя и экстренная рассылка
CheckinController (Api/src/modules/attendance/controllers/CheckinController.ts, /attendance/checkin) предоставляет два SMS-эндпоинта:
POST /page—{ visitId, message }: отправляет сообщение опекунам одного зарегистрированного ребёнка (экран выдачи на киоске, ручной режим).POST /broadcast—{ serviceId, message }: отправляет SMS всем взрослым зарегистрированных домохозяйств для службы (настройки администратора киоска, за листом подтверждения типаEMERGENCYвB1Checkin/app/adminSettings.tsx).
Оба маршрута находят взрослых членов домохозяйств через шлюз membership, затем передают доставку MessagingModuleGateway.sendBulkText (Api/src/shared/modules/MessagingModuleGateway.ts) — межмодульный вход к настроенному провайдеру текстовых сообщений церкви (@churchapps/texting: TextInChurch, Clearstream или MutualMinistry; встроенного SMS-отправителя нет). Шлюз записывает строку sentText и отдельные записи deliveryLog для каждого получателя и ограничивает пакет 500 получателями; если провайдер не настроен, он возвращает no_provider, и киоск показывает «No SMS provider configured». Метод dispatch() контроллера убирает дубликаты номеров и пропускает людей без мобильного номера или с флагом optedOut, возвращая { sent, failed, skippedOptedOut, skippedNoPhone }, чтобы киоск мог показать, что было пропущено.
Киоск (B1Checkin)
Экраны — это файлы expo-router в B1Checkin/app/; общее состояние между экранами хранится в статическом классе CachedData (src/helpers/CachedData.ts), а не в состоянии React.
index (загрузка/автовход) → selectChurch → services ──▶ lookup ──▶ household ──▶ checkinComplete
│ │ ▲ │ │ │
загружает serviceTimes, │ │ └─────────┘ └▶ addGuest └▶ печать этикеток,
groups, │ └▶ checkout (ручной режим) автовозврат
groupServiceTimes, │ к lookup
labelTemplates │
- Поиск (
app/lookup.tsx) — поиск по телефону (GET /membership/people/search/phone?number=, последние 4 цифры или полный номер) или по имени (GET /membership/people/search?term=). При выборе совпадения загружается домохозяйство (GET /membership/people/household/{householdId}) и существующие визиты (GET /attendance/visits/checkin), после чегоpendingVisitsзаполняется выбором прошлой недели. - Просмотр домохозяйства (
app/household.tsx,src/components/MemberList.tsx) — в строке каждого члена показываются бейдж «уже зарегистрирован», бейдж аллергии /nametagNotesи текущие чипы комнат. При раскрытии участника видно каждое время служения с кнопкой комнаты и чипами типа регистрации Member / Guest / Volunteer (MemberServiceTimes.tsx). Под названием каждого времени служенияServiceTimeHelper.getGroupSummary()показывает группы, предлагаемые там (названия изserviceTime.groups, обрезанные, без повторов без учёта регистра, через запятую); если групп нет, ничего не выводится. - Назначение группы (
app/selectGroup.tsx) — дерево категорий, построенное изserviceTime.groups, где подходящие по возрасту и классу комнаты выделены, а неподходящие затемнены и требуют подтверждения сотрудника (см. Соответствие по возрасту и классу); выбор комнаты записывает визит-занятие{ session: { serviceTimeId, groupId } }в ожидающий визит человека (src/helpers/VisitSessionHelper.ts). Кнопка «None» очищает выбор. - Завершение (
app/checkinComplete.tsx) —POST /attendance/visits/checkinсpendingVisits(каждый с проставленнымcheckinType), затем печать этикеток, если настроен принтер, и автовозврат к lookup. Ответ409с причиной вместимости илиnotOpenпоказывает название комнаты с причиной (заполнена/закрыта или регистрация не открыта); предупреждение о соотношении предлагает подтверждение сотрудника, которое повторно отправляет запрос сacknowledgeWarnings=true.
Экран выдачи (app/checkout.tsx) принимает 4-символьный код безопасности через поле ввода с автофокусом — поэтому сканеры штрихкодов по USB/Bluetooth работают без камеры — или экранную клавиатуру с тем же алфавитом, которая отправляет код автоматически при 4 символах. Кнопка Scan открывает лист с общей камерой src/components/CodeScanner.tsx (по умолчанию задняя, принимает QR, Code 128 и Code 39), чтобы станции без сканера могли считать этикетку для выдачи; отсканированный код попадает в тот же путь handleCode(), что и введённый вручную. Экран находит код, показывает детей, которых забирают, и показывает доверенных лиц домохозяйства как карточки, которые можно нажать, рядом с сеткой фото взрослых членов (плюс вариант «Other» со свободным вводом, который сверяется нечётко со списком не-авторизованных — см. Доверенные лица и не-авторизованные при выдаче), затем отправляет POST /attendance/visits/checkout с именем/id выбранного человека. В ручном режиме экран также предлагает Page a parent (POST /attendance/checkin/page) и повторную печать защитной этикетки — reprint() заново формирует этикетки семьи через LabelHelper.getAllLabelsFor(...) и передаёт их через тот же конвейер PrintUI, что и при регистрации.
Режим станции задаётся флагом AsyncStorage @StationMode ("self" | "manned", переключается в app/adminSettings.tsx). Ручной режим добавляет точку входа для выдачи на экран поиска и редактирование профиля человека с экрана домохозяйства (POST /membership/people). Защита киоска встроена: необязательный PIN (app/setPin.tsx, src/components/PinEntryModal.tsx) защищает экраны администратора и принтера, экран администратора открывается только семью быстрыми нажатиями на логотип в заголовке, а экран ожидания (src/hooks/useInactivityTimer.ts) сменяет предыдущую семью.
Самостоятельная регистрация (B1App)
Участники регистрируются на портале b1.church на экране /mobile/checkin (маршрутизируется B1App/src/app/[sdSlug]/mobile/components/ScreenRouter.tsx на screens/CheckinPage.tsx). Требуется вход в систему, и проходятся те же четыре шага, что и на киоске — службы → домохозяйство → группы → завершение — по тем же эндпоинтам, с состоянием в B1App/src/helpers/CheckinHelper.ts. Отличия от киоска: домохозяйство берётся из собственного householdId вошедшего пользователя (шага поиска нет), и печати этикеток нет — вместо этого на экране завершения показывается код безопасности пакета в виде QR (qrcode.react) с подсказкой «покажите это на станции регистрации». Если домохозяйство уже зарегистрировано при загрузке страницы, кнопка «Show check-in code» заново показывает QR из первого существующего визита (из GET /attendance/visits/checkin), в котором есть securityCode. Регистрация записывается сразу при отправке (состояния ожидания нет); QR нужен только для печати этикеток на киоске.
Печать этикеток с телефона на киоск (B1Checkin/app/scan.tsx, открывается кнопкой «Scan code» с QR на экране lookup): киоск показывает CodeScanner (CameraView из expo-camera, по умолчанию фронтальная камера, переключаемая), который сканирует QR-коды. ScanCodeHelper.parse() принимает данные только тогда, когда они представляют собой голый 4-символьный код из алфавита кодов безопасности, а ScanCodeHelper.isRepeat() игнорирует тот же код в течение 4 секунд, поэтому работают и QR из B1App, и QR-блок напечатанной этикетки. Затем экран идёт по пути повторной печати при выдаче — GET /attendance/visits/code/{code} → GET /membership/people/ids → LabelHelper.getAllLabelsFor(visits, people, code) → PrintUI — и возвращается к lookup. Запись посещаемости при сканировании не происходит: печатаются только этикетки. Коды без активных визитов, станции без принтера и группы без этикеток показывают всплывающее уведомление и возвращают к lookup.
Типы и ApiHelper/ArrayHelper берутся из @churchapps/helpers и @churchapps/apphelper; React-компоненты с B1Admin не разделяются.
Посещаемость на стороне администратора (B1Admin)
- Настройка —
/attendance(B1Admin/src/attendance/AttendancePage.tsx) отображает дерево структуры и создаёт службы (ServiceEdit.tsx) и времена служений (ServiceTimeEdit.tsx). Данные о кампусах поступают из membership через хукuseCampuses(). - Ручной учёт посещаемости находится в разделе групп, а не в разделе посещаемости:
B1Admin/src/groups/components/GroupSessionsTab.tsxсоздаёт занятия (POST /attendance/sessions; при добавленииSessionEdit.tsxможет создать по одному занятию для каждой другой группы, которая собирается в выбранное время служения, пропуская группы, у которых уже есть занятие в эту дату) и отмечает людей присутствующими черезPOST /attendance/visitsessions/log, который находит или создаёт визит для этого человека и занятия. Руководители групп могут записывать посещаемость своих групп без праваattendance.edit— контроллеры проверяютau.leaderGroupIds. - Отчёты — отчёты о тенденции посещаемости и посещаемости групп определены на сервере (
B1Admin/src/components/reporting/ReportWithFilter.tsxработает с ReportingApi; определения вApi/reports/*.json). Оба принимаютstartDate/endDate(конечная дата включается); отчёт о тенденции по умолчанию охватывает период от года назад до сегодня и добавляет для каждой недели столбецsessionDates, а дерево посещаемости групп на экране включаетcheckinTimeкаждого визита иmembershipStatusчеловека. CSV посещаемости групп формируется из сопутствующего отчётаgroupAttendanceDownload, которыйGroupAttendanceDownloadHelperсводит в одну строку на каждого участника группы со столбцом «присутствовал/отсутствовал» для каждого занятия с датой; история по конкретному человеку доступна черезGET /attendance/attendancerecords?personId=(B1Admin/src/people/components/PersonAttendance.tsx).
Печать этикеток
Шаблоны и редактор
Церкви создают собственные этикетки в B1Admin по адресу /mobile/checkin/labels (B1Admin/src/attendance/LabelsPage.tsx + components/LabelEditor.tsx, открывается со страницы настроек регистрации). Шаблон — это строка labelTemplates, поле content которой — массив JSON-блоков типов text, field, barcode, qrcode или box. Каждый блок позиционируется в процентных координатах с шрифтом, выравниванием, символикой (code39/code128/qr) и необязательными условиями показа (например, выводить блок аллергии только если person.nametagNotes не пуст). Существует два labelType: nametag (по одному на каждого зарегистрированного человека; поля вроде person.displayName, sessions, securityCode и person.isBirthdayWeek — значение "true", если месяц и день рождения приходятся на промежуток не более 3 дней от сегодня с переходом через конец года, вычисляется в LabelHelper.isBirthdayWithin()) и pickup (по одному на семью; поля вроде children, childrenAllergies). Сервер поддерживает только один шаблон по умолчанию на тип для каждой церкви (LabelTemplateController.save). Редактор поставляется со стартовыми шаблонами, которые повторяют встроенные этикетки киоска, и показывает предпросмотр на примерных данных.
Рендеринг и печать на киоске
По завершении регистрации B1Checkin/src/helpers/LabelHelper.ts решает, что печатать, на основании флагов групп каждого ожидающего визита: бейджи для групп с printNametag, плюс одна семейная этикетка для выдачи, если какой-либо визит попал в группу с parentPickup. Визиты с checkinType volunteer пропускаются LabelHelper.selectChildVisits(), поэтому работник детской комнаты в комнате Parent Pickup никогда не вызывает этикетку для выдачи. Код безопасности из ответа на регистрацию попадает на бейджи детей и на этикетку для выдачи; бейджи взрослых печатаются без кода. Если у церкви есть шаблоны, LabelRenderer (src/helpers/LabelRenderer.ts) превращает блоки и контекст полей в самостоятельный HTML-документ; иначе используются встроенные HTML-этикетки из B1Checkin/assets/labels/ с подстановкой заполнителей.
Штрихкоды генерируются как встроенный SVG чистыми TypeScript-кодировщиками в B1Checkin/src/helpers/barcode.ts — таблицы шаблонов Code 39 и таблицы ширин Code 128 (набор B с контрольной суммой mod-103), а QR — через пакет qrcode. Эти кодировщики намеренно продублированы в B1Admin (LabelEditor.tsx встраивает те же таблицы, что отмечено комментарием в коде), чтобы предпросмотр в редакторе был точным пиксель в пиксель с выводом киоска; изменение в одном месте нужно повторить в другом.
Конвейер печати (src/components/PrintUI.tsx) рендерит каждую HTML-этикетку в WebView, сохраняет её в JPG через react-native-view-shot и передаёт URI изображений нативному Expo-модулю printer-helper (B1Checkin/modules/printer-helper/). Модуль предоставляет scan(), checkInit(), printUris() и события статуса, с провайдером для каждой марки на обеих платформах:
| Марка | Android | iOS | Примечания |
|---|---|---|---|
| Brother | BrotherProvider.kt (SDK печати Brother) | BrotherProvider.swift (BRLMPrinterKit.xcframework) | Сетевые принтеры серии QL (QL-800/810W/820NWB/1100/1110NWB…), вырубные этикетки 29×90, рекомендуемый вариант по умолчанию |
| Zebra | ZebraProvider.kt (SDK Link-OS) | ZebraProvider.swift + ZebraBridge | Поиск в сети + печать изображений по TCP/ZPL |
Выбор принтера находится в app/printers.tsx (сканирование сети возвращает записи вида brand~model~ip; выбор сохраняется в AsyncStorage), а src/helpers/PrinterLog.ts ведёт диагностический журнал на устройстве, который выводится через индикатор статуса в заголовке киоска.
Гостевая регистрация
Два пути создают человека прямо во время регистрации:
- На киоске — кнопка «Add guest» на экране домохозяйства открывает
B1Checkin/app/addGuest.tsx, который сначала ищет существующее не-участническое совпадение черезGET /membership/people/search?term=, а если его нет — создаёт человека черезPOST /membership/people, привязанного к текущему домохозяйству. Гость затем проходит назначение группы как любой участник. - Самостоятельно через QR — когда в настройке церкви
enableQRGuestRegistrationвключена (настраивается в разделе Check-In в B1Admin и читается изGET /membership/settings/public/{churchId}), экран lookup на киоске показывает QR-код со ссылкой наhttps://{subdomain}.b1.church/guest-register?serviceId=. Эта страница B1App (src/app/[sdSlug]/(public)/guest-register/page.tsx) позволяет приходящей семье зарегистрироваться самостоятельно на своём телефоне через анонимный эндпоинтPOST /membership/people/guest-register, не задерживая очередь на киоске. В листе QR есть также кнопка Register here, которая открывает ту же страницу на киоске (app/guestRegister.tsx) в инкогнито-WebViewбез кеша;src/helpers/GuestRegisterHelper.tsстроит URL и для QR, и для WebView и блокирует переход за пределыhttps://{subdomain}.b1.church/guest-register. Экран возвращается к lookup по Done, по кнопке «назад» или после 120 секунд бездействия (ввод в форме передаётся из WebView как активность), размонтируя WebView, чтобы данные одной семьи никогда не попали к следующей.
Регистрация по QR управляется настройками церкви, которые сохраняются из карточки QR Guest Registration в B1Admin (src/mobile/CheckInPage.tsx):
| Настройка | Видимость | Назначение |
|---|---|---|
enableQRGuestRegistration | публичная | Переключатель включения для QR на киоске и анонимных эндпоинтов |
guestRegistrationFields | публичная | JSON-карта email, phone, address, birthDate, gender, maritalStatus, grade, comments → "off" / "optional" / "required". По умолчанию: email и телефон необязательны, остальное выключено. Имя и фамилия всегда обязательны |
guestRegistrationImage | публичная | URL фото в шапке; B1App выводит его в формате 16:9 вместо значка на форме и на экране подтверждения |
guestRegistrationGroupId | приватная | Группа, в которую добавляется каждый зарегистрировавшийся (гости её никогда не видят и не выбирают) |
guestRegistrationRecordAttendance | приватная | "true", чтобы также записывать посещаемость этой группы |
src/components/checkin/GuestRegister.tsx в B1App получает список полей из анонимного GET /membership/people/guest-register/options?churchId= и выводит только включённые поля (email, телефон, семейное положение и адрес у основного контакта; дата рождения, пол и класс — у каждого члена; одно поле комментариев), отправляя только их. Сервер повторно применяет этот список в GuestRegistrationHelper.sanitize(): отключённые поля отбрасываются, отсутствующие обязательные или значения вне списка дают 400 — и только потом запускается PersonHelper.registerGuestHousehold(). Сначала для каждого члена с email или телефоном вызывается PersonRepo.findGuestMatch(): ровно один живой человек с тем же именем и тем же email или цифрами телефона повторно используется (ноль или несколько совпадений создают нового человека, так что система ничего не угадывает). Член без контактов сопоставляется по имени внутри совпавшего домохозяйства. Повторно используемых людей никогда не редактируют, поэтому анонимная форма не может перезаписать сохранённые данные, а ответ повторяет переданные имена. Несовпавшие члены присоединяются к совпавшему домохозяйству или к новому, со статусом membershipStatus: "Visitor", и для каждого нового человека отправляется person.created. После этого ошибки записываются в журнал, а не возвращаются: участники добавляются в настроенную группу (group.member.added); если учёт посещаемости включён, AttendanceModuleGateway.recordAttendance() отмечает каждого члена присутствующим на всех расписанных временах служения группы, чьё окно регистрации (CheckinGateHelper.isServiceTimeOpen) открыто прямо сейчас, создавая занятие на сегодняшнюю дату по местному времени церкви, если нужно — нерасписанные времена служения и регистрации вне окна ничего не записывают; а комментарии становятся скрытой беседой-заметкой о человеке у главы домохозяйства (автор сообщения «Guest sign-up»), связанной через person.conversationId.
Связанные страницы
- Эндпоинты Attendance — полный REST-интерфейс для кампусов, служб, занятий, визитов и визитов-занятий
- Эндпоинты Membership — люди, домохозяйства и группы
- Вебхуки — события
session.created,attendance.recordedиattendance.checkout - Структура модулей — как организован модуль посещаемости на стороне сервера