tdc114plus/docs/00_policy_tdc114plus_development_2026-07-02.md

# 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 앱 변경 시 최소 검증:

```bash
./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. 질문 및 확인 원칙

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

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

## 9. 문서 우선순위

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

1. `docs/00_policy_tdc114plus_decoupled_api_migration_2026-07-07.md`
2. `docs/00_policy_tdc114plus_development_2026-07-02.md`
3. `docs/00_contract_tdc114plus_api_2026-07-02.md`
4. `docs/00_policy_tdc114plus_screen_feature_2026-07-07.md`
5. `docs/00_policy_tdc114plus_testing_2026-07-02.md`
6. `docs/00_guide_tdc114plus_work_progress_timetable_2026-07-02.md`
7. `docs/guide_baron_sso_reference_source_2026-07-02.md`
8. `docs/references/baron-safe-policies/`

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