Эндпоинты посещаемости
Модуль посещаемости управляет кампусами, богослужениями, временем служений, сессиями посещаемости, визитами и сессиями визитов. Он обеспечивает инфраструктуру для учёта того, кто посетил какое богослужение или встречу группы, поддерживает сценарии регистрации (check-in) и предоставляет отчёты о динамике и сводке посещаемости.
Базовый путь: /attendance
Кампусы
Базовый путь: /attendance/campuses
Стандартный CRUD-контроллер (наследует GenericCrudController). Предоставляет маршруты getById, getAll, post и delete через базовый класс CRUD.
| Метод | Путь | Авторизация | Разрешение | Описание |
|---|---|---|---|---|
| GET | / | JWT | — | Получить все кампусы церкви |
| GET | /:id | JWT | — | Получить кампус по ID |
| POST | / | JWT | Services.Edit | Создать или обновить кампусы |
| DELETE | /:id | JWT | Services.Edit | Удалить кампус |
Богослужения
Базовый путь: /attendance/services
Наследует GenericCrudController с CRUD-маршрутами getById, getAll, post и delete. Эндпоинты getAll (GET /) и search переопределены собственной реализацией.
| Метод | Путь | Авторизация | Разрешение | Описание |
|---|---|---|---|---|
| GET | / | JWT | — | Получить все богослужения (включая информацию о кампусе) |
| GET | /:id | JWT | — | Получить богослужение по ID |
| GET | /search?campusId= | JWT | — | Найти богослужения по ID кампуса |
| POST | / | JWT | Services.Edit | Создать или обновить богослужения |
| DELETE | /:id | JWT | Services.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 | /:id | JWT | — | Получить время служения по ID |
| GET | /search?campusId=&serviceId= | JWT | — | Найти времена служений по кампусу и богослужению |
| GET | /public/:churchId | Публичный | — | Получить дерево «кампус → богослужение → время» для церкви. Используется элементом serviceTimes конструктора сайтов |
| POST | / | JWT | Services.Edit | Создать или обновить времена служений. Необязательные поля расписания: dayOfWeek (0 = воскресенье … 6), startTime / endTime (HH:mm), checkinOpenMinutes (до начала), checkinCloseMinutes (после окончания). Регистрация ограничивается по времени только тогда, когда заданы оба поля: dayOfWeek и startTime |
| DELETE | /:id | JWT | Services.Edit | Удалить время служения |
Группы и времена служений
Базовый путь: /attendance/groupservicetimes
Связывает группы с конкретными временами служений.
| Метод | Путь | Авторизация | Разрешение | Описание |
|---|---|---|---|---|
| GET | / | JWT | — | Получить все связи «группа — время служения». Фильтр по ?groupId= возвращает связи с названиями служений |
| GET | /:id | JWT | — | Получить связь «группа — время служения» по ID |
| POST | / | JWT | Services.Edit | Создать или обновить связи «группа — время служения» |
| DELETE | /:id | JWT | Services.Edit | Удалить связь «группа — время служения» |
Записи посещаемости
Базовый путь: /attendance/attendancerecords
Предоставляет доступ только для чтения к агрегированным данным о посещаемости для отчётов и отображения.
| Метод | Путь | Авторизация | Разрешение | Описание |
|---|---|---|---|---|
| GET | / | JWT | Attendance.View | Загрузить записи посещаемости человека. Требуется ?personId= |
| GET | /my | JWT | — | Только для себя: собственные записи посещаемости вошедшего участника за последние 12 месяцев, сначала самые новые. Возвращает 401, если пользователь не связан с человеком. Используется разделом My Attendance страницы B1 Me |
| GET | /tree | JWT | — | Загрузить полное дерево посещаемости (кампусы, богослужения, времена служений, группы) |
| GET | /trend?campusId=&serviceId=&serviceTimeId=&groupId= | JWT | Attendance.View Summary | Загрузить данные о динамике посещаемости с необязательными фильтрами |
| GET | /groups?serviceId=&week= | JWT | Attendance.View | Загрузить посещаемость групп для богослужения за указанную неделю |
| GET | /sessionStatus?serviceTimeId=&date= | JWT | Attendance.View | Для каждой группы, назначенной на время служения, вернуть { groupId, sessionId, attendanceCount } за указанную дату (date в формате YYYY-MM-DD; sessionId равен null, если у группы нет сессии). Используется диалогом Who Still Needs Attendance в B1Admin |
| GET | /search?campusId=&serviceId=&serviceTimeId=&groupId=&startDate=&endDate= | JWT | Attendance.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 | / | JWT | Attendance.View или руководитель группы | Получить все сессии. Фильтр по ?groupId= (включает названия). Руководители групп могут просматривать сессии своих групп |
| GET | /:id | JWT | Attendance.View | Получить сессию по ID |
| POST | / | JWT | Attendance.Edit или руководитель группы | Создать или обновить сессии. Руководители групп могут сохранять сессии своих групп |
| DELETE | /:id | JWT | Attendance.Edit | Удалить сессию |
Визиты
Базовый путь: /attendance/visits
Управляет отдельными записями визитов (присутствие человека в конкретную дату) и предоставляет сценарий регистрации (check-in).
| Метод | Путь | Авторизация | Разрешение | Описание |
|---|---|---|---|---|
| GET | / | JWT | Attendance.View | Получить все визиты. Фильтр по ?personId= |
| GET | /:id | JWT | Attendance.View | Получить визит по ID |
| GET | /checkin?serviceId=&peopleIds= | JWT | Attendance.View или Attendance.Checkin | Загрузить данные регистрации людей на богослужении. Возвращает визиты с сессиями визитов из последней записанной даты |
| POST | / | JWT | Attendance.Edit | Создать или обновить визиты |
| POST | /checkin?serviceId=&peopleIds= | JWT | Attendance.Edit или Attendance.Checkin | Отправить данные регистрации. Создаёт или обновляет визиты и сессии визитов, удаляет устаревшие записи |
| DELETE | /:id | JWT | Attendance.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 | / | JWT | Attendance.View или руководитель группы | Получить сессии визитов. Фильтр по ?sessionId=. Руководители групп могут просматривать сессии визитов своих групп |
| GET | /:id | JWT | Attendance.View | Получить сессию визита по ID |
| GET | /download/:sessionId | JWT | Attendance.View | Загрузить посещаемость сессии (возвращает имена людей со статусом «присутствовал» или «отсутствовал») |
| POST | / | JWT | Attendance.Edit | Создать или обновить сессии визитов |
| POST | /log | JWT | Attendance.Edit или руководитель группы | Быстро записать посещаемость человека на сессию. При необходимости автоматически создаёт визит. Руководители групп могут записывать посещаемость своих групп |
| DELETE | /:id | JWT | Attendance.Edit | Удалить сессию визита по ID |
| DELETE | /?personId=&sessionId= | JWT | Attendance.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/:personId | JWT | — | Загрузить серии посещений человека |
Связанные страницы
- Эндпоинты членства — Люди, группы, роли и управление церковью
- Аутентификация и разрешения — Процесс входа, JWT, модель разрешений
- Структура модуля — Организация кода