kevin/tdc114plus

Fork 0

Files

T

Codex cb36612b88 Move external secrets behind auth broker

2026-07-20 14:19:55 +09:00

35 KiB

Raw Blame History

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-20 기준 앱에는 Baron org-context key와 NAVER WORKS secret을 주입하지 않는다. 해당 값은 tdc114plus-auth 서버 env에서만 관리하고, 앱은 중계서버 URL과 앱 세션 token만 사용한다
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. 다음 작업

다음 작업은 아래 순서로 진행한다.

앱 직원검색/조직도/상세 화면의 공통 resolver를 네이버웍스 -> UUID 파일명 -> 기본 아바타 순서로 정리한다.
네이버웍스 302, 404 실응답 규칙을 tdc114plus-auth 프록시와 UUID fallback 분기에 연결한 상태를 유지 검증한다.
샘플 사용자 외에 UUID 이미지 성공, UUID 이미지 없음, 이메일 누락, DEFAULT 기본 아바타 케이스를 추가 검증한다.
먼저 5001 auth broker의 실행 중 upstream 값이 https://sadmin.hmac.kr로 유지되는지 재확인한다.
실기기 검증 전 adb reverse tcp:5001 tcp:5001, adb reverse tcp:5000 tcp:5000이 유지되는지 확인한다.
로그인 후 30초 이상 세션이 유지되는지 다시 확인한다.
조직 하위 subtree API 보강 요청 이슈 초안을 정리하고 Baron SSO 개발자 검토용 명세를 확정한다.
Swagger 공개 path 중 직원검색/조직도/로그인에 대응하는 실제 endpoint를 표로 다시 정리한다.
현재 코드의 /api/v1/tdc114plus/... 가정 path를 유지, 교체, 폐기로 분류한다.
교체 대상으로 분류된 path부터 대체 Swagger path/DTO를 코드와 mock에 반영한다.
각 교체 단계마다 로그인, 직원검색, 조직도, 초기 선택 scope 기능 보존 테스트를 수행한다.
org-context 응답을 기준으로 현재 앱 화면 요소와 모델 필드를 1:1 매핑한 판단서를 만든다.
staging 승인 완료 E2E와 예외 케이스 범위를 체크리스트로 구체화한다.
Hosted Login + PKCE 기준 수동 검증 절차를 Baron SSO RP 설정 기준으로 재정렬한다.
검토 결과를 test log와 체크리스트에 반영한다.
USB reverse 기반 로컬 실행과 별도로, 실제 공개 path를 사용한 독립형 실기기 APK 검증 단계를 실행한다.
Baron SSO RP의 전체 Client ID를 TDC114_OIDC_CLIENT_ID로 주입하고 discovery 문서의 실제 endpoint와 일치하는지 확인한다.
https://114.hmac.kr/auth/callback이 앱으로 연결되는 HTTPS App Link 설정과 assetlinks.json을 검증한다.
callback의 state, authorization code, PKCE code_verifier 검증 및 token 교환을 구현한다.
AuthSession에 선택적 orgContextCredential 구조를 추가한다.
org-context API client가 session credential -> staging env fallback 순서로 인증값을 선택하도록 정리한다.
Baron SSO Hosted Login 시작부터 callback 수신, 세션 저장, 직원검색 진입까지 실기기 E2E를 수행한다.
현재 baron-sso-tdc114plus-api에 남아 있는 기능을 배포 필수, 개발 중 임시, 제거 가능으로 분류한다.
배포 필수 기능 중 tdc114plus-auth로 흡수 가능한 항목과 Baron SSO 원본 staging/prod 의존으로 남겨야 할 항목을 구분한다.
로컬 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 프록시 바이너리 응답을 검증했다.

다음날 또는 네트워크 장애 후 재개 순서는 아래를 기본으로 한다.

