⚙️ [기능추가][출석] 출석체크 QR코드 체크인 페이지 구현

[discipline24]

📝 현재 문제점

• 프론트엔드에 출석체크를 위한 QR코드 체크인 로직이 없습니다.
• 사용자 입장에서 QR 찍기 -> (잠시 로딩) -> 출석 완료 라는 간단한 플로우를 가진 기능으로 제공해야 합니다.
• 웹에서는 deviceId를 사용할 수 없기에, 백엔드 API 요청값에서 제외시켜야 합니다.

🛠️ 해결 방안 / 제안 기능

출석 체크인 메커니즘 흐름

[1단계] QR 발급 및 렌더링 (관리자 화면)

1. 프론트엔드: /api/attendance/rounds/{roundId}/qr-stream (SSE)로 연결 시도
2. 백엔드: 설정된 주기마다(현재 3분) 새로운 qrToken을 SSE 채널로 send
3. 프론트엔드: 받은 토큰을 qrcode.react같은 라이브러리에 넣고, 실시간으로 변하는 QR 코드 이미지를 화면에 렌더링

[2단계] QR 스캔 (사용자 웹)

1. 사용자: 카메라로 관리자 화면의 QR 촬영
2. 프론트엔드: QR 코드에 담긴 qrToken 문자열 추출

[3단계] 체크인 요청 (사용자 웹)

1. 프론트엔드: 추출한 토큰을 담아 POST /api/attendance/check-in API 호출
2. 백엔드

• 토큰 만료 여부 확인
• 어느 라운드의 토큰인지 확인
• 현재 로그인한 유저(@AuthenticationPrincipal)가 이 세션의 멤버인지 확인
• 모두 통과하면 출석 처리!

따라서 프론트엔드에 QR코드 렌더링 페이지 및 출석체크 페이지, 관리자 페이지의 버튼 추가가 필요합니다.

⚙️ 작업 내용

요약

백엔드: POST /check-in에서 deviceId 필드 제거
프론트엔드

• QR코드 렌더링 페이지 구현
• QR 스캔 시 자동으로 API를 쏘는 Landing Page 구현
• 로그인 예외 처리
• 출석체크 관리자 페이지에 버튼 추가
  *향후 구현할 관리자 페이지로 옮기지 않습니다. 현재 디자인과 같이 구현해주시면 됩니다.

---

페이지 1. QR코드 렌더링 페이지 구현

• 백엔드 SSE API 연결
• QR에 사용할 token값을 SSE로 받아, 실시간으로 변하는 QR 코드 이미지를 화면에 렌더링

디자인

• QR코드 버튼 하나 생성
• QR코드는 라운드별로 생성되기 때문에, 버튼 위치는 위 페이지에 라운드별로, 회차 옆에 생성 (1회차, 2회차, 3회차 옆에 각각 존재해야 함)
• 버튼 클릭 시, 새로운 탭에서 QR코드 렌더링한 화면이 전체화면급으로 커지게 나옴

QR 코드 URL 확정

• 관리자 화면에서 생성할 QR 코드에, 프론트엔드의 체크인 전용 페이지 주소를 담아야 함
• URL 형식: https://domain.com/attendance/check-in?token={qrToken}
• 이유: 일반 카메라로 찍었을 때 바로 웹사이트로 연결되어야 함

페이지 2. 하이패스 체크인 페이지 구현

• 토큰 추출: URL 파라미터에서 token 값 확인
• 로그인 체크: LocalStorage/Cookie 등 브라우저에 accessToken이 있는지 확인
• 없다면: 로그인 페이지로 보냅니다. (이때, 로그인 후 다시 이 페이지로 돌아오도록 returnUrl을 저장해두면 센스 만점!)
• 있다면: 즉시 백엔드 API 호출 - POST /api/attendance/check-in

3. 결과 처리:

성공: "출석이 완료되었습니다!" 메시지와 함께 메인으로 이동
실패: "이미 출석했거나 만료된 QR입니다." 등의 에러 메시지 노출

• SSE 연결 원리 등 자세한 내용은 해당 기능 백엔드 담당자에게 문의바랍니다. @daye200 @nayoung04

🙋‍♂️ 담당자

• 백엔드: @daye200
• 프론트엔드: @yyunee
• 디자인: 이름
• AI : 이름