tdc114plus 개발 정책

작성일: 2026-07-02 최종 개정일: 2026-07-10 상태: v2.2

목적: tdc114plus 개발 시 Baron SSO 연동 원칙, Flutter 앱 구조, 문서 우선순위, 테스트 및 협업 기준을 고정한다.

상위 기준 문서:

docs/00_policy_tdc114plus_decoupled_api_migration_2026-07-07.md

1. 서비스 및 인증 전제

tdc114plus 신규 앱은 Baron SSO에 추가되는 별도 RP(Relying Party)다.
앱 인증은 Baron SSO가 제공하는 공식 인증 절차를 소비하는 방식으로 설계한다.
신규 앱의 기본 로그인 방식은 Baron SSO Hosted Login + OIDC Authorization Code + PKCE다.
신규 앱은 Baron SSO에 등록된 PKCE 공개 클라이언트 RP이며 Client Secret을 앱 코드, APK, 환경 파일에 저장하지 않는다.
private_key_jwt 서명용 개인키도 공개 모바일 APK에 포함하지 않는다.
Flutter 앱은 Baron headless API(/api/v1/auth/headless/...)를 직접 호출하지 않는다.
휴대폰번호 입력, 문자/메일 링크 발송, 링크 승인 처리는 Baron SSO Hosted Login 화면과 Baron SSO 서버 내부 책임으로 본다.
RP의 OIDC issuer는 https://sso.hmac.kr/oidc, 인증 callback은 https://114.hmac.kr/auth/callback을 기준으로 한다.
앱은 authorization 요청 전 PKCE code_verifier, state, nonce를 생성/보관하고, callback에서 state 검증 후 code_verifier로 authorization code를 교환한다.
전체 Client ID 39d6190d-72f6-4a58-a84f-cdc5ece3e8af는 공개 RP 식별자이므로 APK 기본 설정에 포함한다.
환경별 RP가 달라질 경우 TDC114_OIDC_CLIENT_ID Dart define으로 기본값을 재정의할 수 있다.
기본 로그인 순서는 앱 -> Baron SSO 인증 URL 열기 -> Hosted Login 화면에서 휴대폰번호 입력 -> 문자/메일 링크 인증 -> https://114.hmac.kr/auth/callback -> 앱 복귀 -> code를 token으로 교환이다.
로그인 성공 후 Baron SSO가 조직도 API 호출에 필요한 연동 키 묶음을 전달하는 것을 최종 계약으로 준비한다.
해당 Baron SSO 기능이 미개발인 동안에는 staging org-context 검증을 위해 로컬 비추적 env/Dart define에만 고정 키를 둘 수 있다.
이 임시 고정 키는 tracked 문서, tracked 소스, 운영 APK 기본값에 넣지 않는다.
기존 Baron SSO의 선진행 후확인 방식은 신규 앱의 기본 로그인 정책으로 사용하지 않는다.
기존 phone-login이 남아 있더라도 개발용 fallback 또는 제한적 호환 경로로만 본다.

2. Baron SSO 연동 원칙

신규 앱은 Baron SSO 백엔드 소스를 직접 수정해서 맞추는 방식으로 개발하지 않는다.
앱은 Swagger에 정의된 공식 Request/Response 계약을 기준으로만 통신 계층을 설계한다.
실제 배포 전까지 앱이 참고하고 검증할 Baron SSO API 문서는 staging https://sadmin.hmac.kr/api/docs#/를 기준으로 한다.
조직/직원 데이터 API는 staging GET https://sadmin.hmac.kr/api/v1/integrations/org-context를 우선 기준으로 검증한다.
Baron SSO 내부 구현은 참고 대상일 뿐, 앱의 상위 기준은 공식 인터페이스 문서다.
기존 API 응답을 앱 요구사항에 맞게 임의로 바꾸는 것을 기본 전제로 삼지 않는다.
Baron SSO 관련 명칭, 경로, DTO가 앱 코드에 과도하게 박혀 있으면 점진적으로 일반화한다.
Baron SSO backend/orgFront 변경과 tdc114plus Flutter 앱 변경은 저장소와 커밋을 분리한다.

3. 인터페이스 중심 개발 원칙

