kevin/tdc114plus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
tdc114plus/docs/policy_android_app_install_execution_2026-07-06.md
T

14 KiB
Raw Permalink Blame History

Android 앱 설치/실행 재발 방지 정책

작성일: 2026-07-06 상태: v1.4

목적: Windows Android Studio emulator + WSL/Docker Flutter 환경과 Android 공기계 USB 연결 환경에서 tdc114plus 앱을 테스트할 때, 환경값 누락과 ADB 연결 장애로 같은 문제를 반복하지 않도록 설치/실행 정책을 고정한다.

관련 문서:

  • docs/policy_android_studio_wsl_adb_2026-07-03.md
  • docs/scenario_android_emulator_device_integration_test_2026-07-03.md
  • scripts/README.md

1. 이번 장애 요약

2026-07-06에 아래 문제가 재현되었다.

  • 최신 코드를 빌드한 뒤 adb install로 debug APK만 직접 설치했다.
  • 그러나 이 앱은 TDC114_API_BASE 같은 runtime 값을 --dart-define으로 받는다.
  • APK 직접 설치 방식은 이 값을 전달하지 못한다.
  • 결과적으로 앱은 기본값 https://sso.example.invalid를 바라보게 되었고, 직원 목록 API가 실패했다.
  • 사용자는 코드가 반영되지 않았거나 필터 버그가 남아 있다고 오해할 수 있었다.

핵심 원인:

  • 문제는 코드 수정 자체가 아니라 설치 방식이 앱의 runtime config 구조와 맞지 않은 것이었다.

2. 필수 원칙

  • tdc114plus Android 수동 검증 기본 경로는 flutter run이다.
  • TDC114_API_BASE가 필요한 앱 실행은 반드시 dart-define 포함 경로로 띄운다.
  • adb install 또는 APK 파일 직접 설치는 기본 검증 경로로 사용하지 않는다.
  • local Baron SSO 검증은 emulator 기준 http://10.0.2.2:5000을 사용한다.
  • 앱/API 버그 판단 전에는 먼저 ./scripts/api-smoke.sh로 backend 상태를 확인한다.
  • Windows adb.exe devices에서 대상 emulator가 device 상태로 안정화되기 전에는 WSL/Docker Android 스크립트를 실행하지 않는다.
  • 2026-07-08 기준 Windows Android Studio emulator + Docker Flutter 표준 연결 방식은 ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037이다.
  • TDC114_ADB_CONNECT_ADDRESS=<WINDOWS_HOST_IP>:<EMULATOR_PORT> 직접 연결 방식은 Windows ADB 서버 공유 방식이 실패하거나 integration test의 VM service port forwarding 이슈가 확인된 경우에만 보조 경로로 사용한다.
  • 2026-07-08 이후 신규 수동 기능점검의 기본 target은 가능하면 Android 공기계 USB 연결 방식으로 전환한다.
  • emulator 경로는 보조/fallback으로 보존하되, 물리 키보드 한글 입력이나 emulator portproxy 문제를 해결하기 위해 emulator 설정을 반복하지 않는다.
  • 공기계에서는 10.0.2.2를 사용할 수 없으므로 adb reverse tcp:5000 tcp:5000 + TDC114_API_BASE=http://127.0.0.1:5000을 우선 사용한다.
  • USB 없는 독립형 실기기 검증에서는 TDC114_API_BASE=https://<staging-or-production-host>를 사용하고 TDC114_SKIP_SESSION_BOOTSTRAP=true로 로컬 bootstrap/mocking을 끈다.
  • 2026-07-08 이후 로그인과 데이터 소스를 분리해야 하면 TDC114_AUTH_API_BASE, TDC114_DIRECTORY_API_BASE, TDC114_ORGANIZATION_API_BASE를 별도로 지정할 수 있다. 값을 지정하지 않으면 모두 TDC114_API_BASE를 사용한다.

3. 허용 경로와 금지 경로

3.1 기본 허용 경로

