tdc114plus/docs/00_guide_tdc114plus_deployment_migration_matrix_2026-07-19.md

tdc114plus 배포 구조 마이그레이션 표

작성일: 2026-07-19 상태: v1.2

목적: baron-sso-tdc114plus-api 의존을 줄이고, 최종적으로 tdc114plus + tdc114plus-auth + Baron SSO 원본 staging/prod 구조로 전환하기 위해 현재 남아 있는 기능을 배포 필수, 개발 중 임시, 제거 가능으로 분류한다.

관련 문서:

• docs/00_guide_tdc114plus_work_progress_timetable_2026-07-02.md
• docs/00_guide_tdc114plus_auth_broker_redirect_flow_2026-07-15.md
• docs/00_policy_tdc114plus_auth_repo_2026-07-15.md
• docs/00_policy_tdc114plus_decoupled_api_migration_2026-07-07.md

1. 목표 구조

최종 배포 목표 구조는 아래와 같다.

• 모바일 앱: tdc114plus
• 인증/중계 서버: tdc114plus-auth
• 인증/조직 원본: Baron SSO 원본 staging -> 안정화 후 production

제거 목표:

• 로컬 개발 전용 Baron worktree baron-sso-tdc114plus-api가 배포 시점의 필수 구성으로 남지 않도록 한다.

2. 현재 확인 기준

2026-07-19 당시 auth 서버에 실제 등록된 route는 아래와 같았다.

• GET /health
• GET /.well-known/jwks.json
• GET /api/v1/auth/jwks.json
• POST /api/v1/auth/link/init
• POST /api/v1/auth/link/poll
• GET /api/v1/integrations/org-context

같은 날짜 기준 추가 확인:

• 당시 실행 중이던 5001 서버는 /api/v1/profile-image에 404를 반환했다.
• 당시 체크아웃된 tdc114plus-auth 코드에도 /api/v1/profile-image route 등록이 없었다.
• 따라서 프로필 사진 1순위/2순위/3순위 실기기 검증은 profile-image endpoint 복구 또는 대체 경로 확정 전에는 완료 처리할 수 없다.

2026-07-20 추가 확인:

• 실기기와 로컬 tdc114plus-auth:5001 연결 자체는 정상이다.
• adb reverse tcp:5001 tcp:5001 정상 확인했다.
• 앱에서 link/init 호출 후 pendingRef 생성과 link/poll 반복도 서버 로그로 확인했다.
• 따라서 같은 날짜 기준 로그인 end-to-end 막힘의 주 blocker는 앱/로컬 auth broker 연결이 아니라 Baron SSO 문자 링크 실제 발송 또는 SMS 연계 구간이다.
• tdc114plus-auth에 GET /api/v1/profile-image route를 복구했고, 미인증 호출 기준 401 unauthorized가 반환되는 것을 확인했다. 즉 route 부재 404 상태는 해소됐다.
• 로그인 정상화 후 NAVER_WORKS와 BARON_UUID_R2 source가 서버 로그와 실기기 화면에서 확인됐다.
• 네이버웍스 원본 302 Location URL은 앱에서 직접 열 수 없는 경우가 있어, tdc114plus-auth에 GET /api/v1/profile-image/naver-photo 프록시 route를 추가했다.
• 프록시 route는 네이버웍스 Access Token으로 실제 이미지 바이너리를 받아 앱에 image/jpeg로 내려준다.

2-A. 현재 사용 API 목록

2026-07-20 기준 신규앱과 tdc114plus-auth가 실제 작업 기준으로 삼는 API는 아래와 같이 분류한다.

