Перейти до основного вмісту

Реєстрація дітей

Реєстрація — це одна система з трьома точками входу: кіоск B1Checkin для станцій з персоналом і самообслуговування, самостійна реєстрація в порталі учасників B1App і облік відвідуваності в B1Admin. Усі три записують дані в один модуль відвідуваності в ядрі Api, а маршрутизація до класних кімнат повністю визначається групами — окремої сутності «локацій» або «кімнат» немає. Поверх цього працює рівень безпеки дітей: типи реєстрації для кожного візиту, серверні перевірки місткості й співвідношення волонтерів, перевірка віку й класу на боці кіоска, підтвердження довірених осіб під час видачі дитини та сповіщення батьків через текстові повідомлення від постачальника SMS церкви. Ця сторінка описує модель даних, сценарії реєстрації, рівень безпеки та процес друку етикеток.

Огляд​

┌──────────────────────────┐
│ B1Checkin (Expo kiosk) │──┐ ┌──────────────────────────────────────────────┐
│ lookup → household → │ │ │ Api │
│ groups → complete/print │ │ HTTPS │ ┌─ membership module ─────────────────────┐ │
├──────────────────────────┤ ├───────▶ │ │ people · households · groups │ │
│ B1App (self check-in) │──┤ │ └─────────────────────────────────────────┘ │
│ /mobile/checkin screen │ │ │ ┌─ attendance module ─────────────────────┐ │
├──────────────────────────┤ │ │ │ campuses → services → serviceTimes │ │
│ B1Admin (staff) │──┘ │ │ groupServiceTimes (room routing) │ │
│ setup · reports · │ │ │ sessions ← visitSessions → visits │ │
│ label designer │ │ │ labelTemplates │ │
└──────────────────────────┘ │ └─────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘

Label print path (kiosk only):
POST /attendance/visits/checkin ──▶ { securityCode, streaks }
└▶ LabelHelper (label templates, or bundled HTML fallback)
└▶ LabelRenderer → HTML doc + inline SVG barcodes
└▶ PrintUI: WebView render → ViewShot JPG capture
└▶ printer-helper native module → Brother QL / Zebra
ПоверхняРепозиторійСтекРоль
КіоскB1CheckinExpo / React Native, маршрутизація файлів expo-router; збірки EAS для Android, Amazon Fire та iOS; OTA-оновлення через expo-updatesСтанція з персоналом або самообслуговуванням із друком етикеток і перевіреною видачею дитини
Самостійна реєстраціяB1AppNext.js (портал учасників b1.church)Авторизовані учасники реєструють свою родину з телефона; друку немає
АдмінB1AdminReact SPAНалаштовує структуру служінь, призначає групи на час служіння, створює етикетки, вносить ручний облік відвідуваності, формує звіти

Усі три поверхні викликають два модулі API через ApiHelper: MembershipApi (/membership) для людей, родин і груп та AttendanceApi (/attendance) для всього, що описано нижче.

Модель даних (Api/src/modules/attendance)​

