Files

7.5 KiB

이벤트 상세 API 연동 PRD

문서 정보

  • 상태: 구현 완료 (로컬 계약 검증 완료, 실서버 검증 제외)
  • 작성일: 2026-10-29
  • 대상: Android 이벤트 상세 조회
  • 요구사항·승인: 사용자 제공 API 계약, 후속 상세 딥링크 고려 요청, 레거시 최소 수정 승인
  • 구현 계획: plan-task.md
  • API 계약: 이 문서의 API 계약 절을 기준으로 한다.

목표와 범위

이벤트 상세는 목록/배너의 오래된 Parcelable 내용을 표시하지 않고, 양수 Long 이벤트 ID로 서버의 최신 상세와 조회 가능 여부를 확인한다. 후속 딥링크도 같은 ID 전용 상세 진입점을 사용할 수 있어야 한다.

  • 신규 상세 Activity, ViewModel, API, Repository 및 연결 코드는 kr.co.vividnext.sodalive.v2.event에 둔다.
  • 기존 settings.event.EventDetailActivity는 Parcelable에서 ID를 추출해 신규 상세로 전달하고 종료하는 연결부로만 변경한다.
  • 기존 목록·배너·팝업 호출부와 EventItem은 유지한다. Parcelable과 별도 ID를 중복 전달하지 않는다.
  • 공통 DI 등록과 신규 Activity manifest 등록만 추가하며 공통 네트워크/인증 동작은 변경하지 않는다.
  • 상세 화면의 기존 레이아웃과 이미지+참여 버튼 정책을 재사용한다. 상세 이미지가 null인 정상 응답도 처리한다.

제외

  • 딥링크 URL 형식·파서·intent-filter 등록은 후속 작업이다.
  • 목록 API 전환, 목록의 링크 직접 이동 정책 변경, 배너/팝업 라우팅 일괄 전환, 레거시 공통 계층 리팩터링은 하지 않는다.
  • 신규 의존성, 화면 재디자인, 실제 운영 데이터 변경, 기기·에뮬레이터 UI/계측 테스트는 포함하지 않는다.
  • 서버 동시 개발 중이므로 구현 완료 후에도 실서버 연결 테스트를 수행하지 않는다. 제공 계약 기반 로컬 fake/fixture와 Retrofit 요청·역직렬화 검증으로 한정한다(사용자 명시 지시).

API 계약

GET {API_BASE_URL}/api/v2/events/{id}. id는 필수 양수 64비트 정수. body와 query 없음. 비로그인 시 Authorization 없음, 로그인 시 Bearer {accessToken}. 공통 Retrofit/OkHttp/언어 헤더/TokenAuthenticator를 유지한다.

성공: HTTP 200, ApiResponse envelope의 success=true와 유효한 단일 data 객체를 함께 확인한다.

필드 계약
id 정수 Long; 요청 ID와 일치
thumbnailImageUrl 문자열 필수
detailImageUrl 문자열 또는 null
popupImageUrl 문자열 또는 null
link 문자열 또는 null

제목·본문·기간·언어·성인/팝업 여부를 추정하거나 추가하지 않는다. 이미지 URL은 원문 그대로 사용한다.

조회 불가: HTTP 200, success=false, data=null, message="잘못된 요청입니다.", errorProperty=null. 미존재/비활성/기간/조건 불일치, 잘못된 ID는 동일 계약이다. 문자열 메시지나 404로 오류 종류를 분기하지 않는다. 클라이언트 ID 진입은 Long으로 한정하고 누락/0/음수는 요청 없이 종료한다. 비숫자·범위 초과 문자열 ID 파싱은 후속 딥링크의 경계 책임이다.

네트워크·인증·비정상 HTTP 오류는 공통 클라이언트 처리를 유지하고 Rx error 경로로 처리한다. 임의의 오류 JSON envelope를 파싱하지 않는다.

기능 요구사항과 수용 기준