구분	Method	Path	호출 주체	현재 판단	용도
앱 중계 로그인 시작	POST	/api/v1/auth/link/init	tdc114plus -> tdc114plus-auth	현재 사용	앱에서 전화번호 기준 로그인 링크 요청
앱 중계 로그인 확인	POST	/api/v1/auth/link/poll	tdc114plus -> tdc114plus-auth	현재 사용	문자 링크 승인 후 앱 세션 발급 확인
앱 세션 JWKS	GET	/api/v1/auth/jwks.json	Baron/RP 검증 또는 내부 검증	현재 사용	앱 세션/JWT 검증 키 제공
조직/직원 중계	GET	/api/v1/integrations/org-context	tdc114plus -> tdc114plus-auth	현재 핵심 사용	직원검색, 조직도, members[].id UUID 확보
프로필 사진 lookup	GET	/api/v1/profile-image	tdc114plus -> tdc114plus-auth	현재 사용	NAVER WORKS -> Baron UUID R2 -> DEFAULT 판단
네이버웍스 사진 프록시	GET	/api/v1/profile-image/naver-photo	tdc114plus -> tdc114plus-auth	현재 사용	NAVER WORKS 원본 URL 직접 노출 없이 image/jpeg 제공
원본 조직/직원 API	GET	https://sadmin.hmac.kr/api/v1/integrations/org-context	tdc114plus-auth -> Baron SSO 원본	현재 핵심 원본	조직/직원 원본 데이터 조회, 앱에 key/secret 비노출
Baron 링크 로그인 시작 원본	POST	https://sso.hmac.kr/api/v1/auth/headless/link/init	tdc114plus-auth -> Baron SSO 원본	현재 사용	실제 문자 링크 생성/발송 요청
Baron 링크 로그인 확인 원본	POST	https://sso.hmac.kr/api/v1/auth/headless/link/poll	tdc114plus-auth -> Baron SSO 원본	현재 사용	pendingRef 승인 상태 확인
Baron 매직 링크 검증	POST	https://sso.hmac.kr/api/v1/auth/magic-link/verify	문자 링크/Baron SSO 원본 흐름	연동 참고	사용자가 문자 링크를 눌렀을 때 승인 처리 후보/참고 경로
NAVER WORKS 사진 조회	GET	https://www.worksapis.com/v1.0/users/{userId}/photo	tdc114plus-auth -> NAVER WORKS	현재 사용	프로필 사진 1순위 조회, 302 Location 및 프록시 바이너리 응답 기반

현재 기준에서 직접 사용하지 않는 API는 아래처럼 둔다.

구분	Method	Path	현재 판단	이유
공개 조직도	GET	/api/v1/public/orgchart	참고 API	공유 링크/공개 조회 성격이므로 신규앱 내부 기준 데이터는 integrations/org-context로 유지
레거시 직원목록	GET	/api/v1/tdc114plus/directory/employees	제거 대상	org-context 기반 재구성으로 대체
레거시 직원상세	GET	/api/v1/tdc114plus/directory/employees/{employeeId}	제거 대상	org-context members[] 또는 auth proxy 보강으로 대체
레거시 테넌트 목록	GET	/api/v1/tdc114plus/organization/tenants	제거 대상	org-context tenants/tree 기준으로 대체
레거시 조직도	GET	/api/v1/tdc114plus/organization/orgchart	제거 대상	org-context tree 기준으로 대체
레거시 전화번호 로그인	POST	/api/v1/tdc114plus/auth/phone-login	제거 대상	현재 기본 로그인은 tdc114plus-auth link/init/link/poll 중계 흐름

3. 기능 분류표

기능/자산	현재 위치	현재 용도	분류	목표 방향	비고
앱 UI/상태관리	tdc114plus	모바일 앱 본체	배포 필수	유지	최종 배포 직접 대상
링크 로그인 진입 link/init	tdc114plus-auth	앱 로그인 시작	배포 필수	유지	Baron SSO headless/link upstream 호출
링크 로그인 완료 link/poll	tdc114plus-auth	앱 세션 발급	배포 필수	유지	2026-07-19 기준 user 메타데이터 확장 반영 완료
앱 세션 JWT 발급/검증	tdc114plus-auth	앱 인증 유지	배포 필수	유지	앱 전용 세션 계층
JWKS 제공	tdc114plus-auth	Baron RP/JWKS 연계	배포 필수	유지	도메인 기준 배포 필요
org-context proxy	tdc114plus-auth	앱이 Baron key 없이 조직도 조회	배포 필수	유지	staging/prod 원본 의존
Baron OIDC authorization / token / consent 흐름	Baron SSO 원본	인증 원본	배포 필수	Baron 원본 의존	로컬 worktree 필수 아님
Baron headless link/init, link/poll	Baron SSO 원본	문자 링크 승인 원본	배포 필수	Baron 원본 의존	auth 서버가 소비
GET /api/v1/integrations/org-context 원본	Baron SSO 원본	조직/직원 원본 데이터	배포 필수	Baron 원본 의존	앱은 auth proxy 또는 직접 staging 기준 확인
/api/v1/tdc114plus/directory/employees	baron-sso-tdc114plus-api	과거 직원검색 경로	제거 가능	org-context 중심으로 교체	레거시 흔적
/api/v1/tdc114plus/organization/tenants	baron-sso-tdc114plus-api	과거 테넌트 목록 경로	제거 가능	org-context 중심으로 교체	레거시 흔적
/api/v1/tdc114plus/organization/orgchart	baron-sso-tdc114plus-api	과거 조직도 경로	제거 가능	org-context 중심으로 교체	레거시 흔적
/api/v1/tdc114plus/auth/phone-login	baron-sso-tdc114plus-api	과거 예외 로그인 seed	제거 가능	기본 로그인 경로에서 제외	테스트용 예외 경로만 검토
로컬 Baron compose runtime	baron-sso-tdc114plus-api	로컬 재현/비교	개발 중 임시	staging/prod 기준 검증으로 축소	배포 필수 구성 아님
프로필 사진 /api/v1/profile-image	tdc114plus-auth	NAVER WORKS -> UUID -> DEFAULT	배포 필수	auth 서버에 유지	2026-07-20 route 복구 및 실기기 확인
네이버웍스 사진 프록시 /api/v1/profile-image/naver-photo	tdc114plus-auth	NAVER WORKS 이미지 바이너리 프록시	배포 필수	auth 서버에 유지	원본 Location 직접 노출 방지
PostgreSQL 기반 프로필 매핑안	tdc114plus-auth 과거 검토	사진 fallback 대안	제거 가능	운영 기본안에서 제외	보류 대안