5001 health와 adb reverse 5001/5000을 먼저 확인한다.
실기기에서 NAVER_WORKS, BARON_UUID_R2, DEFAULT source별 화면 검증을 확대한다.
직원 상세/조직도/즐겨찾기 화면에서도 동일 이미지 규칙이 유지되는지 확인한다.
필요 시 샘플 사용자 추가로 {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. 외부서버(테이블) 측 단계별 작업 초안

기존 이미지 파일을 Baron UUID 기준 [uuid].jpg 로 변경한다.
변경된 파일을 employee_img/ 하위에 재배치한다.
샘플 사용자 여러 건의 공개 URL 응답을 검증한다.
네이버웍스 1순위 경로와 UUID 이미지 2순위 경로의 fallback 순서를 앱과 서버 역할에 맞게 반영한다.
이메일 변경이나 인사 이동이 생겨도 UUID 기준 파일명 정책이 유지되는지 운영 절차를 정리한다.

3. 신규앱 측 단계별 작업 초안

현재 직원 DTO와 org-context 응답에서 member.id를 안정적으로 확보할 수 있는지 유지 확인한다.
앱은 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 -> 기본 아바타 규칙으로 정리했다.
앱은 더 이상 이메일 기반 또는 해시 기반 파일명을 만들지 않는다.
화면별 fallback 처리 이미지 조회 실패, key 누락, 외부서버 404, timeout 상황에서는 기본 아바타를 노출한다. 프로필 사진 실패 때문에 직원검색/조직도 본문 데이터가 깨지거나 로딩이 멈추지 않도록 분리 처리한다.
캐시 및 placeholder 정책 반영 검색 결과 목록과 조직도는 동일 이미지가 반복 노출될 수 있으므로, 앱 이미지 캐시와 placeholder 표시 규칙을 함께 정리한다.
테스트 시나리오 추가 최소 검증 항목은 아래와 같다.
- 네이버웍스 사진이 있을 때 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분이다.

정책과 타임테이블에 공기계 USB 테스트 전환 단계를 먼저 반영한다.
실기기 전용 env 예시(scripts/android-device.env.example)를 추가한다.
실기기 preflight 스크립트(scripts/check-android-device-env.sh)를 추가한다.
Windows ADB server 공유 방식에서 물리 단말이 device로 보이는지 확인한다.
adb reverse tcp:5000 tcp:5000을 우선 적용하고, 실패하면 PC LAN IP 방식으로 fallback 한다.
manual-postlogin-run.sh로 수동 기능점검을 먼저 안정화한다.
수동 점검이 통과하면 integration_tests.sh를 공기계 target으로 확장한다.
검증 결과를 test log와 관련 정책 문서에 기록한다.

5-B. USB 없는 독립형 실기기 테스트 전환 작업 순서

공기계에 앱이 설치되어 있어도, 현재처럼 TDC114_API_BASE=http://127.0.0.1:5000을 쓰는 실행 모드라면 USB를 뽑는 순간 로컬 Baron API 경로가 끊긴다. USB 없이도 동작하려면 아래 단계가 필요하다. 예상 소요는 환경 정리 20~~30분, 실서버 APK 1차 검증 30~~60분이다.

실행 모드를 둘로 분리해 문서에 고정한다.
- 로컬 개발 모드: adb reverse + http://127.0.0.1:5000
- 독립 실행 모드: https://<staging-or-production-host>
staging 또는 production 중 실제 실기기 검증에 사용할 Baron API base URL을 확정한다.
해당 환경에서 headless phone-login, link/poll, integrations/org-context, public/orgchart가 모두 공개 HTTPS 경로에서 정상 동작하는지 확인한다.
실기기 APK 전용 env 파일을 분리한다.
- 예: scripts/.env.android-device.staging.local
- 예: scripts/.env.android-device.production.local
로그인과 데이터 host를 분리해야 하면 아래 override를 함께 준비한다.
- TDC114_AUTH_API_BASE
- TDC114_DIRECTORY_API_BASE
- TDC114_ORGANIZATION_API_BASE
manual-postlogin-run.sh 또는 별도 실행 스크립트에서 실서버 URL과 필요한 override를 주입해 APK를 다시 설치한다.
USB 연결 상태에서 1차 설치와 실행만 수행하고, 앱이 실행된 뒤 USB를 분리한다.
USB 분리 후에도 Wi-Fi만으로 로그인, 직원검색, 조직도 조회가 유지되는지 확인한다.
실사용 폰 설치 전에는 아래를 추가 확인한다.
- 앱 아이콘/앱명/버전 표기
- cleartext 미사용 여부
- staging/production 혼선이 없는지
- headless 승인 로그인 수신 채널(문자/메일) 실제 도달 여부
실사용 폰 테스트 단계에서는 APK 전달, 설치, 로그인 승인, 검색/조직도/전화/문자 동작까지 한 번의 시나리오로 점검한다.

6. 작업 기록 원칙

새 작업이 생기면 본 문서의 작업진행 절차 또는 다음 작업에 반영한다.
완료된 작업은 상태를 갱신하고 산출물 위치를 기록한다.
중요 실행 결과는 docs/test-logs/ 또는 docs/daily-issues/에 남긴다.
과거 세부 이력은 보존하되, 현재 실행 기준은 본 문서의 최신 Phase 상태를 따른다.

35 KiB Raw Blame History