Stabilize auth flow and profile images

docs/daily-issues/2026-07-03.md

@@ -0,0 +1,73 @@
+# 2026-07-03 작업 이슈 및 처리내역
+
+## 목적
+
+당일 작업 중 실제로 확인한 이슈, 처리 내용, 검증 결과, 남은 후속 작업을 기록한다.
+
+## 이슈 1. 외부 org-context 직원 필터의 회사 subtree 누락
+
+- 현상:
+  - `GET /api/v1/tdc114plus/directory/employees?tenantSlug=hanmac` 호출 시 최초에는 1명만 반환됐다.
+- 원인:
+  - 외부 `org-context` 기준 `tenantSlug` 필터가 회사 하위 조직 subtree가 아니라 direct match 위주로 처리되고 있었다.
+- 처리:
+  - Baron backend `tdc114plus_handler.go`에서 외부 직원 필터를 ancestor/subtree 기준으로 보정했다.
+  - 관련 handler test를 추가/보강했다.
+- 검증:
+  - backend rebuild 후 `tenantSlug=hanmac` 결과가 `total=339`로 증가한 것을 실제 API로 확인했다.
+- 후속:
+  - 실제 앱 초기 범위와 체감 성능 기준으로 추가 정합성 확인이 남아 있다.
+
+## 이슈 2. 초기 범위를 회사보다 더 좁은 조직 slug로 축소 필요
+
+- 현상:
+  - 일부 가족사는 직원 수가 1000명 이상일 수 있어 회사 단위 초기 조회도 무거울 수 있다.
+- 판단:
+  - 조직도 예시의 `name`, `slug` 조합은 팀/부서 단위 조직 slug로 볼 수 있다.
+- 처리:
+  - 앱에서 로그인 사용자 회사 범위 안에서 자기 전화번호/이름으로 본인을 다시 검색해 실제 조직 slug를 식별하도록 구현했다.
+- 검증:
+  - 실제 smoke 로그인 사용자 `문형석 / +821091365338`는 `tenantSlug=hanmac` 범위 재검색 시 조직 slug `is-3`, 조직명 `IS3`으로 식별됐다.
+  - `tenantSlug=is-3` 기준 실제 직원목록은 총 6명으로 확인됐다.
+- 후속:
+  - 초기 조직 slug 식별 실패 시 회사 slug fallback이 계속 적절한지 추가 확인이 필요하다.
+
+## 이슈 3. Android emulator integration test의 NDK/CMake license blocker
+
+- 현상:
+  - Android integration test 실행 시 `ndk;28.2.13676358` license 미승인으로 `assembleDebug`가 실패했다.
+- 처리:
+  - `scripts/flutter-docker.sh`에 Android SDK license 선행 승인 로직을 추가했다.
+  - Docker cache 아래 Android SDK `licenses`, `ndk`, `cmake` 디렉터리가 유지되도록 재사용 경로를 활용했다.
+- 검증:
+  - 재실행 시 NDK/CMake license가 승인되고 실제 설치가 완료됐다.
+  - 이후 Android emulator integration test가 끝까지 통과했다.
+- 후속:
+  - 첫 Android 빌드 시간이 여전히 길어 추가 warm-up 또는 캐시 최적화 여지는 있다.
+
+## 이슈 4. 홈화면 직원목록 실제 노출 검증
+
+- 목표:
+  - 전화번호 로그인 후 홈화면에 본인 팀 소속 직원목록이 실제로 표시되는지 확인한다.
+- 처리:
+  - integration test에 실제 API 로그인 후 홈화면에서 `검색 결과`, `문형석`, `IS3` 노출을 확인하는 검증을 추가했다.
+- 검증:
+  - Android emulator integration test에서 실제 API 로그인 후 `직원검색`, `검색 결과`, `문형석`, `IS3`가 노출되는 것을 확인했다.
+  - 결과적으로 홈화면 직원목록 노출 목표를 당일 기준 달성했다.
+- 후속:
+  - 조직도 탭 표현과 정렬/요약 표시의 세부 UX 검토는 다음 작업 후보로 남는다.
+
+## 이슈 5. 다음 출근 시 기동 확인 및 복구 절차 필요
+
+- 배경:
+  - 퇴근 시 VS Code, 터미널, Android emulator를 모두 종료하면 다음 출근 시 어떤 순서로 기동 확인과 복구를 해야 하는지 빠르게 참고할 문서가 필요하다.
+- 처리:
+  - `docs/checklist_morning_startup_runtime_2026-07-03.md` 문서를 추가했다.
+- 포함 내용:
+  - Baron runtime 확인
+  - API smoke 확인
+  - Android emulator/device 인식 확인
+  - integration test 실행
+  - 실패 시 복구 순서
+- 후속:
+  - 실제 다음 출근 시 이 문서로 재개하면서 부족한 부분이 있으면 보완한다.

docs/daily-issues/2026-07-14_work_handoff.md

