본문으로 건너뛰기

공통 인증 도메인 재편 및 Kakao 로그인 단계별 구현 전략

문서 목적과 범위​

  • 공통 인증 도메인으로의 구조 재편과 Kakao 로그인(KR 전용) 도입을 순차적으로 진행하기 위한 실행 계획을 제시한다.
  • 각 단계는 의존성이 낮은 순서로 정렬되어 있으며, 완료 기준, 테스트 범위, 백로그 반영 포인트를 명확히 한다.

단계 개요​

  1. 문서 및 메타데이터 재배치
  2. NX 라이브러리 스캐폴딩 및 태그 제약 설정
  3. 공통 인증 서비스 리팩터링
  4. EU/DE 공급자 마이그레이션
  5. Kakao 공급자 구현 및 KR 앱 연동
  6. 테스트/문서 보완 및 롤아웃 준비

1단계: 문서 및 메타데이터 재배치​

  • 작업 내용
    • apps/dta-wi-doc/docs/domains/common/core-domains/auth 핵심 내용을 domains/common/core-domains/auth 경로로 승격한다.
  • 공통/지역 확장 섹션을 나누고, 신규 문서(index.md, ../../common/core-domains/auth/index.md, ../../kr/core-domains/auth/overview.md, architecture.md, implementation-plan.md)에 내비게이션 링크를 설정한다.
    • 백로그 툴에서 문서 재배치 작업 태스크를 등록하고 링크 업데이트 이력을 남긴다.
  • 완료 조건
    • 모든 공통 규칙 문서가 common/ 경로에 존재하고, DE 경로에는 지역 특화 내용만 남는다.
    • 문서 내 상대 링크가 깨지지 않으며, Backlog 태스크에 문서 이동이 기록된다.
  • 테스트/검증
    • backlog search "auth"로 문서 링크가 최신 경로를 사용함을 확인한다.
    • Spell/Markdown lint(yarn lint:docs 존재 시) 실행.

2단계: NX 라이브러리 스캐폴딩 및 태그 제약 설정​

  • 작업 내용
    • 기존 라이브러리 정리
      • libs/feature/auth에 공통 서비스/레지스트리를 배치하고, 필요 시 하위 모듈로 공급자를 분리한다.
      • libs/shared/contracts-auth를 확장해 Kakao/TIME 이벤트 DTO를 추가한다.
      • libs/feature/auth-wir는 레거시 시스템과의 일시적 통합 용도이므로 이번 구조 재편 범위에서 제외한다.
    • 신규 라이브러리 생성이 필요한 경우에만 다음 명령을 사용한다.
      • 공통 인프라: nx g @nx/nest:lib --name=core-auth --directory=libs/core/auth --importPath=@core/auth --tags=scope:core,domain:auth
      • KR 공급자: nx g @nx/nest:lib --name=feature-auth-kr --directory=libs/feature/auth-kr --importPath=@feature/auth-kr --tags=scope:feature,domain:auth,region:kr
      • EU 공급자(선택): nx g @nx/nest:lib --name=feature-auth-eu --directory=libs/feature/auth-eu --importPath=@feature/auth-eu --tags=scope:feature,domain:auth,region:eu
      • HTTP 어댑터 등 인프라 유틸: nx g @nx/js:lib --name=core-http-kakao --directory=libs/core/http-kakao --importPath=@core/http-kakao --tags=scope:core,type:http
    • nx.json 또는 tsconfig.base.json의 depConstraints를 업데이트해 지역 태그가 교차 의존하지 않도록 설정한다.
    • project.json에 lint/test executor를 추가하고 기본 스켈레톤 테스트를 생성한다.
  • 완료 조건
    • 새 라이브러리가 생성되고 빌드/테스트 명령(nx test <project>)이 통과한다.
    • 태그 제약 위반 여부를 nx graph --focus=@dta/feature-auth/providers-kr나 nx lint로 확인한다.
  • 테스트/검증
    • yarn nx:graph 또는 nx show project로 의존성 구조를 점검한다.
    • CI 파이프라인(json) 업데이트 후 yarn test:all 사전 실행.

3단계: 공통 인증 서비스 리팩터링​

  • 작업 내용
    • 기존 AuthService/AuthModule 구현을 libs/feature/auth로 이동하고, AuthProviderRegistry, AuthProvider 인터페이스, 이벤트 발행 규칙을 정의한다.
    • TimeMachine, Redis, 이벤트 버스 등 인프라 의존을 libs/core-auth에서 주입하도록 정리한다.
    • 공통 DTO·도메인 이벤트를 libs/shared/auth로 추출하고, API 호출 계층과 상호작용하는 계약을 명시한다.
    • 익명/게스트 토큰 발급 엔드포인트를 appToken 인증 흐름과 통합하고, 기본 클레임(tier=anonymous, allowed_domains=["faq","docs-public","agent-help-public"], data_persistence=none)을 강제한다. 토큰 누락 시 anonymous로 폴백하는 정책을 문서/테스트에 반영한다.
  • 완료 조건
    • 공통 인증 테스트(libs/feature/auth/__tests__)가 통과하며, 기존 앱 빌드가 깨지지 않는다.
    • TimeMachine 주입과 도메인 예외 사용이 정책과 일치한다.
  • 테스트/검증
    • yarn test:features 중 인증 관련 스펙이 통과.
    • 주요 API 시나리오에 대한 회귀 테스트(통합 스펙)가 성공.