프론트엔드와 백엔드는 API 계약을 먼저 고정한 뒤 병행 개발한다.
Flutter 앱은 request/response DTO, API client, repository interface, UI를 분리한다.
UI는 repository interface만 의존해야 하며, HTTP 세부사항을 직접 다루지 않는다.
화면 코드가 JSON 응답 구조를 직접 해석하는 형태는 금지한다.
백엔드 구현이 완료되지 않았더라도 mock 데이터와 mock repository로 화면 개발이 가능해야 한다.
API 계약이 바뀌면 문서, DTO, service, repository, test를 함께 갱신한다.

4. Flutter 공통 구현 원칙

공통 Flutter 코드는 처음부터 Android/iOS 모두를 고려해 작성한다.
화면, 상태관리, API client, repository, model은 플랫폼 공통 코드로 우선 설계한다.
플랫폼별 차이가 있는 기능은 공통 interface를 먼저 만들고 Android/iOS 구현체를 분리한다.
인증 UI와 상태관리는 SSO 로그인 시작 -> 외부 Hosted Login -> App Link callback -> state 검증 -> token 교환 -> 세션 저장 흐름을 기준으로 설계한다.
Flutter 앱은 승인 링크 자체를 생성하거나 RP 비밀값, client_assertion, 개인키를 보관하지 않는다.
화면 UX, 기본값, 조직 탐색 규칙은 docs/00_policy_tdc114plus_screen_feature_2026-07-07.md를 기준으로 삼는다.
공지사항, 전자결재, 수신전화식별, 수신팝업은 1차 범위에서 보류한다.
1차 범위는 직원검색, 전화번호검색, 가족사 필터, 조직도, 직원목록, 전화걸기, 문자보내기, 즐겨찾기에 집중한다.

5. 플랫폼별 구현 원칙

플랫폼별 네이티브 기능은 Android에서 먼저 PoC를 완성한 뒤 iOS로 확장한다.
iOS를 지나치게 늦게 검증하지 않는다.
푸시, 생체 인증, 보안 저장소, bridge는 공통 인터페이스와 플랫폼 구현체를 분리한다.
운영 배포 전에는 Android/iOS 모두 동일한 보안 기준을 통과해야 한다.

6. 개발 방식

작업은 계약 확인 -> DTO 정리 -> repository 정리 -> mock 유지 -> UI 연결 -> 실제 API 검증 순서로 진행한다.
한 번에 전체 기능을 갈아엎지 않고 feature 단위로 점진 개편한다.
mock 데이터는 임시 코드가 아니라 병행 개발을 위한 공식 수단으로 유지한다.
실제 API 연결 전에도 widget test와 unit test가 가능한 구조를 우선 만든다.
구현체 이름이 강하게 박힌 타입명은 점진적으로 일반화한다.

7. 검증 원칙

Flutter 앱 변경 시 최소 검증:

./scripts/flutter-docker.sh analyze
./scripts/flutter-docker.sh test

상세 테스트 기준은 아래 문서를 따른다.

docs/00_policy_tdc114plus_testing_2026-07-02.md

실제 API 연동 검증은 아래 기준을 따른다.

Swagger 계약과 DTO 필드 일치 확인
Hosted Login authorization URL 생성, App Link callback 수신, state 검증, PKCE token 교환, 세션 저장, 로그인 후 첫 화면 진입 확인
mock 경로와 real API 경로가 동일한 UI 흐름을 유지하는지 확인

8. 질문 및 확인 원칙

작업 진행 중 판단이 필요하면 아래 순서로 진행한다.

관련 정책 문서를 먼저 확인한다.
문서 기준으로 처리 가능한 것은 바로 진행한다.
정책 간 충돌, 해석 불명확, 보안 영향, 배포 영향이 있는 경우에만 질문한다.
질문 시에는 확인한 문서, 판단 포인트, 선택지, 권장안을 함께 정리한다.
새로운 결정이 내려지면 관련 문서와 타임테이블을 함께 갱신한다.

9. 문서 우선순위

개발 중 판단 기준은 아래 순서로 적용한다.

docs/00_policy_tdc114plus_decoupled_api_migration_2026-07-07.md
docs/00_policy_tdc114plus_development_2026-07-02.md
docs/00_contract_tdc114plus_api_2026-07-02.md
docs/00_policy_tdc114plus_screen_feature_2026-07-07.md
docs/00_policy_tdc114plus_testing_2026-07-02.md
docs/00_guide_tdc114plus_work_progress_timetable_2026-07-02.md
docs/guide_baron_sso_reference_source_2026-07-02.md
docs/references/baron-safe-policies/

참고 문서는 배경자료이며, 직접 정책보다 우선하지 않는다.

7.8 KiB Raw Blame History