@@ -0,0 +1,193 @@
+# 2026-07-14 업무 인계 메모
+
+작성 시각: 2026-07-14 16:54 KST
+
+## 오늘 최종 상태
+
+- 실기기 로그인 흐름은 Baron SSO 공식 정책에 맞춰 동작 확인했다.
+- 사용자는 앱에서 전화번호 입력 후 문자 링크를 받는다.
+- 문자 링크를 누르면 Chrome에서 Baron SSO 승인 완료 화면에 머문다.
+- 사용자가 직접 TDC114PLUS 앱으로 돌아오면 앱이 저장된 pendingRef로 poll을 재개하고 직원검색 메인 화면에 진입한다.
+- Baron SSO 정책상 문자 링크 클릭 후 Chrome이 자동으로 앱으로 돌아오는 기능은 현재 지원되지 않는다.
+- 직원검색 화면의 직원/조직 정보 호출은 `tdc114plus-auth` 5001 서버의 `/api/v1/integrations/org-context`를 사용한다.
+- 실기기에서 직원목록 표시 확인 완료:
+  - IS3 중복 뱃지 제거 확인
+  - 전화번호 `010-0000-0000` 형식 표시 확인
+  - 직원목록 표시 확인
+
+## 오늘 발생한 주요 이슈
+
+### 1. 로그인 승인 후 앱 복귀 UX
+
+현상:
+- 문자 링크 클릭 후 Chrome의 `로그인 승인 완료` 화면에 머물렀다.
+- 사용자가 `로그인 창으로 이동하기` 버튼을 누르면 Baron SSO 로그인창/대시보드 흐름으로 이동해 앱 메인 진입 흐름과 맞지 않았다.
+
+확인된 정책:
+- Baron SSO 개발자 답변 기준, `/api/v1/auth/headless/link/init`에는 post-verify redirect 필드가 없다.
+- SMS 링크를 누른 브라우저는 verify-only approver로 동작한다.
+- 승인 완료 후 브라우저가 앱 callback/App Link로 자동 이동하는 정책은 없다.
+
+현재 대응:
+- 앱 문구를 “문자 승인 후 앱으로 돌아오면 자동 로그인됩니다” 흐름으로 맞췄다.
+- 앱 복귀 시 저장된 pendingRef로 poll을 재개하도록 처리했다.
+
+내일 확인할 것:
+- 사용자가 앱 복귀 시 즉시 메인으로 들어가는지 반복 테스트한다.
+- 자동 앱 복귀가 꼭 필요하면 Baron SSO 쪽 정책/기능 추가 요청 사안으로 분리한다.
+
+### 2. `auth_provider_unavailable`
+
+현상:
+- 로그인 화면에서 `승인 상태 확인 실패: auth_provider_unavailable` 발생.
+
+원인:
+- 5001 `tdc114plus-auth` 서버가 Baron SSO `link/poll` 완료 후 OIDC redirect/consent/token exchange를 처리하는 구간에서 실패할 수 있었다.
+- 이후 서버를 최신 소스 기준으로 재기동하고 로그를 직접 확인했다.
+
+확인 로그:
+- `link/init` 성공
+- `link/poll` pending 반복
+- `link/poll status=ok`
+- `/consent` redirect 감지
+- consent accept 성공
+- callback URL에 code 포함
+- token exchange 성공
+
+결론:
+- 최신 `tdc114plus-auth` 소스와 올바른 환경값으로 실행하면 login -> poll -> consent -> token exchange는 정상 동작한다.
+
+### 3. 직원검색 화면 로딩 지속
+
+현상:
+- 직원검색 화면에 진입했지만 중앙 로딩만 표시되고 직원목록이 나오지 않았다.
+
+확인:
+- 5001 서버 로그에 `GET /api/v1/integrations/org-context`가 여러 번 찍혔다.
+- 즉 앱이 직원/조직 API를 호출하지 않은 것이 아니라, 호출은 하고 있었다.
+
+원인:
+- 5001 auth 서버를 수동 재기동하면서 조직도 연동 키 환경값을 빠뜨렸다.
+- 누락된 값:
+  - `BARON_ORG_CONTEXT_KEY_ID`
+  - `BARON_ORG_CONTEXT_KEY_SECRET`
+
+조치:
+- `scripts/.env.android-device.local`에 있는 값을 기준으로 5001 서버를 기동하도록 자동화했다.
+- 새 스크립트 추가:
+  - `scripts/start-auth-server.sh`
+- `scripts/startup.sh`에서 업무시작 시 `start-auth-server.sh --restart`를 자동 호출하도록 연결했다.
+- `scripts/shutdown.sh`에서 5001 auth 서버도 종료하도록 연결했다.
+- `scripts/.env.android-device.local`, staging env 파일 권한을 `600`으로 조정했다.
+
+검증:
+
+```bash
+./scripts/start-auth-server.sh --restart
+curl -fsSL --max-time 5 http://127.0.0.1:5001/health
+```
+
+응답:
+
+```json
+{"jwks":"ok","provider":"baron","status":"ok"}
+```
+
+실기기 화면:
+- 직원검색 화면에서 직원목록 정상 표시 확인.
+
+## 내일 업무 시작 순서
+
+1. Windows 관리자 PowerShell에서 ADB portproxy/방화벽 상태 확인이 필요하면 기존 절차대로 확인한다.
+2. Windows 일반 PowerShell에서 실기기 ADB 연결 확인:
+
+```powershell
+cd $env:LOCALAPPDATA\Android\Sdk\platform-tools
+.\adb.exe devices
+```
+
+3. WSL에서 업무시작 기동:
+
+```bash
+ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/startup.sh --auto --wait=40
+```
+
+4. 5001 auth 서버 확인:
+
+```bash
+curl -fsSL --max-time 5 http://127.0.0.1:5001/health
+```
+
+정상 기준:
+
+```json
+{"jwks":"ok","provider":"baron","status":"ok"}
+```
+
+5. 실기기 reverse 확인:
+
+```bash
+ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/flutter-docker.sh adb -s R5CT42QTCNX reverse --list
+```
+
+필수:
+
+```text
+tcp:5000 tcp:5000
+tcp:5001 tcp:5001
+```
+
+6. 앱 실행 후 확인:
+   - 로그인 세션이 남아 있으면 직원검색 화면 진입
+   - 직원목록이 바로 표시되는지 확인
+   - 로딩이 지속되면 5001 로그 확인
+
+```bash
+tail -n 120 logs/$(date +%F)/tdc114plus-auth.log
+```
+
+## 내일 우선 점검할 항목
+
+- `startup.sh`가 `start-auth-server.sh --restart`를 정상 호출하는지 확인한다.
+- 직원검색 화면 진입 시 `GET /api/v1/integrations/org-context`가 5001 로그에 찍히는지 확인한다.
+- 직원목록 로딩이 다시 멈추면 가장 먼저 아래를 확인한다:
+  - 5001 health
+  - `scripts/.env.android-device.local` 존재 여부
+  - `TDC114_BARON_KEY_ID`, `TDC114_BARON_KEY_SECRET` 값 누락 여부
+  - adb reverse `tcp:5001 tcp:5001`
+
+## 오늘 변경된 주요 파일
+
+- `scripts/start-auth-server.sh`
+  - 5001 `tdc114plus-auth` 로컬 서버 기동 스크립트.
+  - `scripts/.env.android-device.local`에서 조직도 키를 읽어 `BARON_ORG_CONTEXT_*`로 주입한다.
+
+- `scripts/startup.sh`
+  - 업무시작 기동 시 `tdc114plus-auth` 5001 서버를 자동 기동하도록 연결.
+
+- `scripts/shutdown.sh`
+  - 업무종료 시 5001 auth 서버도 종료하도록 연결.
+
+- `app/lib/src/features/auth/presentation/login_screen.dart`
+  - 문자 승인 후 앱 복귀 안내 문구 반영.
+  - pendingRef 복원/poll 오류 표시 개선.
+
+- `docs/00_policy_tdc114plus_screen_feature_2026-07-07.md`
+  - Baron SSO 공식 verify-only 정책과 앱 복귀 방식 반영.
+
+## 주의 사항
+
+- `scripts/.env.android-device.local`에는 실제 연동 키가 들어 있으므로 외부 공유 금지.
+- 내일 APK를 다시 빌드할 때는 반드시 auth base define을 포함한다.
+
+```bash
+./scripts/flutter-docker.sh build apk --debug \
+  --dart-define=TDC114_API_BASE=http://127.0.0.1:5000 \
+  --dart-define=TDC114_AUTH_API_BASE=http://127.0.0.1:5001 \
+  --dart-define=TDC114_DIRECTORY_API_BASE=http://127.0.0.1:5000 \
+  --dart-define=TDC114_ORGANIZATION_API_BASE=http://127.0.0.1:5000 \
+  --dart-define=TDC114_ORG_CONTEXT_API_BASE=http://127.0.0.1:5001
+```
+
+- 직원검색의 실제 직원/조직 조회는 현재 5001 auth broker를 통해 `/api/v1/integrations/org-context`로 간다.
+- 5000의 예전 `/api/v1/tdc114plus/employees` 류 경로는 현재 직원검색의 주 경로가 아니다.