공기계 USB 수동 기능점검을 우선한다.

ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037 \
TDC114_SMOKE_ENV_FILE=scripts/.env.android-device.local \
TDC114_FLUTTER_DEVICE_ID=<PHYSICAL_DEVICE_ID> \
./scripts/manual-postlogin-run.sh

사전 조건:

  • Windows PowerShell adb.exe devices에서 공기계가 device 상태다.
  • adb reverse tcp:5000 tcp:5000이 적용되어 있다.
  • scripts/.env.android-device.local의 TDC114_API_BASE는 http://127.0.0.1:5000이다.

3.1-B USB 없는 독립형 실기기 허용 경로

staging 또는 production 공개 API에 직접 붙는 실기기 검증은 아래 경로를 사용한다.

ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037 \
TDC114_SMOKE_ENV_FILE=scripts/.env.android-device.staging.local \
TDC114_FLUTTER_DEVICE_ID=<PHYSICAL_DEVICE_ID> \
./scripts/manual-postlogin-run.sh

사전 조건:

  • TDC114_API_BASE는 https://... 공개 HTTPS Baron API 주소다.
  • 필요 시 로그인은 staging, 직원/조직 데이터는 production으로 분리 주입할 수 있다.
  • TDC114_SKIP_SESSION_BOOTSTRAP=true가 설정되어 있다.
  • 로그인은 앱의 Baron SSO로 로그인 버튼에서 Hosted Login을 열고, App Link callback과 PKCE token 교환으로 완료한다.
  • USB는 최초 설치/실행 후 분리 가능해야 한다.

3.1-A emulator fallback 허용 경로

emulator를 쓸 경우 아래 경로만 허용한다.

ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037 \
TDC114_SMOKE_ENV_FILE=scripts/.env.android-emulator.local \
./scripts/manual-postlogin-run.sh

용도:

  • post-login 상태 수동 기능 점검
  • local API base URL 포함 실행
  • 실제 phone-login bootstrap 또는 mock fallback 포함 실행

실제 로그인 화면 검증이 필요하면 RP issuer/client/callback 값이 맞는지 확인한 뒤 Baron SSO로 로그인 버튼에서 외부 Hosted Login을 연다.

3.2 조건부 허용 경로

ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037 \
TDC114_SMOKE_ENV_FILE=scripts/.env.android-emulator.local \
./scripts/integration_tests.sh

용도:

  • integration smoke
  • post-login 가정 자동 검증

3.3 금지 경로

아래 방식은 정책상 기본 검증 경로로 금지한다.

adb install app-debug.apk

금지 이유:

  • TDC114_API_BASE
  • TDC114_PREAUTH_*
  • TDC114_SMOKE_USE_MOCK_DIRECTORY

같은 runtime define 값이 전달되지 않는다.

예외:

  • 단순 설치 가능 여부 확인
  • 패키지명 확인
  • manifest 수준 점검

이 경우에도 기능 검증용 실행으로 간주하지 않는다.

3-A. 직원검색 초기 기본값 정책

직원검색 첫 진입 시 기본값은 아래처럼 고정한다.

  • 초기 조회 범위: 로그인 사용자의 회사급 범위
  • 상단 기본 노출 칩: 회사급 칩 + 본인팀 칩
  • 금지 동작: 앱 시작 직후 phone/name 재조회로 본인 1명 결과에 맞춰 초기 범위를 다시 팀 또는 개인 단위로 축소하는 로직

정책 이유:

  • 첫 진입에서 사용자가 자기 자신만 보이면 디렉터리 앱 기본 UX와 맞지 않는다.
  • 조직/회사 단위 탐색이 시작점이어야 하고, 본인팀은 빠른 재선택용 칩으로 유지하면 충분하다.
  • 회사급 범위 조회와 본인팀 칩 고정 노출은 서로 다른 정책이므로 둘 다 함께 유지해야 한다.

4. 실행 전 체크 순서

Android 기능점검 전에는 아래 순서를 고정한다.

4.1 공기계 USB 기본 순서

  1. Windows PowerShell에서 adb.exe devices 확인
  2. 공기계가 device 상태인지 확인
  3. ./scripts/api-smoke.sh 통과 확인
  4. adb reverse tcp:5000 tcp:5000 적용
  5. scripts/check-android-device-env.sh 통과 확인
  6. manual-postlogin-run.sh 실행

