출석 체크 시스템

선생님은 실시간으로 출석 코드를 생성하고, 학생들은 해당 코드를 입력하여 출석 체크를 할 수 있습니다.

주요 기능

1. 출석 세션 생성 (선생님)

경로: /c/[slug]/attendance
권한: Owner, Admin만 접근 가능
기능:
- 8자리 고유 출석 코드 자동 생성 (혼동하기 쉬운 문자 제외: I, O, 0, 1, L)
- 기본 5분 유효 시간 (설정 가능)
- 실시간 카운트다운 타이머
- 코드 복사 기능
- 활성 세션 목록 확인
- 과거 세션 히스토리

2. 출석 체크 (학생)

경로: /c/[slug]/check-in
권한: 커뮤니티 멤버 모두
기능:
- 8자리 코드 입력
- 대소문자 구분 없음
- 실시간 검증
- 성공 시 +5 포인트 자동 지급
- 중복 출석 방지

3. 출석 통계

세션별 통계:
- 출석한 학생 수
- 출석률
- 세션 시간
학생별 통계:
- 개별 출석률
- 총 출석 횟수
- 출석 기록

API 엔드포인트

POST /api/attendance/sessions

출석 세션 생성

Request:

{
  "communitySlug": "korean-topik-master",
  "duration": 5
}

Response:

{
  "success": true,
  "session": {
    "id": 1,
    "code": "ABC12345",
    "expiresAt": "2025-12-14T13:05:00.000Z",
    "createdAt": "2025-12-14T13:00:00.000Z"
  }
}

GET /api/attendance/sessions?community=slug

활성 출석 세션 목록 조회

Response:

{
  "activeSessions": [
    {
      "id": 1,
      "code": "ABC12345",
      "expiresAt": "2025-12-14T13:05:00.000Z",
      "attendeeCount": 15
    }
  ]
}

POST /api/attendance/mark

출석 체크 (학생)

Request:

{
  "code": "ABC12345"
}

Response:

{
  "success": true,
  "message": "출석이 완료되었습니다! +5 포인트"
}

Error Responses:

404: 잘못된 출석 코드
410: 출석 코드가 만료됨
409: 이미 출석 체크 완료

GET /api/attendance/stats?community=slug

출석 통계 조회

Response:

{
  "sessions": [
    {
      "id": 1,
      "code": "ABC12345",
      "createdAt": "2025-12-14T13:00:00.000Z",
      "expiresAt": "2025-12-14T13:05:00.000Z",
      "attendeeCount": 15,
      "attendanceRate": 75
    }
  ],
  "memberStats": [
    {
      "memberId": 1,
      "userName": "김철수",
      "attendanceCount": 8,
      "attendanceRate": 80
    }
  ],
  "summary": {
    "totalSessions": 10,
    "totalAttendance": 150,
    "averageAttendanceRate": 75
  }
}

데이터베이스 스키마

attendanceSessions 테이블

{
  id: serial("id").primaryKey(),
  communityId: integer("community_id").notNull(),
  createdBy: integer("created_by").notNull(),
  code: varchar("code", { length: 8 }).notNull().unique(),
  expiresAt: timestamp("expires_at").notNull(),
  createdAt: timestamp("created_at").notNull().defaultNow()
}

attendanceRecords 테이블

{
  id: serial("id").primaryKey(),
  sessionId: integer("session_id").notNull(),
  memberId: integer("member_id").notNull(),
  markedAt: timestamp("marked_at").notNull().defaultNow(),
  // Unique constraint on (sessionId, memberId)
}

사용 시나리오

선생님 워크플로우

수업 시작 시 "출석 세션 생성" 버튼 클릭
생성된 8자리 코드를 화면에 표시하거나 구두로 공지
실시간으로 출석 현황 확인
5분 후 자동으로 만료 (필요시 새 세션 생성)
수업 후 출석 통계 확인

학생 워크플로우

사이드바에서 "출석 체크" 메뉴 선택
선생님이 제공한 8자리 코드 입력
출석 완료 시 +5 포인트 획득
성공/실패 메시지 확인

보안 및 검증

코드 생성

8자리 랜덤 코드
혼동 문자 제외 (I, O, 0, 1, L)
데이터베이스 unique 제약으로 중복 방지
최대 10회 재시도로 유일성 보장

유효성 검증

서버 사이드 만료 시간 검증
중복 출석 방지 (unique index)
커뮤니티 멤버십 검증
세션 존재 여부 확인

보안 고려사항

코드는 일회성이 아니므로 5분 내 여러 학생이 동일 코드 사용 가능
한 학생은 한 세션당 한 번만 출석 가능
만료된 코드는 재사용 불가
Owner/Admin만 세션 생성 가능

UI/UX 특징

선생님 페이지

실시간 카운트다운 타이머
코드 원클릭 복사
활성/과거 세션 탭 구분
출석 통계 테이블
한눈에 보는 출석률

학생 페이지

대형 입력창 (모바일 친화적)
자동 대문자 변환
8자리 길이 제한
즉각적인 피드백 (성공/실패)
사용 방법 안내

포인트 시스템 연동

출석 체크 시

자동으로 +5 포인트 지급
awardPoints() 함수 호출
포인트 이력에 "출석 체크" 기록
레벨 업 자동 계산

확장 가능성

향후 추가 가능 기능

QR 코드 생성 및 스캔
위치 기반 출석 (GPS)
출석 패턴 분석
지각/결석 자동 기록
학부모 알림
출석부 Excel 내보내기
출석 보너스 포인트 (연속 출석)

트러블슈팅

학생이 코드를 입력했는데 실패할 경우

코드가 만료되었는지 확인 (5분 경과)
이미 출석 체크를 했는지 확인
코드를 정확히 입력했는지 확인 (대소문자 무관)

선생님이 세션을 생성할 수 없는 경우

Owner 또는 Admin 권한 확인
네트워크 연결 상태 확인
브라우저 콘솔 에러 확인

통계가 표시되지 않는 경우

페이지 새로고침 (30초마다 자동 갱신)
출석 세션이 최소 1개 이상 있는지 확인