toki/appsok
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
appsok/agent-ops/rules/project/domain/device-console/rules.md

3.4 KiB
Raw Blame History

domain last_rule_review_commit last_rule_updated_at
device-console c1c4c41886 2026-06-14

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/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 오류 표현

유지할 패턴

  • 화면 코드에서 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를 모두 보존해 사용자에게 원인 파악 정보를 제공한다.
  • 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 handoff는 shell이 조율하고, device-console은 설치/logcat 요청을 수행한다.
  • macos-platform: bundled ADB 리소스, sandbox, codesign, packaging 제약은 macos-platform에서 관리하고, runtime 선택과 command semantics는 device-console에서 관리한다.

금지 사항

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