docs/daily-issues/2026-07-15_work_handoff.md

@@ -0,0 +1,189 @@
+# 2026-07-15 업무 인계 메모
+
+작성 시각: 2026-07-15 KST
+
+## 오늘 최종 상태
+
+- 실기기 직원검색 화면에서 실제 프로필 사진 노출을 확인했다.
+- 현재 프로필 이미지 정책은 아래 순서로 정리된 상태다.
+  1. 네이버웍스 프로필 사진
+  2. Baron SSO `members[].id` 기준 UUID 파일명 이미지
+  3. 앱 기본 아바타
+- `tdc114plus-auth`의 `GET /api/v1/profile-image`는 `NAVER_WORKS -> BARON_UUID_R2 -> DEFAULT` 순서로 동작하도록 정리했다.
+- 앱은 `GET /api/v1/profile-image`를 우선 호출하고, 응답 실패 또는 미발견 시 `https://baroncs.co.kr/employee_img/{uuid}.jpg` 경로를 보조 fallback으로 사용하도록 보강했다.
+- 실기기 캡처 기준으로 직원목록의 여러 사용자가 기본 이니셜 원이 아니라 실제 사진으로 표시되는 것을 확인했다.
+
+## 오늘 진행한 핵심 작업
+
+### 1. 네이버웍스 1순위 경로 실검증
+
+확인 내용:
+
+- 서비스 계정 자격값을 최신값으로 다시 반영했다.
+- 토큰 발급이 실제로 성공하는지 재검증했다.
+- `GET /users/{userId}` 와 `GET /users/{userId}/photo`를 실제 호출해 `302`, `404` 동작을 다시 확인했다.
+
+확인 결과:
+
+- `thlee3@samaneng.com`
+  - 프로필 조회 `HTTP 200`
+  - 사진 조회 `HTTP 302`
+- `khkang@samaneng.com`
+  - 프로필 조회 `HTTP 200`
+  - 사진 조회 `HTTP 404`
+
+의미:
+
+- 네이버웍스 사진이 있는 사용자는 1순위 경로로 바로 쓸 수 있다.
+- 네이버웍스 사진이 없는 사용자는 2순위 UUID 이미지로 내려가면 된다.
+
+### 2. Baron UUID 기반 2순위 경로 재확정
+
+확인 내용:
+
+- `org-context` 실응답의 `members[].id`가 실제 UUID 형식인지 다시 확인했다.
+- 기존 CSV와 가족사 전체 응답을 대조한 매핑 결과를 기준으로 UUID 파일명 정책을 유지하기로 정리했다.
+- 외부 공개 경로는 `https://baroncs.co.kr/employee_img/{uuid}.jpg` 규칙으로 본다.
+
+현재 판단:
+
+- 2순위 식별자는 이메일 local-part나 해시명이 아니라 Baron UUID로 보는 것이 가장 안정적이다.
+- 프로필 이미지 전용 DB는 운영 기본안으로 채택하지 않고 보류 대안으로만 남긴다.
+
+### 3. `tdc114plus-auth` 프로필 이미지 endpoint 보강
+
+오늘 반영한 내용:
+
+- `GET /api/v1/profile-image`에 네이버웍스 1순위 조회를 연결했다.
+- 네이버웍스에서 사진이 없으면 Baron UUID 기준 공개 이미지 경로를 2순위로 판단하게 정리했다.
+- 기존 PostgreSQL 매핑 경로는 최후 예비안 수준으로만 남겼다.
+
+실검증 결과:
+
+- `GET /api/v1/profile-image?email=thlee3@samaneng.com`
+  - `found=true`
+  - `source=NAVER_WORKS`
+- `GET /api/v1/profile-image?email=khkang@samaneng.com`
+  - `found=true`
+  - `source=BARON_UUID_R2`
+
+의미:
+
+- 서버 레벨에서는 1순위/2순위 fallback이 실제 응답으로 이미 확인된 상태다.
+
+### 4. 앱 프로필 이미지 resolver 보강
+
+오늘 반영한 내용:
+
+- 앱은 다시 `tdc114plus-auth /api/v1/profile-image`를 우선 호출하도록 정리했다.
+- 응답 실패, 미발견, 또는 세션 문제 상황에서는 UUID 형식 `employee.id`가 있으면 공개 UUID 이미지 경로를 직접 fallback 하도록 보강했다.
+- 관련 단위 테스트를 추가하고 통과시켰다.
+
+테스트 결과:
+
+- `app/test/directory/profile_image_api_client_test.dart`
+  - auth endpoint 경유 성공
+  - 이메일 없음 시 기본 null 처리
+  - auth 미발견 시 UUID 공개 경로 fallback
+  - 테스트 통과 확인
+
+### 5. 실기기 반영 및 화면 확인
+
+실행 내용:
+
+- auth 서버 기동 상태 확인
+- APK 빌드 및 실기기 설치
+- 공기계에서 직원검색 화면 재진입
+- 실기기 화면 캡처로 실제 사진 표시 여부 확인
+
+최종 확인:
+
+- 직원검색 목록에서 여러 사용자 사진이 실제로 표시됨
+- 오늘 목표였던 “실기기에서 사진 뜨는지 확인”은 완료
+
+## 오늘 발생한 보조 이슈
+
+### 1. 실기기 재실행 중 bootstrap 일시 실패
+
+현상:
+
+- 일부 재실행 구간에서 `127.0.0.1:5000` bootstrap 연결 실패 메시지가 한 차례 있었다.
+
+현재 판단:
+
+- 이후 권한 포함 재실행에서는 정상 bootstrap 후 앱이 다시 올라왔다.
+- 오늘 최종 결과는 실기기 사진 표시 성공으로 본다.
+
+### 2. Docker/ADB 권한 및 대기 시간 이슈
+
+현상:
+
+- 일부 재실행 또는 조회 명령은 Docker 권한/ADB 응답 지연 때문에 중간 확인이 매끄럽지 않았다.
+
+현재 판단:
+
+- 기능 자체의 blocker는 아니었다.
+- 최종적으로 실기기 캡처까지 확보했으므로 오늘 작업 결론에는 영향 없다.
+
+## 오늘 변경 및 반영한 주요 파일
+
+- `app/lib/src/features/directory/data/profile_image_api_client.dart`
+  - auth endpoint 우선 호출
+  - UUID 직접 fallback 추가
+  - debug 로그 보강
+
+- `app/test/directory/profile_image_api_client_test.dart`
+  - UUID fallback 관련 테스트 추가
+
+- `scripts/start-auth-server.sh`
+  - 네이버웍스 env를 함께 읽어 auth 서버 기동 시 반영되도록 정리
+
+- `docs/00_guide_tdc114plus_profile_image_identifier_mapping_2026-07-14.md`
+  - 오늘 실검증 결과와 실기기 성공 결과 반영
+
+- `docs/00_guide_tdc114plus_work_progress_timetable_2026-07-02.md`
+  - 오늘 진행 상태와 다음 검증 포인트 반영
+
+## 내일 바로 이어서 볼 항목
+
+1. 현재 화면에 뜬 각 프로필 사진이 `NAVER_WORKS`인지 `BARON_UUID_R2`인지 source별로 구분 검증한다.
+2. 직원검색뿐 아니라 직원 상세/조직도 화면에서도 같은 규칙으로 사진이 표시되는지 확인한다.
+3. `DEFAULT` 케이스도 샘플로 잡아 기본 아바타 fallback이 자연스러운지 확인한다.
+4. 필요 시 프로필 이미지 관련 debug 로그를 더 짧게 정리하거나 제거한다.
+
+## 내일 업무 시작 순서
+
+1. auth 서버 상태 확인
+
+```bash
+curl -fsSL --max-time 5 http://127.0.0.1:5001/health
+```
+
+2. 실기기 reverse 상태 확인
+
+```bash
+ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/flutter-docker.sh adb -s R5CT42QTCNX reverse --list
+```
+
+3. 필요 시 auth 서버 재기동
+
+```bash
+./scripts/start-auth-server.sh --restart --env-file=/home/ubuntu/workspace/tdc114plus/scripts/.env.android-device.local
+```
+
+4. 필요 시 실기기 앱 재실행
+
+```bash
+ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 TDC114_FLUTTER_DEVICE_ID=R5CT42QTCNX TDC114_SMOKE_ENV_FILE=scripts/.env.android-device.local ./scripts/manual-postlogin-run.sh
+```
+
+5. 첫 확인 포인트
+   - 직원검색 목록 진입
+   - 사진이 계속 노출되는지 확인
+   - source별 구분 검증 대상으로 사용자 샘플 확보
+
+## 오늘 결론
+
+- 오늘 작업의 핵심 목표였던 “실기기에서 프로필 사진이 실제로 뜨는지 확인”은 완료했다.
+- 현재 구조는 `네이버웍스 -> Baron UUID 이미지 -> 기본 아바타` 정책과 실제 코드/실기기 화면이 서로 맞물리는 상태다.
+- 내일은 새로운 구현보다, 오늘 붙인 구조를 source별로 더 명확히 검증하고 화면 범위를 넓히는 단계로 이어가면 된다.

