# scripts 폴더 안내

이 폴더는 `tdc114plus` 앱 초기 설정, Flutter 실행 보조, 테스트 자동화용 shell script를 모아둔 위치이다.

## 파일별 용도

- `api-smoke.sh`: `TDC114_API_BASE` 대상 Baron SSO 연동 API에 최소 smoke test를 수행한다. `TDC114_SMOKE_PHONE`이 있으면 `TDC114_SMOKE_AUTH_FLOW`에 따라 legacy `phone-login` 호환 경로 또는 headless 링크 흐름을 확인한다.
- `smoke.env.example`: authenticated smoke용 로컬 env 예시 파일이다. `scripts/.env.smoke.local`로 복사해 `TDC114_API_BASE`, `TDC114_SMOKE_PHONE`을 넣어 사용할 수 있다.
- `smoke.staging.env.example`: staging Baron SSO 검증용 env 예시 파일이다. `scripts/.env.staging.local`로 복사해 `TDC114_API_BASE`, `TDC114_SMOKE_PHONE`과 optional expected label 값을 넣어 사용할 수 있다.
- `android-device.env.example`: Android 공기계 USB 테스트용 env 예시 파일이다. `scripts/.env.android-device.local`로 복사해 `adb reverse` 기준 `TDC114_API_BASE=http://127.0.0.1:5000`, `TDC114_AUTH_API_BASE=http://127.0.0.1:5001`을 사용한다.
- `android-device.staging.env.example`: Android 공기계/실폰의 USB 없는 staging 직접 로그인 테스트용 env 예시 파일이다. `scripts/.env.android-device.staging.local`로 복사해 공개 staging HTTPS base URL을 넣어 사용한다. Baron org-context key는 앱 env가 아니라 `tdc114plus-auth` 서버 env에만 둔다.
- `android-device.production.env.example`: Android 공기계/실폰의 USB 없는 production 직접 로그인 테스트용 env 예시 파일이다. `scripts/.env.android-device.production.local`로 복사해 공개 production HTTPS base URL을 넣어 사용한다.
- `bootstrap-baron-api-env.sh`: Baron SSO API worktree의 `.env.sample`을 바탕으로 로컬 smoke용 `.env`를 생성하고 localhost/알림 비활성 override를 덧붙인다.
- `check-baron-api-env.sh`: Baron SSO API worktree의 `.env`, compose, config, Docker runtime 준비 상태를 점검해 실제 API smoke 가능 여부를 빠르게 확인한다.
- `check-android-device-env.sh`: Android 공기계 USB 연결, Windows ADB server 공유, 선택적 `adb reverse` 상태를 점검한다.
- `host-adb.sh`: Docker를 거치지 않고 WSL 호스트의 Linux adb로 Windows ADB server에 접속한다. ADB 로그/스크린샷/reverse 조회처럼 Flutter가 필요 없는 작업에 사용한다.
- `install-host-adb-from-docker.sh`: Docker Flutter 이미지에서 Linux adb 바이너리를 `.tools/android-platform-tools/adb`로 1회 추출한다. 이후 ADB 조회 작업은 Docker 권한 없이 `host-adb.sh`로 처리한다.
- `startup.sh`: Baron SSO runtime 기동, 상태 확인, API smoke 재시도를 자동화한다. `check-baron-api-env.sh`에 warning이 남거나 `api-smoke.sh`가 실패하면 비정상 종료한다.
- `shutdown.sh`: 대상 helper 프로세스 종료, compose 로그 수집, Baron SSO runtime 중지, 선택적 컨테이너 정리와 권한 복구를 자동화한다.
- `bootstrap.sh`: 로컬 Flutter SDK가 설치된 환경에서 `app/` 프로젝트의 `flutter pub get`을 실행한다.
- `create-flutter-app.sh`: `app/` Flutter 프로젝트가 없을 때 Android/iOS 기반 앱 골격을 생성한다.
- `flutter-docker.sh`: Docker Flutter 이미지를 이용해 `app/` 디렉터리에서 Flutter 명령을 실행한다. `.android-adb/`, `.docker-cache/flutter/` 아래 ADB key, Gradle, pub, Android SDK 일부 cache를 재사용한다.
- `manual-postlogin-run.sh`: Android target에 `dart-define`을 포함한 `flutter run` 경로로 앱을 띄운다. 기본 정책은 Baron SSO Hosted Login + PKCE 진입이며, 필요 시에만 legacy local `phone-login` bootstrap으로 post-login 상태를 seed 한다.
- `format-dart.sh`: Docker Flutter 환경에서 Dart 코드 포맷을 적용한다.
- `generate-release-report.sh`: 현재 git 상태와 릴리스 점검 항목을 기반으로 report를 생성한다.
- `integration_tests.sh`: `app/integration_test/` smoke test를 실행한다. Android target 선행 확인은 실기기 기준이 기본이며 emulator는 fallback이다. `TDC114_API_BASE`와 `TDC114_SMOKE_PHONE`을 넘기면 실제 API 로그인 smoke까지 확장할 수 있다.
- `mock-server.sh`: 향후 mock API 서버 제어용 scaffold 스크립트이다. 현재는 `status`, `stop`만 간단히 동작하고 `start`는 미구현 안내를 출력한다.
- `perf_smoke.sh`: 현재 앱/테스트 파일 수와 기본 상태를 빠르게 확인하는 경량 smoke 스크립트이다.
- `quality-gate.sh`: Docker Flutter 환경에서 `flutter analyze`와 `flutter test`를 순서대로 실행한다.
- `save-snapshots.sh`: widget/integration snapshot 산출물이 있으면 지정한 report 경로로 복사해 보관한다.
- `test.sh`: 로컬 Flutter SDK가 설치된 환경에서 `flutter analyze`와 `flutter test`를 실행한다.
- `redteam/run_all.sh`: 현재 앱 범위에서는 미사용인 AI/LLM redteam 자동화용 scaffold 스크립트이다.

