docs(event): 이벤트 딥링크 요구사항과 계획을 기록한다

This commit is contained in:
2026-10-29 15:24:56 +09:00
parent a4c69bfb36
commit 4c58d7593c
2 changed files with 370 additions and 0 deletions
@@ -0,0 +1,102 @@
# 이벤트 상세 딥링크·AppsFlyer 연동 PRD
## 문서 정보
- 상태: Phase1·Phase2 구현·로컬 검증 완료 (실서버 검증 제외)
- 작성일: 2026-10-29
- 대상: 이벤트 상세 직접 URI·푸시·AppsFlyer UDL 진입
- 결정권자: 사용자
- 관련 계획: [plan-task.md](plan-task.md)
- 이번 작업은 이벤트 상세 API 연동과 별도 작업이다. 기존 API/화면은 재사용하며 이전 작업 문서는 수정하지 않는다.
## 1. 목표
직접 URI, 기존 FCM/알림함/Notifly의 클릭 URL 및 AppsFlyer direct/deferred 콜백에서 양수 Long 이벤트 ID로 동일한 `v2.event.EventDetailActivity`를 연다. 비로그인도 이벤트 상세에 진입하고, 늦은 콜백·앱 준비 전 전달·동일 진입 중복·Activity 재생성에 대응한다.
## 2. 현재 문제
- `DeepLinkActivity`와 `MainV2Activity`의 라우터에 event-detail 분기가 없다.
- FCM notification+data의 런처 진입은 raw extras를 MainV2에 전달하지만 MainV2는 `deep_link`만 URL로 읽고 `deepLink`를 정규화하지 않는다.
- MainV2의 공통 라우팅 앞 로그인 검사로 공개 이벤트도 차단된다.
- AppsFlyer 콜백은 마케팅 값을 저장하지만 MainV2에 저장 목적지를 소비하는 연결이 없다.
- SDK는 `init → start → subscribeForDeepLink` 순서이며 공식 UDL 지침은 listener를 start 전에 등록하도록 한다.
## 3. 확정 입력 계약
| 입력 | 계약 |
|---|---|
| release 직접 URI | `voiceon://event-detail/{eventId}` |
| debug 직접 URI | `voiceon-test://event-detail/{eventId}` |
| FCM data | `deep_link`에 전체 URI; 기존 `deepLink` 별칭도 수용 |
| 알림함 | 기존 `deepLink` 필드에 같은 URI |
| Notifly | 캠페인 클릭 URL에 같은 URI; SDK 1.12.0은 ACTION_VIEW로 전달 |
| OneLink URL | 현재 빌드의 APPLINK_HOST에 대한 HTTPS URL, `deep_link_value=event-detail`, `deep_link_sub5={eventId}` |
| AppsFlyer UDL | 콜백의 `deep_link_value=event-detail`, `deep_link_sub5={eventId}` |
ID는 하나의 ASCII 십진수 문자열을 양수 Long으로 파싱한다. `1..9223372036854775807`을 보존하며 0/음수/비숫자/공백/overflow/추가 경로를 거부한다. direct path ID는 query의 다른 ID로 대체하지 않는다. 잘못된 이벤트 입력을 다른 도메인 라우팅으로 바꾸지 않는다. 서로 다른 환경 스킴이나 임의 외부 HTTPS host를 이벤트 링크로 수용하지 않는다.
`EventDetailActivity.newIntent(context, eventId: Long)`만 호출하고 Parcelable 데이터나 새 상세 API는 만들지 않는다. 상세 조회의 loading/성공/조회 불가/오류는 기존 화면 책임이다.
## 4. 기능 요구사항
| ID | 상태 | 요구사항·수용 기준 |
|---|---|---|
| EDL-001 | 확정 | 허용 URI/OneLink/UDL의 양수 Long을 동일한 상세 진입점에 연결한다. 누락·무효 입력은 상세를 열지 않는다. |
| EDL-002 | 확정 | foreground와 Splash를 거치는 cold/background, MainV2 새 Intent에서 동일 이벤트를 처리한다. FCM 두 URL key를 이벤트 경계에서 정규화한다. |
| EDL-003 | 확정 | 이벤트만 비로그인 진입 가능하다. 기존 다른 도메인 로그인/성인 가드, 자체 FCM 수신의 토큰 조건은 변경하지 않는다. |
| EDL-004 | 확정 | AppsFlyer listener를 start 전에 등록하고 기존 마케팅 PID/UTM 저장·Firebase 추적을 유지한다. |
| EDL-005 | 확정 | Activity 준비 전 또는 준비 후 늦게 도착한 UDL을 처리한다. 백그라운드에서 강제로 Activity를 띄우거나 종료된 Activity 참조를 유지하지 않는다. |
| EDL-006 | 확정 | 같은 이벤트 OneLink의 URI+UDL은 UDL만 이동을 소유하여 이중 실행하지 않는다. Intent 재생성·handoff는 단회 처리한다. 새로운 명시적 동일 이벤트 진입과 새 UDL 전달은 허용하며 영구 eventId 차단/임의 TTL은 사용하지 않는다. |
| EDL-007 | 확정 | 라이브룸의 기존 이동 확인을 거친다. 오디오 알림·gift·DM·콘텐츠·채널 등의 기존 라우팅 우선순위와 정책은 유지한다. |
| EDL-008 | 확정 | 기존 Manifest 공개 라우터를 사용하고 상세 Activity의 exported=false를 유지한다. 필요한 최소 경계만 변경한다. |
| EDL-009 | 확정 | 이벤트도 기존 Bundle 정규화·목적지 dispatcher에서 실행한다. handleEventEntry/handleEventDeepLink의 별도 선행 실행은 제거하고, AppsFlyer helper는 입력 대기·전달만 담당한다. |
## 5. 포함·제외 및 승인
- 신규 helper·상태·테스트는 `kr.co.vividnext.sodalive.v2.event` 하위에 작성한다.
- 사용자 승인: `main/DeepLinkActivity.kt`, `app/SodaLiveApp.kt`를 이벤트 연결 및 AppsFlyer 초기화 순서 보정에 한해 최소 수정한다.
- MainV2의 이벤트 연결, 필요하면 v2 이벤트 상세의 lifecycle 연결은 이번 범위다. 이벤트 API·표시 UI는 바꾸지 않는다.
- Manifest/FCM 서비스/Splash/알림함/LiveRoomActivity/공통 인증 저장소/기존 OneLink 공유 함수의 전면 수정은 하지 않는다.
- AppsFlyer SDK 업그레이드·대시보드 변경·신규 SDK/의존성·다른 도메인의 UDL 복구·기기 UI/계측 테스트는 제외한다.
- 사용자 지시대로 현재 main 브랜치에 직접 작업한다. worktree/새 브랜치/커밋/푸시는 만들지 않는다.
- 사용자 지시대로 실서버 연결 테스트와 실제 푸시 발송은 하지 않는다. 로컬 fake/fixture 및 Robolectric 라우팅 테스트만 사용한다.
## 6. 검증 시나리오
1. 정상: 직접 URI, 두 FCM URL key, OneLink query, UDL direct/deferred의 유효 ID가 기존 상세를 연다. release/debug 설정을 각각 지킨다.
2. 경계: 잘못된 ID·외부 scheme/host·경로/query 충돌·중복 alias를 거부하고 Int 범위 초과/Long.MAX_VALUE를 보존한다.
3. 비동기: 콜백 선도착·후도착, 준비 전 여러 입력, background→foreground, Activity 재생성/종료, URI/UDL 양쪽 순서, 사용자의 같은 ID 재클릭을 검증한다.
4. 인접 회귀: 비로그인 이벤트와 비이벤트 가드, 라이브룸 확인·취소, 오디오 알림·gift 단회 소비·기존 푸시 extras 및 마케팅 저장을 확인한다.
## 7. 외부 의존과 검증 한계
- AppsFlyer 대시보드의 OneLink template, SHA-256, fallback, 실제 캠페인 설정은 로컬 코드로 입증하지 않는다.
- SDK가 두 콜백에 동일한 클릭 식별자를 보장하지 않는 경우 중복 방지의 정확한 소유 범위와 한계를 구현 계획에 명시한다. 추측한 provider field를 도입하지 않는다.
- 키·토큰·서명 정보·SDK payload 전체를 로그나 문서에 기록하지 않는다.
## 8. 전달 소유권과 생명주기
- 커스텀 이벤트 URI는 Intent가 소유한다. 이벤트 OneLink URI는 앱 bootstrap만 수행하고 상세 이동은 유효한 UDL 콜백이 소유한다. SDK 실패 시 URL만으로 상세 이동하는 자동 fallback은 추가하지 않는다.
- Application 소유 event helper는 main thread에서 process-local FIFO를 관리하고 resumed Activity를 weak reference로만 참조한다. Splash·DeepLink trampoline 및 초기 라우팅이 완료되지 않은 Main에서는 대기한다.
- 콜백 도착과 Activity resume 모두 대기 전달을 확인한다. 현재 Activity가 종료/일시정지됐으면 실행하지 않는다. background에서 강제 startActivity하지 않는다.
- UDL은 현재 resumed Activity를 통해 명시적 DeepLinkActivity Intent로 넘겨 기존 라이브룸 확인을 재사용한다. 전달 후 큐에서 제거하며 사용자가 확인을 취소해도 재전달하지 않는다.
- 각 Intent 진입의 로컬 token과 전달/소비 상태를 handoff Bundle 및 savedInstanceState에 보존한다. 이는 동일 entry 재생성 방지용이지 provider 클릭 identity가 아니다.
- 새로운 SDK 콜백은 새로운 전달로 취급한다. provider가 같은 클릭을 중복 callback으로 전달한 경우와 실제 동일 ID 재클릭을 입력 필드만으로 구분할 수 없으며, 이 경우 새 클릭 보존을 우선한다. 커스텀 URI가 별도 event UDL echo까지 일으키는 비표준 발송 조합의 완전 중복 제거는 보장하지 않는다.
- 프로세스 종료 후 별도 영구 navigation queue는 복구하지 않는다. 복원된 launch Intent/saved state 또는 새 SDK callback을 사용한다. 마케팅 preference를 navigation queue로 읽지 않는다.
## Decision Log
| 날짜 | ID | 결정·근거 |
|---|---|---|
| 2026-10-29 | EDEC-001 | 별도 작업으로 PRD/계획 생성. 기존 이벤트 API 작업과 구분한다. |
| 2026-10-29 | EDEC-002 | 사용자 요청으로 AppsFlyer도 동일 이벤트 상세에 연결한다. |
| 2026-10-29 | EDEC-003 | 사용자 승인으로 DeepLinkActivity/SodaLiveApp의 최소 연결·등록 순서 변경 허용. |
| 2026-10-29 | EDEC-004 | 단일 event-detail 계약, guest 이벤트만 허용, 공통 다른 라우팅·추적은 보존한다. |
| 2026-10-29 | EDEC-005 | Oracle 설계 검토에 따라 custom URI/OneLink UDL 소유권 분리. 제공되지 않은 click ID나 시간 기반 중복 차단을 만들지 않는다. OneLink는 SDK 전달 성공에 의존한다. |
| 2026-10-29 | EDEC-006 | 사용자 요청으로 기존 공통 라우팅 확장 + AppsFlyer 입력 어댑터 방향으로 후속 리팩터링한다. Phase1의 별도 이벤트 실행 분기는 공통 dispatcher 내부 이벤트 목적지로 대체한다. EDEC-005 소유권·비동기 전달·외부 입력 계약은 유지한다. |
## 완료 기준
- [x] EDL-001~008의 로컬 테스트 및 회귀 통과
- [x] 전체 unit suite·main/test ktlint·debug 빌드 검증 및 한계 기록
- [x] 최종 리뷰 승인: [phase1-event-deeplink-appsflyer-review.md](reviews/phase1-event-deeplink-appsflyer-review.md)
- [x] 소유 임시 자원 정리
## Phase2 추가 완료 기준
- [x] DeepLinkActivity.routeForegroundDeepLink와 MainV2Activity.executeBundleRoute에서 이벤트 목적지를 처리하고, 별도 이벤트 실행 우회 함수가 없다.
- [x] 이벤트 ID/URL은 입력 정규화에서 검증하며 raw event_id·외부 URL·SDK 소유 입력이 실행 가능한 이벤트로 승격되지 않는다.
- [x] 비로그인 정책·단회 소비·새 same-ID 클릭·late UDL·기존 도메인 회귀를 보존한다.
- [x] 전체 로컬 검증·Phase2 리뷰·이번 단계 임시 자원 정리 완료.
Task2.1 로컬 증거: 기존156개 + 정규화/공통 dispatcher 신규14개 = **170개 통과**, main/test ktlint 통과. 정확한 interface·RED/GREEN·실행 명령·임시 로그 위치는 [계획 Task2.1 검증](plan-task.md)에 기록했다. 전체 suite/build/Phase2 리뷰와 최종 자원 정리는 parent Task2.2에서 수행한다.
Task2.2 최종 증거: 전체1736개 통과·lint 위반0·debug 빌드 성공. [Phase2 코드 리뷰](reviews/phase2-common-event-routing-review.md) APPROVE. 실서버와 기기 UI는 제외했으며 중간 인증 테스트 실패/worker 중단 기록과 검증 한계는 계획·리뷰에 보존한다.