docs/daily-issues/2026-07-16_morning_start_checklist.md

@@ -0,0 +1,83 @@
+# 2026-07-16 아침 시작 체크리스트
+
+목적: 오늘 작업을 바로 이어가기 위해, 가장 먼저 확인할 항목만 짧게 정리한다.
+
+## 1. 먼저 볼 기준
+
+- 현재 프로필 이미지 정책:
+  1. 네이버웍스
+  2. Baron UUID 이미지
+  3. 기본 아바타
+- 전날 최종 상태:
+  - 실기기 직원검색 화면에서 실제 프로필 사진 노출 확인 완료
+  - 앱은 `tdc114plus-auth /api/v1/profile-image` 우선 호출
+  - 실패 또는 미발견 시 `https://baroncs.co.kr/employee_img/{uuid}.jpg` fallback 사용
+
+## 2. 아침 시작 순서
+
+### 1) auth 서버 상태 확인
+
+```bash
+curl -fsSL --max-time 5 http://127.0.0.1:5001/health
+```
+
+정상 기준:
+
+```json
+{"jwks":"ok","provider":"baron","status":"ok"}
+```
+
+### 2) reverse 상태 확인
+
+```bash
+ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/flutter-docker.sh adb -s R5CT42QTCNX reverse --list
+```
+
+필수 확인:
+
+```text
+tcp:5000 tcp:5000
+tcp:5001 tcp:5001
+```
+
+### 3) 필요 시 auth 서버 재기동
+
+```bash
+./scripts/start-auth-server.sh --restart --env-file=/home/ubuntu/workspace/tdc114plus/scripts/.env.android-device.local
+```
+
+### 4) 필요 시 실기기 앱 재실행
+
+```bash
+ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 TDC114_FLUTTER_DEVICE_ID=R5CT42QTCNX TDC114_SMOKE_ENV_FILE=scripts/.env.android-device.local ./scripts/manual-postlogin-run.sh
+```
+
+## 3. 첫 확인 포인트
+
+- 직원검색 목록 진입되는가
+- 사진이 계속 표시되는가
+- 어떤 사용자가 `NAVER_WORKS`인지, 어떤 사용자가 `BARON_UUID_R2`인지 샘플을 잡을 수 있는가
+
+## 4. 오늘 바로 이어서 할 일
+
+1. 실기기 기준 `NAVER_WORKS` 케이스 확인
+2. 실기기 기준 `BARON_UUID_R2` 케이스 확인
+3. `DEFAULT` 기본 아바타 케이스 확인
+4. 직원 상세/조직도 화면에서도 같은 규칙 유지 확인
+
+## 5. 문제 생기면 먼저 볼 것
+
+- `5001 health` 정상 여부
+- `adb reverse`에 `5000`, `5001` 둘 다 있는지
+- `scripts/.env.android-device.local` 경로와 값 누락 여부
+- 필요 시 auth 로그 확인
+
+```bash
+tail -n 120 logs/$(date +%F)/tdc114plus-auth.log
+```
+
+## 6. 참고 문서
+
+- [2026-07-15_work_handoff.md](/home/ubuntu/workspace/tdc114plus/docs/daily-issues/2026-07-15_work_handoff.md)
+- [00_guide_tdc114plus_profile_image_identifier_mapping_2026-07-14.md](/home/ubuntu/workspace/tdc114plus/docs/00_guide_tdc114plus_profile_image_identifier_mapping_2026-07-14.md)
+- [00_guide_tdc114plus_work_progress_timetable_2026-07-02.md](/home/ubuntu/workspace/tdc114plus/docs/00_guide_tdc114plus_work_progress_timetable_2026-07-02.md)

