# 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부터 코드 개편을 시작한다.
