# tdc114plus Swagger API 목록 및 Feature 매핑

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

목적: 타임테이블의 다음 작업인 `Swagger 기준 1차 사용 API 목록 고정`, `현재 Flutter feature 매핑`, `구조 차이점 정리`를 한 문서에 정리한다.

상위 기준 문서:

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

주의:

- 현재 기준은 Baron Swagger 문서와 앱 소스의 대조 결과를 합친 중간 정리본이다.
- 신규앱 전용 `/api/v1/tdc114plus/...` API는 공식 계약으로 간주하지 않는다.
- 옛 `/api/v1/tdc114plus/...` 경로는 과거 구현 흔적 또는 호환 경로이며, 기능이 무너지지 않게 테스트하면서 점진 제거한다.

## 1. 1차 사용 API 목록

현재 Baron Swagger 기준 1차 사용 또는 즉시 검토 대상 API는 아래다.

| 구분 | Method | Path | 현재 상태 | 앱 사용 목적 |
| --- | --- | --- | --- | --- |
| auth | `GET` | `https://sso.hmac.kr/oidc/oauth2/auth` | RP 설정 기준 | Baron SSO Hosted Login 시작 |
| auth | `POST` | `https://sso.hmac.kr/oidc/oauth2/token` | RP 설정 기준 | PKCE authorization code token 교환 |
| auth | `GET` | `https://sso.hmac.kr/oidc/userinfo` | RP 설정 기준 | 로그인 사용자 정보 조회 |
| auth reference | `POST` | `/api/v1/auth/phone-login` | 앱 직접 호출 제외 | Baron SSO Hosted Login 내부 전화번호 로그인 구현 참고 |
| auth reference | `POST` | `/api/v1/auth/headless/phone-login` | 앱 직접 호출 제외 | Baron SSO Hosted Login 내부 구현 참고 |
| auth reference | `POST` | `/api/v1/auth/headless/link/poll` | 앱 직접 호출 제외 | Baron SSO Hosted Login 내부 구현 참고 |
| auth reference | `POST` | `/api/v1/auth/enchanted-link/init` | 앱 직접 호출 제외 | Baron SSO 링크 로그인 내부 구현 참고 |
| auth reference | `POST` | `/api/v1/auth/enchanted-link/poll` | 앱 직접 호출 제외 | Baron SSO 링크 로그인 내부 구현 참고 |
| auth reference | `POST` | `/api/v1/auth/sms`, `/api/v1/auth/verify-sms` | 앱 직접 호출 제외 | Baron SSO SMS 인증 내부 구현 참고 |
| auth reference | `POST` | `/api/v1/auth/qr/*` | 앱 직접 호출 제외 | Baron SSO QR 인증 내부 구현 참고 |
| organization | `GET` | `/api/v1/integrations/org-context` | 공식 계약 | 조직 subtree/구성원 조회 |
| organization | `GET` | `/api/v1/public/orgchart` | 공식 계약 | 공유용 조직도 조회 |
| legacy auth | `POST` | `/api/v1/tdc114plus/auth/phone-login` | 호환 흔적 | 테스트용 세션 seed 예외 경로 |
| legacy directory | `GET` | `/api/v1/tdc114plus/directory/employees` | 제거 대상 | 과거 직원검색 목록 가정 |
| legacy organization | `GET` | `/api/v1/tdc114plus/organization/tenants` | 제거 대상 | 과거 회사 필터 가정 |
| legacy organization | `GET` | `/api/v1/tdc114plus/organization/orgchart` | 제거 대상 | 과거 조직도 가정 |

## 2. Feature별 현재 매핑

### 2.1 auth

관련 코드:

- `app/lib/src/features/auth/data/auth_api_client.dart`
- `app/lib/src/features/auth/data/auth_repository.dart`

현재 매핑:

| 기능 | 기준 API | 비고 |
| --- | --- | --- |
| 로그인 시작 | `GET https://sso.hmac.kr/oidc/oauth2/auth` | 기본 로그인 경로. 외부 Baron SSO Hosted Login 화면을 연다 |
| callback 처리 | `https://114.hmac.kr/auth/callback` | App Link로 앱 복귀 |
| token 교환 | `POST https://sso.hmac.kr/oidc/oauth2/token` | PKCE `code_verifier`로 authorization code 교환 |
| 사용자 정보 | `GET https://sso.hmac.kr/oidc/userinfo` | 후속 연결 대상 |
| fallback 로그인 | legacy `POST /api/v1/tdc114plus/auth/phone-login` | 예외 호환 경로만 유지 |
| 세션 저장 | API 아님 | `AuthSessionStore`에서 로컬 저장 |

구조 메모:

