# tdc114plus 외부 API 사용 및 앱 내 활용 정리

작성일: 2026-07-03
최종 개정일: 2026-07-20
상태: v3.4

목적: `tdc114plus` 앱이 Baron SSO가 이미 제공하는 API를 어떤 원칙으로 직접 소비해야 하는지, 그리고 어떤 인증값이 앱에 들어가면 안 되는지 정리한다.

상위 기준 문서:

- `docs/00_policy_tdc114plus_development_2026-07-02.md`
- `docs/00_contract_tdc114plus_api_2026-07-02.md`

## 1. 한 줄 결론

- 신규 앱은 Baron SSO에 추가되는 별도 `RP`다.
- Baron SSO 원본에 신규앱 전용 `/api/v1/tdc114plus/...` API를 추가하지 않는다는 현재 기준을 따른다.
- 단, 앱 비밀값 보호와 모바일 세션 유지를 위해 `tdc114plus-auth` 중계서버는 별도 운영한다.
- 앱은 Baron SSO/조직도 사이트가 이미 제공하는 공식 API를 직접 소비하는 클라이언트다.
- 다만 앱에 넣으면 안 되는 운영 Key나 비밀값은 계속 서버/운영자 전용으로 본다.
- 현재 코드에 남아 있는 `tdc114plus` 전용 API 가정은 레거시 흔적으로 보고, 기능 보존 테스트를 동반해 점진 제거한다.

## 2. 현재 API 계층 해석

2026-07-08 기준 현재 해석은 아래와 같다.

| 계층 | 호출 주체 | 용도 | 비고 |
| --- | --- | --- | --- |
| Baron 공개/기존 API | Flutter 앱 | 조직도, 조직/사용자 데이터 조회 | Swagger에 노출된 endpoint 기준으로 재확인 필요 |
| Baron 로그인/웹 절차 | Flutter 앱 + 사용자 브라우저/링크 | RP 로그인, 승인 링크 처리 | Hosted Login + PKCE 원칙 |
| 운영 Key 기반 외부 연동 API | 운영 서버 또는 운영자 | 원본 데이터 조회 또는 관리자성 연동 | 모바일 앱 직접 탑재 금지 |

정리하면, Flutter 앱은 Baron SSO 원본에 신규앱 전용 API를 새로 요구하지 않는다. 대신 앱에 노출되면 안 되는 key/secret, Baron SSO 링크 로그인 중계, 앱 세션 JWT, 프로필 이미지 lookup은 `tdc114plus-auth`가 맡는다.

## 3. 신규 앱의 인증 해석

- `tdc114plus`는 Baron SSO에 추가되는 별도 `RP(Relying Party)`다.
- 앱 로그인은 Baron SSO의 RP 로그인 절차 일부다.
- 기본 인증 방식은 `Baron SSO Hosted Login + OIDC Authorization Code + PKCE`다.
- 흐름은 `앱 -> Baron SSO 인증 URL 열기 -> Hosted Login 화면에서 휴대폰번호 입력 -> 문자/메일 링크 인증 -> App Link callback -> token 교환 -> 앱 로그인 완료`다.
- 앱은 승인 링크를 직접 만들지 않고, 휴대폰번호/인증정보도 직접 처리하지 않는다.
- Swagger의 `phone-login`, `headless`, `enchanted-link`, `sms`, `qr` 계열 Auth API는 Baron SSO Hosted Login 화면과 서버 내부 구현의 참고 대상이다.
- Flutter 앱 기본 구현은 위 Auth API를 직접 조합하지 않고, OIDC authorization endpoint와 token endpoint를 사용한다.
- 로그인 성공 후 Baron SSO가 조직도 API 호출에 필요한 연동 키 묶음을 전달하면 앱은 이를 선택적 세션 값으로 받아 사용할 준비를 한다.
- 해당 기능이 Baron SSO에 구현되기 전까지는 staging `org-context` 검증을 위해 로컬 비추적 env/Dart define의 고정 키 fallback을 사용한다.

2026-07-20 현재 로컬 실기기 검증 흐름에서는 모바일 앱이 Baron SSO 원본을 직접 호출하지 않고 `tdc114plus-auth`의 아래 중계 API를 호출한다.

```http
POST /api/v1/auth/link/init
POST /api/v1/auth/link/poll
GET /api/v1/integrations/org-context
GET /api/v1/profile-image
```

위 API는 Baron SSO 원본에 새로 추가한 신규앱 API가 아니라, 신규앱 전용 중계서버 `tdc114plus-auth`의 API다.