Сутність / таблицяКлючові поляЗначення
campusesname, addressЗастаріла сутність — кампуси ведуться в модулі членства (/membership/campuses); копія в модулі відвідуваності заморожена, лише для читання, для застарілих читачів (models/Campus.ts)
servicescampusId, nameРегулярне зібрання, наприклад «Недільний ранок» (models/Service.ts)
serviceTimesserviceId, name, dayOfWeek, startTime, endTime, checkinOpenMinutes, checkinCloseMinutesЧасовий проміжок у межах служіння, наприклад «9:00» (models/ServiceTime.ts). Колонки розкладу необов’язкові (міграція tools/migrations/attendance/2026-10-10_service_time_schedule.ts) і визначають вікно реєстрації
groupServiceTimesgroupId, serviceTimeIdТаблиця зв’язку: які групи (класні кімнати) збираються в які часи служіння (models/GroupServiceTime.ts)
sessionsgroupId, serviceTimeId, sessionDateОдне заняття однієї групи в одну дату — створюється ліниво під час реєстрації (models/Session.ts)
visitspersonId, serviceId, visitDate, checkinTime, securityCode, checkinType, checkedInById, checkoutTime, checkedOutBy, checkedOutByIdОдна людина, яка відвідала служіння в одну дату (models/Visit.ts). checkinType — це member / guest / volunteer (NULL = застарілий учасник); встановлюється кіоском і використовується перевірками місткості та співвідношення
visitSessionsvisitId, sessionIdЯкі заняття охоплює відвідування — дитина, зареєстрована на два часи служіння, має два рядки (models/VisitSession.ts)
labelTemplatesname, 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). Далі сервер:

  1. Перевіряє місткість і співвідношення до будь-якого запису. evaluateGates() → CheckinGateHelper.evaluate() перевіряє для кожної цільової кімнати місткість, місткість для гостей, прапорець закриття та співвідношення волонтерів порівняно з поточною зайнятістю. postCheckin не є транзакційним, тому перевірка має виконуватися до першого збереження: серйозне порушення повертає 409 з назвою кімнати (кімнат) і нічого не зберігається. Див. Перевірки місткості та співвідношення волонтерів.
  2. Лініво визначає заняття. getSessionId() знаходить або створює рядок sessions для (groupId, serviceTimeId, today) — ідентифікатори занять кешуються в процесі для кожної дати. Нові заняття породжують вебхук session.created. Цикл є for..of з await — раніше forEach(async …) без очікування перегонявся із збереженням і записував NULL як sessionId під час створення першого заняття (виправлено; відзначено в коментарі до коду біля циклу).
  3. Замінює записи дня. Усі наявні відвідування цих людей на це служіння сьогодні видаляються разом із їхніми visitSessions, після чого зберігається надіслана множина. Повторна реєстрація родини, отже, є ідемпотентною операцією «це поточний стан», а не додаванням. Якщо передати ?checkDuplicates=true, сервер повертає { duplicates: [personId…] } без запису — так кіоск попереджає перед перезаписом.
  4. Створює один код безпеки на пакет. SecurityCodeHelper.generate() формує 4-символьний код з алфавіту 23456789BCDFGHJKLMNPQRSTVWXYZ (без голосних і неоднозначних символів, щоб коди не складалися в слова й не читалися помилково). Сервер повторює генерацію при колізії з відкритими сьогодні візитами тієї самої церкви і вказує код на кожному візиті в пакеті.
  5. Повертає { streaks, securityCode }. streaks зіставляє personId з кількістю послідовних тижнів відвідування; кіоск відзначає віхи (кожного 5-го тижня) конфетті.

Кожен збережений візит також породжує вебхук attendance.recorded. Читальна сторона, GET /attendance/visits/checkin, повертає візити людей з їхньої останньої зафіксованої дати — якщо це був попередній тиждень, ідентифікатори видаляються, і клієнт отримує попередньо заповнену копію вибору кімнат минулого тижня, яка збережеться як нові записи.

Видача дитини​

Два endpoint-и завершують цикл (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-role) (RoleHelper і міграція 2026-11-01_remove_everyone_checkin), тож його треба надавати через справжню роль; attendance.view/attendance.edit покривають звітність і ручне внесення; структура (служіння, часи служіння, призначення груп) вимагає services.edit. Самостійна реєстрація учасника (B1App) не потребує жодного дозволу: будь-який автентифікований користувач із прив’язаною особою в церкві може викликати GET/POST /attendance/visits/checkin, а сервер обмежує надіслані personId власною родиною викликача (інакше 403) — саме це обмеження не дає читати securityCode чужих родин. Членство є підставою доступу; те, чи учасники бачать цю функцію, контролюється вкладками навігації B1App церкви. Інші endpoint-и реєстрації (code/:code, checkout, guardians, CheckinController) залишаються лише для кіосків і персоналу.

