# 출근 후 기동 확인 및 복구 체크리스트

**작성일**: 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)

초기 버전: 기본 기동 절차 및 복구 순서