[D2C-44] 사용자 행동 이벤트 로그 발생 로직 구현

[jjunier]

개요

본 PR은 D2C-44 사용자 행동 이벤트 로그 발생 로직 구현 결과를 develop 브랜치에 반영하기 위한 PR입니다.

D2C-44에서는 D2C-43에서 구현한 POST /events API를 프론트엔드 주요 사용자 행동 지점에 연결했습니다.

본 PR에서는 상품 목록, 상품 상세, 장바구니, 체크아웃, 주문 내역, 쿠폰함, 리뷰 작성 화면에서 발생하는 페이지 진입 및 주요 버튼 클릭 이벤트를 event_logs에 저장하도록 구현합니다. 이를 통해 이후 로그/검증 단계에서 사용자 행동 이벤트를 기반으로 운영계 데이터와 이벤트 로그 간 흐름을 점검할 수 있는 기반을 마련합니다.

---

포함 범위

프론트엔드 이벤트 로그 공통 타입

• 이벤트 로그 생성 요청 타입 추가
• 이벤트 로그 생성 응답 타입 추가
• 이벤트 타입 정의
• 이벤트 source 타입 정의
• 사용자 행동 이벤트 payload 구조 정의
• user_id, session_id, entity_type, entity_id nullable 처리
• properties를 이벤트별 확장 필드로 구성

프론트엔드 이벤트 로그 API 클라이언트

• POST /events 호출 함수 추가
• 프론트엔드 사용자 행동 이벤트 기본값 구성
• event_type = user_behavior 설정
• source = frontend 설정
• 이벤트 저장 실패 시 사용자 화면 흐름을 막지 않도록 처리
• 이벤트 저장 실패 시 콘솔 로그만 남기고 null 반환

상품 목록 사용자 행동 이벤트

• 상품 목록 페이지 진입 이벤트 추가
• 상품 목록에서 장바구니 담기 클릭 이벤트 추가
• 상품 목록 진입 시 product_list_viewed 기록
• 상품 담기 클릭 시 product_add_to_cart_clicked 기록
• 상품 ID, 상품명, 진입 페이지, 수량 정보를 properties에 포함

상품 상세 사용자 행동 이벤트

• 상품 상세 페이지 진입 이벤트 추가
• 상품 상세에서 장바구니 담기 클릭 이벤트 추가
• 상품 상세 진입 시 product_detail_viewed 기록
• 상품 담기 클릭 시 product_add_to_cart_clicked 기록
• 상품 ID, 상품명, 진입 페이지, 선택 수량 정보를 properties에 포함

장바구니 사용자 행동 이벤트

• 장바구니 페이지 진입 이벤트 추가
• 장바구니 수량 변경 클릭 이벤트 추가
• 장바구니 상품 제거 클릭 이벤트 추가
• 장바구니 진입 시 cart_viewed 기록
• 수량 변경 시 cart_quantity_change_clicked 기록
• 상품 제거 시 cart_item_remove_clicked 기록
• 장바구니 ID, 장바구니 항목 ID, 상품 ID, 상품명, 기존 수량, 변경 수량 정보를 properties에 포함

체크아웃 사용자 행동 이벤트

• 체크아웃 페이지 진입 이벤트 추가
• 쿠폰 적용 클릭 이벤트 추가
• 주문 생성 클릭 이벤트 추가
• 결제 성공 시뮬레이션 클릭 이벤트 추가
• 결제 실패 시뮬레이션 클릭 이벤트 추가
• 체크아웃 진입 시 checkout_started 기록
• 쿠폰 적용 클릭 시 coupon_apply_clicked 기록
• 주문 생성 클릭 시 order_create_clicked 기록
• 결제 성공 클릭 시 payment_success_clicked 기록
• 결제 실패 클릭 시 payment_fail_clicked 기록
• 장바구니 ID, 쿠폰명, 주문 ID, 결제 방식, 시뮬레이션 결과 정보를 properties에 포함

주문 내역 사용자 행동 이벤트

• 주문 내역 페이지 진입 이벤트 추가
• 주문 내역 진입 시 order_history_viewed 기록
• 페이지 경로 정보를 properties에 포함

쿠폰함 사용자 행동 이벤트

• 쿠폰함 페이지 진입 이벤트 추가
• 쿠폰함 진입 시 coupon_wallet_viewed 기록
• 페이지 경로 정보를 properties에 포함

리뷰 작성 사용자 행동 이벤트