## 4. 앱이 실제로 호출할 인증 API

현재 저장소 코드에는 아래 레거시 경로 가정이 남아 있거나 제거 대상이다.

```http
POST /api/v1/auth/headless/phone-login
POST /api/v1/auth/headless/link/poll
POST /api/v1/tdc114plus/auth/phone-login
```

하지만 2026-07-08 사용자 확인 기준으로 `tdc114plus 앱 전용 API는 없다`.

따라서 위 경로들 중 legacy `POST /api/v1/tdc114plus/auth/phone-login`을 포함한 레거시 표기는 `확정 계약`이 아니라 `기존 로컬/가정 기반 경로`로 격하한다.

처리 원칙:

1. 먼저 Swagger에서 대응 endpoint를 찾는다.
2. 그 다음 앱 DTO/repository를 대체 계약으로 맞춘다.
3. mock/real 테스트와 실제 화면 검증이 끝난 뒤에만 옛 경로를 제거한다.

현재 확정 사실:

- 신규 앱의 기본 로그인 정책은 Hosted Login + PKCE다.
- 사용자가 링크를 클릭해야 앱 로그인이 완료된다는 정책은 유지한다.
- 다만 링크 발송/승인 처리는 앱이 직접 headless API로 수행하지 않고 Baron SSO Hosted Login 화면과 서버 내부 구현에 맡긴다.
- Swagger에 `POST /api/v1/auth/phone-login` 또는 `POST /api/v1/auth/headless/phone-login`이 보이더라도, 앱의 기본 로그인 버튼은 이 API를 직접 호출하지 않는다.

## 5. 팀장 전달 외부 API 정보의 위치

현재 저장소 기준으로 팀장 전달 정보와 직접 연결되는 외부 연동 대상은 아래 API다.

```http
GET https://sadmin.hmac.kr/api/v1/integrations/org-context
X-Baron-Key-ID: {KEY_ID}
X-Baron-Key-Secret: {KEY_SECRET}
```

참고:

- Swagger UI: `https://sadmin.hmac.kr/api/docs#/Integrations/get_api_v1_integrations_org_context`
- OpenAPI: `https://sadmin.hmac.kr/api/openapi.yaml`
- 로컬 참고 문서: `docs/guide_baron_org_context_api_reference_2026-07-03.md`

중요 해석:

- 이 API는 앱 화면을 구성할 때 참고해야 하는 원본/공식 문서 계층이다.
- 장기적으로는 로그인 성공 후 Baron SSO가 내려주는 조직도 API 연동 키를 사용한다.
- 단기적으로는 Baron SSO의 키 전달 기능이 아직 미개발이므로, 개발/검증용 staging 고정 키를 로컬 비추적 env/Dart define에만 둔다.
- tracked 문서, tracked 소스, 운영 APK 기본값에는 `X-Baron-Key-ID`, `X-Baron-Key-Secret` 실제 값을 넣지 않는다.

## 6. 앱이 실제로 호출하는 데이터 API

현재 저장소 코드에는 아래 레거시 데이터 경로 가정이 남아 있다.

```http
GET /api/v1/tdc114plus/directory/employees
GET /api/v1/tdc114plus/directory/employees/{employeeId}
GET /api/v1/tdc114plus/organization/tenants
GET /api/v1/tdc114plus/organization/orgchart
```

하지만 이 역시 `확정 계약`으로 보지 않는다.

현재 확인된 근거:

- `sadmin.hmac.kr`는 org-context 참고 host이지 `tdc114plus` 앱 route host는 아니다.
- `sorg.hmac.kr/login?returnTo=%2Fchart`는 웹 로그인 진입 주소이며 JSON API가 아니라 HTML 응답을 돌려준다.
- Swagger 화면에는 `Public /api/v1/public/orgchart` 같은 조직도 관련 공개 API 흔적이 보인다.

따라서 앞으로의 기준은 아래와 같다.

1. 조직도/가족사/사용자 조회는 Swagger에 실제로 존재하는 `integrations/org-context`, `public/orgchart` 기준으로 다시 잡는다.
2. 현재 코드의 `/api/v1/tdc114plus/...` 경로는 전면 재확정 대상이다.
3. 정확한 path, query, 응답 스키마가 확인되기 전에는 코드 경로를 확정 표현으로 문서화하지 않는다.
4. 레거시 경로 정리는 `유지`, `교체`, `제거` 분류표를 먼저 만든 뒤 순차적으로 수행한다.