중단 기준:

  • Windows adb.exe devices에서 공기계가 unauthorized이면 단말 RSA 승인 전까지 진행하지 않는다.
  • adb reverse가 실패하면 LAN IP 방식으로 바꾸기 전에는 127.0.0.1:5000 기준 앱 실행을 하지 않는다.
  • 앱에서 HTTP API가 차단되면 debug 전용 cleartext 허용 설정을 먼저 검토한다.

4.1-B USB 없는 독립형 실기기 순서

  1. Windows PowerShell에서 adb.exe devices 확인
  2. 공기계 또는 실사용 폰이 device 상태인지 확인
  3. TDC114_API_BASE=https://<staging-or-production-host>로 env를 준비
  4. TDC114_SKIP_SESSION_BOOTSTRAP=true 상태로 manual-postlogin-run.sh 실행
  5. 앱 첫 화면에서 Baron SSO로 로그인 수행
  6. 문자 또는 메일의 링크 승인 완료
  7. 직원검색, organization/tenants, organization/orgchart 화면 동작 확인
  8. 앱이 열린 뒤 USB를 분리하고 같은 동작이 유지되는지 재확인

중단 기준:

  • 공개 HTTPS base URL이 확정되지 않았으면 진행하지 않는다.
  • Hosted Login, App Link callback, PKCE token 교환이 staging/production 환경에서 준비되지 않았으면 local mode로 되돌리지 않고 RP 설정과 서버 준비 상태를 먼저 맞춘다.
  • 승인 링크 수신 채널이 준비되지 않았으면 USB 없는 독립 검증 완료로 간주하지 않는다.

4.2 emulator fallback 순서

  1. Windows PowerShell에서 adb.exe devices 확인
  2. 대상 emulator가 device 상태인지 확인
  3. ./scripts/api-smoke.sh 통과 확인
  4. Windows ADB server 5037 -> 127.0.0.1:5037 portproxy와 방화벽 rule 확인
  5. 그 다음 manual-postlogin-run.sh 또는 integration_tests.sh 실행

중단 기준:

  • Windows adb.exe devices에서 대상 emulator가 offline이면 WSL/Docker 스크립트를 실행하지 않는다.
  • Windows adb.exe devices가 device인데 Docker local ADB 직접 연결이 offline이면, 직접 emulator port 연결을 반복하지 않고 ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037 방식으로 전환한다.
  • Android Studio Device Manager의 표시 이름과 실제 AVD 폴더 이름이 달라도, C:\Users\user\.android\avd에 저장된 AVD 수와 Windows adb.exe devices 상태를 우선 기준으로 삼는다.
  • AVD 프로세스가 terminated되거나 Android Studio가 failed to connect within 5 minutes를 표시하면 WSL/Docker 확인으로 넘어가지 않고 Windows 단독 emulator 부팅 안정화부터 처리한다.

완료 기준:

  • 앱이 local API 기준으로 실행된다
  • 직원검색 또는 로그인 화면이 기대한 경로로 열린다

5. 포트가 왜 바뀌는가

질문: 코드 수정이 생길 때마다 포트가 바뀌는가?

답: 아니다. 코드 수정 때문에 포트가 바뀌는 것이 아니다.

포트가 바뀌는 이유는 보통 아래 중 하나다.

  • 새 emulator 인스턴스를 띄웠다
  • 기존 emulator를 끄고 다른 emulator 번호로 다시 띄웠다
  • emulator-5554, 5556, 5558처럼 여러 인스턴스가 섞였다
  • Windows portproxy가 그 emulator의 adbd port와 맞지 않았다

즉:

  • 코드 변경
  • Flutter rebuild
  • hot reload

이 자체는 emulator port를 바꾸지 않는다.

6. 반복 절차를 줄이는 고정 운영안

반복을 줄이기 위해 아래 운영안을 기본값으로 사용한다.