• 리뷰 작성 페이지 진입 이벤트 추가
• 리뷰 등록 클릭 이벤트 추가
• 리뷰 작성 페이지 진입 시 review_create_page_viewed 기록
• 리뷰 등록 클릭 시 review_submit_clicked 기록
• 상품 ID, 주문 항목 ID, 상품명, 평점, 추천 여부, 제목/본문 입력 여부를 properties에 포함

---

검증 결과

프론트엔드 타입 체크를 실행하여 정상 통과를 확인했습니다.

cd apps/web
npm run typecheck

프론트엔드 빌드를 실행하여 정상 통과를 확인했습니다.

cd apps/web
npm run build

백엔드 전체 테스트를 실행하여 정상 통과를 확인했습니다.

cd apps/api
python -m pytest ./tests -v

수동 확인 항목:

• 상품 목록 페이지 진입 이벤트 코드 추가 확인
• 상품 목록 장바구니 담기 클릭 이벤트 코드 추가 확인
• 상품 상세 페이지 진입 이벤트 코드 추가 확인
• 상품 상세 장바구니 담기 클릭 이벤트 코드 추가 확인
• 장바구니 페이지 진입 이벤트 코드 추가 확인
• 장바구니 수량 변경 클릭 이벤트 코드 추가 확인
• 장바구니 상품 제거 클릭 이벤트 코드 추가 확인
• 체크아웃 페이지 진입 이벤트 코드 추가 확인
• 쿠폰 적용 클릭 이벤트 코드 추가 확인
• 주문 생성 클릭 이벤트 코드 추가 확인
• 결제 성공 시뮬레이션 클릭 이벤트 코드 추가 확인
• 결제 실패 시뮬레이션 클릭 이벤트 코드 추가 확인
• 주문 내역 페이지 진입 이벤트 코드 추가 확인
• 쿠폰함 페이지 진입 이벤트 코드 추가 확인
• 리뷰 작성 페이지 진입 이벤트 코드 추가 확인
• 리뷰 등록 클릭 이벤트 코드 추가 확인
• 이벤트 저장 실패가 사용자 화면 흐름을 막지 않도록 처리되었는지 확인
• Frontend typecheck 통과 확인
• Frontend build 통과 확인
• Backend 테스트 통과 확인

---

브랜치 통합 방식

이번 PR의 통합 흐름은 아래와 같습니다.

feature/D2C-44-user-behavior-event-logging
→ develop

develop 병합 후에는 프론트엔드 주요 사용자 행동 이벤트 로그 발생 로직이 로그/검증 스프린트에 반영됩니다.

---

향후 브랜치 운영 원칙

로그/검증 단계에서는 아래 브랜치 운영 원칙을 유지합니다.

• Jira 이슈키별 독립 feature 브랜치 생성
• 각 feature 브랜치는 develop에서 분기
• 작업 완료 후 develop으로 개별 PR 생성
• PR 단위로 CI 검증 후 병합
• 의미 있는 사용자 흐름 단위가 완료되면 develop을 main에 병합
• main은 배포 기준 브랜치로 유지
• 기능 작업이 누적된 장기 브랜치는 지양

---

체크리스트

• D2C-44 브랜치를 develop 기준으로 분기
• 이벤트 로그 프론트엔드 타입 추가
• 이벤트 로그 API 클라이언트 추가
• 이벤트 저장 실패 시 사용자 흐름을 막지 않도록 처리
• 상품 목록 진입 이벤트 추가
• 상품 목록 장바구니 담기 클릭 이벤트 추가
• 상품 상세 진입 이벤트 추가
• 상품 상세 장바구니 담기 클릭 이벤트 추가
• 장바구니 진입 이벤트 추가
• 장바구니 수량 변경 클릭 이벤트 추가
• 장바구니 상품 제거 클릭 이벤트 추가
• 체크아웃 진입 이벤트 추가
• 쿠폰 적용 클릭 이벤트 추가
• 주문 생성 클릭 이벤트 추가
• 결제 성공 시뮬레이션 클릭 이벤트 추가
• 결제 실패 시뮬레이션 클릭 이벤트 추가
• 주문 내역 진입 이벤트 추가
• 쿠폰함 진입 이벤트 추가
• 리뷰 작성 페이지 진입 이벤트 추가
• 리뷰 등록 클릭 이벤트 추가
• Frontend typecheck 통과 확인
• Frontend build 통과 확인
• Backend 테스트 통과 확인