docs/daily-issues/2026-07-16_work_handoff.md

@@ -0,0 +1,224 @@
+# 2026-07-16 업무 인계 메모
+
+작성 시각: 2026-07-16 KST
+
+## 오늘 최종 상태
+
+- 실기기 로그인은 다시 정상 진행됐다.
+- 문자 링크 승인 후 앱 복귀 시 직원검색 목록이 다시 표시되는 것까지 확인했다.
+- 오늘 최종 복구 기준은 `로그인 성공 -> 직원검색 목록 표시 성공`이다.
+- 다만 프로필 사진 1순위/2순위/3순위 화면 검증은 아직 오늘 완료 범위에 포함하지 않는다.
+
+## 오늘 발생한 주요 이슈와 원인
+
+### 1. 로그인 후 직원검색이 다시 무너지는 문제
+
+현상:
+
+- 로그인 링크 발송은 되지만 앱 진입 후 직원검색 화면이 비거나 로딩만 지속됐다.
+- 잠시 후 `로그인이 만료되었거나 권한을 확인할 수 없습니다.` 화면으로 떨어졌다.
+
+중간에 확인한 사실:
+
+- 앱 SharedPreferences 안에는 세션 토큰이 실제로 저장되고 있었다.
+- 저장된 토큰은 Baron access token이 아니라 `tdc114plus-auth`가 발급한 app session token 형식이었다.
+- 저장된 user 정보는 아래처럼 fallback 값이었다.
+  - `id = baron-user`
+  - `name = Baron User`
+  - `tenantSlug = ""`
+
+의미:
+
+- 세션 토큰이 전혀 저장되지 않는 문제는 아니었다.
+- 다만 user 메타데이터는 충분하지 않았고, 동시에 org-context 중계 경로도 깨져 있었다.
+
+### 2. 핵심 장애 원인: 5001 auth broker의 org-context self-recursion
+
+현상:
+
+- `tdc114plus-auth` 로그에 `/api/v1/integrations/org-context` 요청이 들어온 뒤,
+  같은 5001 서버가 다시 자기 자신의 `/api/v1/integrations/org-context`를 호출하는 패턴이 반복됐다.
+- 내부 재호출 요청에는 `Authorization`, `X-App-Session` 헤더가 없어서 결국 unauthorized 흐름으로 무너졌다.
+
+실제 확인값:
+
+- 실행 중인 5001 프로세스 환경변수에서 아래를 직접 확인했다.
+
+```text
+BARON_ORG_CONTEXT_BASE_URL=http://127.0.0.1:5001
+```
+
+즉:
+
+- 원래 의도는 `https://sadmin.hmac.kr`를 upstream으로 호출해야 하는데,
+- 실제 실행 중 프로세스는 자기 자신 `http://127.0.0.1:5001`을 upstream으로 잡고 있었다.
+
+근본 원인:
+
+- `scripts/start-auth-server.sh`가
+  `TDC114_AUTH_UPSTREAM_ORG_CONTEXT_API_BASE` 값을 env 파일 `source` 전에 먼저 읽고 있었다.
+- 그래서 `scripts/.env.android-device.local` 안에
+  `TDC114_AUTH_UPSTREAM_ORG_CONTEXT_API_BASE=https://sadmin.hmac.kr`
+  가 있어도 반영되지 않았다.
+- 그 결과 fallback으로 `TDC114_ORG_CONTEXT_API_BASE=http://127.0.0.1:5001`를 사용하면서 self-recursion이 발생했다.
+
+### 3. 오늘 복구 조치
+
+수정 파일:
+
+- `scripts/start-auth-server.sh`
+
+수정 내용:
+
+- `UPSTREAM_ORG_CONTEXT_BASE` 읽는 위치를 env 파일 `source` 뒤로 옮겼다.
+- 이후 5001 auth broker를 재기동했다.
+
+재기동 후 직접 확인한 실행 환경:
+
+```text
+PORT=5001
+APP_SESSION_SECRET=tdc114plus-dev-session
+BARON_ORG_CONTEXT_BASE_URL=https://sadmin.hmac.kr
+BARON_ORG_CONTEXT_TENANT_SLUG=hanmac-family
+```
+
+결과:
+
+- self-recursion 원인이 제거됐다.
+- 다시 로그인 후 실기기 직원검색 목록이 정상 표시됐다.
+
+## 오늘 추가로 확인한 기술 메모
+
+### 1. `baron-user / Baron User` 생성 위치
+
+파일:
+
+- `/home/ubuntu/workspace/tdc114plus-auth/cmd/server/main.go`
+
+확인 내용:
+
+- `link/poll` 완료 후 `poll.User`에 값이 없을 때 fallback으로 아래 값이 채워진다.
+  - `baron-user`
+  - `Baron User`
+
+현재 판단:
+
+- 이 값은 오늘 새로 생긴 회귀가 아니라 기존 구조였다.
+- 오늘의 실장애 원인은 이것 자체보다 `org-context upstream 오배선`이었다.
+
+### 2. `tenantSlug` 누락 구조는 후속 개선 대상
+
+현재 확인 결과:
+
+- `tdc114plus-auth`의 `link/poll` 응답 user 모델에는 `tenantSlug`, `tenantId`, `tenantName`이 없다.
+- 앱은 세션 user의 `tenantSlug`가 비어 있으면 후속 조직도/초기 선택 계산에서 fallback을 더 많이 타게 된다.
+
+중요 판단:
+
+- 오늘 직원검색이 완전히 무너진 직접 원인은 self-recursion이었다.
+- 하지만 `tenantSlug` 누락 구조는 다음 작업에서 별도로 정리해야 한다.
+
+## 오늘 수정/추가한 파일
+
+- `scripts/start-auth-server.sh`
+  - org-context upstream env 읽는 순서를 수정했다.
+
+- `app/lib/src/core/config/app_environment.dart`
+  - 빌드 시각 define 표시용 항목을 유지했다.
+
+- `app/lib/src/features/auth/presentation/login_screen.dart`
+  - 실기기에서 최신 APK 식별을 위해 빌드 시각 표시를 유지했다.
+
+## 확인 완료한 테스트
+
+1. 5001 health 확인
+
+```bash
+curl -i --max-time 5 http://127.0.0.1:5001/health
+```
+
+결과:
+
+```json
+{"jwks":"ok","provider":"baron","status":"ok"}
+```
+
+2. 실행 중 5001 프로세스 환경변수 확인
+
+- `BARON_ORG_CONTEXT_BASE_URL=https://sadmin.hmac.kr` 반영 확인
+
+3. 실기기 세션 저장 확인
+
+- SharedPreferences 안에 app session token 저장 확인
+- user fallback 값 저장 확인
+
+4. 실기기 재로그인 후 직원검색 확인
+
+- 문자 링크 승인 성공
+- 앱 복귀 성공
+- 직원검색 목록 표시 성공
+
+## 내일 업무 시작 순서
+
+1. 전일 인계 문서 먼저 확인
+
+- `docs/daily-issues/2026-07-16_work_handoff.md`
+
+2. 5001 auth broker health 확인
+
+```bash
+curl -fsSL --max-time 5 http://127.0.0.1:5001/health
+```
+
+3. 실행 중 5001 프로세스 upstream 값 확인
+
+```bash
+ss -ltnp '( sport = :5001 )'
+tr '\0' '\n' < /proc/<PID>/environ | rg 'BARON_ORG_CONTEXT_BASE_URL|BARON_ORG_CONTEXT_TENANT_SLUG'
+```
+
+정상 기준:
+
+```text
+BARON_ORG_CONTEXT_BASE_URL=https://sadmin.hmac.kr
+BARON_ORG_CONTEXT_TENANT_SLUG=hanmac-family
+```
+
+4. 실기기 ADB 연결 및 reverse 확인
+
+```bash
+ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/flutter-docker.sh adb -s R5CT42QTCNX reverse --list
+```
+
+5. 앱 재로그인 후 첫 확인
+
+- 직원검색 목록이 바로 뜨는지
+- 30초 뒤에도 만료 화면으로 떨어지지 않는지
+
+## 내일 우선 점검할 항목
+
+1. `org-context` self-recursion이 정말 재발하지 않는지 먼저 확인한다.
+2. `tenantSlug` 누락 구조를 `tdc114plus-auth` 응답 모델 기준으로 정리한다.
+3. 프로필 사진 우선순위 검증을 아래 순서로 이어간다.
+   - NAVER_WORKS
+   - BARON_UUID_R2
+   - DEFAULT
+4. 직원검색 외에 조직도/상세/즐겨찾기 화면도 같은 세션 상태에서 유지되는지 확인한다.
+
+## 보안상 주의사항
+
+- 아래 값들은 문서에 실제 값을 남기지 않는다.
+  - NAVER WORKS 서비스 계정 자격값
+  - Baron org-context key id / secret
+  - private key 경로 및 원문
+
+- `scripts/.env.android-device.local`
+- `secrets/naver_works_service_account.local.env`
+
+위 두 파일은 계속 비공개 로컬 파일로만 유지한다.
+
+## 내일 첫 판단 기준
+
+- 내일 첫 목표는 “또 고치는 것”이 아니라 “오늘 복구한 5001 upstream 상태가 유지되는지 먼저 검증”이다.
+- 그 상태가 유지되면 사진 정책 검증으로 넘어가고,
+- 유지되지 않으면 가장 먼저 `start-auth-server.sh`와 실행 중 프로세스 환경변수부터 다시 본다.