Групи керують маршрутизацією до кімнат​

У системі немає жодної сутності кімнати чи класу. «Кімната» — це група членства з увімкненим trackAttendance, пов’язана з одним або кількома часами служіння через groupServiceTimes. Поля групи (у Api/src/modules/membership/models/Group.ts), які визначають поведінку кіоска:

ПолеВплив
trackAttendanceГрупа взагалі бере участь у обліку відвідуваності; дерево налаштування в B1Admin позначає групи з trackAttendance без рядка в groupServiceTimes як непризначені
parentPickupПозначає дитячу кімнату: реєстрація в неї робить візит «дитячим», що друкує сімейну етикетку для видачі та розміщує код безпеки на бейджі
printNametagЧи друкується бейдж під час реєстрації в цю групу взагалі
capacity / guestCapacity / checkinClosedЛіміти місткості кімнати та жорсткий перемикач «закрито», які застосовує сервер через перевірку реєстрації (редагується в налаштуваннях групи B1Admin у розділі «Місткість реєстрації»)
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, а потім для кожного часу служіння до serviceTime.groups збираються групи, чий рядок groupServiceTimes вказує на нього. Цей масив і показує вибір кімнати, упорядкований за 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 означає застарілий/учасник; міграція tools/migrations/attendance/2026-07-03_checkin_type.ts). Тип обирається на боці кіоска: чіпи «Учасник» / «Гість» / «Волонтер» у розгорнутому рядку учасника (B1Checkin/src/components/MemberServiceTimes.tsx), і прикріплюються до кожного очікуваного візиту під час завершення (app/checkinComplete.tsx, за замовчуванням member). Сервер використовує це значення в перевірці: волонтери зараховуються до покриття співвідношення замість місткості, а гості — до guestCapacity.

Перевірки місткості та співвідношення волонтерів​

CheckinGateHelper.evaluate() (Api/src/modules/attendance/helpers/CheckinGateHelper.ts) виконується всередині postCheckin до будь-якого збереження (endpoint не є транзакційним, тож коректність забезпечує перевірка до запису). Вона завантажує поточну зайнятість для кожної цільової групи (VisitRepo.countActiveByGroupToday) і конфігурацію групи через шлюз модуля членства, а потім класифікує порушення:

  • Жорсткі (завжди блокують): checkinClosed, current + incoming > capacity, кількість гостей понад guestCapacity. Пакет відхиляється з 409 { error: "capacity", groups: [{ groupId, groupName, reason }] } — кіоск показує назву кімнати.
  • Співвідношення (попередження або блокування): вхідні не-волонтери до кімнати, де volunteers < minVolunteers, зовсім без волонтерів або коли children > volunteers × volunteerRatio. Серйозність визначається налаштуванням церкви ratioEnforcement ("warn" за замовчуванням / "block", редагується в B1Admin: Керування церквою → Реєстрація, CheckinSettingsEdit.tsx). У режимі попередження повертається 409 { warning: true, error: "ratio", … }, доки клієнт не надішле повторно із acknowledgeWarnings=true — це повторне надсилання і є перевизначенням від працівника, яке підтверджує кіоск.

Заплановані вікна реєстрації​