- `AuthRepository` 추상화는 이미 존재한다.
- 구현체 이름은 `RemoteAuthRepository`로 일반화했다.
- `OidcLoginRepository`는 Hosted Login authorization URL 생성, PKCE transaction 저장, callback token 교환을 담당한다.
- Swagger Auth 섹션에 표시되는 `phone-login`, `headless`, `enchanted-link`, `sms`, `qr` 계열 API는 Baron SSO Hosted Login 화면/서버 내부 구현 참고 대상으로 분류한다.
- 기존 headless/legacy phone login 계층은 테스트 호환 및 제거 대상 분류용으로만 유지한다.
- 로그인 성공 후 Baron SSO가 `org-context` 호출용 연동 키를 내려주면 앱 세션의 선택적 credential로 받아 사용한다.
- 해당 기능이 미개발인 동안은 staging `org-context` 고정 키를 비추적 env/Dart define fallback으로 사용한다.

### 2.2 directory

관련 코드:

- `app/lib/src/features/directory/data/directory_api_client.dart`
- `app/lib/src/features/directory/data/directory_repository.dart`

현재 매핑:

| 기능 | 기준 API | 비고 |
| --- | --- | --- |
| 직원 목록/검색 | `GET /api/v1/integrations/org-context` 기반 재구성 | 메인 직원검색 진입점 |
| 직원 상세 | `org-context` member 필드 또는 후속 공식 API 확인 필요 | API 계약 재정렬 중 |

구조 메모:

- `DirectoryRepository` 추상화는 존재한다.
- 구현체 이름은 `RemoteDirectoryRepository`로 일반화했다.
- 현재는 directory repository를 `org-context` 기반 구조로 재정렬하는 단계다.

### 2.3 organization

관련 코드:

- `app/lib/src/features/organization/data/organization_api_client.dart`

현재 매핑:

| 기능 | 기준 API | 비고 |
| --- | --- | --- |
| 테넌트/상위 조직 | `GET /api/v1/integrations/org-context` | 실제 화면 사용 높음 |
| 조직도/공유형 | `GET /api/v1/public/orgchart` | 공유/외부 링크 전용 |

구조 메모:

- organization 쪽은 repository 추상화가 추가됐다.
- `orgContextProvider`를 통해 subtree 조회를 별도 책임으로 분리한다.
- 1차 화면 재사용 범위는 `orgContextProvider`까지로 고정한다.
- `org-context` 전용 provider를 준비하되, 현재 직원검색 화면 연결은 점진 전환한다.

## 3. 구조 차이점 및 정리 우선순위

### 3.1 우선순위 1

- Hosted Login + PKCE를 기본 로그인 계약으로 고정
- 앱 내부 phone 입력/headless 직접 호출 UI와 API 의존 제거
- callback `state` 검증, token 교환, userinfo 조회 연결

### 3.2 우선순위 2

- organization 상태 재사용 범위를 `org-context` 중심으로 먼저 고정
- `org-context` 전용 provider를 준비하고, 실제 UI 연결은 후속 단계로 분리
- directory 화면에서 subtree/member 비동기 조합 방식을 더 다듬을지 검토

### 3.3 우선순위 3

- 직원 상세 API를 화면에서 실제로 쓰는 범위를 확대할지 판단
- orgchart client를 drilldown 화면에 실제 연결할지 판단

## 4. 현재 확인된 구조상 이슈

1. 일부 코드와 문서에 legacy `/api/v1/tdc114plus/...` 흔적이 남아 있다.
2. 실제 `org-context` 응답 필드 대조가 끝나기 전까지는 DTO 필드 확정 표현을 최소화해야 한다.
3. Baron SSO의 로그인 성공 응답 또는 후속 userinfo/session 응답에 조직도 API 연동 키가 아직 포함되지 않을 수 있다.
4. 따라서 앱은 `세션 credential 우선 -> 비추적 env fallback` 순서로 구현되어야 한다.

## 5. 다음 코드 작업 제안

다음 코드 작업은 아래 순서를 권장한다.

1. organization 상태 재사용은 `orgContextProvider` 우선으로 유지
2. legacy `/api/v1/tdc114plus/...` 의존은 테스트를 곁들여 단계적으로 제거
3. 실제 UI 연결 전 `org-context` 매핑과 member 검색 규칙을 먼저 고정
4. auth session 모델에 선택적 `orgContextCredential` 수신/저장 구조를 추가
5. `org-context` client는 session credential을 우선 사용하고 없으면 staging env fallback을 사용

## 6. 이 문서로 완료된 타임테이블 항목

이 문서로 아래 작업을 1차 수행했다.

- Swagger 기준 1차 사용 API 목록 문서화
- 현재 Flutter 코드의 auth/directory/organization feature 매핑
- feature별 DTO/repository/mock 구조 차이점의 초안 정리
- auth feature의 기본 로그인 경로와 fallback 경로 역할 분리
- directory repository와 organization repository의 1차 책임 경계 분리
- organization 상태 재사용 범위와 orgchart 연결 범위 1차 확정
- orgchart 전용 provider 준비 완료, 실제 UI 연결은 후속 단계로 유지
- auth/directory 구현체 명칭을 `Remote...Repository`로 일반화
- auth/directory 구현체 명칭 일반화 후 관련 테스트 통과

다만 실제 Swagger UI 대조 확인은 후속 작업으로 남아 있다.