---
domain: device-console
last_rule_review_commit: fea3860d011f006a058506cb1f054407a5975a87
last_rule_updated_at: 2026-06-24
---

# device-console

## 목적 / 책임

USB로 연결된 Android 기기 조회, APK 설치, ADB runtime 해석/진단, logcat/ADB 콘솔 경험을 담당한다.

## 포함 경로

- `lib/src/features/devices/` — ADB device 목록과 설치 대상 선택 UI
- `lib/src/features/console/` — logcat viewer와 필터 UI
- `lib/src/models/adb_device.dart` — ADB device 모델
- `lib/src/models/install_attempt_result.dart` — 설치 시도 결과, 요약, masked copy report 모델
- `lib/src/services/adb_service.dart` — `adb devices`, `adb install`, `adb logcat` 실행

## 제외 경로

- `lib/src/services/jenkins_client.dart` — Jenkins API 호출은 `artifact-flow` 책임
- `lib/src/features/builds/` — artifact 선택과 다운로드는 `artifact-flow` 책임
- `lib/src/models/pending_install.dart` — 설치 대기 handoff DTO는 `app-shell` 책임이며 device-console은 입력으로만 소비
- `macos/` — sandbox, process 실행, USB 접근 정책은 `macos-platform` 책임

## 주요 구성 요소

- `DevicesPage` — 연결 기기 목록 UI
- `ConsolePage` — logcat console UI
- `AdbDevice` — serial/state/model/product metadata
- `AdbService` — ADB command 실행 wrapper
- `AdbRuntimeConfig`, `AdbRuntime` — bundled/custom/system ADB 선택과 `ADB_SERVER_PORT` 환경 구성
- `AdbLogcatSession` — running `adb logcat` process lifetime wrapper
- `AdbRuntimeDiagnostics` — ADB executable path/source/version/SHA-256 진단 결과
- `AdbInstallResult`, `AdbException` — 설치 결과와 ADB 오류 표현
- `InstallAttemptResult`, `InstallAttemptOutcome` — pending APK, device, ADB install result를 묶은 설치 결과와 민감정보 masking 리포트

## 유지할 패턴

- 화면 코드에서 `Process.run` 또는 `Process.start`를 직접 호출하지 않고 `AdbService`를 통한다.
- ADB runtime 선택은 custom path, bundled path, system fallback 순서를 유지하고, 기본 AppSok 전용 server port는 `5038`로 둔다.
- `adb devices -l` parsing은 다양한 state(`device`, `unauthorized`, `offline`)를 허용한다.
- 설치 결과는 exit code, stdout, stderr를 모두 보존해 사용자에게 원인 파악 정보를 제공한다.
- 설치 결과 요약이나 복사용 리포트는 URL, token/password/secret, device serial을 masking한 값만 UI/clipboard에 노출한다.
- logcat stream은 pause/clear/filter 같은 UI 상태와 process lifetime을 분리하고, `AdbLogcatSession.stop`으로 process를 종료한다.
- 콘솔 UI는 오래 실행되는 logcat session에서 화면 보관 line 수를 제한하고 level/text filter를 UI 상태로만 관리한다.
- ADB 진단은 `adb version` timeout과 executable SHA-256 계산을 best-effort로 수행한다.

## 다른 도메인과의 경계

- **artifact-flow**: 설치할 staged APK path와 metadata만 입력으로 받고 Jenkins 인증/다운로드 상태에는 의존하지 않는다. settings 화면에 ADB diagnostics panel이 있어도 진단 타입과 loader semantics는 device-console 소유다.
- **app-shell**: pending install, 선택 device, 마지막 설치 결과의 lifecycle state는 shell이 조율하고, device-console은 설치/logcat 요청 수행과 설치 결과 표현 모델을 소유한다.
- **macos-platform**: bundled ADB 리소스, sandbox, codesign, packaging 제약은 macos-platform에서 관리하고, runtime 선택과 command semantics는 device-console에서 관리한다.

## 금지 사항

- device serial, logcat 원문에 secret이 포함될 수 있으므로 불필요하게 tracked 파일에 저장하지 않는다.
- 설치 실패 stdout/stderr, 복사용 리포트, device serial 원문을 masking 없이 UI나 clipboard에 노출하지 않는다.
- split APK/APKS/AAB 설치를 단일 APK 설치 흐름에 섞어 임시 처리하지 않는다.
- 무한 logcat stream을 dispose 없이 방치하지 않는다.
- 화면 widget에서 ADB binary 경로, environment, server port를 직접 구성하지 않는다.
