본문으로 건너뛰기

출석 엔드포인트

출석(Attendance) 모듈은 캠퍼스 위치, 예배, 예배 시간, 출석 세션, 방문(visit), 방문 세션을 관리합니다. 누가 어떤 예배나 소그룹 모임에 참석했는지 추적하는 기반을 제공하며, 체크인 워크플로를 지원하고 출석 추세와 요약 보고서를 제공합니다.

기본 경로: /attendance

캠퍼스​

기본 경로: /attendance/campuses

표준 CRUD 컨트롤러입니다(GenericCrudController를 확장함). CRUD 기본 클래스를 통해 getById, getAll, post, delete 라우트를 제공합니다.

메서드경로인증권한설명
GET/JWT—교회의 모든 캠퍼스 목록 조회
GET/:idJWT—ID로 캠퍼스 조회
POST/JWTServices.Edit캠퍼스 생성 또는 수정
DELETE/:idJWTServices.Edit캠퍼스 삭제

예배​

기본 경로: /attendance/services

GenericCrudController를 확장하며 getById, getAll, post, delete CRUD 라우트를 제공합니다. 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를 확장하며 getById, post, delete CRUD 라우트를 제공합니다. getAll 및 search 엔드포인트는 자체 구현입니다.

메서드경로인증권한설명
GET/JWT—모든 예배 시간 목록 조회. ?serviceId=로 필터링. ?include=groups를 추가하면 그룹 데이터를 함께 반환. 각 행에는 계산된 checkinOpen 불리언 값이 포함됨(체크인 일정이 있고 현재 시간이 그 일정 기간 밖일 때만 false). 기간은 예배가 속한 캠퍼스의 시간대를 기준으로 측정하며, 없으면 교회의 시간대, 그다음으로 시간대가 설정된 첫 번째 캠퍼스, 마지막으로 America/New_York을 사용
GET/:idJWT—ID로 예배 시간 조회
GET/search?campusId=&serviceId=JWT—캠퍼스와 예배 기준으로 예배 시간 검색
GET/public/:churchIdPublic—교회의 캠퍼스 → 예배 → 예배 시간 트리 조회. 웹사이트 빌더의 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 반환. 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). 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를 확장하며 getById와 delete CRUD 라우트를 제공합니다. getAll과 save 엔드포인트는 그룹 리더가 자신의 그룹 세션을 관리할 수 있도록 하는 자체 구현입니다.

메서드경로인증권한설명
GET/JWTAttendance.View 또는 그룹 리더모든 세션 목록 조회. ?groupId=로 필터링(이름 포함). 그룹 리더는 자신이 맡은 그룹의 세션을 조회할 수 있음
GET/:idJWTAttendance.ViewID로 세션 조회
POST/JWTAttendance.Edit 또는 그룹 리더세션 생성 또는 수정. 그룹 리더는 자신이 맡은 그룹의 세션을 저장할 수 있음
DELETE/:idJWTAttendance.Edit세션 삭제

방문​

기본 경로: /attendance/visits

개별 방문 기록(특정 날짜에 한 사람이 참석한 기록)을 관리하고 체크인 워크플로를 제공합니다.

메서드경로인증권한설명
GET/JWTAttendance.View모든 방문 목록 조회. ?personId=로 필터링
GET/:idJWTAttendance.ViewID로 방문 조회
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.ViewID로 방문 세션 조회
GET/download/:sessionIdJWTAttendance.View세션의 출석 다운로드(출석/결석 상태가 포함된 사람 이름 반환)
POST/JWTAttendance.Edit방문 세션 생성 또는 수정
POST/logJWTAttendance.Edit 또는 그룹 리더한 사람의 출석을 세션에 빠르게 기록. 필요하면 방문을 자동으로 생성. 그룹 리더는 자신이 맡은 그룹의 출석을 기록할 수 있음
DELETE/:idJWTAttendance.EditID로 방문 세션 삭제
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—한 사람의 연속 출석 기록 조회

관련 페이지​