Перейти к основному содержимому

Эндпоинты посещаемости

Модуль посещаемости управляет кампусами, богослужениями, временем служений, сессиями посещаемости, визитами и сессиями визитов. Он обеспечивает инфраструктуру для учёта того, кто посетил какое богослужение или встречу группы, поддерживает сценарии регистрации (check-in) и предоставляет отчёты о динамике и сводке посещаемости.

Базовый путь: /attendance

Кампусы​

Базовый путь: /attendance/campuses

Стандартный CRUD-контроллер (наследует GenericCrudController). Предоставляет маршруты getById, getAll, post и delete через базовый класс CRUD.

МетодПутьАвторизацияРазрешениеОписание
GET/JWT—Получить все кампусы церкви
GET/:idJWT—Получить кампус по ID
POST/JWTServices.EditСоздать или обновить кампусы
DELETE/:idJWTServices.EditУдалить кампус

Богослужения​

Базовый путь: /attendance/services

Наследует GenericCrudController с CRUD-маршрутами getById, getAll, post и delete. Эндпоинты getAll (GET /) и search переопределены собственной реализацией.

МетодПутьАвторизацияРазрешениеОписание
GET/JWT—Получить все богослужения (включая информацию о кампусе)
GET/:idJWT—Получить богослужение по ID
GET/search?campusId=JWT—Найти богослужения по ID кампуса
POST/JWTServices.EditСоздать или обновить богослужения
DELETE/:idJWTServices.EditУдалить богослужение

Пример: поиск богослужений по кампусу​

GET /attendance/services/search?campusId=abc-123
Authorization: Bearer <token>
[
{
"id": "svc-001",
"churchId": "church-123",
"campusId": "abc-123",
"name": "Sunday Morning"
}
]

Время богослужений​

Базовый путь: /attendance/servicetimes

Наследует GenericCrudController с CRUD-маршрутами getById, post и delete. Эндпоинты getAll и search реализованы собственным кодом.

МетодПутьАвторизацияРазрешениеОписание
GET/JWT—Получить все времена служений. Фильтр по ?serviceId=. Добавьте ?include=groups, чтобы включить данные о группах. Каждая строка содержит вычисляемое логическое поле checkinOpen (значение false только тогда, когда у времени служения есть расписание регистрации и окно регистрации сейчас закрыто). Окно вычисляется во временной зоне кампуса служения, затем во временной зоне церкви, затем по первому кампусу, у которого она задана, и наконец по America/New_York
GET/:idJWT—Получить время служения по ID
GET/search?campusId=&serviceId=JWT—Найти времена служений по кампусу и богослужению
GET/public/:churchIdПубличный—Получить дерево «кампус → богослужение → время» для церкви. Используется элементом serviceTimes конструктора сайтов
POST/JWTServices.EditСоздать или обновить времена служений. Необязательные поля расписания: dayOfWeek (0 = воскресенье … 6), startTime / endTime (HH:mm), checkinOpenMinutes (до начала), checkinCloseMinutes (после окончания). Регистрация ограничивается по времени только тогда, когда заданы оба поля: dayOfWeek и startTime
DELETE/:idJWTServices.EditУдалить время служения

Группы и времена служений​

Базовый путь: /attendance/groupservicetimes

Связывает группы с конкретными временами служений.

МетодПутьАвторизацияРазрешениеОписание
GET/JWT—Получить все связи «группа — время служения». Фильтр по ?groupId= возвращает связи с названиями служений
GET/:idJWT—Получить связь «группа — время служения» по ID
POST/JWTServices.EditСоздать или обновить связи «группа — время служения»
DELETE/:idJWTServices.EditУдалить связь «группа — время служения»

Записи посещаемости​

Базовый путь: /attendance/attendancerecords

Предоставляет доступ только для чтения к агрегированным данным о посещаемости для отчётов и отображения.

МетодПутьАвторизацияРазрешениеОписание
GET/JWTAttendance.ViewЗагрузить записи посещаемости человека. Требуется ?personId=
GET/myJWT—Только для себя: собственные записи посещаемости вошедшего участника за последние 12 месяцев, сначала самые новые. Возвращает 401, если пользователь не связан с человеком. Используется разделом My Attendance страницы B1 Me
GET/treeJWT—Загрузить полное дерево посещаемости (кампусы, богослужения, времена служений, группы)
GET/trend?campusId=&serviceId=&serviceTimeId=&groupId=JWTAttendance.View SummaryЗагрузить данные о динамике посещаемости с необязательными фильтрами
GET/groups?serviceId=&week=JWTAttendance.ViewЗагрузить посещаемость групп для богослужения за указанную неделю
GET/sessionStatus?serviceTimeId=&date=JWTAttendance.ViewДля каждой группы, назначенной на время служения, вернуть { groupId, sessionId, attendanceCount } за указанную дату (date в формате YYYY-MM-DD; sessionId равен null, если у группы нет сессии). Используется диалогом Who Still Needs Attendance в B1Admin
GET/search?campusId=&serviceId=&serviceTimeId=&groupId=&startDate=&endDate=JWTAttendance.ViewПоиск записей посещаемости с фильтрами (кампус, богослужение, время служения, группа, диапазон дат)

Пример: динамика посещаемости​

GET /attendance/attendancerecords/trend?serviceId=svc-001
Authorization: Bearer <token>
[
{ "week": "2025-01-05", "count": 142 },
{ "week": "2025-01-12", "count": 156 },
{ "week": "2025-01-19", "count": 138 }
]

Сессии​

Базовый путь: /attendance/sessions

