Stabilize auth flow and profile images

docs/00_guide_tdc114plus_work_progress_timetable_2026-07-02.md

@@ -0,0 +1,367 @@
+# tdc114plus 작업진행 절차 및 타임테이블
+
+작성일: 2026-07-02
+최종 개정일: 2026-07-20
+상태: v3.0
+
+목적: `tdc114plus` 개발 작업을 새 분리형 API 전환 정책 기준으로 어떤 순서로 진행할지 고정하고, 현재 진행 상태를 최신 기준으로 유지한다.
+
+상위 기준 문서:
+
+- `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`
+
+## 1. 현재 기준
+
+`tdc114plus`는 Baron SSO에 추가되는 별도 `RP(Relying Party)` 성격의 신규 앱이다.
+
+현재 구조는 `개발 중 임시 운영 구조`와 `최종 배포 목표 구조`를 구분해서 본다.
+
+- 개발 중 임시 운영 구조:
+  - 앱 저장소 `tdc114plus`
+  - 중계서버 저장소 `tdc114plus-auth`
+  - Baron SSO API 검증용 로컬 worktree `baron-sso-tdc114plus-api`
+- 최종 배포 목표 구조:
+  - 신규앱은 `tdc114plus` + `tdc114plus-auth` 기준으로 배포 준비를 진행한다.
+  - 인증/조직 원본은 로컬 Baron worktree가 아니라 Baron SSO 원본 `staging`을 먼저 바라본다.
+  - 안정화 확인 후 Baron SSO 원본 `production`을 바라보는 구조로 전환한다.
+  - 따라서 `baron-sso-tdc114plus-api`는 현재 개발/검증용 임시 worktree로 보고, 최종 운영 필수 구성으로 간주하지 않는다.
+
+현재 1차 범위:
+
+- Baron SSO Hosted Login + PKCE 로그인
+- 직원검색
+- 가족사/조직 탐색
+- 조직도
+- 직원 상세
+- 전화걸기/문자보내기
+- 즐겨찾기 로컬 저장
+
+1차 보류:
+
+- 공지사항
+- 전자결재
+- 수신전화식별
+- 수신팝업
+- 서버 기반 즐겨찾기 동기화
+
+## 2. 작업진행 절차
+
+| 순서 | 단계 | 상태 | 작업 내용 | 산출물 |
+| --- | --- | --- | --- | --- |
+| 1 | 저장소 및 앱 골격 준비 | 완료 | Flutter 프로젝트, 기본 문서, 기본 스크립트, 테스트 기반 구성 | `app/`, `docs/`, `scripts/` |
+| 2 | Mock 기반 화면 구축 | 완료 | 직원검색/조직도/상세/즐겨찾기 화면을 mock 데이터로 우선 구현 | 동작 가능한 UI 및 widget test |
+| 3 | API 연동 1차 구현 | 진행 중 | auth, directory, organization API client/repository 및 세션 저장 흐름 구현 | Flutter API 계층, 단위 테스트 |
+| 4 | Hosted Login + PKCE 전환 | 진행 중 | Baron SSO 인증 URL 생성, App Link callback, state 검증, PKCE token 교환, 세션 저장 흐름을 기본 로그인으로 반영 | auth client/repository/UI |
+| 5 | 분리형 API 정책 정리 | 완료 | RP, Swagger 중심 계약, mock/real 병행 개발 원칙 문서화 | 정책 문서 개정본 |
+| 6 | Swagger 기준 계약 재정렬 | 진행 중 | 실제 사용 endpoint와 DTO를 Swagger 기준으로 재확정하고 1차 사용 API/feature 매핑 문서를 추가했다 | 계약 문서 및 feature별 매핑 |
+| 7 | Repository/Mock 구조 정리 | 진행 중 | feature별 remote/mock 구현을 더 명확히 분리하기 위해 organization repository 추상화를 추가하고 directory의 직접 API client 의존을 한 단계 분리했다 | repository interface 및 mock 구현 |
+| 8 | 실제 API 정합성 검증 | 완료 | 로그인, 직원검색, 조직/테넌트 응답의 실제 정합성 점검 | smoke/integration 결과 |
+| 8-A | Android integration runtime 기준 정렬 | 완료 | 실제 API smoke 완료 후 Android target bridge 포트와 integration 실행 기준을 최신 정책값으로 정렬하고 재검증했다 | target/ADB 점검 결과 및 재실행 로그 |
+| 9 | staging 반영 검토 준비 | 진행 중 | 승인 완료 E2E, 예외 케이스, 환경값/롤백 경로 정리와 함께 실제 API 공백은 Baron SSO 이슈 명세로 분리 정리 | 수동 점검 체크리스트, API 보강 요청 초안 |
+| 9-A | 직원검색/조직도 UI 정렬 보정 | 진행 중 | 선택 칩 강조, 칩 overflow 스크롤 탐색, 조직도 인원 정렬 규칙을 정책과 코드에 반영 | 개정 정책 문서, widget test, emulator 확인 |
+| 9-B | 직원검색 규칙/프로필 표현 보강 | 진행 중 | 검색 범위 정책, 한글/전화번호 최소 입력 규칙, 프로필 사진 노출 가능 조건을 정책과 코드에 반영 | 개정 정책 문서, widget test, emulator 확인 |
+| 9-C | 프로필 사진 식별자 매핑 검토 | 진행 중 | 네이버웍스 우선, Baron SSO `members[].id` 기반 UUID 파일명 2순위, 앱 기본 아바타 3순위 구조로 정책을 재정렬하고 파일 재배치/앱 연동 기준을 정리 | 매핑 정책 문서, UUID 매핑 CSV, 샘플 URL 검증 |
+| 9-D | 입력기/구분 표식 보정 | 진행 중 | 직원검색 입력기의 한글 입력 친화 설정과 상하 영역 구분 표식을 정책과 코드에 반영 | 개정 정책 문서, widget test, emulator 확인 |
+| 9-E | 초기 선택 scope 재정렬 | 진행 중 | 앱 첫 진입 시 회사급이 아니라 본인 팀 뱃지가 실제 선택 상태가 되도록 정책과 코드에 반영하고, 중앙 구분 아이콘은 제거 | 개정 정책 문서, widget test, emulator 확인 |
+| 9-F | 공기계 USB 테스트 전환 | 진행 중 | emulator 기반 수동 검증의 반복 장애를 줄이기 위해 공기계 USB 연결, `adb reverse`, 실기기 env/preflight를 추가하고 수동 점검부터 안정화 | 공기계 정책 문서, device env 예시, preflight 스크립트, 수동 실행 결과 |
+| 9-G | 독립형 실기기 서버 연동 전환 | 진행 중 | USB reverse 기반 로컬 실행과 별도로, 공기계/실사용 폰이 USB 없이도 staging 또는 production Baron API에 직접 붙어 동작할 수 있도록 공개 base URL, 인증 흐름, APK 실행 조건을 정리 | 독립 실행 체크리스트, 환경값 표, 실서버 APK 검증 절차 |
+| 9-H | 레거시 전용 API 흔적 단계적 제거 | 진행 중 | `/api/v1/tdc114plus/...` 가정 path와 Baron 전용 DTO 흔적을 실제 Swagger path 매핑 기준으로 `유지/교체/제거` 분류하고, 기능 보존 테스트를 동반해 순차 제거 | 레거시 분류표, 대체 path 매핑, 기능 보존 테스트 결과 |
+| 9-I | Baron SSO RP/PKCE 연결 | 진행 중 | 등록된 PKCE RP의 issuer, callback, client ID를 앱 환경에 반영하고 Hosted Login 완료 후 OIDC 세션 연결을 검증 | RP 설정표, 앱 링크 설정, callback 수신 및 토큰 교환 테스트 |
+| 9-J | Headless 직접 호출 계약 정리 | 진행 중 | headless API 직접 호출은 앱 기본 흐름에서 제외하고, Baron SSO Hosted Login 내부 구현 참고사항으로 격하 | 정책 개정, 레거시 코드 제거 계획 |
+| 9-K | 로그인 후 org-context credential 수신 준비 | 진행 중 | Baron SSO가 로그인 성공 후 조직도 API 연동 키를 내려줄 예정이므로 세션 모델/저장소/API client에 선택적 credential 구조를 준비하고, 미개발 기간에는 staging env fallback을 유지 | AuthSession 확장, credential 우선순위, fallback 테스트 |
+| 10 | 빌드/배포 준비 | 대기 | Android debug APK, README, 잔여 이슈 정리 | APK 및 배포 준비 문서 |
+
+## 3. 단계별 타임테이블
+
+| 단계 | 상태 | 목표 | 주요 작업 | 완료 기준 |
+| --- | --- | --- | --- | --- |
+| Phase 0 | 완료 | 저장소와 개발환경 출발점 확보 | clone, 문서 이관, Flutter 실행 기반 구성 | 기본 프로젝트 동작 |
+| Phase 1 | 완료 | Mock 기반 UI/상태 흐름 확보 | 로그인 화면, 직원검색, 조직도, 상세, 즐겨찾기 구성 | analyze/test 통과 |
+| Phase 2 | 완료 | 초기 API 연동 골격 확보 | auth/directory/organization client, repository, session 저장 | 단위 테스트 통과 |
+| Phase 3 | 진행 중 | 기본 로그인 흐름을 Hosted Login + PKCE 방식으로 전환 | authorization URL 생성, 외부 SSO 로그인, App Link callback, token 교환, 세션 저장 | PKCE 로그인 기본 흐름 코드 반영 |
+| Phase 4 | 진행 중 | Swagger 기준 계약 재정렬 | 실제 사용 endpoint/DTO/에러 구조 재확정, 1차 사용 API/feature 매핑 문서화 | 계약 문서와 코드 구조 정렬 |
+| Phase 5 | 진행 중 | feature별 분리형 구조 고정 | remote data source, repository interface, mock implementation 정리 | mock/real 전환 가능한 구조 확보 |
+| Phase 6 | 완료 | 실제 API 응답 정합성 점검 | 로그인, directory, organization smoke 및 integration 확인 | 핵심 응답 필드 일치 확인 |
+| Phase 7 | 진행 중 | staging 반영 검토 준비 | 승인 완료 E2E, 예외 케이스, 수동 체크리스트 정리, API 공백 이슈 분리 | staging 검토 가능 상태 및 API 보강 요청 초안 |
+| Phase 7-A | 진행 중 | 직원검색/조직도 시인성 보정 | 선택 상태가 눈에 띄는 칩 표현, 스크롤 가능한 칩 탐색, 조직도 인원 정렬 규칙 반영 | 캡쳐 요청사항 반영 및 widget test |
+| Phase 7-B | 진행 중 | 직원검색 규칙/프로필 표현 보강 | 검색 입력 최소 조건, 선택 범위 내 검색 원칙, 프로필 사진 노출 가능 구조 반영 | 정책 반영 및 emulator 확인 |
+| Phase 7-C | 진행 중 | 프로필 사진 식별자 매핑 검토 | 네이버웍스 우선, Baron SSO `members[].id` 기반 UUID 파일명 이미지 2순위, 앱 기본 아바타 3순위 구조를 기준으로 실제 매핑 가능 조건과 파일 재배치/앱 연동 기준을 정리 | UUID 매핑 CSV, 샘플 URL 검증, 앱 공통 resolver 정리 |
+| Phase 7-D | 진행 중 | 입력기/구분 표식 보정 | 직원검색 입력기의 한글 입력 친화 설정과 상하 영역 구분 표식 반영 | emulator 확인 및 사용성 점검 |
+| Phase 7-E | 진행 중 | 초기 선택 scope 재정렬 | 첫 진입 시 본인 팀을 실제 선택 상태로 맞추고 불필요한 중앙 아이콘 제거 | emulator 확인 및 정책 일치 |
+| Phase 7-F | 진행 중 | 공기계 USB 테스트 전환 | 실기기 연결 preflight, `adb reverse`, 실기기 env, 수동 실행 경로를 추가하고 emulator 경로는 fallback으로 보존 | 공기계에서 수동 post-login 점검 가능 |
+| Phase 7-G | 진행 중 | USB 없는 독립형 실기기 테스트 전환 | 공기계/실폰이 로컬 PC 연결 없이도 staging 또는 production Baron API에 직접 붙도록 공개 API base URL, HTTPS, headless 승인 로그인, APK 실행값을 정리 | USB 분리 후에도 앱이 실서버 기준으로 로그인/직원검색 가능 |
+| Phase 7-H | 진행 중 | 레거시 전용 API 흔적 단계적 제거 | 전용 API 가정 path와 Baron 종속 DTO를 `유지/교체/제거`로 분류하고, 각 단계마다 로그인/직원검색/조직도 기능 보존 테스트를 수행 | Swagger 기준 재매핑 후 기능 유지 상태 확보 |
+| Phase 7-I | 진행 중 | 등록된 Baron SSO RP와 앱 연결 | PKCE 공개 클라이언트 설정, HTTPS callback 수신, state 검증, authorization code 교환을 Hosted Login callback에 연결 | 실기기에서 SSO 로그인 완료 후 앱 세션 생성 |
+| Phase 7-J | 진행 중 | 로그인 후 조직도 API 키 수신 준비 | Baron SSO 로그인 성공 응답/후속 session 응답에서 org-context credential을 받을 수 있게 앱 모델을 확장하고, 미개발 동안 staging 고정 키 fallback을 유지 | session credential 우선, env fallback 보장 |
+| Phase 8 | 대기 | 빌드/배포 준비 | APK, 실행 문서, 잔여 이슈 정리 | 배포 준비 산출물 확보 |
+
+## 4. 현재 진행 상태
+
+완료된 핵심 항목:
+
+- Flutter 앱 기본 프로젝트 및 테스트 기반 구성
+- 직원검색/조직도/상세/즐겨찾기 mock 화면 구축
+- auth, directory, organization API client 및 repository 초안 구성
+- 세션 저장/복원 흐름 구현
+- Baron SSO Hosted Login + PKCE callback 수신 경로 반영
+- 분리형 API 전환 정책 문서 수립
+- 개발 정책, API 계약, 테스트 정책 개정
+- 1차 사용 API 및 auth/directory/organization feature 매핑 문서화
+
+진행 중 핵심 항목:
+
+- Swagger 기준 실제 사용 API 목록 재정리
+- Hosted Login + PKCE 기준 실제 응답 정합성 점검
+- directory/organization 응답의 실제 데이터 정합성 검토
+- feature별 remote/mock 구조 정리
+- organization repository 추상화 추가 및 directory 직접 의존 완화
+- auth repository의 기본 경로와 fallback 경로 역할 분리
+- directory repository는 employees만, organization repository는 tenants만 담당하도록 1차 경계 분리
+- organization 상태 재사용은 `org-context` 중심으로 유지하고 공유 orgchart UI 연결은 후속 단계로 분리
+- `org-context` 전용 provider를 추가하고 실제 UI 연결은 후속 단계로 유지
+- auth/directory 구현체 명칭을 `Remote...Repository`로 일반화
+- 실제 API smoke와 Android emulator fallback integration smoke를 모두 통과했고, 당일 override 포트(`5561`) 기준 실행도 확인했다
+- Android integration 실행기는 현재 Flutter 버전 기준 `flutter drive` + `integration_test` driver 조합으로 정렬 완료했다
+- 조직 하위 subtree 응답 부재를 실제 API에서 확인했고, 앱 fallback 정책과 별도로 Baron SSO 보강 이슈를 문서화해 병행 진행한다
+- 직원검색/조직도 화면에 대해 선택 칩 시인성, overflow 스크롤, 조직도 인원 정렬 우선순위 보정 요청을 추가 반영 중이다
+- 직원검색 범위는 선택된 상단 뱃지 기준으로 유지하고, 최소 입력 규칙과 프로필 사진 표현 보강을 추가 반영 중이다
+- 프로필 사진은 현재 `profileImageUrl` 필드가 있으면 표현 가능하지만, 사번 기반 로컬/원격 이미지 매핑은 직원 DTO에 사번 식별자가 없어 추가 검토가 필요하다
+- 프로필 이미지 정책은 현재 `네이버웍스 우선 -> Baron SSO org-context UUID 파일명 이미지 -> 앱 기본 아바타` 기준으로 재정렬했다
+- 2026-07-20 기준 `tdc114plus-auth /api/v1/profile-image` route를 복구/보강하고, 네이버웍스 사진 원본 URL을 앱에 직접 주지 않도록 `/api/v1/profile-image/naver-photo` 프록시를 추가했다
+- 네이버웍스 `Location` 원본 URL은 앱이 직접 열 때 `400 Authentication failed`가 발생할 수 있으므로, 1순위 NAVER_WORKS 이미지는 중계서버 프록시를 통해 `image/jpeg` 바이너리로 제공한다
+- 2026-07-20 기준 실기기에서 기존에 기본 이니셜로 떨어지던 네이버웍스 사진 보유 인원의 이미지 표시가 정상화된 것을 확인했다
+- 같은 시점 서버 로그에서 `NAVER_WORKS`와 `BARON_UUID_R2` source가 모두 확인되어 1순위/2순위 분기 동작을 확인했다
+- 2026-07-15 기준 `org-context` 실응답에서 `members[].id`가 실제 UUID 형식으로 내려오는 것을 확인했다
+- 2026-07-15 기준 가족사 전체 `org-context`와 기존 CSV를 대조해 `2457/2457` 전건 UUID 매핑 성공을 확인했다
+- 관련 산출물로 `docs/references/profile_image_uuid_rename_candidates.csv`를 생성했다
+- 2026-07-15 기준 네이버웍스 서비스 계정 토큰 발급과 실제 User/Profile API 호출을 확인했다
+- 샘플 `khkang@samaneng.com`는 `GET /users/{userId}/photo` 결과 `HTTP 404`로 무사진 케이스를 확인했다
+- 샘플 `thlee3@samaneng.com`는 `GET /users/{userId}/photo` 결과 `HTTP 302`와 `Location` 헤더를 확인했다
+- 2026-07-15 기준 UUID 파일명 공개 URL 샘플 2건이 `HTTP 200 image/jpeg`로 응답하는 것을 확인했다
+- 기존 `tdc114plus-auth + PostgreSQL` profile-image fallback 경로는 기술 검증 자료로만 남기고, 현재 운영 기본안으로는 채택하지 않는다
+- 현재 Phase 7-C의 중심 작업은 `앱 공통 resolver를 새 우선순위로 정리`하고 `302 -> UUID -> 기본 아바타` fallback 분기를 연결하는 일이다
+- 2026-07-15 기준 Android 실기기 직원검색 화면에서 실제 프로필 사진 노출을 확인했다
+- 현재 앱은 `tdc114plus-auth /api/v1/profile-image`를 우선 호출하고, 응답 실패 또는 미발견 시 UUID 공개 경로 fallback을 사용하는 보조 안전장치를 함께 둔다
+- 2026-07-16 기준 실기기 로그인 후 직원검색이 다시 무너지는 핵심 원인은 `tdc114plus-auth` 5001 서버의 `org-context upstream self-recursion`이었다
+- 원인은 `scripts/start-auth-server.sh`가 `TDC114_AUTH_UPSTREAM_ORG_CONTEXT_API_BASE`를 env 파일 `source` 전에 읽던 순서 문제였고, 이 때문에 실행 중 `BARON_ORG_CONTEXT_BASE_URL`이 `http://127.0.0.1:5001`로 잘못 설정되었다
+- 2026-07-16 기준 해당 스크립트 순서를 수정하고 5001 재기동 후 실행 중 프로세스 환경값이 `BARON_ORG_CONTEXT_BASE_URL=https://sadmin.hmac.kr`로 반영된 것을 확인했다
+- 위 복구 이후 실기기에서 `로그인 성공 -> 직원검색 목록 표시 성공`까지 다시 확인했다
+- 직원검색 한글 입력은 코드상 차단 요소를 제거한 상태로 정렬하고, 상하 영역 구분 표식을 추가 반영 중이다
+- 초기 진입 선택 상태는 본인 팀 뱃지가 실제 선택되도록 재정렬 중이며, 중앙 구분 아이콘은 제거 방향으로 반영 중이다
+- Android emulator의 물리 키보드/ADB/portproxy 반복 장애가 확인되어, 공기계 USB 연결을 기본 수동 테스트 경로로 전환하는 작업을 시작한다
+- 공기계 USB 연결 기준으로는 실데이터 화면까지 확인했지만, 현재 실행 모드는 `adb reverse + http://127.0.0.1:5000` 기반 로컬 Baron API 연결이므로 USB 분리 후 독립 동작은 아직 보장하지 않는다
+- USB 없이 동작하는 실서버 APK 테스트로 가려면 `TDC114_API_BASE`를 staging 또는 production 공개 URL로 전환하고, headless 승인 로그인과 HTTPS 경로를 그 환경에서 다시 검증해야 한다
+- 2026-07-08 기준 앱/스크립트는 `TDC114_AUTH_API_BASE`, `TDC114_DIRECTORY_API_BASE`, `TDC114_ORGANIZATION_API_BASE` 분리 주입을 지원하므로 `로그인은 staging`, `직원/조직 데이터는 production` 조합까지 실행 준비가 되어 있다
+- 2026-07-10 기준 조직/직원 원본 참고 host는 staging `https://sadmin.hmac.kr`로 되돌린다. `admin.brsw.kr` production host는 현재 앱 개발 기준에서 우선 사용하지 않는다
+- 2026-07-10 기준 Baron SSO 로그인 성공 시 조직도 API 호출용 ID/Secret을 함께 내려주는 기능은 아직 미개발로 보고, 앱은 해당 값을 받을 준비만 먼저 한다
+- 해당 기능이 완성되기 전까지 조직/직원 데이터는 staging `org-context` endpoint와 로컬 비추적 env/Dart define의 고정 키 fallback으로 검증한다
+- 따라서 USB 없는 독립형 실기기 최종 검증의 현재 외부 blocker는 `신규앱 public TDC114_API_BASE` 확정이다
+- 2026-07-08 사용자 확인 기준으로는 `신규앱 public TDC114_API_BASE` 자체를 별도 `tdc114plus 전용 API host`로 찾는 방향이 아니라, Swagger에 공개된 Baron 기존 API path를 앱 데이터 소스로 직접 쓰는 방향으로 재정렬해야 한다
+- 따라서 현재 진짜 blocker는 `별도 host 탐색`이 아니라 `Swagger 공개 path 중 무엇이 직원검색/조직도/로그인에 대응하는지 endpoint 단위로 재매핑`하는 일이다
+- 그에 따라 현재 코드와 문서에 남아 있는 `/api/v1/tdc114plus/...` 전용 API 흔적은 레거시로 분류하고, 기능이 무너지지 않도록 테스트를 동반해 단계적으로 제거하는 것을 기본 작업원칙으로 추가한다
+- 2026-07-19 기준 배포 관점의 기준 구조를 다시 정리한다
+- `tdc114plus-auth`는 최종 배포 단위로 유지한다
+- `baron-sso-tdc114plus-api`는 현재 로컬 개발/검증용 worktree로만 취급하고, 배포 시점의 직접 필수 구성으로 보지 않는다
+- 최종적으로 신규앱은 Baron SSO 원본 `staging` 연동을 먼저 안정화하고, 이후 Baron SSO 원본 `production` 연동으로 승격하는 순서를 기본 정책으로 삼는다
+- 따라서 지금부터의 정리 작업은 `무엇을 tdc114plus-auth에 남길지`, `무엇을 Baron SSO 원본에 의존할지`, `무엇을 로컬 전용 임시 자산으로 볼지`를 분리하는 방향으로 진행한다
+
+대기 중 핵심 항목:
+
+- staging 승인 완료 E2E 검증
+- Android debug APK 빌드 및 실행 점검
+- 운영 전 저장소/보안 저장 방식 재검토
+
+## 5. 다음 작업
+
+다음 작업은 아래 순서로 진행한다.
+
+1. 앱 직원검색/조직도/상세 화면의 공통 resolver를 `네이버웍스 -> UUID 파일명 -> 기본 아바타` 순서로 정리한다.
+2. 네이버웍스 `302`, `404` 실응답 규칙을 `tdc114plus-auth` 프록시와 UUID fallback 분기에 연결한 상태를 유지 검증한다.
+3. 샘플 사용자 외에 `UUID 이미지 성공`, `UUID 이미지 없음`, `이메일 누락`, `DEFAULT 기본 아바타` 케이스를 추가 검증한다.
+4. 먼저 5001 auth broker의 실행 중 upstream 값이 `https://sadmin.hmac.kr`로 유지되는지 재확인한다.
+5. 실기기 검증 전 `adb reverse tcp:5001 tcp:5001`, `adb reverse tcp:5000 tcp:5000`이 유지되는지 확인한다.
+6. 로그인 후 30초 이상 세션이 유지되는지 다시 확인한다.
+7. 조직 하위 subtree API 보강 요청 이슈 초안을 정리하고 Baron SSO 개발자 검토용 명세를 확정한다.
+8. Swagger 공개 path 중 직원검색/조직도/로그인에 대응하는 실제 endpoint를 표로 다시 정리한다.
+9. 현재 코드의 `/api/v1/tdc114plus/...` 가정 path를 `유지`, `교체`, `폐기`로 분류한다.
+10. `교체` 대상으로 분류된 path부터 대체 Swagger path/DTO를 코드와 mock에 반영한다.
+11. 각 교체 단계마다 `로그인`, `직원검색`, `조직도`, `초기 선택 scope` 기능 보존 테스트를 수행한다.
+12. `org-context` 응답을 기준으로 현재 앱 화면 요소와 모델 필드를 1:1 매핑한 판단서를 만든다.
+13. staging 승인 완료 E2E와 예외 케이스 범위를 체크리스트로 구체화한다.
+14. Hosted Login + PKCE 기준 수동 검증 절차를 Baron SSO RP 설정 기준으로 재정렬한다.
+15. 검토 결과를 test log와 체크리스트에 반영한다.
+16. USB reverse 기반 로컬 실행과 별도로, 실제 공개 path를 사용한 독립형 실기기 APK 검증 단계를 실행한다.
+17. Baron SSO RP의 전체 Client ID를 `TDC114_OIDC_CLIENT_ID`로 주입하고 discovery 문서의 실제 endpoint와 일치하는지 확인한다.
+18. `https://114.hmac.kr/auth/callback`이 앱으로 연결되는 HTTPS App Link 설정과 `assetlinks.json`을 검증한다.
+19. callback의 `state`, authorization code, PKCE `code_verifier` 검증 및 token 교환을 구현한다.
+20. AuthSession에 선택적 `orgContextCredential` 구조를 추가한다.
+21. `org-context` API client가 `session credential -> staging env fallback` 순서로 인증값을 선택하도록 정리한다.
+22. Baron SSO Hosted Login 시작부터 callback 수신, 세션 저장, 직원검색 진입까지 실기기 E2E를 수행한다.
+23. 현재 `baron-sso-tdc114plus-api`에 남아 있는 기능을 `배포 필수`, `개발 중 임시`, `제거 가능`으로 분류한다.
+24. `배포 필수` 기능 중 `tdc114plus-auth`로 흡수 가능한 항목과 Baron SSO 원본 `staging/prod` 의존으로 남겨야 할 항목을 구분한다.
+25. 로컬 Baron worktree 없이도 신규앱이 배포 구조에서 동작할 수 있도록 최종 연동도와 점검표를 만든다.
+
+## 5-B. 2026-07-15 Phase 7-C 연속성 메모
+
+다음 작업 재개 시 우선 확인할 기준점은 아래와 같다.
+
+- 2순위 프로필 이미지 식별자는 Baron SSO `org-context`의 `members[].id`다.
+- 2026-07-15 기준 `members[].id`가 실제 UUID 형식으로 내려오는 것을 실조회로 확인했다.
+- 공개 이미지 prefix는 `https://baroncs.co.kr/employee_img/` 다.
+- 기존 매핑 원본은 `docs/references/file_rename_hash_results.csv` 다.
+- UUID 리네임 작업용 산출물은 `docs/references/profile_image_uuid_rename_candidates.csv` 다.
+- 2026-07-15 기준 기존 CSV `2457`건은 가족사 전체 `org-context` UUID와 전건 매핑 성공했다.
+- 2026-07-15 기준 UUID 파일명 공개 URL 샘플 2건은 `HTTP 200 image/jpeg` 응답을 확인했다.
+- 2026-07-15 기준 네이버웍스 사진 API는 `khkang@samaneng.com`에서 `404`, `thlee3@samaneng.com`에서 `302`를 확인했다.
+- 현재 운영 기본안은 `네이버웍스 -> UUID 파일명 이미지 -> 기본 아바타` 다.
+- 기존 `tdc114plus-auth + PostgreSQL` profile-image fallback 경로는 보류된 대안으로만 남긴다.
+- 2026-07-20 기준 네이버웍스 1순위 사진은 앱이 원본 `Location` URL을 직접 열지 않고 `tdc114plus-auth` 프록시를 통해 표시한다.
+- 2026-07-20 기준 `tdc114plus-auth`와 앱 테스트에서 1순위/2순위/3순위 fallback 및 NAVERWORKS 프록시 바이너리 응답을 검증했다.
+
+다음날 또는 네트워크 장애 후 재개 순서는 아래를 기본으로 한다.
+
+1. 5001 health와 `adb reverse 5001/5000`을 먼저 확인한다.
+2. 실기기에서 `NAVER_WORKS`, `BARON_UUID_R2`, `DEFAULT` source별 화면 검증을 확대한다.
+3. 직원 상세/조직도/즐겨찾기 화면에서도 동일 이미지 규칙이 유지되는지 확인한다.
+4. 필요 시 샘플 사용자 추가로 `{uuid}.jpg` 공개 URL 응답을 더 점검한다.
+
+## 5-C. 2026-07-09 Baron SSO RP 확정값
+
+| 항목 | 확정값/정책 |
+| --- | --- |
+| RP 유형 | PKCE 공개 클라이언트 |
+| OIDC issuer | `https://sso.hmac.kr/oidc` |
+| Discovery | `https://sso.hmac.kr/oidc/.well-known/openid-configuration` |
+| Authorization endpoint | `https://sso.hmac.kr/oidc/oauth2/auth` |
+| Token endpoint | `https://sso.hmac.kr/oidc/oauth2/token` |
+| UserInfo endpoint | `https://sso.hmac.kr/oidc/userinfo` |
+| Redirect URI | `https://114.hmac.kr/auth/callback` |
+| Client ID | `39d6190d-72f6-4a58-a84f-cdc5ece3e8af`를 APK 기본 설정에 포함하고 환경별로 `TDC114_OIDC_CLIENT_ID` 재정의 가능 |
+| Client Secret | 사용 금지. PKCE 앱에는 Client Secret이 없음 |
+
+현재 반영 상태:
+
+- Android callback host를 `114.hmac.kr`로 변경했다.
+- callback 화면과 `/auth/callback` 앱 라우트는 수신 준비 상태다.
+- OIDC issuer, redirect URI, Client ID 환경 주입 항목을 추가했다.
+- authorization 요청 생성, PKCE verifier 보관, code 교환은 다음 구현 단계다.
+- `114.hmac.kr` 서버의 Android App Link 위임 파일(`/.well-known/assetlinks.json`)이 준비되기 전에는 HTTPS 링크가 앱 대신 브라우저에서 열릴 수 있다.
+- 2026-07-09 최신 debug APK를 공기계에 설치하고 callback URL을 실행했으며, Android 앱 선택창이 표시되는 것까지 확인했다.
+- debug APK의 package/SHA-256 지문을 기준으로 `docs/references/assetlinks.debug.json`을 생성했다.
+- `https://114.hmac.kr/.well-known/assetlinks.json` 배포는 임시 Windows 테스트 서버 방식으로 검증한다.
+- 2026-07-09 임시 Windows 테스트 서버에서 `assetlinks.json`을 제공하고 외부 HTTPS HTTP 200/JSON 응답을 확인했다.
+- 구형 공기계는 자동 App Link 상태가 `undefined`여서 테스트 기본 앱을 지정했으며, callback URL이 TDC114PLUS `.MainActivity`를 직접 열고 `test-code`를 수신하는 것까지 확인했다.
+- RP 전체 Client ID를 APK 기본 설정에 반영했다.
+- 다음 작업은 authorization 요청 생성과 PKCE code 교환 구현이다.
+- 공식 headless API는 `private_key_jwt client_assertion`을 필수 요구하지만 등록 RP는 PKCE 공개 앱이므로, Flutter 앱의 기본 로그인 경로에서는 해당 API를 직접 호출하지 않는다.
+- 표준 PKCE 생성, state 검증, token 교환 계층을 우선 구현한다.
+
+## 5-D. Phase 7-C 프로필 사진 식별자 매핑 검토 초안
+
+현재 신규앱은 프로필 사진 파일을 자체 보관하지 않고, 외부 공개 경로의 이미지를 화면에 표시하는 방향을 기본 전제로 둔다.
+
+현재 채택안의 핵심은 아래와 같다.
+
+- 앱은 더 이상 `이메일 @앞부분.jpg` 파일명을 직접 만들지 않는다.
+- 앱은 해시 파일명도 직접 계산하지 않는다.
+- 2순위 프로필 이미지는 Baron SSO 조직도 `members[].id`를 파일명으로 사용하는 UUID 이미지다.
+- 공개 경로는 `https://baroncs.co.kr/employee_img/{uuid}.jpg` 규칙으로 고정한다.
+- 1순위는 네이버웍스, 3순위는 앱 기본 아바타다.
+
+### 1. 목표
+
+- 내부 파일명 규칙을 앱과 URL에서 직접 노출하지 않는다.
+- 기존 이미지 자산을 전면 재가공하지 않고도 단계적으로 재사용 가능하게 만든다.
+- 직원검색, 조직도, 직원 상세 화면에서 동일한 규칙으로 프로필 이미지를 노출한다.
+- 이미지가 없거나 매핑이 실패해도 기본 아바타로 안전하게 fallback 한다.
+
+### 2. 외부서버(테이블) 측 단계별 작업 초안
+
+1. 기존 이미지 파일을 Baron UUID 기준 `[uuid].jpg` 로 변경한다.
+2. 변경된 파일을 `employee_img/` 하위에 재배치한다.
+3. 샘플 사용자 여러 건의 공개 URL 응답을 검증한다.
+4. 네이버웍스 1순위 경로와 UUID 이미지 2순위 경로의 fallback 순서를 앱과 서버 역할에 맞게 반영한다.
+5. 이메일 변경이나 인사 이동이 생겨도 UUID 기준 파일명 정책이 유지되는지 운영 절차를 정리한다.
+
+### 3. 신규앱 측 단계별 작업 초안
+
+1. 현재 직원 DTO와 `org-context` 응답에서 `member.id`를 안정적으로 확보할 수 있는지 유지 확인한다.
+2. 앱은 `member.id` 또는 그와 동등한 Baron UUID를 이용해 2순위 이미지 URL을 만든다.
+   2026-07-15 기준 앱 공통 resolver에서 기존 `GET /api/v1/profile-image` fallback 의존을 제거하고, `profileImageUrl -> https://baroncs.co.kr/employee_img/{uuid}.jpg -> 기본 아바타` 규칙으로 정리했다.
+3. 앱은 더 이상 이메일 기반 또는 해시 기반 파일명을 만들지 않는다.
+4. 화면별 fallback 처리
+   이미지 조회 실패, key 누락, 외부서버 404, timeout 상황에서는 기본 아바타를 노출한다.
+   프로필 사진 실패 때문에 직원검색/조직도 본문 데이터가 깨지거나 로딩이 멈추지 않도록 분리 처리한다.
+
+5. 캐시 및 placeholder 정책 반영
+   검색 결과 목록과 조직도는 동일 이미지가 반복 노출될 수 있으므로, 앱 이미지 캐시와 placeholder 표시 규칙을 함께 정리한다.
+
+6. 테스트 시나리오 추가
+   최소 검증 항목은 아래와 같다.
+   - 네이버웍스 사진이 있을 때 1순위 이미지 노출
+   - UUID 이미지가 있을 때 2순위 이미지 노출
+   - UUID 이미지가 없을 때 기본 이미지 노출
+   - 응답 지연 또는 timeout 시 화면 본문 기능 유지
+   - 잘못된 사용자 이미지가 다른 직원에게 매핑되지 않는지 확인
+
+### 4. 현재 판단 기준
+
+- `이메일 @앞부분.jpg` 직접 조합 방식은 더 이상 채택하지 않는다.
+- 현재 기본안은 Baron SSO `members[].id` 기반 UUID 파일명 방식이다.
+- 가족사 전체 매핑 검증 결과 `2457/2457` 전건 대응이 확인됐으므로, 파일 재배치만 완료되면 운영 기준으로 사용할 수 있다.
+- 따라서 현재 Phase 7-C의 실질적 핵심은 `UUID 파일 실배치 완료`, `앱 공통 resolver 재정리`, 그리고 `tdc114plus-auth /api/v1/profile-image`를 `네이버웍스 -> UUID 이미지 -> 기본 아바타` 순서로 재정리한 뒤 실제 기동 검증까지 마무리하는 것이다.
+
+### 5. 후속 확인 필요 항목
+
+- 네이버웍스 개발자 계정 기준 실제 `GET /users/{userId}/photo` 응답 규칙
+- UUID 파일 재배치 완료 후 공개 URL 반영 시점
+- 퇴사자/미등록자 이미지 처리 기준
+- Baron UUID가 장기적으로 변경되지 않는지 운영 측 확인
+
+## 5-A. 공기계 USB 테스트 전환 작업 순서
+
+공기계 전환은 아래 순서로 진행한다. 예상 소요는 정책/스크립트 보강 20~30분, 실제 단말 연결 검증 10~20분이다.
+
+1. 정책과 타임테이블에 공기계 USB 테스트 전환 단계를 먼저 반영한다.
+2. 실기기 전용 env 예시(`scripts/android-device.env.example`)를 추가한다.
+3. 실기기 preflight 스크립트(`scripts/check-android-device-env.sh`)를 추가한다.
+4. Windows ADB server 공유 방식에서 물리 단말이 `device`로 보이는지 확인한다.
+5. `adb reverse tcp:5000 tcp:5000`을 우선 적용하고, 실패하면 PC LAN IP 방식으로 fallback 한다.
+6. `manual-postlogin-run.sh`로 수동 기능점검을 먼저 안정화한다.
+7. 수동 점검이 통과하면 `integration_tests.sh`를 공기계 target으로 확장한다.
+8. 검증 결과를 test log와 관련 정책 문서에 기록한다.
+
+## 5-B. USB 없는 독립형 실기기 테스트 전환 작업 순서
+
+공기계에 앱이 설치되어 있어도, 현재처럼 `TDC114_API_BASE=http://127.0.0.1:5000`을 쓰는 실행 모드라면 USB를 뽑는 순간 로컬 Baron API 경로가 끊긴다. USB 없이도 동작하려면 아래 단계가 필요하다. 예상 소요는 환경 정리 20~30분, 실서버 APK 1차 검증 30~60분이다.
+
+1. 실행 모드를 둘로 분리해 문서에 고정한다.
+   - `로컬 개발 모드`: `adb reverse + http://127.0.0.1:5000`
+   - `독립 실행 모드`: `https://<staging-or-production-host>`
+2. staging 또는 production 중 실제 실기기 검증에 사용할 Baron API base URL을 확정한다.
+3. 해당 환경에서 `headless phone-login`, `link/poll`, `integrations/org-context`, `public/orgchart`가 모두 공개 HTTPS 경로에서 정상 동작하는지 확인한다.
+4. 실기기 APK 전용 env 파일을 분리한다.
+   - 예: `scripts/.env.android-device.staging.local`
+   - 예: `scripts/.env.android-device.production.local`
+5. 로그인과 데이터 host를 분리해야 하면 아래 override를 함께 준비한다.
+   - `TDC114_AUTH_API_BASE`
+   - `TDC114_DIRECTORY_API_BASE`
+   - `TDC114_ORGANIZATION_API_BASE`
+6. `manual-postlogin-run.sh` 또는 별도 실행 스크립트에서 실서버 URL과 필요한 override를 주입해 APK를 다시 설치한다.
+7. USB 연결 상태에서 1차 설치와 실행만 수행하고, 앱이 실행된 뒤 USB를 분리한다.
+8. USB 분리 후에도 Wi-Fi만으로 로그인, 직원검색, 조직도 조회가 유지되는지 확인한다.
+9. 실사용 폰 설치 전에는 아래를 추가 확인한다.
+   - 앱 아이콘/앱명/버전 표기
+   - cleartext 미사용 여부
+   - staging/production 혼선이 없는지
+   - headless 승인 로그인 수신 채널(문자/메일) 실제 도달 여부
+10. 실사용 폰 테스트 단계에서는 APK 전달, 설치, 로그인 승인, 검색/조직도/전화/문자 동작까지 한 번의 시나리오로 점검한다.
+
+## 6. 작업 기록 원칙
+
+- 새 작업이 생기면 본 문서의 `작업진행 절차` 또는 `다음 작업`에 반영한다.
+- 완료된 작업은 상태를 갱신하고 산출물 위치를 기록한다.
+- 중요 실행 결과는 `docs/test-logs/` 또는 `docs/daily-issues/`에 남긴다.
+- 과거 세부 이력은 보존하되, 현재 실행 기준은 본 문서의 최신 Phase 상태를 따른다.