---
ui_doc_type: view
view_id: devices
status: 구현됨
frame: null
source_evidence:
  - type: code
    path: lib/src/features/devices/devices_page.dart
    notes: "DevicesPage, _DeviceTile, _PendingInstallBanner, _InstallResultBanner"
  - type: docs
    path: README.md
    notes: "Android device 목록 조회와 adb install scope"
  - type: user
    path: null
    notes: "agent-ui 생성 요청"
regions:
  - devices.pending-install
  - devices.install-result
  - devices.filter-bar
  - devices.device-grid
---

# Devices

View ID: `devices`

Frame:
- 없음

Status: `구현됨`

## Source Evidence

| Type | Path | Notes |
|------|------|-------|
| code | `lib/src/features/devices/devices_page.dart` | `DevicesPage`, `_DeviceTile`, `_PendingInstallBanner`, `_InstallResultBanner` |
| docs | `README.md` | Android device 목록 조회와 `adb install` scope |
| user | 없음 | agent-ui 생성 요청 |

## Purpose

USB로 연결된 Android device를 상태별로 확인하고, 빌드 화면에서 넘어온 pending APK를 ready device에 설치한다. 최근 설치 결과와 masked report copy action도 제공한다.

## Primary Users

- 설치 대상 Android device를 선택하고 설치 결과를 확인하는 개발자 또는 QA 담당자

## Primary Tasks

- device 목록을 새로고침하고 ready/attention 상태로 필터링한다.
- pending APK를 ready device에 설치한다.
- 설치 성공/실패 결과를 확인하고 리포트를 복사한다.
- 특정 device의 logcat을 console 화면에서 연다.

## Information Priority

1. pending install 또는 현재 설치 결과 banner
2. ready/attention filter와 refresh action
3. device tile grid의 readiness, serial, metadata, install/logcat action

## Regions

| Region ID | Purpose | Component | Priority | Notes |
|-----------|---------|-----------|----------|-------|
| `devices.pending-install` | 설치 대기 APK와 취소 action 표시 | `install-banner` | high | `pending-install-banner` |
| `devices.install-result` | 현재 설치 결과, masked output, copy/clear action 표시 | `install-banner` | high | `install-result-banner` |
| `devices.filter-bar` | 전체/준비됨/대기 filter와 새로고침 | 없음 | medium | `SegmentedButton`, `device-refresh-button` |
| `devices.device-grid` | device tile grid와 install/logcat action | `device-tile` | high | `GridView.builder` |

## Actions

| Action ID | Trigger | Result | Guard |
|-----------|---------|--------|-------|
| `devices.change-filter` | SegmentedButton 선택 | 전체/준비됨/대기 device 목록을 표시 | 없음 |
| `devices.refresh` | 새로고침 button | ADB device loader 재실행 | loading 중이 아님 |
| `devices.cancel-pending-install` | pending banner close button | pending APK cleanup 요청 | install 진행 중이 아님 |
| `devices.install` | device tile 설치 icon | selected device에 pending APK 설치 | pending install 있음, device ready, installer 있음 |
| `devices.open-logcat` | device tile logcat icon | console view로 이동하고 device를 선택 | device ready |
| `devices.copy-install-report` | 설치 결과 copy icon | masked report를 clipboard로 복사 | install result 있음 |
| `devices.clear-install-result` | 설치 결과 close icon | 현재 install result banner 제거 | install result 있음 |

## States

- loading: device refresh 중 linear progress와 empty grid loading indicator를 표시한다.
- empty: device가 없으면 empty view를 표시한다.
- error: ADB device load error와 retry action을 표시한다.
- permission-denied: ADB 권한/상태 문제는 device state chip과 error로 표현한다.

## Open Questions

- 없음

## Decision History

- 2026-06-25: ADB device grid와 install handoff 상태를 `devices` view로 기록했다.