docs/daily-issues/2026-07-20_work_handoff.md

@@ -0,0 +1,305 @@
+# 2026-07-20 업무 인계 메모
+
+작성 시각: 2026-07-20 KST
+
+## 오늘 핵심 결론
+
+- `tdc114plus` 앱과 로컬 `tdc114plus-auth:5001` 연결은 정상 확인했다.
+- 실기기 `adb reverse tcp:5001 tcp:5001`도 정상 확인했다.
+- 앱에서 `link/init` 호출 후 `pendingRef` 생성, 이후 `link/poll` 반복까지 서버 로그로 확인했다.
+- 즉 오늘 로그인 막힘의 핵심은 `앱 <-> 로컬 중계서버` 구간이 아니라 `Baron SSO 문자 링크 실제 발송/SMS 연계 구간`으로 판단했다.
+
+## 오늘 확인한 최종 상태
+
+### 1. 로컬 auth broker 상태
+
+정상 확인값:
+
+```bash
+curl -i --max-time 5 http://127.0.0.1:5001/health
+```
+
+응답:
+
+```json
+{"jwks":"ok","provider":"baron","status":"ok"}
+```
+
+의미:
+
+- 로컬 `tdc114plus-auth` 5001은 떠 있었다.
+- 최소한 health 기준으로는 죽어 있지 않았다.
+
+### 2. 실기기 reverse 상태
+
+사용자 확인 결과:
+
+```text
+adb reverse --list
+UsbFfs tcp:5001 tcp:5001
+```
+
+의미:
+
+- 실기기에서 `127.0.0.1:5001`로 가는 호출은 PC 로컬 5001로 붙는 상태였다.
+- 따라서 실기기에서 auth broker 접속이 안 되는 상태는 아니었다.
+
+### 3. 앱이 실제로 5001에 요청을 보내는지 확인
+
+서버 로그에서 아래를 직접 확인했다.
+
+```text
+linkInit body={"phoneNumber":"01091365338","device":{"platform":"android","appVersion":"0.1.0","deviceName":"android"}}
+```
+
+그리고 이어서:
+
+```text
+POST /api/v1/auth/link/init
+POST /api/v1/auth/link/poll
+```
+
+반복 확인했다.
+
+의미:
+
+- 앱에서 로그인 버튼을 눌렀을 때 요청이 실제로 로컬 auth broker까지 도달했다.
+- `pendingRef` 생성도 정상 진행됐다.
+
+### 4. 앱 내부 pending 상태 저장 확인
+
+실기기 SharedPreferences에서 아래 항목을 직접 확인했다.
+
+- `flutter.tdc114plus.auth.pending.ref`
+- `flutter.tdc114plus.auth.pending.expiresAt`
+
+의미:
+
+- 앱이 로그인 요청 직후 pending 상태를 저장하지 못하는 문제는 아니었다.
+- 앱 내부 상태 저장까지는 정상으로 봐도 된다.
+
+## 오늘 발생한 실제 장애
+
+현상:
+
+- 앱에서는 `승인 대기 중` 화면으로 넘어간다.
+- 하지만 사용자 휴대폰에는 실제 문자 링크가 도착하지 않는다.
+- 재전송 시도 후에도 동일하다.
+
+중요 판단:
+
+- 앱 요청 실패 아님
+- 로컬 auth broker 연결 실패 아님
+- `adb reverse` 누락 문제 아님
+- 현재 가장 의심되는 구간은 Baron SSO 쪽 `문자 링크 실제 발송 처리` 또는 그 뒤 SMS 연계 구간이다.
+
+## 오늘 중간에 있었던 혼선 정리
+
+### 1. `auth_provider_unavailable`
+
+한 시점에는 앱에 아래 문구가 보였다.
+
+```text
+로그인 링크 요청 실패: auth_provider_unavailable
+```
+
+이때 직접 확인한 사실:
+
+- 같은 시각 `sso.hmac.kr /oidc/oauth2/auth`가 `502 Bad Gateway`를 반환하던 구간이 있었다.
+- 이후 재확인 시 다시 `302 Location: /login?login_challenge=...`로 정상 응답했다.
+
+의미:
+
+- Baron SSO upstream authorization 시작점이 한때 불안정했다.
+- 하지만 이후 복구된 뒤에도 최종적으로는 `문자 미수신` 문제가 남았다.
+
+### 2. callback URL 혼선
+
+아래 주소는 현재 직접 열면 `404 page not found`가 보인다.
+
+```text
+https://114-auth.hmac.kr/api/v1/auth/oidc/callback
+```
+
+정리:
+
+- 이 URL은 브라우저에서 직접 여는 진입 URL이 아니라 OIDC 최종 code 수신용 callback 경로다.
+- 현재 `문자 미수신` 문제의 직접 원인으로 확정한 상태는 아니다.
+- 다만 라우트 정합성은 후속 점검 대상으로 계속 유지한다.
+
+## 오늘 외부 전달용 요약
+
+Baron SSO 개발자에게 전달할 핵심은 아래였다.
+
+```text
+- 신규앱 -> 로컬 tdc114plus-auth(5001) 요청 정상
+- adb reverse 정상
+- auth 서버 로그상 link/init, pendingRef 생성, link/poll 반복 정상
+- 그런데 실제 문자 링크가 사용자 휴대폰에 도착하지 않음
+- 따라서 Baron SSO 쪽 문자 링크 실제 발송 처리 또는 SMS 연계 구간 확인 필요
+```
+
+## 오늘 기준 남아 있는 작업
+
+### 1. 문자 미수신 이슈 답변 대기
+
+- Baron SSO 개발자 확인 결과를 받아야 한다.
+- 그 전까지는 앱/로컬 중계서버 쪽에서 더 고쳐도 문자 미수신 문제를 끝낼 수 없다.
+
+### 2. 프로필 사진 route 상태 정리
+
+현재 확인 상태:
+
+- 앱은 `/api/v1/profile-image`를 먼저 시도한다.
+- 하지만 현재 5001 서버는 해당 route에 `404`를 반환한다.
+
+의미:
+
+- 사진 1순위/2순위/3순위 실기기 검증은 아직 시작 조건이 완전히 갖춰지지 않았다.
+
+### 3. 로그인 화면 상태 문구 정리
+
+관찰된 화면:
+
+- 실패 문구
+- 승인 대기 박스
+- 재전송 카운트
+
+이 조합이 시점별로 다르게 보였다.
+
+후속 과제:
+
+- 요청 시작 시 이전 에러 문구를 항상 지우는지
+- pending 복원 시 에러 상태를 같이 끌고 오지 않는지
+- 문자 미수신과는 별개로 화면 상태 표현이 꼬이지 않는지
+
+## 외부 답변 대기 중 내부 진행 순서
+
+문자 발송 구간 답변이 오기 전에도 아래 순서로는 내부 작업을 진행할 수 있다.
+
+1. `tdc114plus-auth` 응답 메타데이터 정합성 재확인
+   - `tenantSlug`, `tenantId`, `tenantName`, `department`, `grade`, `position`, `jobTitle`
+   - 앱이 실제로 어떤 필드를 저장하고 소비하는지 확인
+
+2. 로그인 화면 상태 표현 정리
+   - `실패 문구`와 `승인 대기 UI`가 동시에 남지 않도록 정리
+   - pending 복원 시 문구 초기화 조건 확인
+
+3. `/api/v1/profile-image` route 복구 준비
+   - 현재 앱 호출 형식 고정
+   - auth 서버 route 부재 상태 문서화
+   - 복구 시 필요한 응답 형태 확정
+
+4. 프로필 사진 검증 대상 사용자 표 준비
+   - NAVER WORKS 1순위 예상 사용자
+   - UUID 이미지 2순위 예상 사용자
+   - DEFAULT 3순위 예상 사용자
+
+5. `baron-sso-tdc114plus-api` 제거 마이그레이션 표 세분화
+   - 남은 기능이 진짜 필요한지
+   - `tdc114plus-auth`에 흡수할지
+   - 완전히 제거할지 분류
+
+## 2026-07-20 메타데이터 정합성 재확인 결과
+
+확인 결과:
+
+- `tdc114plus-auth`가 내보내는 사용자 메타데이터 JSON 키와
+- `tdc114plus` 앱이 저장/사용하는 JSON 키는 현재 서로 맞는다.
+
+확인한 키:
+
+- `tenantId`
+- `tenantName`
+- `tenantSlug`
+- `department`
+- `grade`
+- `position`
+- `jobTitle`
+
+정리:
+
+1. 중계서버 출력
+   - `tdc114plus-auth/cmd/server/main.go`
+   - `readUser(...)`가 위 항목들을 읽는다.
+   - `issueAppSessionToken(...)`가 같은 키명으로 JWT `user` 클레임에 넣는다.
+
+2. 앱 수신/저장
+   - `app/lib/src/features/auth/domain/auth_models.dart`
+   - `LoginUser.fromJson(...)`가 같은 키명으로 파싱한다.
+   - `app/lib/src/features/auth/data/auth_session_store.dart`
+   - 세션 저장 시 `response.user.toJson()` 그대로 SharedPreferences에 저장한다.
+
+3. 앱 소비 위치
+   - `app/lib/src/features/directory/presentation/directory_screen.dart`
+   - `tenantSlug`가 있으면 초기 회사 선택에 바로 사용한다.
+   - `tenantSlug`가 비어 있으면 조직도 조회 fallback으로 현재 사용자 소속을 다시 찾는다.
+   - `department`가 있으면 초기 부서 고정에도 바로 사용한다.
+   - `profile_image_api_client.dart`에서도 `tenantSlug`/`tenantName`를 회사코드 추정에 사용한다.
+
+현재 판단:
+
+- 구조적 키 mismatch 문제는 아니다.
+- 진짜 남은 위험은 `Baron upstream 응답에서 값이 비어 들어오는 경우`다.
+- 특히 `tenantSlug`가 비면 앱은 fallback으로 버티지만, 초기 선택과 사진 1차 lookup 정확도는 떨어질 수 있다.
+
+## 2026-07-20 프로필 사진 검증 대상 표
+
+현재 문서와 과거 실검증 이력을 기준으로, source별 우선 확인 대상은 아래처럼 정리한다.
+
+| 우선순위 | 예상 source | 사용자 | 근거 | 현재 상태 |
+| --- | --- | --- | --- | --- |
+| 1순위 | `NAVER_WORKS` | `thlee3@samaneng.com` | 2026-07-15 네이버웍스 사진 조회 `HTTP 302` 확인 이력 | route 복구 후 실기기 재검증 필요 |
+| 2순위 | `BARON_UUID_R2` | `khkang@samaneng.com` | 2026-07-15 네이버웍스 사진 조회 `HTTP 404`, UUID 공개 이미지 fallback 이력 | route 복구 후 실기기 재검증 필요 |
+| 3순위 | `DEFAULT` | 미확정 | 실제 운영 사용자 중 `네이버웍스 없음 + UUID 이미지 없음` 샘플을 아직 확정하지 못함 | 샘플 대상 추가 선정 필요 |
+
+현재 판단:
+
+- 1순위와 2순위는 과거 실검증 이력이 있는 샘플이 이미 있다.
+- 3순위는 억지로 추정하지 말고, route 복구 후 실제 미보유 샘플을 한 명 확정하는 것이 안전하다.
+
+## 2026-07-20 `/api/v1/profile-image` 복구 진행 결과
+
+이번 복구에서 반영한 범위:
+
+- `tdc114plus-auth`에 `GET /api/v1/profile-image` route를 다시 등록했다.
+- 현재 복구 로직은 아래 순서로 동작한다.
+  1. `NAVER_WORKS`
+  2. `BARON_UUID_R2`
+  3. `DEFAULT`
+
+구체 복구 내용:
+
+- 네이버웍스 서비스 계정 env가 있으면 `GET /users/{email}/photo`의 `302/404` 규칙을 사용한다.
+- 네이버웍스에서 사진이 없으면 `org-context`에서 email 기준 Baron UUID를 찾는다.
+- UUID가 있으면 `https://baroncs.co.kr/employee_img/{uuid}.jpg` 공개 경로 존재 여부를 확인한다.
+- 둘 다 없으면 `found=false`, `source=DEFAULT`를 반환한다.
+
+검증 결과:
+
+- `go test ./cmd/server` 통과
+- 로컬 5001 재기동 완료
+- 무인증 호출 기준 이전 `404 page not found`가 아니라 아래처럼 바뀐 것을 확인했다.
+
+```json
+{"error":"unauthorized","message":"앱 세션을 확인하세요."}
+```
+
+현재 판단:
+
+- route 자체는 현재 기동 서버에 복구됐다.
+- 즉 이전처럼 endpoint 자체가 없는 상태는 아니다.
+- 다음 실제 확인은 `로그인된 앱 세션` 상태에서 1순위/2순위/3순위 화면 검증으로 넘어가면 된다.
+
+## 내일 또는 다음 작업 시작 시 우선 순서
+
+1. `5001 health` 먼저 확인
+2. `adb reverse --list` 먼저 확인
+3. 앱에서 `link/init` 로그가 실제로 찍히는지 확인
+4. 문자 수신 여부를 먼저 확인
+5. 문자 미수신이면 앱 수정으로 우회하지 말고 Baron SSO 답변 상태부터 확인
+6. 문자 문제가 외부에서 정리되면 그 다음에 프로필 사진 검증으로 넘어간다
+
+## 한 줄 요약
+
+2026-07-20 기준 로그인 막힘의 핵심은 `앱이 요청을 못 보내는 문제`가 아니라 `요청은 정상인데 실제 문자 링크가 사용자에게 도착하지 않는 문제`다.