## 참고

- 테스트 자동화 운영 기준은 `docs/guide_tdc114plus_script_automation_plan_2026-07-02.md`를 따른다.
- Docker 기반 Flutter 검증이 기본 경로이므로 일반적인 앱 변경 후에는 `format-dart.sh`, `quality-gate.sh`를 우선 사용한다.
- `api-smoke.sh`, `integration_tests.sh`는 `scripts/.env.smoke.local` 파일이 있으면 자동으로 읽는다.
- staging 검증 시에는 `TDC114_SMOKE_ENV_FILE=scripts/.env.staging.local` 방식으로 env 파일을 명시해 실행한다.
- Android 공기계 USB 검증 시에는 `TDC114_SMOKE_ENV_FILE=scripts/.env.android-device.local`과 `TDC114_FLUTTER_DEVICE_ID=<PHYSICAL_DEVICE_ID>`를 명시한다.
- ADB 로그 조회, `devices`, `reverse --list`, `screencap` 등 Flutter가 필요 없는 ADB 작업은 `flutter-docker.sh adb` 대신 `ADB_SERVER_SOCKET=tcp:172.21.128.1:5037 ./scripts/host-adb.sh ...`를 우선 사용한다.
- USB 없는 staging 직접 로그인 검증 시에는 `TDC114_SMOKE_ENV_FILE=scripts/.env.android-device.staging.local`과 `TDC114_FLUTTER_DEVICE_ID=<PHYSICAL_DEVICE_ID>`를 명시한다.
- 로그인만 staging, 직원/조직 정보만 production으로 분리해야 할 경우 `TDC114_AUTH_API_BASE`, `TDC114_DIRECTORY_API_BASE`, `TDC114_ORGANIZATION_API_BASE`를 추가로 지정한다. 값을 비우면 모두 `TDC114_API_BASE`를 따른다.
- 앱 실행 env에는 `TDC114_BARON_KEY_ID`, `TDC114_BARON_KEY_SECRET`, NAVER WORKS secret을 넣지 않는다. 조직도 key와 네이버웍스 key는 `tdc114plus-auth` 서버 환경변수에서만 관리한다.
- `startup.sh`, `shutdown.sh`는 테스트나 다른 worktree 재사용을 위해 `BARON_SSO_WORKTREE`, `TDC114_LOG_BASE`, `DOCKER_BIN` 같은 환경 변수 override를 지원한다.
- 업무 시작 절차에서는 앱 직접 App Link callback 테스트 서버를 더 이상 기동하지 않는다. 현재 로그인은 `tdc114plus-auth`의 `/api/v1/auth/link/init`, `/api/v1/auth/link/poll` 경로를 사용한다.
- Windows Android Studio emulator + WSL/Docker Flutter 운영 기준은 `docs/policy_android_studio_wsl_adb_2026-07-03.md`를 따른다.
- Android 앱 설치/실행 재발 방지 기준은 `docs/policy_android_app_install_execution_2026-07-06.md`를 따른다.
- 반복 지연 대응 정리는 `docs/troubleshooting/flutter-docker-repeated-delay-countermeasures-2026-07-03.md`를 참고한다.
- `TDC114_SESSION_BOOTSTRAP_MODE=legacy-phone-login`은 옛 호환 점검용 예외 경로다. 신규 정책 기본값은 mock seed 또는 실제 Hosted Login + PKCE 검증이다.