3-A. baron-sso-tdc114plus-api -> tdc114plus-auth 흡수 가능 기능 표

기능	현재 기준	tdc114plus-auth 흡수 가능 여부	이유	현재 상태
앱 로그인 시작/완료	이미 tdc114plus-auth 담당	완료	앱 전용 broker 책임과 일치	유지
앱 세션 JWT 발급/검증	이미 tdc114plus-auth 담당	완료	모바일 세션 경계는 auth 서버 책임	유지
로그인 user 메타데이터 반환	tdc114plus-auth 담당	완료	앱이 초기 컨텍스트에 바로 사용 가능	2026-07-19 확장 반영
Baron org-context key 은닉 proxy	이미 tdc114plus-auth 담당	완료	앱에 key/secret 비노출	유지
직원/조직 초기 컨텍스트 계산 보조	일부 앱 fallback 혼재	가능	auth 응답 메타데이터가 충분하면 앱 fallback 감소	후속 검증 필요
프로필 사진 lookup endpoint	tdc114plus-auth	완료	사진 우선순위 정책은 auth 서버가 가장 자연스러움	2026-07-20 route 복구 및 실기기 확인
네이버웍스 사진 프록시 endpoint	tdc114plus-auth	완료	네이버웍스 원본 URL을 앱이 직접 열 수 없는 케이스를 서버가 흡수	배포 필수 기능으로 유지
/api/v1/tdc114plus/directory/* 레거시 API	baron-sso-tdc114plus-api	불필요	org-context 중심 구조와 중복	제거 대상
/api/v1/tdc114plus/organization/* 레거시 API	baron-sso-tdc114plus-api	불필요	org-context 중심 구조와 중복	제거 대상
로컬 Baron compose runtime	baron-sso-tdc114plus-api	흡수 대상 아님	개발용 재현 자산이지 auth 기능이 아님	축소 대상
Baron 원본 로그인/consent/token 발급	Baron SSO 원본	흡수 불가	공식 인증 원본이므로 대체 대상 아님	staging/prod 의존 유지

3-B. 제거 마이그레이션 실행 표

아래 표는 baron-sso-tdc114plus-api에 남아 있는 흔적을 실제 작업 단위로 쪼갠 것이다.

구분	현재 남은 흔적	실제 사용 주체	목표 처리	선행 조건	최종 판단
로그인 진입	/api/v1/tdc114plus/auth/phone-login	앱 구버전/초기 테스트 흔적	신규앱 경로에서 제거	현재 앱이 link/init, link/poll만 쓰는지 재확인	제거 가능
직원검색 목록	/api/v1/tdc114plus/directory/employees	앱 일부 코드/테스트 흔적	org-context 재구성 결과로 완전 대체	목록/검색/상세가 org-context 기준으로 동일 동작	제거 가능
직원 상세	/api/v1/tdc114plus/directory/employees/:id	앱 일부 코드 흔적	org-context members[] 기반 또는 auth proxy 보강으로 대체	현재 상세 화면 필요 필드 표 확정	제거 가능
회사/테넌트 목록	/api/v1/tdc114plus/organization/tenants	앱 일부 코드/테스트 흔적	org-context tenants[]로 대체	현재 tenant chip/초기 선택 로직 안정화	제거 가능
조직도 트리	/api/v1/tdc114plus/organization/orgchart	앱 일부 코드/테스트 흔적	org-context tree + tenants[]로 대체	조직도 화면 회귀 검증	제거 가능
조직도 credential 은닉	Baron 전용 key/secret 직접 처리 필요성	신규앱	tdc114plus-auth /api/v1/integrations/org-context 유지	app session + proxy 정상 유지	auth에 유지
앱 세션 발급	Baron 원본에 없는 앱 전용 세션 계층	신규앱	tdc114plus-auth 유지	현재 JWT 검증 안정화	auth에 유지
프로필 이미지 lookup	/api/v1/profile-image auth 구현	신규앱	auth에 유지	1순위/2순위 실기기 확인 완료, DEFAULT 확대 검증	auth에 유지
로컬 Baron runtime	worktree 기동/비교 환경	개발자 로컬	배포 필수 구성에서 제외	staging/prod 기준 검증 루틴 확보	개발 전용 유지

3-C. 워크스페이스별 최종 역할 표

워크스페이스	오늘 기준 역할	배포 직접 관여	비고
tdc114plus	모바일 앱 UI, 상태관리, 사진 fallback, 직원검색/조직도 화면	예	최종 APK/앱 배포 대상
tdc114plus-auth	앱 전용 인증 broker, 앱 세션 JWT, org-context proxy, profile-image lookup/proxy	예	신규앱 전용 중계서버
baron-sso-tdc114plus-api	과거 레거시 API 검증, 로컬 비교, 흔적 확인용 worktree	아니오	제거/축소 대상
Baron SSO staging/prod 원본	실제 OIDC, 문자 링크, org-context 원본	예	신규앱의 최종 외부 의존 원본

4. 바로 이어서 손봐야 하는 항목

4.1 tdc114plus-auth에서 유지하되 보강이 필요한 것

1. link/poll 응답의 사용자 메타데이터 확장

   • 2026-07-19 기준 아래 항목을 응답과 앱 세션 JWT user 클레임에 함께 담도록 반영했다.
     • tenantSlug
     • tenantId
     • tenantName
     • department
     • grade
     • position
     • jobTitle
   • 남은 확인:
     • 실기기 로그인 후 앱에서 이 값들이 실제로 저장/사용되는지 확인
     • 실제 Baron upstream 응답마다 중첩 구조 차이가 없는지 샘플 확대 확인

2. /api/v1/profile-image route 상태 재정렬

   • 2026-07-20 기준 tdc114plus-auth에 route를 복구했다.
   • 미인증 호출 기준 401 unauthorized가 반환되어 route 등록은 확인했다.
   • 네이버웍스 302 Location 원본 URL 직접 사용 시 400 Authentication failed가 발생할 수 있어 /api/v1/profile-image/naver-photo 프록시를 추가했다.
   • 2026-07-20 기준 NAVER WORKS 1순위와 Baron UUID R2 2순위는 실기기 화면 및 서버 로그로 확인했다.
   • 남은 확인은 DEFAULT 3순위와 직원 상세/조직도/즐겨찾기 화면 확대 검증이다.

3. OIDC callback 실서버 기준 정합성 유지

   • 현재 문서 기준 redirect URI는 https://114-auth.hmac.kr/api/v1/auth/oidc/callback
   • 실제 배포 기준 도메인/프록시와 일치하게 유지해야 한다.

4.2 baron-sso-tdc114plus-api에서 빼야 하는 것

1. /api/v1/tdc114plus/... 전용 경로에 대한 앱 직접 의존
2. 로컬 Baron compose가 항상 떠 있어야만 앱이 개발되는 구조
3. 사진 fallback용 PostgreSQL 기본안

5. 마이그레이션 순서 제안

1. tdc114plus-auth link/poll 사용자 메타데이터 확장을 먼저 반영한다. 완료.
2. 실기기 로그인 후 저장된 user/session에서 tenantSlug 등 메타데이터가 실제로 유지되는지 확인한다. 진행 예정.
3. Baron SSO 문자 링크 실제 발송/SMS 연계 이슈 답변을 먼저 받는다. 진행 중.
4. /api/v1/profile-image를 현재 auth 코드 기준으로 복구한다. 완료.
5. 앱 코드에서 남아 있는 /api/v1/tdc114plus/... 직접 의존을 다시 표로 수집한다. 진행 예정.
6. 조직/직원 데이터는 org-context 기준으로만 유지되도록 경계를 정리한다. 진행 예정.
7. 로컬 Baron worktree 없이도 staging 기준 로그인 + 직원검색 + 조직도 + 사진 fallback이 되는지 검증한다. 진행 예정.
8. 그 다음에 production 승격 체크리스트를 만든다. 진행 예정.

6. 현재 판단

2026-07-20 기준 현재 가장 중요한 사실은 아래 두 가지다.

1. baron-sso-tdc114plus-api는 이미 최종 배포 직접 대상이라기보다 개발 중 임시 worktree로 보는 것이 맞다.
2. profile-image는 tdc114plus-auth에 유지할 배포 필수 기능으로 정리한다. 네이버웍스 원본 URL 직접 노출 문제는 auth 프록시로 처리한다.

따라서 다음 실제 작업은 아래 순서가 가장 안전하다.

1. DEFAULT 기본 아바타와 직원 상세/조직도/즐겨찾기 이미지 규칙 확대 검증
2. auth 응답 메타데이터 실기기 반영 유지 확인
3. 실기기 기능 재검증
4. 레거시 경로 제거