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

tdc114plus 분리형 API 전환 정책

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

목적: tdc114plus Flutter 앱을 Baron SSO 백엔드 소스 직접 의존 방식에서 분리하고, 공식 API 인터페이스 중심 구조로 전환하기 위한 작업 원칙과 단계별 진행 순서를 고정한다.

기준 인터페이스:

• Swagger/API Docs: https://sadmin.hmac.kr/api/docs#/

운영 전환 메모:

• 2026-07-10 팀장 지시 기준으로 Baron SSO 원본 참고 API 기준은 production(admin.brsw.kr)이 아니라 staging(sadmin.hmac.kr)으로 다시 본다.
• 실제 배포 전까지 신규앱에서 사용하는 Baron SSO API 참고 기준은 staging Swagger(https://sadmin.hmac.kr/api/docs#/)다.
• 조직/직원 데이터 검증은 staging GET https://sadmin.hmac.kr/api/v1/integrations/org-context를 우선 사용한다.
• Baron SSO가 로그인 성공 후 조직도 API 연동 키를 내려주는 기능은 아직 미개발이므로, 앱은 받을 준비를 하되 현재 개발/검증은 로컬 비추적 env/Dart define의 staging 고정 키 fallback으로 진행한다.
• 운영 CLIENT ID, X-Baron-Key-Secret 실제 값은 tracked 문서나 tracked 앱 코드에 넣지 않고 로컬 비추적 .env에만 저장한다.

관련 문서:

• docs/00_policy_tdc114plus_development_2026-07-02.md
• docs/00_contract_tdc114plus_api_2026-07-02.md
• docs/00_guide_tdc114plus_work_progress_timetable_2026-07-02.md
• docs/00_policy_tdc114plus_screen_feature_2026-07-07.md

1. 최우선 원칙

• 신규 앱은 Baron SSO에 추가되는 별도 RP(Relying Party)로 간주한다.
• 신규 앱은 Baron SSO 백엔드 소스를 직접 수정해서 맞추는 방식으로 개발하지 않는다.
• 앱은 Swagger에 정의된 공식 Request/Response 계약을 기준으로만 통신 계층을 설계한다.
• 백엔드 구현 완료 여부와 무관하게 Flutter 앱은 mock 데이터와 repository 추상화로 독립 개발 가능해야 한다.
• 기존 코드가 동작하더라도 Swagger 계약과 다르면 계약 기준으로 재정렬한다.
• Baron SSO 관련 명칭, 경로, DTO가 앱 내부에 과도하게 박혀 있으면 점진적으로 일반화한다.
• 인증 기본 원칙은 Baron SSO Hosted Login + OIDC Authorization Code + PKCE다.
• Flutter 앱은 휴대폰번호/문자/메일 인증을 직접 처리하는 headless API 클라이언트가 아니라, Baron SSO 인증 URL을 열고 callback의 authorization code를 token으로 교환하는 공개 RP다.
• 휴대폰번호 입력과 링크 발송/승인 처리는 Baron SSO Hosted Login 화면과 서버 내부 구현으로 둔다.
• Swagger Auth 섹션의 phone-login, headless, enchanted-link, sms, qr 계열 API는 Baron SSO 화면/서버 내부 구현 참고사항으로 분류하고 앱 기본 로그인 구현에서 직접 조합하지 않는다.
• 기존 선진행 후확인 방식은 신규 앱의 기본 로그인 정책으로 채택하지 않는다.
• 현재 코드와 문서에 남아 있는 /api/v1/tdc114plus/... 전용 API 가정은 레거시 흔적으로 분류한다.
• 레거시 흔적 제거는 한 번에 삭제하지 않고 실제 사용처 확인 -> 대체 Swagger path 매핑 -> mock/real 테스트 통과 -> 제거 순서로 진행한다.
• 레거시 제거 과정에서 기능이 무너지지 않도록 기존 화면 동작, 로그인 흐름, 검색/조직 표시를 단계별로 검증한다.

2. 판단 결론

• 개발환경은 새로 갈아엎지 않는다.
• 기존 Flutter 프로젝트 뼈대는 유지한다.
• 다만 API 계층, 모델 계층, 환경설정, 테스트 기준은 분리 아키텍처에 맞게 중간 규모로 재정비한다.

즉, 이번 작업은 재시작이 아니라 구조 개편형 마이그레이션으로 본다.

3. 작업 범위

포함:

• Swagger 기준 API 목록 재정리
• RP 관점의 인증 흐름 정리
• Request/Response DTO 정리
• API client/service/repository 계층 정리
• mock 구현 및 테스트 데이터 정비
• 화면이 repository interface만 의존하도록 연결 정리
• 환경별 base URL 및 인증 헤더 주입 방식 정리
• 문서/테스트/개발 순서 정리

제외:

• Baron SSO 운영 백엔드 내부 로직 직접 수정
• Swagger에 없는 비공식 응답 구조 전제 개발
• 화면 요구사항과 무관한 대규모 UI 재설계
• 1차 범위 밖 기능 추가

4. 단계별 진행 순서

Phase 1. 계약 기준 고정

작업:

• Swagger에서 신규 앱에 실제 필요한 endpoint만 1차 사용 목록으로 확정한다.
• 신규 앱 RP 등록/식별에 필요한 인증 전제와 로그인 시작점을 함께 정리한다.
• 각 endpoint별 method, path, request, response, error 형식을 앱 기준 표로 정리한다.
• 기존 내부 문서와 Swagger가 다르면 Swagger를 우선 기준으로 명시한다.

완료 기준:

• 앱에서 사용할 API 목록과 필수 필드가 문서로 고정되어 있다.

Phase 2. 앱 내부 의존성 분리 설계

작업:

• feature별로 remote data source -> repository interface -> UI 흐름을 고정한다.
• 특정 백엔드 구현체 이름이 드러나는 타입명은 일반화 대상 목록으로 분류한다.
• 인증, 직원검색, 조직도, 즐겨찾기 중 실제 API 의존 기능과 로컬 기능을 분리한다.

완료 기준:

• 어떤 레이어가 Swagger 계약에 직접 의존하고, 어떤 레이어가 추상화에 의존하는지 구조가 정리되어 있다.

Phase 3. DTO 및 API 클라이언트 정렬

작업:

• 현재 Dart 모델을 Swagger 응답 구조 기준으로 재검토한다.
• endpoint별 request/response DTO를 feature 단위로 정리한다.
• 공통 에러 모델, 타임아웃, 인증 헤더, base URL 처리 방식을 통일한다.

완료 기준:

• 각 feature의 API 호출 코드가 Swagger 계약과 1:1로 대응된다.

Phase 4. Repository 추상화 및 Mock 우선 개발

작업:

• repository interface를 기준으로 remote/mock 구현체를 분리한다.
• 백엔드 미구현 또는 스펙 검증 전 단계에서는 mock repository로 화면 개발이 가능하도록 유지한다.
• widget test와 unit test가 실제 네트워크 없이도 핵심 흐름을 검증하도록 구성한다.

완료 기준:

• API가 불완전해도 화면 개발과 테스트가 계속 가능하다.

Phase 5. 실제 API 연결

작업:

• 환경값으로 Swagger 대상 base URL을 주입한다.
• mock 구현을 유지한 채 remote 구현을 교체 가능하게 연결한다.
• 로그인, 직원검색, 조직도 등 우선 기능부터 실제 응답 정합성을 점검한다.
• 로그인은 authorization URL 생성 -> 외부 Hosted Login 완료 -> App Link callback 수신 -> state 검증 -> PKCE token 교환 -> session 저장 완료 기준으로 본다.

완료 기준:

• 동일한 UI가 mock/real repository 전환만으로 동작한다.

Phase 6. 정리 및 고정

작업:

• Baron SSO 직접 의존 흔적, 임시 fallback, 오래된 계약 문구를 문서와 코드에서 정리한다.
• /api/v1/tdc114plus/...처럼 전용 API를 전제한 레거시 경로는 유지, 교체, 제거로 분류한 뒤 순차적으로 없앤다.
• 각 제거 단계마다 최소한 로그인, 직원검색, 조직 탐색, 조직도 동작 확인을 먼저 수행한다.
• 테스트 기준과 수동 점검 순서를 갱신한다.
• 이후 신규 기능도 같은 패턴으로 추가하도록 개발 규칙을 고정한다.

완료 기준:

• 팀이 같은 방식으로 후속 기능을 이어서 개발할 수 있다.

5. 실제 실행 우선순위

가장 먼저 할 일:

1. Swagger 기준 1차 사용 API 목록 확정
2. 현재 코드의 API/DTO/repository 구조와 Swagger 차이점 목록화
3. 차이가 큰 feature부터 DTO와 repository interface 정리
4. mock 구현 유지 상태에서 remote 구현 교체
5. 실제 API smoke 및 화면 검증

6. 수정 방식 원칙

• 한 번에 전체 기능을 갈아엎지 않는다.
• feature 단위로 계약 확인 -> DTO 정리 -> repository 정리 -> mock 유지 -> UI 연결 순서로 바꾼다.
• 레거시 endpoint 제거는 대체 endpoint 반영 -> 테스트 통과 -> 실제 화면 확인 이후에만 진행한다.
• 화면 코드가 API 응답 JSON 구조를 직접 해석하는 형태는 금지한다.
• UI에서 HTTP, header, endpoint path를 직접 다루지 않는다.
• mock 데이터는 임시 코드가 아니라 공식 개발 수단으로 유지한다.

7. 문서 반영 원칙

• Swagger 기준 변경사항이 생기면 문서와 코드 중 문서를 먼저 갱신한다.
• 새 endpoint를 쓰기 시작하면 request/response 예시와 필수 필드를 문서에 남긴다.
• 진행 상태가 바뀌면 docs/00_guide_tdc114plus_work_progress_timetable_2026-07-02.md를 함께 갱신한다.

8. 이번 저장소에서의 즉시 적용 해석

현재 저장소는 아래 판단으로 진행한다.

• Flutter 앱 기본 프로젝트와 테스트 기반은 유지한다.
• 기존 auth, directory, organization, favorites 구조는 재사용한다.
• BaronSso...처럼 구현체 이름에 종속된 부분은 점진적으로 일반화한다.
• 기존 Baron SSO 전용 계약 문서는 유지하되, 앞으로는 Swagger 기준 문서가 상위 실행 기준이 된다.
• 앞으로의 구현 순서는 이 문서의 Phase 순서를 따른다.

9. 다음 작업 시작점

다음 작업은 아래 순서로 시작한다.

1. Swagger 기준 1차 사용 API를 문서로 고정한다.
2. 현재 Flutter 코드에서 그 API를 쓰는 feature를 매핑한다.
3. feature별 차이점과 수정 우선순위를 정리한다.
4. 우선순위 1 feature부터 코드 개편을 시작한다.