Час служіння може мати необов’язковий тижневий розклад (dayOfWeek 0–6, де 0 = неділя; startTime/endTime у форматі HH:mm; checkinOpenMinutes; checkinCloseMinutes), який редагується у формі часу служіння Обліку відвідуваності → Налаштування в B1Admin (B1Admin/src/attendance/components/ServiceTimeEdit.tsx, «Розклад реєстрації»). CheckinGateHelper.hasSchedule() вважає час служіння запланованим, лише якщо задані і dayOfWeek, і startTime; незаплановані часи ніколи не обмежуються за часом. isServiceTimeOpen() обчислює вікно за місцевим настінним часом (DateHelper.toChurchTime). Часовий пояс визначається для кожного часу служіння функцією CheckinTimeZoneHelper.load() (Api/src/modules/attendance/helpers/CheckinTimeZoneHelper.ts): спершу береться timezone кампусу служіння (service.campusId, через MembershipModuleGateway.loadCampusTimeZones), далі — timeZone церкви (вказаний у B1Admin → Інформація про церкву), потім — перший неви­далений кампус із заданим timezone (loadCampusTimeZone), і лише після цього — America/New_York. Кампус має пріоритет, оскільки більшості церков часовий пояс церкви був автоматично заповнений як America/New_York. Обидва шляхи — список і відправлення — нижче визначають пояс однаково. Вікно триває від checkinOpenMinutes до початку до checkinCloseMinutes після кінця (або після початку, якщо кінця немає), і коректно обробляє вікна, що переходять через північ або межу тижня.

Вікно застосовується в двох місцях:

  • Список: GET /attendance/servicetimes позначає кожен рядок обчисленим булевим значенням checkinOpen. Самостійна реєстрація в B1App (CheckinPage.tsx) і вибір служіння в B1Checkin (app/services.tsx) залишають усі часи. Якщо всі часи служіння закриті, вони показують найближче відкриття («Реєстрація відкривається в неділю о 9:30.» у B1App, «Реєстрація на це служіння відкривається в неділю о 9:30.» у B1Checkin, з CheckinHelper.opensLabel / ServiceTimeHelper.getOpensLabel), а якщо відкриття не можна обчислити — напис «Реєстрація на це служіння зараз не відкрита.» (кіоск пропонує кнопку «Назад», щоб вибрати інше служіння). В інших випадках закриті часи відображаються як непридатний для вибору рядок «Закрито» / «Закрито · відкривається о 9:30». Екран родини в B1Checkin (MemberServiceTimes.tsx) наживо перевіряє відкритість за годинником пристрою через ServiceTimeHelper.isCheckinOpen() (часовий пояс пристрою, а не церкви), тож кіоск, який працює без перезапуску, відкривається й закривається вчасно, і показує «Дитяча кімната 1 · Зареєстровано» (назва групи) для закритого часу, на який людина вже зареєстрована.
  • Відправлення: усередині evaluateGates(), перед оцінкою місткості та співвідношення, findClosedServiceTimeGroups() відхиляє пакет з 409 { error: "notOpen", groups: [{ groupId, groupName, reason: "notOpen" }] }, якщо час служіння будь-якого цільового заняття поза вікном. Оскільки наявні візити родини на сьогодні повторно відправляються з кожною реєстрацією, заняття, які людина вже має (personId|sessionId у наявних візитах), пропускають цю перевірку — тому додавання пізнішого відкритого часу служіння не відхиляється через те, що попереднє вікно вже закрилося. B1Checkin показує це на своєму екрані жорсткої перевірки з поясненням «реєстрація зараз не відкрита» (порушення місткості, як і раніше, позначаються як «кімната заповнена або закрита»).

Перевірка віку та класу (на боці кіоска)​

Перевірка придатності кімнати є порадчою для інтерфейсу, її виконує кіоск, а не сервер. 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 обирає найближче настання на сьогодні або раніше. Вибір кімнати виділяє придатні кімнати та приглушує непридатні; вибір приглушеної кімнати вимагає підтвердження від персоналу.

Довірені та недозволені особи для видачі​

Особи для видачі — це сутність членства в межах родини: 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. Персонал керує списком на картці Видача сторінки особи (B1Admin/src/people/components/PickupPeople.tsx) — фото, стосунок і позначка статусу «Довірений» / «Не уповноважений».

