Stabilize auth flow and profile images

2026-07-20 13:38:39 +09:00
parent 57caca8dc8
commit 5d3eee7a16
128 changed files with 28860 additions and 1468 deletions
@@ -0,0 +1,163 @@
+# 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 대조 확인은 후속 작업으로 남아 있다.