docs/daily-issues/README.md

@@ -0,0 +1,40 @@
+# Daily Handoff Policy
+
+## 목적
+
+매일 업무 시작 시 전날 작업 흐름, 남은 이슈, 테스트 상태를 먼저 확인해서 같은 문제를 반복하지 않도록 한다.
+
+## 필수 규칙
+
+1. 업무 시작 전 `docs/daily-issues/`의 최신 전일 작업 인계 MD 파일을 먼저 확인한다.
+2. `scripts/startup.sh`는 런타임 기동 전에 최신 전일 인계 문서를 로그에 출력한다.
+3. 전일 인계 문서가 없으면 기본적으로 startup을 중단한다.
+4. 예외 복구 상황에서만 아래 환경값으로 강제 진행할 수 있다.
+
+```bash
+TDC114_REQUIRE_DAILY_HANDOFF=false ./scripts/startup.sh --auto --wait=40
+```
+
+## 작성 규칙
+
+오늘 업무 종료 전에는 반드시 아래 내용을 포함한 MD 파일을 남긴다.
+
+- 오늘 최종 상태
+- 오늘 발생한 주요 이슈와 원인
+- 오늘 수정/추가한 파일
+- 확인 완료한 테스트
+- 내일 업무 시작 순서
+- 내일 우선 점검할 항목
+- 보안상 공유하면 안 되는 값 또는 주의사항
+
+## 파일명
+
+```text
+YYYY-MM-DD_work_handoff.md
+```
+
+예:
+
+```text
+2026-07-14_work_handoff.md
+```