ID 요구사항 수용 기준
EVT-001 ID 전용 상세 진입과 기존 Parcelable 호환 newIntent(context, eventId: Long)로 단독 진입; 레거시 연결부는 ID만 전달하고 종료
EVT-002 정확한 GET 및 선택적 인증 Long.MAX_VALUE 및 Int 범위 초과 ID 보존; body/query 없음; 비로그인 헤더 생략
EVT-003 서버 응답만 표시 stale Parcelable 이미지는 표시하지 않음; 유효한 success/data만 Content
EVT-004 상태 분리 Loading, Content, Unavailable, Error 구분; success=false/잘못된 ID는 이전 화면 복귀
EVT-005 비정상 데이터·전송 오류 null data/누락 필수 데이터/요청과 다른 ID는 성공 아님; 네트워크/HTTP 오류는 조회 불가와 구분하고 공통 오류 안내·재시도
EVT-006 이미지·링크 정책 이미지와 링크가 함께 있으면 이미지+참여 버튼; 링크만 있어도 정상 화면의 참여 동작 제공; 자동 외부 이동하지 않음
EVT-007 안전한 링크 기존 배너의 http/https 및 앱 내부 scheme 정책 적용; 잘못된 URL·미지원 scheme·실행할 앱 없음은 충돌 없이 공통 오류 안내
EVT-008 lifecycle 화면 재생성 시 중복 최초 요청 방지; 종료 시 구독·로딩/오류 표시 정리

보안

API 응답, Intent ID, 서버 제공 링크를 입력 경계로 본다. 임의 scheme 실행, 토큰/BuildConfig/내부 예외의 UI·로그 노출을 추가하지 않는다. 기존 인증자와 오류 흐름을 우회하는 별도 HTTP 클라이언트를 만들지 않는다.

검증 시나리오

  1. 정상: 실제 Retrofit 직렬화/요청 경계와 ViewModel을 통해 정확한 ID·선택적 헤더·단일 객체를 검증하고 URL 원문 및 이미지+링크 표시 결정을 확인한다.
  2. 경계: success=false, null/무효 data, 잘못된 진입 ID, nullable 이미지, 링크만/미지원 링크 응답, 요청 중 재시도/재생성을 검증한다.
  3. 회귀: 기존 홈·콘텐츠 배너의 Parcelable Intent 계약 및 레거시 연결부의 ID 추출/종료, 공통 HTTP 오류 전달을 확인한다.

자동 검증은 app/src/test의 로직/local unit test로 수행한다. 레이아웃 크기·간격·visibility 속성 자체를 테스트하지 않는다. 실서비스 조회와 실제 기기 UI 확인을 수행하지 못한 경우 검증 한계를 명시한다.

Decision Log

날짜 ID 결정 근거
2026-10-29 DEC-001 ID-only v2 상세 + 기존 Parcelable의 ID 추출 연결부 후속 딥링크는 목록 데이터 없이 진입; 기존 6개 호출 경로 일괄 수정 방지
2026-10-29 DEC-002 레거시 상세 최소 연결 수정 허용 사용자 명시 승인: 레거시 최소 수정 승인
2026-10-29 DEC-003 상세에서는 link-only도 참여 버튼, 자동 외부 이동 없음 기존 상세 화면 정책 보존; 목록의 직접 외부 이동은 별도 기존 동작
2026-10-29 DEC-004 현재 main 브랜치에서 직접 작업, worktree 생성 없음 사용자 명시 지시
2026-10-29 DEC-005 실서버 연결 테스트 제외 서버 동시 개발 중이라는 사용자 명시 지시; 로컬 계약 테스트로 검증

완료 기준

  • EVT-001~008 구현 및 관련 로컬 테스트 통과
  • 관련 회귀·전체 unit suite·debug 빌드 결과와 제약 기록
  • 변경 범위 리뷰 승인: phase1-event-detail-api-review.md
  • 임시 자원 정리

후속 UI 변경 — 2026-10-30

  • EVT-009 (확정): 이벤트 상세의 이벤트 참여하기 TextView 배경색을 @color/soda_400으로 변경한다. 기존 drawable의 10dp round corner, 문구, 크기, 클릭·표시 정책은 유지한다.
  • v2 EventDetailActivity.setupView()에서 해당 TextView의 배경 tint만 지정한다. 레거시 XML과 공용 drawable은 변경하지 않는다.
  • API·라우팅·의존성 변경과 기기 UI·스크린샷 검증은 제외한다. 기존 이벤트 상세 navigation local unit test와 debug 빌드로 회귀를 확인한다.