kevin/tdc114plus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Stabilize auth flow and profile images

Browse Source
This commit is contained in:
Codex
2026-07-20 13:38:39 +09:00
parent 57caca8dc8
commit 5d3eee7a16
128 changed files with 28860 additions and 1468 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/checklist_morning_startup_runtime_2026-07-03.md
+474
View File
@@ -0,0 +1,474 @@
# 출근 후 기동 확인 및 복구 체크리스트
**작성일**: 2026-07-03
**최종 업데이트**: 2026-07-19
**버전**: 2.5 (개발용 로컬 Baron worktree와 최종 배포 목표 구조 구분 반영)
## 목적
전날 퇴근하면서 VS Code, 터미널, Android target을 모두 종료한 뒤, 다음 출근 시 `tdc114plus` 작업을 빠르게 재개할 수 있도록 기동 확인과 복구 절차를 고정한다.
**핵심 정책**: 소스코드 변경을 요하지 않는 자동 복구(컨테이너 재시작, 충돌 컨테이너 정리, 권한 수정, 디렉터리 정리 등)는 사용자 승인 없이 자동으로 진행한다.
---
## 1. 적용 대상
- 앱 저장소: `/home/ubuntu/workspace/tdc114plus`
- Baron SSO API worktree: `/home/ubuntu/workspace/baron-sso-tdc114plus-api`
- auth 중계서버 저장소: `/home/ubuntu/workspace/tdc114plus-auth`
- Windows ADB 서버 공유 기반 Android target + WSL/Docker Flutter 조합
주의:
- 이 체크리스트는 `현재 개발/검증용 업무시작 기동` 기준이다.
- 최종 배포 목표 구조에서는 로컬 `baron-sso-tdc114plus-api` 기동이 없어지는 방향을 목표로 한다.
- 다만 2026-07-19 현재는 아직 일부 로그인/조직 연동 검증이 로컬 Baron worktree에 의존하므로, 업무 시작 기동 대상에서 바로 제거하지 않는다.
---
## 2. 출근 후 기본 순서
아래 순서를 기본값으로 사용한다.
1. VS Code를 연다.
2. 작업 기준 문서를 먼저 연다.
- `docs/00_guide_tdc114plus_work_progress_timetable_2026-07-02.md`
- `docs/daily-issues/YYYY-MM-DD.md`
3. Android target 선행 확인
4. Baron SSO runtime 초기화 (아래 섹션 참고)
5. `tdc114plus-auth` broker 기동 및 health 확인
6. 1차 상태 확인 명령 실행
7. Integration test 실행
현재 해석:
- `tdc114plus`와 `tdc114plus-auth`는 최종 배포 직접 대상이다.
- `baron-sso-tdc114plus-api`는 현재 개발 중 연동 검증용 보조 worktree다.
- Baron SSO 원본 `staging`/`production` 연동으로 완전히 전환되기 전까지는 이 보조 worktree 기동 여부가 앱 개발 중 동작에 직접 영향을 줄 수 있다.
---
## 3. 런타임 초기화 및 1차 확인
### 3.0 Android target 선행 확인
`startup.sh`는 이제 **가장 먼저** Android target 상태를 확인한다. 실기기 또는 emulator가 `offline`, `unauthorized`, `connection refused` 중 하나면 Baron runtime 기동 전에 멈추고, Windows에서 무엇을 해야 하는지 단계별로 출력한다.
기본 정책:
- 기본 타깃은 실기기 1대다. emulator는 fallback일 때만 1대만 켠다.
- Windows `adb.exe devices`에서 대상 Android target이 `device` 상태인지 먼저 확인한다.
- 표준 연결 방식은 Windows ADB server 공유 방식인 `ADB_SERVER_SOCKET=tcp:172.21.128.1:5037`을 사용한다.
- 직접 emulator port 연결인 `TDC114_ADB_CONNECT_ADDRESS=<host>:<port>`는 Docker local ADB가 꼭 필요한 예외 상황에만 사용한다.
- Windows 단독 `device` 상태가 확인되기 전에는 WSL/Docker Android 스크립트를 실행하지 않는다.
권장 실행:
```bash
# Android preflight + startup 계획 확인
ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/startup.sh --dry-run --wait=40
# 실제 기동
ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/startup.sh --auto --wait=40
```
Android target preflight 실패 시 사용자가 로컬 PC에서 최소한으로 해야 하는 일:
1. Windows에서 Android Studio를 연다.
2. 실기기면 USB 디버깅 연결을 확인하고, emulator fallback이면 Device Manager에서 1대만 켠다.
3. Windows PowerShell에서 `adb.exe devices`를 실행해 `device` 상태를 확인한다.
4. 여전히 `offline`이면 대상 기기 또는 emulator를 재시작한다.
5. Windows adb는 정상인데 WSL/Docker에서만 실패하면 우선 `5037 -> 127.0.0.1:5037` portproxy와 방화벽 rule을 확인한다.
6. `5037` 공유 방식은 정상인데 특정 integration test에서만 막히면 그때 `<EMULATOR_PORT> -> 127.0.0.1:<EMULATOR_PORT>` 직접 연결 보조 경로를 검토한다.
이 단계는 Codex가 대신 할 수 없다.
Codex가 계속할 수 있는 작업:
- WSL/Docker에서 Android target 재인식 확인
- Baron runtime 기동
- API smoke 확인
- integration/manual Android 명령 실행
- `tdc114plus-auth` broker 기동 확인 및 자동 실행 시도
### 3.05 앱 직접 App Link callback 제거
2026-07-15 기준 신규 앱은 Baron SSO OIDC callback을 직접 받지 않는다.
기본 정책:
- 앱은 `https://114.hmac.kr/auth/callback` App Link를 사용하지 않는다.
- 앱은 `tdc114plus-auth`의 `/api/v1/auth/link/init`, `/api/v1/auth/link/poll`만 호출한다.
- Baron SSO OIDC callback은 `tdc114plus-auth`가 받는다.
- 필요한 redirect URI는 `https://114-auth.hmac.kr/api/v1/auth/oidc/callback`이다.
- Windows 로컬 App Link 테스트 서버는 업무 시작 기동 대상이 아니다.
참조 문서:
```text
docs/00_guide_tdc114plus_auth_broker_redirect_flow_2026-07-15.md
```
### 3.1 Baron SSO 런타임 전체 초기화
**중요**: Baron SSO는 인프라(PostgreSQL, Redis, ClickHouse)와 Ory 인증(Kratos, Hydra, Keto) 서비스가 **모두 필수**다.
단순히 `docker compose up -d`로는 불충분하다. **반드시 모든 compose 파일을 포함**해야 한다:
```bash
cd /home/ubuntu/workspace/baron-sso-tdc114plus-api
# 모든 compose 파일 포함하여 안전 중지 후 재시작
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml down 2>/dev/null || true
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d
# compose up 실패 시(예: name conflict) 기존 관련 컨테이너 정리 후 1회 재시도
docker ps -a --format '{{.Names}}' | grep -iE "baron|ory" | xargs -r docker rm -f
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d
# 서비스 안정화 대기 (인지 마이그레이션/헬스체크 완료)
sleep 30
# tdc114plus로 돌아가기
cd /home/ubuntu/workspace/tdc114plus
```
### 3.2 1차 상태 확인 명령
```bash
cd /home/ubuntu/workspace/tdc114plus
# Baron runtime 상태 확인 (스크립트로 자동 실행 가능)
./scripts/check-baron-api-env.sh
# API smoke 테스트 (스크립트로 자동 실행 가능)
./scripts/api-smoke.sh
```
**실행 방법 (권장)**:
- 수동: 위 명령을 복사해 실행
- 자동(권장): `scripts/startup.sh`를 사용
**자동 실행 예 (dry-run 권장)**:
```bash
# Dry-run: Android preflight 포함, 어떤 작업을 할지 미리 확인
ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/startup.sh --dry-run
# 실제 재기동(주의)
ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/startup.sh --auto --wait=40
```
**기대 결과**:
- `check-baron-api-env.sh`: `"RESULT ready-ish: 0 failure(s), 0 warning(s)"`
- `api-smoke.sh`: 성공 코드 0
- `tdc114plus-auth` health: `{"jwks":"ok","provider":"baron","status":"ok"}`
- `scripts/startup.sh --auto`: Android preflight, Baron runtime, `tdc114plus-auth`, smoke 조건 중 하나라도 충족하지 못하면 비정상 종료(exit 1)
---
## 4. 자동 복구 정책 및 규칙
### 4.1 자동 복구 대상 (사용자 승인 불필요)
다음 사항들은 소스 변경을 요하지 않으므로 **자동으로 복구**한다:
- **컨테이너 미실행**: 자동 재시작 또는 전체 재기동
- **컨테이너 명 충돌**: 기존 컨테이너 강제 제거 후 1회 재시작
- **권한 문제**: `chmod`, `chown` 자동 수정
- **설정 디렉터리 부재**: 자동 생성 또는 복원
- **헬스체크 실패 또는 warning**: 최대 6회 재시도
- **서비스 안정화 대기**: 자동 진행 (최대 60초)
### 4.2 수동 개입 필요 (사용자 승인 필요)
다음 사항들은 설정 또는 소스 변경을 요하므로 **명시적 승인**을 받는다:
- 소스코드 수정
- 환경 변수 값 변경
- 설정 파일 내용 수정
- 데이터베이스 마이그레이션 또는 초기화
- API 엔드포인트 주소 변경
---
## 5. 실패 시 복구 순서
### 5.1 `check-baron-api-env.sh` 실패 또는 warning 다수
Baron SSO runtime 상태 확인 및 복구:
```bash
cd /home/ubuntu/workspace/baron-sso-tdc114plus-api
```
**자동 복구 절차** (순차 실행):
```bash
# 1단계: 안전 중지 후 전체 재시작
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml down 2>/dev/null || true
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d
# 2단계: name conflict가 보이면 관련 컨테이너 정리 후 1회 재시작
docker ps -a --format '{{.Names}}' | grep -iE "baron|ory" | xargs -r docker rm -f
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d
# 3단계: 서비스 안정화 대기
sleep 30
# 4단계: 재확인
cd /home/ubuntu/workspace/tdc114plus
./scripts/check-baron-api-env.sh
```
**상태 확인 명령어**:
```bash
docker ps --format '{{.Names}} {{.Status}}' | grep -E "baron_backend|baron_gateway|ory_kratos|ory_postgres"
```
**정상 기대 상태**:
| 서비스 | 상태 | 설명 |
|--------|------|------|
| `baron_backend` | Up (healthy) | 메인 백엔드 서비스 |
| `baron_gateway` | Up | 리버스 프록시 |
| `baron_postgres` | Up (healthy) | 메인 데이터베이스 |
| `baron_redis` | Up | 캐시/세션 저장소 |
| `ory_postgres` | Up (healthy) | Ory 데이터베이스 |
| `ory_kratos` | Up | 사용자 관리/인증 |
| `ory_hydra` | Up | OAuth2/OIDC 제공자 |
| `ory_keto` | Up | 권한 관리 |
---
### 5.2 `api-smoke.sh` 실패 (HTTP 502/503)
#### 원인 분석
```bash
# Ory Kratos 로그 확인 (인증 서비스)
docker logs ory_kratos 2>&1 | tail -30
# Baron backend 로그 확인
docker logs baron_backend 2>&1 | tail -30
# 전체 컨테이너 상태
docker ps | grep -iE "baron|ory"
```
#### 자동 복구
Ory 또는 Baron 서비스가 준비 완료되지 않은 경우:
```bash
cd /home/ubuntu/workspace/baron-sso-tdc114plus-api
# 전체 재시작 (가장 안전한 방법)
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml down
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d
sleep 40
# 재확인
cd /home/ubuntu/workspace/tdc114plus
./scripts/api-smoke.sh
```
#### HTTP 401 (인증 오류)
```bash
cat /home/ubuntu/workspace/tdc114plus/scripts/.env.smoke.local | grep -E "PHONE|PROVIDER"
```
전화번호, provider 설정이 올바른지 확인. 변경 필요시 사용자 승인 후 수정.
---
## 6. Android target 확인
`startup.sh`가 이 단계를 먼저 수행하지만, 수동 재확인이 필요하면 아래 명령을 쓴다.
실기기 우선이면 USB 디버깅 연결을 먼저 확인하고, emulator fallback이면 Windows에서 Android Studio emulator를 켠다.
그 후 WSL/Docker 기준 확인:
```bash
cd /home/ubuntu/workspace/tdc114plus
ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/flutter-docker.sh devices
```
**완료 기준**:
- `emulator-<PORT>` 또는 Android target이 표시된다.
- 직접 emulator port 연결은 표준 방식이 실패하거나 integration test 보조 경로가 필요할 때만 사용한다.
### 6.1 Android device가 보이지 않을 때
우선 정책 문서를 참고한다:
- `docs/policy_android_studio_wsl_adb_2026-07-03.md`
- `docs/scenario_android_emulator_device_integration_test_2026-07-03.md`
가장 흔한 확인 포인트:
- Windows emulator가 실제로 켜져 있는가?
- Windows `adb.exe devices`에서 대상이 `device` 상태인가?
- 당일 emulator port에 맞는 portproxy가 살아 있는가?
- Docker local ADB가 `device` 상태를 보는가?
---
## 7. Android SDK license 관련
현재 `scripts/flutter-docker.sh`에는 Android SDK license 선행 승인 로직이 들어 있다.
다음과 같은 오류가 나면 먼저 cache 상태를 의심한다:
- `ndk;28.2.13676358` license not accepted
- `CMake 3.22.1` license not accepted
**확인 경로**:
```bash
ls -la /home/ubuntu/workspace/tdc114plus/.docker-cache/flutter/android-sdk/licenses/
```
이 디렉터리들이 비어 있지 않으면 재사용되는 것이 정상이다.
---
## 8. 정상 기대 상태
정상 재개 기준:
- ✅ `./scripts/check-baron-api-env.sh` 통과 (0 failures, 0 warnings)
- ✅ `./scripts/api-smoke.sh` 통과 (성공 코드 0)
- ✅ Android emulator device 인식 성공
- ✅ integration test 통과
**Integration test에서 확인할 실제 홈화면 기대값**:
로그인 후 홈화면에는 `문형석`의 조직 slug `is-3` 기준 팀 직원목록이 보여야 한다:
- `직원검색`
- `검색 결과`
- `문형석`
- `IS3`
---
## 9. 다음 조치
위 순서 중 어느 단계에서 실패했는지 `docs/daily-issues/YYYY-MM-DD.md`에 남긴다.
기록할 최소 항목:
- 실패 단계 (예: 3.2, 5.1, 5.2 등)
- 첫 번째 에러 메시지
- 수행한 자동 복구 명령
- 복구 성공 여부
- 추가 수동 개입 필요 여부 및 사유
**기록 예시**:
```
## 2026-07-06 출근 재기동
### 진행 상황
- [x] 3.1 Baron SSO 초기화: 성공
- [x] 3.2 상태 확인: 초기 실패 (baron_backend not running)
- [x] 5.1 자동 복구: docker compose 재시작 → 성공
- [x] 5.2 api-smoke 재확인: 통과
- [ ] 6.0 Android emulator: 미진행 (시간 부족)
### 실패 내역
- Initial check-baron-api-env.sh: WARN baron_backend not running
- Resolved with: docker compose -f ... up -d
- No source code changes needed
```
---
## 부록: 명령 치트시트
### 빠른 전체 초기화 (추천)
```bash
# 1. Baron SSO 전체 재시작 (권장)
cd /home/ubuntu/workspace/baron-sso-tdc114plus-api
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml down 2>/dev/null || true
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d
sleep 30
# 2. tdc114plus 상태 확인
cd /home/ubuntu/workspace/tdc114plus
./scripts/check-baron-api-env.sh && ./scripts/api-smoke.sh
```
### 컨테이너 상태 모니터링
```bash
# 실시간 로그 보기
docker logs -f baron_backend # 백엔드 로그
docker logs -f ory_kratos # 인증 로그
# 모든 baron/ory 컨테이너 상태
docker ps | grep -iE "baron|ory"
# 전체 상태 요약
docker ps --format '{{.Names}} {{.Status}}'
```
### 긴급 초기화 (최후의 수단)
```bash
cd /home/ubuntu/workspace/baron-sso-tdc114plus-api
# 모든 관련 컨테이너 강제 제거
docker ps -a --format '{{.Names}}' | grep -iE "baron|ory|sso" | xargs -r docker rm -f
# 전체 재시작
docker compose -f docker-compose.yaml -f compose.infra.yaml -f compose.ory.yaml up -d
# 서비스 안정화 대기
sleep 40
# 상태 확인
docker ps | grep -iE "baron_backend|ory_kratos"
```
### 일반적인 문제 해결
```bash
# 권한 문제 수정 (config 디렉터리 쓰기 불가)
cd /home/ubuntu/workspace/baron-sso-tdc114plus-api
chmod -R u+w config/.generated/ 2>/dev/null || true
# Ory 마이그레이션 재시도
docker compose -f docker-compose.yaml -f compose.ory.yaml up kratos-migrate
# 특정 컨테이너만 재시작
docker restart baron_backend
docker restart ory_kratos
# 로그 대량 확인
docker logs baron_backend 2>&1 | grep -i error | tail -20
```
---
## 변경 이력
### v2.0 (2026-07-06)
- 자동 복구 정책 섹션 추가 (섹션 4)
- Ory 포함 필수 명시 (섹션 3.1)
- 컨테이너 정리 자동화 (섹션 5.1)
- 안정화 대기 시간 추가 (30~40초)
- 권한 문제 자동 처리 설명 추가
- 명령 치트시트 부록 추가
- 문제 기록 템플릿 추가 (섹션 9)
### v1.0 (2026-07-03)
초기 버전: 기본 기동 절차 및 복구 순서