Під час видачі (B1Checkin/app/checkout.tsx) кіоск завантажує список осіб для видачі родини: записи trusted відображаються як картки, на які можна натиснути, поряд із сіткою фото дорослих членів родини, а вільно введене ім’я «Інший» порівнюється нечітко (відстань Левенштейна, src/helpers/PickupMatchHelper.ts) із записами notAuthorized — збіг блокує видачу з аркушем попередження і кнопкою Перевизначити для персоналу. Перевизначення фіксується в самому візиті: через звичайний POST /attendance/visits/checkout надсилається checkedOutBy як "OVERRIDE: {name}", тож воно потрапляє до запису відвідуваності та вебхука attendance.checkout, а не до окремої таблиці аудиту.

Виклик батьків і екстрене розсилання​

CheckinController (Api/src/modules/attendance/controllers/CheckinController.ts, /attendance/checkin) надає два endpoint-и для SMS:

  • POST /page — { visitId, message }: викликає опікунів однієї зареєстрованої дитини (екран видачі в кіоску, ручний режим).
  • POST /broadcast — { serviceId, message }: надсилає текст дорослим кожної зареєстрованої родини на служіння (налаштування адміністратора кіоска, за аркушем підтвердження типу EMERGENCY у B1Checkin/app/adminSettings.tsx).

Обидва endpoint-и спочатку знаходять дорослих членів родини через шлюз членства, а потім передають доставку в MessagingModuleGateway.sendBulkText (Api/src/shared/modules/MessagingModuleGateway.ts) — міжмодульний вхід до налаштованого в церкві постачальника текстових повідомлень (@churchapps/texting: TextInChurch, Clearstream або MutualMinistry; вбудованого SMS-відправника немає). Шлюз записує рядок sentText та записи deliveryLog для кожного отримувача і обмежує пакет 500 отримувачами; якщо постачальника не налаштовано, він повертає no_provider, що кіоск показує як «SMS-постачальника не налаштовано». dispatch() контролера усуває дублікати телефонних номерів і пропускає людей без мобільного номера або з optedOut, повертаючи { sent, failed, skippedOptedOut, skippedNoPhone }, щоб кіоск міг показати, що було пропущено.

Кіоск (B1Checkin)​

Екрани — це файли expo-router у B1Checkin/app/; стан між екранами зберігається в статичному класі CachedData (src/helpers/CachedData.ts), а не в стані React.