Наследует GenericCrudController с CRUD-маршрутами getById и delete. Эндпоинты getAll и save реализованы собственным кодом и также позволяют руководителям групп управлять сессиями своих групп.

МетодПутьАвторизацияРазрешениеОписание
GET/JWTAttendance.View или руководитель группыПолучить все сессии. Фильтр по ?groupId= (включает названия). Руководители групп могут просматривать сессии своих групп
GET/:idJWTAttendance.ViewПолучить сессию по ID
POST/JWTAttendance.Edit или руководитель группыСоздать или обновить сессии. Руководители групп могут сохранять сессии своих групп
DELETE/:idJWTAttendance.EditУдалить сессию

Визиты​

Базовый путь: /attendance/visits

Управляет отдельными записями визитов (присутствие человека в конкретную дату) и предоставляет сценарий регистрации (check-in).

МетодПутьАвторизацияРазрешениеОписание
GET/JWTAttendance.ViewПолучить все визиты. Фильтр по ?personId=
GET/:idJWTAttendance.ViewПолучить визит по ID
GET/checkin?serviceId=&peopleIds=JWTAttendance.View или Attendance.CheckinЗагрузить данные регистрации людей на богослужении. Возвращает визиты с сессиями визитов из последней записанной даты
POST/JWTAttendance.EditСоздать или обновить визиты
POST/checkin?serviceId=&peopleIds=JWTAttendance.Edit или Attendance.CheckinОтправить данные регистрации. Создаёт или обновляет визиты и сессии визитов, удаляет устаревшие записи
DELETE/:idJWTAttendance.EditУдалить визит

Пример: процесс регистрации​

Шаг 1 -- загрузить существующие данные регистрации:

GET /attendance/visits/checkin?serviceId=svc-001&peopleIds=person-1,person-2
Authorization: Bearer <token>
[
{
"id": "visit-001",
"personId": "person-1",
"visitDate": "2025-01-19T00:00:00.000Z",
"visitSessions": [
{
"id": "vs-001",
"sessionId": "sess-001",
"visitId": "visit-001",
"session": {
"id": "sess-001",
"groupId": "group-001",
"serviceTimeId": "st-001",
"sessionDate": "2025-01-19T00:00:00.000Z"
}
}
]
}
]

Шаг 2 -- отправить регистрацию:

POST /attendance/visits/checkin?serviceId=svc-001&peopleIds=person-1,person-2
Authorization: Bearer <token>

[
{
"personId": "person-1",
"visitSessions": [
{
"session": { "serviceTimeId": "st-001", "groupId": "group-001" }
}
]
}
]

Если у выбранного времени служения есть расписание регистрации и окно регистрации закрыто (вычисляется в том же порядке временных зон, что и для checkinOpen, с приоритетом кампуса), ничего не сохраняется, и ответ имеет вид 409 { "error": "notOpen", "groups": [{ "groupId", "groupName", "reason": "notOpen" }] }. Нарушения лимита мест и соотношения волонтёров также возвращают 409 (error: "capacity" или "ratio"). Сессии, которые человек уже занимает сегодня (повторно отправляются при каждой регистрации), не проверяются по окну времени, поэтому семья может добавить открытое время служения после того, как окно предыдущего уже закрылось.

Сессии визитов​

Базовый путь: /attendance/visitsessions

Управляет связью между визитами и сессиями (на какую конкретную сессию человек пришёл во время визита). Также предоставляет быстрый эндпоинт записи и эндпоинт загрузки/экспорта.

МетодПутьАвторизацияРазрешениеОписание
GET/JWTAttendance.View или руководитель группыПолучить сессии визитов. Фильтр по ?sessionId=. Руководители групп могут просматривать сессии визитов своих групп
GET/:idJWTAttendance.ViewПолучить сессию визита по ID
GET/download/:sessionIdJWTAttendance.ViewЗагрузить посещаемость сессии (возвращает имена людей со статусом «присутствовал» или «отсутствовал»)
POST/JWTAttendance.EditСоздать или обновить сессии визитов
POST/logJWTAttendance.Edit или руководитель группыБыстро записать посещаемость человека на сессию. При необходимости автоматически создаёт визит. Руководители групп могут записывать посещаемость своих групп
DELETE/:idJWTAttendance.EditУдалить сессию визита по ID
DELETE/?personId=&sessionId=JWTAttendance.Edit или руководитель группыУдалить человека из сессии. Удаляет сессию визита и родительский визит, если сессий не осталось. Руководители групп могут удалять посещаемость своих групп

Пример: быстрая запись посещаемости​

POST /attendance/visitsessions/log
Authorization: Bearer <token>

{
"personId": "person-001",
"visitSessions": [
{ "sessionId": "sess-001" }
]
}
{}

Пример: выгрузка посещаемости сессии​

GET /attendance/visitsessions/download/sess-001
Authorization: Bearer <token>
[
{
"id": "vs-001",
"personId": "person-001",
"visitId": "visit-001",
"sessionDate": "2025-01-19T00:00:00.000Z",
"personName": "John Smith",
"status": "present"
},
{
"id": "",
"personId": "person-002",
"visitId": "",
"sessionDate": "2025-01-19T00:00:00.000Z",
"personName": "Jane Doe",
"status": "absent"
}
]

Серии посещений​

Базовый путь: /attendance/streaks

Отслеживает серии посещений отдельных людей -- количество последовательных недель, в которые человек приходил. Полезно для метрик вовлечённости и геймификации.

МетодПутьАвторизацияРазрешениеОписание
GET/person/:personIdJWT—Загрузить серии посещений человека

Связанные страницы​