6.1 1대 고정 원칙

  • 수동 검증용 emulator는 한 번에 1대만 켠다.
  • 기본 장비는 당일 Windows adb.exe devices에서 device로 확인된 emulator 1대다.
  • 다른 emulator가 offline으로 남아 있거나 여러 인스턴스가 섞이면 Android Studio/ADB 상태를 먼저 정리한다.

효과:

  • 어떤 emulator가 현재 대상인지 혼선이 줄어든다.
  • offline/refused 원인 추적이 쉬워진다.

6.2 Windows ADB 서버 공유 원칙

  • Docker/WSL Flutter는 기본적으로 Windows ADB server를 공유한다.
  • 표준 환경변수는 ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037이다.
  • Windows 관리자 PowerShell에서 0.0.0.0:5037 -> 127.0.0.1:5037 portproxy와 방화벽 rule을 유지한다.
  • Windows adb.exe devices에서 emulator-5562 device처럼 정상으로 보이면, Docker Flutter도 같은 Windows ADB server를 통해 장치를 인식해야 한다.
  • 직접 emulator adbd port 연결이 offline으로 반복되면 해당 방식은 중단하고 Windows ADB server 공유 방식만 사용한다.

효과:

  • Docker container 내부 ADB key 불일치로 인한 offline/unauthorized 반복을 줄인다.
  • Windows에서 이미 정상 승인된 ADB 세션을 그대로 사용한다.

6.3 명시 emulator portproxy 원칙

  • 수동 검증 포트는 Windows adb.exe devices에서 확인한 emulator port에 맞춘다.
  • 예: Windows 대상이 emulator-5562이면 5562 -> 127.0.0.1:5562 portproxy와 방화벽 규칙을 확인한다.
  • TDC114_ADB_CONNECT_ADDRESS=<WINDOWS_HOST_IP>:<EMULATOR_PORT>는 보조 경로로만 명시한다.
  • shutdown/startup 스크립트는 과거 고정 포트를 임의로 disconnect하지 않는다.

효과:

  • 실제 대상 포트와 스크립트 포트가 어긋나는 일을 줄인다.

6.4 APK 직접 설치 금지

  • 코드 수정 후 수동 검증은 항상 flutter run 또는 manual-postlogin-run.sh
  • APK 직접 설치는 설치 확인용 보조 수단으로만 사용

효과:

  • runtime define 누락 사고를 막는다.

6.5 같은 세션 재사용

  • emulator를 켠 뒤 가능한 한 끄지 않는다.
  • flutter run 세션이 살아 있을 때는 hot reload/hot restart를 우선한다.
  • 큰 설정 변경이 아닐 때는 재설치보다 같은 세션 재사용을 우선한다.

효과:

  • rebuild/install 시간과 ADB 재연결 횟수가 줄어든다.

7. 표준 명령

7.1 post-login 수동 기능점검

TDC114_SMOKE_ENV_FILE=scripts/.env.android-emulator.local \
ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037 \
./scripts/manual-postlogin-run.sh

7.2 integration smoke

TDC114_SMOKE_ENV_FILE=scripts/.env.android-emulator.local \
ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037 \
./scripts/integration_tests.sh

7.3 backend 상태 확인

./scripts/api-smoke.sh

8. 내일부터의 운영 기준

  • Android 수동 검증 기본 target은 USB 연결 공기계다.
  • Android emulator는 fallback target으로 보존한다.
  • Docker/WSL 기본 연결은 ADB_SERVER_SOCKET=tcp:<WINDOWS_HOST_IP>:5037로 명시한다.
  • TDC114_ADB_CONNECT_ADDRESS=<WINDOWS_HOST_IP>:<EMULATOR_PORT>는 직접 emulator port 연결이 필요한 예외 상황에만 사용
  • 실행 스크립트 기본값은 manual-postlogin-run.sh
  • adb install은 기능검증용 실행으로 인정하지 않음

이 기준을 어기면 다시 아래 오판이 발생할 수 있다.

  • 코드 미반영으로 오해
  • API 장애로 오해
  • 필터 버그 미수정으로 오해
Reference in New Issue View Git Blame Copy Permalink