## 7. 원본 외부 API와 앱 기능의 연결

| 원본 정보 | 앱 또는 중간 가공 결과 | 앱 기능 |
| --- | --- | --- |
| 조직 트리 | `org-context` 또는 공개 `orgchart` 응답을 앱 내부 모델로 매핑 | 회사/조직 구조 표시 |
| 조직 목록 | 상단 칩용 tenant/company 모델 | 상단 필터 칩 |
| 조직 구성원 | 직원 목록/상세용 앱 모델 | 직원검색, 상세 |
| 사용자 전화번호 | `phoneNumber`, `phoneDisplay` | 전화/문자 실행 |
| 사용자 이메일/직급/직위/직무 | 동일 또는 유사 필드 | 상세 정보 표시 |

즉, 앱은 Swagger에 드러나는 원본/공개 응답을 앱 화면용 모델로 직접 매핑하는 구조로 전환될 수 있다.

## 8. 환경변수 및 보안 원칙

앱 측 런타임 값:

- `SSO_BASE_URL`
- `TDC114_API_BASE`
- `APP_VERSION`

서버 측 외부 API 연동 값 예시:

```env
TDC114PLUS_ORG_CONTEXT_BASE_URL=https://sadmin.hmac.kr
TDC114PLUS_ORG_CONTEXT_KEY_ID=
TDC114PLUS_ORG_CONTEXT_KEY_SECRET=
TDC114PLUS_ORG_CONTEXT_TENANT_SLUG=hanmac-family
TDC114PLUS_ORG_CONTEXT_INCLUDE_USERS=true
TDC114PLUS_ORG_CONTEXT_INCLUDE_USER_IDS=true
```

추가 메모:

- 2026-07-10 기준 팀장 지시에 따라 원본 Baron API 기준 host는 `https://sadmin.hmac.kr/`를 사용한다.
- 팀장 전달 운영 키(`CLIENT ID`, `X-Baron-Key-Secret`)는 로컬 비추적 env에만 반영하고 tracked 문서에는 직접 기록하지 않는다.
- 실제 배포 전까지 신규앱에서 사용하는 Baron SSO API 참고 기준은 staging Swagger `https://sadmin.hmac.kr/api/docs#/`다.

보안 원칙:

- `X-Baron-Key-ID`, `X-Baron-Key-Secret` 실제 값은 tracked 앱 소스와 tracked 문서에 넣지 않는다.
- 개발/검증 중 Baron SSO가 키 전달 기능을 제공하기 전까지는 비추적 env/Dart define fallback으로만 제한 사용한다.
- 운영 APK에서는 로그인 성공 후 받은 세션 기반 연동 키 또는 별도 안전한 서버 중계 방식으로 전환한다.
- 앱에는 공개 가능한 RP Client ID, issuer, redirect URI 같은 공개 설정만 기본값으로 둔다.
- RP 비밀값, 승인 링크 생성용 내부 인증정보, 외부 API Key는 모두 서버 전용이다.
- 앱이 저장하는 세션 정보는 운영 전 안전한 저장소 적용 여부를 재검토한다.

## 9. 팀 공유용 핵심 메시지

1. `tdc114plus`는 Baron SSO의 별도 RP다.
2. 로그인은 Baron SSO Hosted Login + PKCE 방식이며, Baron SSO 화면에서 휴대폰번호 입력 후 사용자가 문자/메일 링크를 클릭해야 앱 로그인이 완료된다.
3. 앱 전용 `tdc114plus` backend API는 없다는 현재 기준으로 재정렬한다.
4. 앱은 Baron이 이미 제공하는 Swagger 공개 API를 직접 소비하는 클라이언트 앱이다.
5. 운영 Key나 RP 비밀값은 모바일 앱과 저장소 tracked 파일에 두면 안 된다.

## 10. 현재 기준 주의사항

- `phone-login`은 개발용 fallback 경로일 뿐 기본 UX가 아니다.
- 현재 코드에 남아 있는 `/api/v1/tdc114plus/...` path는 검증 전 가정일 수 있다.
- 해당 가정 path 제거는 기능이 유지되는지 테스트한 뒤 단계적으로만 진행한다.
- 실제 앱 구조는 `auth`, `directory`, `organization` feature별 repository 분리 기준으로 유지하되, endpoint는 Swagger 기준으로 다시 매핑해야 한다.
- 실제 응답 정합성 검증 중이라, 세부 필드명과 사용 범위는 Swagger 기준으로 계속 재확인해야 한다.