tdc114plus/docs/00_guide_tdc114plus_swagger_feature_mapping_2026-07-07.md

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 대조 확인은 후속 작업으로 남아 있다.