4단계: EU/DE 공급자 마이그레이션​

  • 작업 내용
    • 현행 de/EU OAuth 또는 SSO 공급자를 libs/feature/auth-eu 모듈의 공급자(PasswordAuthProvider, EuAuthProvider)로 이전하고, AuthProvider 계약 구현체로 변환한다.
    • 공급자 등록을 AuthProviderRegistry에 연결하고, DE 앱 모듈에서 EU 공급자 모듈만 임포트하도록 조정한다.
    • 지역별 설정 값(.env, config service)을 정리하여 프로바이더 모듈에서 주입받도록 리팩터링한다.
  • 완료 조건
    • DE 빌드(yarn build:dta-wide-api)가 성공하고, 인증 흐름 회귀 테스트가 통과한다.
  • EU 공급자가 공통 인터페이스를 준수하며, 문서(domains/common/core-domains/auth/index.md)에 반영된다.
  • 테스트/검증
    • DE용 e2e 또는 계약 테스트를 실행.
    • Feature flag/환경 변수 미설정 시 graceful fallback 검증.

5단계: Kakao 공급자 구현 및 KR 앱 연동​

  • 작업 내용
    • libs/feature/auth-kr 모듈에 Kakao OAuth 공급자(KakaoAuthProvider)와 도메인 예외, 리더기를 구현한다.
    • libs/core/http-kakao의 KakaoOAuthHttpClient를 작성해 토큰 교환·프로필 조회 HTTP 호출을 캡슐화한다.
    • Redis 기반 idempotency 키, TimeMachine 기반 토큰 만료 계산, 이벤트 발행 로직을 포함한다.
    • KR 앱(apps/dta-wir-api-universal의 KR 설정)에서 공급자 모듈을 주입하고, feature flag/국가별 라우팅을 설정한다.
  • 사용자 연결 플로우 및 UI 계약을 문서(domains/kr/core-domains/auth/endpoints.md)에 상세화한다.
  • 환경 변수(AUTH_OAUTH_KAKAO_*)를 @feature/config 내 authKakaoConfig 네임스페이스로 정의하고, 각 앱 manifest(app-config.manifest.ts)에서 필요한 경우에만 opt-in한다. 샘플 .env/Cloud Run secret JSON에도 동일 키를 추가한다.
  • 완료 조건
    • Kakao 통합 단위/통합 테스트가 추가되고 yarn test:features, 필요 시 yarn test:all이 통과한다.
    • API 통합 문서에 Kakao 엔드포인트, 오류 코드, 재시도 전략이 기록된다.
  • 테스트/검증
    • TimeMachine 스텁으로 토큰 만료/갱신 시나리오 검증.
    • 이벤트 중복 방지 기능에 대한 통합 테스트 작성.
    • 샌드박스 Kakao API 모킹(HTTP 클라이언트 목)으로 회귀 검증.

6단계: 테스트/문서 보완 및 롤아웃 준비​

  • 작업 내용
    • 전체 테스트 번들(yarn test:all, yarn build:dta-wir-api-universal)을 실행하고, CI 파이프라인에 신규 라이브러리 테스트를 연결한다.
    • 문서 최종 정리: 공통/지역 확장 문서, 릴리스 노트, 사건 대응 가이드 업데이트.
    • 백로그 태스크별 구현 노트와 PR 템플릿 초안을 작성한다.
  • 완료 조건
    • 모든 Acceptance Criteria 체크, Backlog 태스크 상태 Done.
    • 카카오 기능에 대한 롤아웃 체크리스트(모니터링, feature flag 전략, 롤백 플랜)가 정의된다.
  • 테스트/검증
    • 스테이징 환경에서 Kakao 플로우 스모크 테스트.
    • 모니터링/알림 설정이 구성되었는지 검토.

리스크 및 완화 전략​

  • 태그 제약 누락: NX lint 파이프라인에 dep constraint 검사를 강제하고, 코드 리뷰 체크리스트에 포함한다.
  • TimeMachine 적용 누락: 공급자 테스트에서 TimeMachine 스텁 사용을 필수화하고, 예외 발생 시 린트 규칙 또는 커스텀 스키마 검증을 도입한다.
  • 외부 API 변경: Kakao SDK/REST 버전에 대한 추상화 레이어를 두고, 재시도 및 장애 감지를 Circuit Breaker 패턴으로 준비한다.
  • 문서 싱크 불일치: Backlog 연동 커맨드를 활용해 문서 업데이트와 태스크 로그를 동시에 남긴다.

백로그 반영 가이드​

  • 주요 단계마다 별도 태스크를 생성하고, Implementation Plan과 Notes를 업데이트한다.
  • 작업 시작 시 태스크를 In Progress로 전환하고, 단계가 끝날 때마다 수용 기준을 체크한다.
  • 릴리스 전에는 yarn clean-build, 필요 시 yarn nx:reset을 실행해 캐시 영향을 제거한다.