diff --git a/tdc114plus/신규앱(TDC114PLUS)과 Baron SSO 연동 쉬운 설명.md b/tdc114plus/신규앱(TDC114PLUS)과 Baron SSO 연동 쉬운 설명.md
new file mode 100644
index 0000000..9b06a3d
--- /dev/null
+++ b/tdc114plus/신규앱(TDC114PLUS)과 Baron SSO 연동 쉬운 설명.md	
@@ -0,0 +1,418 @@
+# 신규앱과 Baron SSO 연동 쉬운 설명
+
+작성일: 2026-07-08
+상태: 초안 v1
+
+목적: 신규앱과 Baron SSO의 관계, 데이터 연동 방식, headless 로그인, 모바일 배포 형태를 다른 팀원도 쉽게 이해할 수 있게 설명한다.
+
+관련 근거:
+
+- `docs/00_contract_tdc114plus_api_2026-07-02.md`
+- `docs/00_policy_tdc114plus_screen_feature_2026-07-07.md`
+- `docs/scenario_staging_baron_sso_login_verification_2026-07-06.md`
+- `docs/policy_android_app_install_execution_2026-07-06.md`
+- `app/lib/src/features/auth/data/auth_api_client.dart`
+- `app/lib/src/features/auth/domain/auth_models.dart`
+- `app/lib/src/features/auth/data/auth_repository.dart`
+
+## 1. 한 줄 요약
+
+`tdc114plus` 신규앱은 Baron SSO 자체가 아니라, Baron SSO를 로그인/사용자정보/조직정보 제공자로 사용하는 별도의 모바일 앱이다.
+
+쉽게 말하면:
+
+- 신규앱 = 사용자가 설치해서 실행하는 앱
+- Baron SSO = 로그인과 사용자/조직 데이터를 제공하는 서버
+- 두 시스템은 API로 데이터를 주고받는다
+
+## 2. 신규앱과 Baron SSO의 관계
+
+### 2.1 무엇이 누구인가
+
+- 신규앱은 Flutter로 만든 Android/iOS 공통 모바일 앱이다.
+- Baron SSO는 사용자 인증과 조직/직원 데이터를 관리하는 서버 쪽 시스템이다.
+- 신규앱은 Baron SSO에 등록되는 별도 `RP(Relying Party)`로 본다.
+
+여기서 `RP`는 쉽게 말하면:
+
+- "SSO를 믿고 로그인 기능을 맡기는 서비스"
+- 즉, 로그인 자체를 새로 만들지 않고 Baron SSO를 통해 인증받는 앱
+
+그래서 신규앱은 Baron SSO의 일부 화면이 아니라, Baron SSO를 사용하는 별도 서비스라고 이해하면 된다.
+
+## 3. 설치되는 앱 실행파일은 무엇인가
+
+### 3.1 Android
+
+Android에서 실제 기기에 설치되는 파일은 보통 아래 둘 중 하나다.
+
+- `APK`
+- `AAB`에서 스토어가 기기별로 풀어 배포한 설치 패키지
+
+개발/테스트 단계에서는 보통:
+
+- `flutter run`
+- debug `APK`
+
+를 사용한다.
+
+운영 배포 관점에서는 보통:
+
+- 사내 직접 배포면 `APK`
+- Play Store 배포면 `AAB`
+
+형태를 생각하면 된다.
+
+현재 저장소 문맥상 Android 테스트에서는 debug APK를 직접 깔 수도 있지만, 기능 검증은 `flutter run` 중심으로 하도록 정책이 잡혀 있다. 이유는 이 앱이 실행 시점에 `TDC114_API_BASE` 같은 환경값을 함께 받아야 하기 때문이다.
+
+### 3.2 iOS
+
+iOS에서 실제 설치/배포에 쓰이는 것은 보통:
+
+- 개발기기 설치용 app bundle
+- TestFlight/App Store 배포용 `IPA`
+
+라고 보면 된다.
+
+즉 정리하면:
+
+- Android는 주로 `APK` 또는 스토어용 `AAB`
+- iOS는 주로 `IPA` 또는 TestFlight/App Store 배포
+
+다.
+
+## 4. 앱 실행파일 자체가 RP인가
+
+이 질문은 자주 헷갈릴 수 있는데, 가장 쉬운 답은 아래와 같다.
+
+- "앱 실행파일 그 자체"를 좁게 보면 그냥 설치 패키지다.
+- 하지만 "그 앱 서비스 전체"를 넓게 보면 Baron SSO 입장에서는 하나의 `RP`다.
+
+즉:
+
+- `APK`, `IPA`는 설치물이다.
+- 그 설치물을 통해 동작하는 `tdc114plus` 앱 서비스가 Baron SSO에 연동되는 `RP`다.
+
+따라서 팀 내 설명에서는 아래처럼 말하면 가장 덜 헷갈린다.
+
+`tdc114plus` 모바일 앱은 Baron SSO에 등록된 별도 RP이며, 사용자는 Android/iOS 기기에 그 RP의 클라이언트 앱을 설치해 사용한다.
+
+## 5. 앱이 설치된 뒤 실제로 어떻게 동작하는가
+
+네, 큰 흐름은 아래 이해가 맞다.
+
+1. 사용자가 각 모바일 디바이스에 신규앱을 설치한다.
+2. 사용자가 앱을 실행한다.
+3. 앱은 Baron SSO 관련 API로 로그인 요청을 보낸다.
+4. Baron SSO가 로그인 승인 절차를 처리한다.
+5. 로그인 완료 후 Baron SSO가 세션 토큰과 사용자 정보를 앱에 돌려준다.
+6. 앱은 그 세션으로 직원검색, 조직도, 사용자 표시 정보를 다시 조회한다.
+7. 앱 화면은 Baron SSO가 준 로그인 결과와 조직/직원 데이터를 사용자에게 보여준다.
+
+즉, "설치된 실행파일이 Baron SSO와 데이터를 주고받으면서 로그인과 표시 내용을 가져온다"는 이해는 맞다.
+
+다만 더 정확히 말하면:
+
+- 로그인 결과 일부는 앱 내부에 저장된다
+- 이후 필요한 화면 데이터는 Baron SSO 연동 API를 다시 호출해서 가져온다
+
+## 6. 어떤 데이터들을 주고받는가
+
+## 6.1 로그인 시작 시 앱 -> Baron SSO
+
+신규앱은 로그인 시작 시 아래 API를 호출한다.
+
+```http
+POST /api/v1/tdc114plus/auth/link/init
+Content-Type: application/json
+Accept: application/json
+```
+
+예시 요청:
+
+```json
+{
+  "phoneNumber": "01012345678",
+  "device": {
+    "platform": "android",
+    "appVersion": "0.1.0",
+    "deviceName": "Pixel 8"
+  }
+}
+```
+
+의미:
+
+- `phoneNumber`: 로그인하려는 사용자 전화번호
+- `device.platform`: android / ios 같은 플랫폼 정보
+- `device.appVersion`: 앱 버전
+- `device.deviceName`: 기기명 또는 기기 구분용 값
+
+즉 앱은 "어떤 사용자가, 어떤 기기에서 로그인하려는지"를 JSON 형식으로 Baron SSO에 보낸다.
+
+## 6.2 로그인 시작 응답 시 Baron SSO -> 앱
+
+예시 응답:
+
+```json
+{
+  "status": "pending",
+  "pendingRef": "pending-ref",
+  "expiresIn": 180,
+  "interval": 3,
+  "resendAfter": 30,
+  "provider": "Ory (Kratos/Hydra)"
+}
+```
+
+의미:
+
+- `status`: 현재 로그인 진행 상태
+- `pendingRef`: 이 로그인 요청을 나중에 다시 조회할 때 쓰는 참조값
+- `expiresIn`: 몇 초 뒤 만료되는지
+- `interval`: 몇 초 간격으로 상태 조회할지
+- `resendAfter`: 재발송 가능 시간
+- `provider`: 내부 인증 제공자 정보
+
+핵심은 Baron SSO가 이 단계에서 바로 로그인 완료를 주는 것이 아니라, "지금은 승인 대기 중이니 이 `pendingRef`로 다시 물어봐라"라고 알려준다는 점이다.
+
+## 6.3 로그인 상태 확인 시 앱 -> Baron SSO
+
+신규앱은 아래 API로 승인 완료 여부를 계속 조회한다.
+
+```http
+POST /api/v1/tdc114plus/auth/link/poll
+Content-Type: application/json
+Accept: application/json
+```
+
+예시 요청:
+
+```json
+{
+  "pendingRef": "pending-ref"
+}
+```
+
+즉 앱은 복잡한 로그인 정보를 매번 보내지 않고, 처음 받은 `pendingRef`만 보내서 "이 건 승인됐나요?"를 확인한다.
+
+## 6.4 승인 대기 중 응답
+
+```json
+{
+  "status": "pending",
+  "code": "authorization_pending",
+  "interval": 3
+}
+```
+
+의미:
+
+- 아직 사용자가 링크를 누르지 않았음
+- 앱은 잠시 기다렸다가 다시 poll 해야 함
+
+## 6.5 승인 완료 응답
+
+```json
+{
+  "status": "ok",
+  "session": {
+    "status": "ok",
+    "token": "baron-sso-session-token",
+    "expiresAt": "2026-07-02T12:00:00Z",
+    "user": {
+      "id": "user-uuid",
+      "name": "홍길동",
+      "phoneNumber": "+821012345678",
+      "tenantId": "tenant-uuid",
+      "tenantName": "한맥",
+      "tenantSlug": "hanmac",
+      "department": "기술연구소",
+      "grade": "책임",
+      "position": "팀장",
+      "jobTitle": "개발"
+    }
+  }
+}
+```
+
+의미:
+
+- `token`: 이후 API 호출 때 사용하는 로그인 세션 토큰
+- `expiresAt`: 세션 만료 시각
+- `user`: 앱 화면 구성에 필요한 로그인 사용자 정보
+
+여기서 사용자 정보는 아래처럼 쓰인다.
+
+- `name`: 화면에 보여줄 사용자명
+- `tenantName`, `tenantSlug`: 어느 회사/테넌트 소속인지
+- `department`: 본인 부서
+- `grade`, `position`, `jobTitle`: 직급/직위/직무
+
+## 6.6 로그인 후 조회하는 업무 데이터
+
+로그인 후에는 아래 같은 업무 데이터를 Baron SSO 연동 API에서 조회한다.
+
+- 직원 목록
+- 조직/가족사 목록
+- 조직도
+- 직원 상세 정보
+
+문서 기준 주요 API는 아래와 같다.
+
+- `GET /api/v1/tdc114plus/directory/employees`
+- `GET /api/v1/tdc114plus/organization/tenants`
+- `GET /api/v1/tdc114plus/organization/orgchart`
+
+즉 Baron SSO는 로그인만 해주는 것이 아니라, 앱이 필요한 직원/조직 데이터도 함께 제공하는 역할을 한다.
+
+## 7. 데이터 형식은 무엇인가
+
+기본 형식은 HTTP + JSON 이다.
+
+조금 더 풀면:
+
+- 통신 방식: 모바일 앱이 HTTPS API 호출
+- 요청 본문 형식: JSON
+- 응답 본문 형식: JSON
+- 헤더: 보통 `Content-Type: application/json`, `Accept: application/json`
+
+즉 이 앱은 웹페이지를 긁어오는 방식이 아니라, 구조화된 JSON API를 호출해서 데이터를 받는다.
+
+## 8. 세션은 앱 안에 어떻게 저장되는가
+
+코드상 현재 앱은 로그인 성공 시 아래 정보를 저장한다.
+
+- `token`
+- `expiresAt`
+- `user`
+
+저장 위치는 앱 내부 저장소(`SharedPreferences`)다.
+
+그래서 앱을 다시 켰을 때:
+
+- 저장된 세션이 아직 유효하면 로그인 화면을 건너뛴다
+- 세션이 없거나 만료되면 다시 Baron SSO 로그인으로 보낸다
+
+즉 앱은 매 화면마다 처음부터 새 로그인하는 것이 아니라, 받은 세션을 보관했다가 재사용한다.
+
+## 9. 헤드리스 로그인(headless login)이란 무엇인가
+
+가장 쉬운 설명부터 하면:
+
+헤드리스 로그인은 "앱 안에 Baron SSO의 로그인 웹화면을 직접 띄우지 않고, 앱이 API로 로그인 절차를 진행하는 방식"이다.
+
+`headless`를 직역하면 "머리/화면이 없는" 느낌인데, 여기서는:
+
+- 로그인용 별도 웹페이지 중심이 아니라
+- 백그라운드 API 호출 중심으로 로그인 절차를 진행한다
+
+는 뜻으로 이해하면 된다.
+
+## 10. 이번 신규앱의 헤드리스 로그인은 왜 특별한가
+
+이번 신규앱 기본 로그인은 단순한 "전화번호 넣고 바로 로그인"이 아니다.
+
+흐름은 아래와 같다.
+
+1. 앱에서 전화번호 입력
+2. 앱이 `link/init` 호출
+3. Baron SSO가 문자 또는 메일로 승인 링크 발송
+4. 사용자가 그 링크를 열어 승인
+5. 앱은 `link/poll`로 승인 완료 여부를 반복 확인
+6. 승인 완료가 확인되면 Baron SSO가 세션 발급
+7. 앱이 세션 저장 후 첫 화면 진입
+
+즉 핵심은:
+
+- 앱이 로그인 시작을 함
+- 최종 승인 행위는 링크 클릭으로 이뤄짐
+- 앱은 그 결과를 poll 해서 받아옴
+
+이다.
+
+## 11. 왜 굳이 headless로 하나
+
+장점은 아래처럼 설명할 수 있다.
+
+- 앱 UI를 우리 서비스 스타일에 맞게 단순하게 유지할 수 있다
+- 앱 안에서 필요한 로그인 절차를 API 중심으로 제어할 수 있다
+- Android/iOS 양쪽에서 같은 로그인 흐름을 구현하기 쉽다
+
+하지만 주의할 점도 있다.
+
+- 앱 코드만 있다고 로그인 검증이 끝나지 않는다
+- Baron SSO 쪽에도 `link/init`, `link/poll`, 링크 발송, 승인 상태 변경이 모두 준비되어 있어야 한다
+- staging/운영 환경에서 실제 테스트 번호와 링크 수신 경로가 맞아야 end-to-end 검증이 된다
+
+## 12. 헤드리스 로그인과 일반 웹 로그인 차이
+
+일반적인 웹 로그인 느낌:
+
+1. 로그인 페이지로 이동
+2. 아이디/비밀번호 또는 인증수단 입력
+3. 브라우저 redirect
+4. 로그인 완료
+
+이번 헤드리스 로그인 느낌:
+
+1. 앱 화면에서 전화번호 입력
+2. 앱이 API 호출
+3. 사용자는 외부로 받은 링크를 열어 승인
+4. 앱은 API로 상태를 확인
+5. 완료되면 앱이 세션을 저장
+
+즉 사용자 입장에서는 앱 화면이 계속 보이지만, 실제 인증 완료 여부는 서버와 승인 링크 절차가 결정한다.
+
+## 13. "전화번호만 넣으면 바로 로그인"과 같은가
+
+아니다. 이번 기본 흐름은 그것과 다르다.
+
+이번 기본 흐름은:
+
+- 전화번호 입력
+- 링크 발송
+- 사용자 승인
+- 승인 확인 후 세션 발급
+
+이다.
+
+즉 전화번호 입력만으로 즉시 로그인시키는 구조가 아니라, 승인 단계를 끼운 비동기 로그인 구조다.
+
+## 14. 팀원들이 가장 헷갈리지 않게 설명하는 표현
+
+아래 표현을 권장한다.
+
+`tdc114plus`는 Baron SSO에 등록된 별도 모바일 RP 앱이다. 사용자는 Android나 iPhone에 앱을 설치하고, 앱은 Baron SSO의 headless 로그인 API를 호출해 로그인한다. 로그인은 전화번호 입력 후 링크 승인 방식으로 진행되며, 승인 완료 뒤 Baron SSO가 세션 토큰과 사용자 정보를 앱에 돌려준다. 이후 앱은 그 세션으로 직원검색/조직도 같은 데이터를 Baron SSO 연동 API에서 조회해 화면에 표시한다.
+
+## 15. 자주 나오는 질문에 대한 짧은 답
+
+### Q1. 신규앱은 Baron SSO 안에 들어가는가
+
+아니라기보다, Baron SSO를 사용하는 별도 앱이다.
+
+### Q2. 앱 실행파일 자체가 RP인가
+
+설치파일 자체보다는, 그 설치파일로 동작하는 앱 서비스 전체를 RP라고 보는 것이 더 정확하다.
+
+### Q3. Android는 APK로 배포하는가
+
+개발/사내 배포는 APK가 가능하고, 스토어 배포는 보통 AAB를 사용한다.
+
+### Q4. iOS는 APK처럼 설치하는가
+
+아니다. 보통 IPA 또는 TestFlight/App Store 방식이다.
+
+### Q5. 앱이 설치된 뒤 Baron SSO와 계속 통신하는가
+
+그렇다. 로그인할 때도 통신하고, 로그인 후 직원/조직 데이터를 가져올 때도 통신한다.
+
+### Q6. 헤드리스 로그인은 화면이 아예 없다는 뜻인가
+
+아니다. 사용자 화면은 앱에 있다. 다만 Baron SSO의 전통적인 웹 로그인 페이지를 직접 띄우지 않고, 앱이 API로 로그인 절차를 처리한다는 뜻에 가깝다.
+
+## 16. 결론
+
+이번 신규앱은 단말에 설치되는 일반 모바일 앱이지만, 인증과 주요 사용자/조직 데이터는 Baron SSO와의 API 연동에 의존한다. 따라서 이 앱은 "독립 실행은 되지만 독립 인증은 하지 않는 RP 앱"이라고 이해하면 가장 정확하다.
+
+또한 이번 로그인은 단순 즉시 로그인 방식이 아니라 `link/init -> 사용자 승인 -> link/poll -> 세션 저장` 흐름의 headless 승인 로그인이다. 그래서 앱 실행파일만 설치되었다고 끝나는 것이 아니라, Baron SSO 쪽 API와 승인 링크 흐름이 함께 정상 동작해야 비로소 로그인과 첫 화면 진입이 완성된다.