# 이벤트 상세 API 연동 PRD ## 문서 정보 - 상태: 구현 완료 (로컬 계약 검증 완료, 실서버 검증 제외) - 작성일: 2026-10-29 - 대상: Android 이벤트 상세 조회 - 요구사항·승인: 사용자 제공 API 계약, 후속 상세 딥링크 고려 요청, 레거시 최소 수정 승인 - 구현 계획: [plan-task.md](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 | 실서버 연결 테스트 제외 | 서버 동시 개발 중이라는 사용자 명시 지시; 로컬 계약 테스트로 검증 | ## 완료 기준 - [x] EVT-001~008 구현 및 관련 로컬 테스트 통과 - [x] 관련 회귀·전체 unit suite·debug 빌드 결과와 제약 기록 - [x] 변경 범위 리뷰 승인: [phase1-event-detail-api-review.md](reviews/phase1-event-detail-api-review.md) - [x] 임시 자원 정리 ## 후속 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 빌드로 회귀를 확인한다.