index (boot/auto-login) → selectChurch → services ──▶ lookup ──▶ household ──▶ checkinComplete
│ │ ▲ │ │ │
loads serviceTimes, groups, │ │ └─────────┘ └▶ addGuest └▶ print labels,
groupServiceTimes, │ └▶ checkout (manned) auto-return
labelTemplates │ to lookup
  1. Пошук (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 вибором кімнат минулого тижня.
  2. Перегляд родини (app/household.tsx, src/components/MemberList.tsx) — кожен рядок учасника має позначку «вже зареєстровано», позначку алергії/nametagNotes і чіпи поточних кімнат. Розгорнувши учасника, видно кожен час служіння з кнопкою кімнати та чіпами типу реєстрації «Учасник» / «Гість» / «Волонтер» (MemberServiceTimes.tsx). Під назвою кожного часу служіння ServiceTimeHelper.getGroupSummary() показує групи, які там пропонуються (назви з serviceTime.groups, обрізані, без повторів без урахування регістру, через кому); якщо в часі немає груп, нічого не відображається.
  3. Призначення групи (app/selectGroup.tsx) — дерево категорій, побудоване з serviceTime.groups, де придатні за віком і класом кімнати виділяються, а непридатні приглушуються і вимагають підтвердження персоналу (див. Перевірка віку та класу); вибір кімнати записує візит-сесію { session: { serviceTimeId, groupId } } у очікуваний візит цієї людини (src/helpers/VisitSessionHelper.ts). «Немає» скасовує вибір.
  4. Завершення (app/checkinComplete.tsx) — POST /attendance/visits/checkin з pendingVisits (кожен із позначкою checkinType), потім друкуються етикетки, якщо налаштовано принтер, і екран автоматично повертається до пошуку. Відповідь 409 для місткості або notOpen показує назву кімнати з причиною (заповнена/закрита або реєстрація не відкрита); попередження співвідношення пропонує підтвердження персоналу, яке повторно надсилає запит із acknowledgeWarnings=true.

Екран видачі (app/checkout.tsx) приймає 4-символьний код безпеки через поле з автофокусом — тож USB- або Bluetooth-сканери штрихкодів, що працюють як клавіатура, працюють без камери — або екранну клавіатуру з тим самим алфавітом, яка автоматично надсилає код на 4 символах. Кнопка Сканувати відкриває аркуш зі спільною камерою src/components/CodeScanner.tsx (за замовчуванням задня, приймає QR, Code 128 і Code 39), щоб станції без сканера-клавіатури могли прочитати етикетку для видачі; відсканований код передається тим самим шляхом handleCode(), що й введений вручну. Екран знаходить код, показує дітей, яких забирають, і подає довірених осіб родини для видачі як картки, на які можна натиснути, поряд із сіткою фото дорослих членів родини (а також варіант «Інший» для вільного тексту, який нечітко перевіряється проти імен, яким не дозволено забирати, — див. Довірені та недозволені особи для видачі), потім надсилає POST /attendance/visits/checkout з іменем/ідентифікатором особи, яку вибрано. У ручному режимі екран також пропонує Викликати батьків (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) захищає екрани адміністратора та принтера; екран адміністратора відкривається лише після 7 швидких натискань на логотип у заголовку; а екран очікування (src/hooks/useInactivityTimer.ts) з’являється в проміжках між родинами.

Самостійна реєстрація (B1App)​

Учасники реєструються з порталу b1.church на екрані /mobile/checkin (маршрутизується з B1App/src/app/[sdSlug]/mobile/components/ScreenRouter.tsx до screens/CheckinPage.tsx). Потрібен вхід до системи, і кроки ті самі, що в кіоску — служіння → родина → групи → завершення — з тими самими endpoint-ами, а стан зберігається в B1App/src/helpers/CheckinHelper.ts. Відмінності від кіоска: родина береться з householdId авторизованого користувача (без кроку пошуку), а друку етикеток немає — натомість екран завершення показує код безпеки пакета як QR (qrcode.react) з підказкою «покажіть це на станції реєстрації». Якщо родина вже зареєстрована під час завантаження сторінки, кнопка «Показати код реєстрації» повторно відображає QR з першого наявного візиту (з GET /attendance/visits/checkin), який має securityCode. Реєстрація записується одразу під час надсилання (стану очікування немає); QR лише запускає друк етикеток на кіоску.

Друк етикеток з телефона на кіоск (B1Checkin/app/scan.tsx, відкривається з кнопки «Сканувати код» біля QR на екрані пошуку): кіоск показує 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 — і повертається до пошуку. Запис відвідуваності під час сканування не відбувається; лише етикетки. Коди без активних візитів, станції без принтера та групи без етикеток показують сповіщення і повертають до пошуку.

Типи та ApiHelper/ArrayHelper походять із @churchapps/helpers і @churchapps/apphelper; жодних React-компонентів із B1Admin не використовується спільно.

Облік відвідуваності в адміністраторі (B1Admin)​

  • Налаштування — /attendance (B1Admin/src/attendance/AttendancePage.tsx) відображає дерево структури та створює служіння (ServiceEdit.tsx) і часи служіння (ServiceTimeEdit.tsx). Дані про кампуси надходять із членства через хук 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(), тож волонтер дитячої кімнати в кімнаті видачі ніколи не запускає етикетку для видачі. Код безпеки з відповіді на реєстрацію додається до бейджів дітей та етикетки видачі; бейджі дорослих друкуються без коду. Якщо в церкві є шаблони, 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() і події статусу з провайдером для кожного бренду на обох платформах:

БрендAndroidiOSПримітки
BrotherBrotherProvider.kt (SDK друку Brother)BrotherProvider.swift (BRLMPrinterKit.xcframework)Мережеві принтери серії QL (QL-800/810W/820NWB/1100/1110NWB…), вирубні етикетки 29×90, рекомендований варіант за замовчуванням
ZebraZebraProvider.kt (SDK Link-OS)ZebraProvider.swift + ZebraBridgeВиявлення в мережі + друк зображень ZPL через TCP

Вибір принтера розміщено в app/printers.tsx (сканування мережі повертає записи brand~model~ip; вибір зберігається в AsyncStorage), а src/helpers/PrinterLog.ts веде діагностичний журнал на пристрої, що відображається через індикатор стану в заголовку кіоска.

Реєстрація гостей​

Два шляхи створюють особу під час реєстрації:

  • На кіоску — кнопка «Додати гостя» на екрані родини відкриває B1Checkin/app/addGuest.tsx, який спершу шукає наявний збіг серед не-учасників через GET /membership/people/search?term=, а якщо його немає — створює нового через POST /membership/people, прикріплюючи до поточної родини. Далі гість проходить призначення групи так само, як і учасник.
  • Самостійна реєстрація через QR — якщо ввімкнено налаштування церкви enableQRGuestRegistration (налаштовується в розділі реєстрації B1Admin, читається з GET /membership/settings/public/{churchId}), екран пошуку на кіоску показує QR-код, що веде на https://{subdomain}.b1.church/guest-register?serviceId=. Ця сторінка B1App (src/app/[sdSlug]/(public)/guest-register/page.tsx) дозволяє родині-відвідувачу зареєструватися зі свого телефона через анонімний endpoint POST /membership/people/guest-register, що не затримує чергу біля кіоска. Аркуш із QR також має кнопку Зареєструватися тут, яка відкриває ту саму сторінку на кіоску (app/guestRegister.tsx) у режимі інкогніто з вимкненим кешем у WebView; src/helpers/GuestRegisterHelper.ts формує URL і для QR, і для WebView, а також блокує переходи за межі https://{subdomain}.b1.church/guest-register. Екран повертається до пошуку після натискання Готово, кнопки «назад» або 120 секунд бездіяльності (набір тексту у формі передається з WebView як активність), а WebView демонтується, щоб дані однієї родини ніколи не потрапили до наступної.

Реєстрація гостей через QR керується налаштуваннями церкви, які зберігаються з картки Реєстрація гостей через QR в B1Admin (src/mobile/CheckInPage.tsx):

НалаштуванняВидимістьПризначення
enableQRGuestRegistrationпублічнеПеремикач для ввімкнення QR на кіоску та анонімних endpoint-ів
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(). Спочатку він викликає PersonRepo.findGuestMatch() для кожного члена з email або телефоном: рівно одна жива особа з тим самим ім’ям і тим самим email або цифрами телефону повторно використовується (нуль або кілька збігів — створюється нова особа, тож система ніколи не вгадує). Член без контактних даних зіставляється за іменем всередині знайденої родини. Повторно використані особи ніколи не редагуються, тож анонімна форма не може перезаписати збережені дані, а відповідь повторює надіслані імена. Незіставлені члени приєднуються до знайденої родини або до нової, зі статусом membershipStatus: "Visitor", і для кожної нової особи надсилається person.created. Далі помилки записуються до журналу, а не повертаються: учасники додаються до налаштованої групи (group.member.added); якщо ввімкнено облік відвідуваності, AttendanceModuleGateway.recordAttendance() позначає кожного члена присутнім для кожного часу служіння групи, який має розклад і чиє вікно реєстрації (CheckinGateHelper.isServiceTimeOpen) відкрите саме зараз, створюючи заняття на сьогоднішню дату за місцевим часом церкви, якщо це потрібно — незаплановані часи служіння та реєстрації поза вікном нічого не фіксують; коментарі стають прихованою нотаткою до особи в розмові з главою родини (автор повідомлення «Реєстрація гостя»), прив’язаною через person.conversationId.

Пов’язані сторінки​