[D2C-43] 이벤트 로그 저장 방식 구현

[jjunier]

개요

본 PR은 D2C-43 이벤트 로그 저장 방식 구현 결과를 develop 브랜치에 반영하기 위한 PR입니다.

D2C-43에서는 사용자 행동 이벤트와 백엔드 도메인 이벤트를 저장하기 위한 공통 이벤트 로그 저장 기반을 구현했습니다.

본 PR에서는 event_logs 테이블, 이벤트 로그 요청/응답 스키마, 공통 이벤트 저장 서비스, POST /events API, 이벤트 로그 API 테스트를 추가하여 이후 로그/검증 단계에서 사용할 이벤트 원천 저장 구조를 마련합니다.

---

포함 범위

이벤트 로그 DB 스키마

• event_logs 테이블 추가
• 신규 DB 생성을 위한 schema.sql 반영
• 기존 DB 변경 적용을 위한 migration 파일 추가
• 이벤트명 기준 조회 인덱스 추가
• 이벤트 타입 기준 조회 인덱스 추가
• 사용자 ID 기준 조회 인덱스 추가
• 세션 ID 기준 조회 인덱스 추가
• 엔티티 타입/ID 기준 조회 인덱스 추가
• 이벤트 발생 시각 기준 조회 인덱스 추가
• properties 컬럼을 JSONB 타입으로 구성
• 이벤트 로그 저장 시각과 생성 시각 컬럼 구성

기존 스키마 보완

• orders 테이블 쿠폰 인덱스 컬럼명 오류 수정
• 존재하지 않는 applied_coupon_id 참조 제거
• 실제 컬럼인 coupon_id 기준으로 인덱스 수정

이벤트 로그 스키마

• 이벤트 로그 생성 요청 스키마 추가
• 이벤트 로그 생성 응답 스키마 추가
• 이벤트명 필드 정의
• 이벤트 타입 필드 정의
• 사용자 ID nullable 처리
• 세션 ID nullable 처리
• 엔티티 타입 nullable 처리
• 엔티티 ID nullable 처리
• 이벤트 source 필드 정의
• 이벤트 properties 필드 정의
• 응답에 이벤트 ID, 발생 시각, 생성 시각, 메시지 포함

이벤트 로그 저장 서비스

• 공통 이벤트 기록 함수 추가
• API 요청 기반 이벤트 생성 함수 추가
• 허용 가능한 이벤트 타입 검증 추가
• 허용 가능한 이벤트 source 검증 추가
• 지원하지 않는 이벤트 타입에 대한 예외 처리
• 지원하지 않는 이벤트 source에 대한 예외 처리
• 프론트엔드 사용자 행동 이벤트와 백엔드 도메인 이벤트에서 재사용 가능한 저장 구조 구성

이벤트 로그 API

• POST /events API 추가
• 프론트엔드에서 사용자 행동 이벤트를 저장할 수 있는 API 진입점 추가
• 정상 이벤트 저장 시 201 Created 반환
• 이벤트 저장 성공 메시지 반환
• 이벤트 타입 검증 실패 시 400 Bad Request 반환
• 이벤트 source 검증 실패 시 400 Bad Request 반환

라우터 등록

• 이벤트 로그 라우터 추가
• FastAPI main app에 events router 등록
• /events 엔드포인트 접근 가능하도록 구성

테스트 추가

• 이벤트 로그 API 테스트 파일 추가
• POST /events 정상 요청 시 201 Created 반환 검증
• 이벤트 로그 응답 필드 검증
• 지원하지 않는 event_type 요청 시 400 Bad Request 반환 검증
• 지원하지 않는 source 요청 시 400 Bad Request 반환 검증

---

검증 결과

백엔드 이벤트 로그 API 테스트를 실행하여 정상 통과를 확인했습니다.

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

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

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

수동 확인 항목:

• POST /events 요청 시 이벤트 로그 저장 확인
• 정상 요청 시 201 Created 응답 확인
• 응답에 event_id 포함 여부 확인
• 응답에 occurred_at 포함 여부 확인
• 응답에 created_at 포함 여부 확인
• 응답에 Event log recorded successfully 메시지 포함 여부 확인
• 지원하지 않는 event_type 요청 시 400 Bad Request 반환 확인
• 지원하지 않는 source 요청 시 400 Bad Request 반환 확인
• 기존 로컬 DB에 migration 적용 후 event_logs 테이블 생성 확인
• PowerShell 환경에서 migration 적용 명령 정상 동작 확인
• event_logs의 UTC 기준 timestamp 저장 정책 확인

---

브랜치 통합 방식

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

feature/D2C-43-event-log-storage
→ develop

develop 병합 후에는 이벤트 로그 저장 기반이 로그/검증 스프린트에 반영됩니다.

---

향후 브랜치 운영 원칙

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

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

---

체크리스트

• D2C-43 브랜치를 develop 기준으로 분기
• event_logs 테이블 추가
• 이벤트 로그 인덱스 추가
• 신규 DB 생성용 schema.sql 반영
• 기존 DB 적용용 migration 파일 추가
• orders 쿠폰 인덱스 컬럼명 오류 수정
• 이벤트 로그 요청 스키마 추가
• 이벤트 로그 응답 스키마 추가
• 공통 이벤트 저장 서비스 추가
• 허용 이벤트 타입 검증 추가
• 허용 이벤트 source 검증 추가
• POST /events API 추가
• 이벤트 로그 라우터 등록
• 이벤트 로그 API 테스트 추가
• POST /events 정상 요청 테스트 통과 확인
• unsupported event_type 테스트 통과 확인
• unsupported source 테스트 통과 확인
• Backend 이벤트 로그 API 테스트 통과 확인
• Backend 전체 테스트 통과 확인