# 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. 레거시 경로 제거