From b5a1d1a4ef663f0b68795a1f3c45381c78460df2 Mon Sep 17 00:00:00 2001 From: toki Date: Thu, 25 Jun 2026 10:50:08 +0900 Subject: [PATCH] =?UTF-8?q?docs(agent-ui):=20=EB=A0=88=EA=B1=B0=EC=8B=9C?= =?UTF-8?q?=20=EA=B8=B0=EC=A4=80=EC=84=A0=EC=9D=84=20=EC=A0=95=ED=95=A9?= =?UTF-8?q?=ED=99=94=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- agent-ui/README.md | 27 +++++ agent-ui/archive/user-review/.gitkeep | 0 .../definition/archive/components/.gitkeep | 0 agent-ui/definition/archive/views/.gitkeep | 0 .../components/adb-diagnostics/index.md | 72 +++++++++++++ .../definition/components/build-row/index.md | 68 ++++++++++++ .../components/device-tile/index.md | 71 +++++++++++++ agent-ui/definition/components/index.md | 37 +++++++ .../components/install-banner/index.md | 72 +++++++++++++ .../components/install-cta/index.md | 69 ++++++++++++ .../jenkins-credential-panel/index.md | 76 +++++++++++++ .../definition/components/job-list/index.md | 69 ++++++++++++ .../components/logcat-viewer/index.md | 67 ++++++++++++ .../components/shell-navigation/index.md | 63 +++++++++++ .../components/status-pill/index.md | 65 ++++++++++++ agent-ui/definition/index.md | 83 +++++++++++++++ agent-ui/definition/views/app-shell/index.md | 88 +++++++++++++++ agent-ui/definition/views/builds/index.md | 100 ++++++++++++++++++ agent-ui/definition/views/console/index.md | 94 ++++++++++++++++ agent-ui/definition/views/devices/index.md | 95 +++++++++++++++++ agent-ui/definition/views/index.md | 48 +++++++++ .../views/jenkins-web-login/index.md | 88 +++++++++++++++ agent-ui/definition/views/settings/index.md | 97 +++++++++++++++++ agent-ui/frame/index.md | 23 ++++ 24 files changed, 1472 insertions(+) create mode 100644 agent-ui/README.md create mode 100644 agent-ui/archive/user-review/.gitkeep create mode 100644 agent-ui/definition/archive/components/.gitkeep create mode 100644 agent-ui/definition/archive/views/.gitkeep create mode 100644 agent-ui/definition/components/adb-diagnostics/index.md create mode 100644 agent-ui/definition/components/build-row/index.md create mode 100644 agent-ui/definition/components/device-tile/index.md create mode 100644 agent-ui/definition/components/index.md create mode 100644 agent-ui/definition/components/install-banner/index.md create mode 100644 agent-ui/definition/components/install-cta/index.md create mode 100644 agent-ui/definition/components/jenkins-credential-panel/index.md create mode 100644 agent-ui/definition/components/job-list/index.md create mode 100644 agent-ui/definition/components/logcat-viewer/index.md create mode 100644 agent-ui/definition/components/shell-navigation/index.md create mode 100644 agent-ui/definition/components/status-pill/index.md create mode 100644 agent-ui/definition/index.md create mode 100644 agent-ui/definition/views/app-shell/index.md create mode 100644 agent-ui/definition/views/builds/index.md create mode 100644 agent-ui/definition/views/console/index.md create mode 100644 agent-ui/definition/views/devices/index.md create mode 100644 agent-ui/definition/views/index.md create mode 100644 agent-ui/definition/views/jenkins-web-login/index.md create mode 100644 agent-ui/definition/views/settings/index.md create mode 100644 agent-ui/frame/index.md diff --git a/agent-ui/README.md b/agent-ui/README.md new file mode 100644 index 0000000..df17bce --- /dev/null +++ b/agent-ui/README.md @@ -0,0 +1,27 @@ +--- +ui_doc_type: readme +surface_type: ops-dev +--- + +# agent-ui + +이 디렉터리는 AppSok의 ops/dev UI 의도, 화면 구조, 반복 구성요소를 사람과 agent가 같은 기준으로 읽기 위한 작업 문맥 저장소다. + +## 대상 + +- 1차 대상: Flutter macOS ops/dev UI +- 확장 후보: product UI 레이어가 필요해지면 brand, content, assets, tokens, motion 정의를 같은 구조 위에 추가한다. + +## 구조 + +- `definition/`: 현재 UI 정의 source of truth +- `frame/`: visual source가 있는 view의 wireframe 연결 +- `USER_REVIEW.md`: 사용자 판단이 필요한 활성 질문 +- `archive/user-review/`: 해결된 사용자 리뷰 로그 + +## 기본 규칙 + +- 현재 기준은 `definition/**`에 둔다. +- visual wireframe은 visual source가 있을 때만 `frame/**`에 둔다. +- `.excalidraw` 파일만으로 UI 기준을 확정하지 않는다. +- `definition/archive/**`와 `archive/user-review/**`는 과거 기록이며 일반 작업에서 읽지 않는다. diff --git a/agent-ui/archive/user-review/.gitkeep b/agent-ui/archive/user-review/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/agent-ui/definition/archive/components/.gitkeep b/agent-ui/definition/archive/components/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/agent-ui/definition/archive/views/.gitkeep b/agent-ui/definition/archive/views/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/agent-ui/definition/components/adb-diagnostics/index.md b/agent-ui/definition/components/adb-diagnostics/index.md new file mode 100644 index 0000000..6db8dff --- /dev/null +++ b/agent-ui/definition/components/adb-diagnostics/index.md @@ -0,0 +1,72 @@ +--- +ui_doc_type: component +component_id: adb-diagnostics +status: 구현됨 +source_evidence: + - type: code + path: lib/src/features/settings/settings_page.dart + notes: "_AdbDiagnosticsSection, _DiagRows, _DiagRow" + - type: docs + path: README.md + notes: "ADB 실행과 USB device 접근 scope" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# ADB Diagnostics + +Component ID: `adb-diagnostics` + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/settings/settings_page.dart` | `_AdbDiagnosticsSection`, `_DiagRows`, `_DiagRow` | +| docs | `README.md` | ADB 실행과 USB device 접근 scope | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +현재 ADB runtime source, executable path, server port, version, version error, SHA-256 요약을 설정 화면에서 확인한다. + +## Used By + +- `settings`: `settings.adb-diagnostics` + +## Anatomy + +- diagnostics title label +- loading/refresh icon +- source row +- path row +- server port row +- optional version row +- optional version error row +- optional hash row + +## Variants + +- default: diagnostics rows 표시 +- loading: hourglass icon +- empty: 진단 정보 없음 +- error: 진단 로드 실패 + +## States + +- default +- loading +- empty +- error +- disabled + +## Rules + +- path/version/hash 값은 길어질 수 있으므로 한 줄 ellipsis를 사용한다. +- version error row는 error color로 표시한다. + +## Decision History + +- 2026-06-25: ADB runtime diagnostics rows를 component로 기록했다. diff --git a/agent-ui/definition/components/build-row/index.md b/agent-ui/definition/components/build-row/index.md new file mode 100644 index 0000000..b3eca2e --- /dev/null +++ b/agent-ui/definition/components/build-row/index.md @@ -0,0 +1,68 @@ +--- +ui_doc_type: component +component_id: build-row +status: 구현됨 +source_evidence: + - type: code + path: lib/src/features/builds/builds_page.dart + notes: "_BuildRow, _StateBadge, _BuildStatus" + - type: docs + path: README.md + notes: "Jenkins build/artifact 조회 scope" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# Build Row + +Component ID: `build-row` + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/builds/builds_page.dart` | `_BuildRow`, `_StateBadge`, `_BuildStatus` | +| docs | `README.md` | Jenkins build/artifact 조회 scope | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +Jenkins build 하나의 결과 상태와 install에 필요한 metadata를 목록에서 스캔 가능하게 표시한다. + +## Used By + +- `builds`: `builds.build-search` +- `builds`: `builds.build-list` + +## Anatomy + +- result state badge +- requestedBy label +- build number, branch, flavor, startedAt, APK file summary +- selected radio icon + +## Variants + +- default: unselected row +- selected: primary outline과 checked icon +- status: build list empty/error/permission 안내 + +## States + +- default +- loading +- empty +- error +- disabled + +## Rules + +- build row는 선택 가능한 Material/InkWell 카드로 유지한다. +- build metadata는 길어질 수 있으므로 한 줄 또는 두 줄 ellipsis를 허용한다. + +## Decision History + +- 2026-06-25: Jenkins build 목록 row와 상태 badge를 component로 기록했다. diff --git a/agent-ui/definition/components/device-tile/index.md b/agent-ui/definition/components/device-tile/index.md new file mode 100644 index 0000000..250eeef --- /dev/null +++ b/agent-ui/definition/components/device-tile/index.md @@ -0,0 +1,71 @@ +--- +ui_doc_type: component +component_id: device-tile +status: 구현됨 +source_evidence: + - type: code + path: lib/src/features/devices/devices_page.dart + notes: "_DeviceTile, _DeviceStateChip, _CompactIconButton" + - type: docs + path: README.md + notes: "Android device 목록 조회 scope" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# Device Tile + +Component ID: `device-tile` + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/devices/devices_page.dart` | `_DeviceTile`, `_DeviceStateChip`, `_CompactIconButton` | +| docs | `README.md` | Android device 목록 조회 scope | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +Android device 하나의 readiness, serial, metadata, logcat/install actions를 grid card 안에서 표시한다. + +## Used By + +- `devices`: `devices.device-grid` + +## Anatomy + +- phone icon tinted by state +- display name +- serial +- product/device metadata +- state message +- state chip +- logcat icon action +- install icon action + +## Variants + +- ready: logcat 가능, pending install이 있으면 설치 가능 +- attention: offline/unauthorized 등 조치 필요 +- installing: install icon이 hourglass로 표시 + +## States + +- default +- loading: installing action 상태 +- empty: 해당 없음 +- error: device state message/chip으로 표현 +- disabled + +## Rules + +- install action은 pending install, installer, ready device, not installing 조건을 모두 만족해야 활성화한다. +- logcat action은 ready device와 callback이 있을 때만 활성화한다. + +## Decision History + +- 2026-06-25: ADB device grid item을 component로 기록했다. diff --git a/agent-ui/definition/components/index.md b/agent-ui/definition/components/index.md new file mode 100644 index 0000000..7766f15 --- /dev/null +++ b/agent-ui/definition/components/index.md @@ -0,0 +1,37 @@ +--- +ui_doc_type: components-index +components: + - shell-navigation + - status-pill + - job-list + - build-row + - install-cta + - device-tile + - install-banner + - logcat-viewer + - jenkins-credential-panel + - adb-diagnostics +--- + +# Component Definitions + +## Component List + +| Component ID | Status | Evidence | Description | +|--------------|--------|----------|-------------| +| `shell-navigation` | 구현됨 | `lib/src/features/app_shell.dart` | AppSok brand header와 NavigationRail page 전환 | +| `status-pill` | 구현됨 | `lib/src/features/app_shell.dart` | Jenkins/ADB 대기 상태를 top bar에 압축 표시 | +| `job-list` | 구현됨 | `lib/src/features/builds/builds_page.dart` | Jenkins job 검색과 job row 목록 | +| `build-row` | 구현됨 | `lib/src/features/builds/builds_page.dart` | build metadata, result badge, selected state 표시 | +| `install-cta` | 구현됨 | `lib/src/features/builds/builds_page.dart` | APK download, progress, retry, install handoff CTA | +| `device-tile` | 구현됨 | `lib/src/features/devices/devices_page.dart` | device 상태, metadata, logcat/install action 카드 | +| `install-banner` | 구현됨 | `lib/src/features/devices/devices_page.dart` | pending install과 현재 설치 결과 banner | +| `logcat-viewer` | 구현됨 | `lib/src/features/console/console_page.dart` | dark log viewer와 level-colored log line 표시 | +| `jenkins-credential-panel` | 구현됨 | `lib/src/features/settings/settings_page.dart` | Jenkins URL, job, credential action, save/clear result 표시 | +| `adb-diagnostics` | 구현됨 | `lib/src/features/settings/settings_page.dart` | ADB runtime source/path/version/hash 진단 row | + +## Rules + +- component 정의는 구현 API가 아니라 UI 사용 규칙을 다룬다. +- view별 변형이 필요하면 `/.md` 또는 하위 디렉터리를 사용한다. +- 실제 구현체 이름과 다를 수 있지만, view 정의서에서 참조하는 component id는 이 목록에 있어야 한다. diff --git a/agent-ui/definition/components/install-banner/index.md b/agent-ui/definition/components/install-banner/index.md new file mode 100644 index 0000000..0c5726d --- /dev/null +++ b/agent-ui/definition/components/install-banner/index.md @@ -0,0 +1,72 @@ +--- +ui_doc_type: component +component_id: install-banner +status: 구현됨 +source_evidence: + - type: code + path: lib/src/features/devices/devices_page.dart + notes: "_PendingInstallBanner와 _InstallResultBanner" + - type: docs + path: README.md + notes: "APK 설치와 결과 확인 scope" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# Install Banner + +Component ID: `install-banner` + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/devices/devices_page.dart` | `_PendingInstallBanner`와 `_InstallResultBanner` | +| docs | `README.md` | APK 설치와 결과 확인 scope | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +디바이스 화면 상단에서 pending install과 현재 설치 결과를 즉시 확인하고 필요한 후속 action을 제공한다. + +## Used By + +- `devices`: `devices.pending-install` +- `devices`: `devices.install-result` + +## Anatomy + +- state icon +- artifact filename +- build/job/size/path metadata +- cancel action +- success/error title and label +- masked output summary +- copy report action +- clear action + +## Variants + +- pending-install: 설치 대기 APK 표시 +- install-result-success: 성공 결과 표시 +- install-result-failure: 실패 결과와 exit code/output 표시 + +## States + +- default +- loading: install 진행 중 cancel disabled +- empty: banner 없음 +- error +- disabled + +## Rules + +- pending install path와 output은 길어질 수 있으므로 ellipsis 처리한다. +- 복사 리포트는 masked report만 사용한다. + +## Decision History + +- 2026-06-25: pending install/result banner를 component로 기록했다. diff --git a/agent-ui/definition/components/install-cta/index.md b/agent-ui/definition/components/install-cta/index.md new file mode 100644 index 0000000..5775c01 --- /dev/null +++ b/agent-ui/definition/components/install-cta/index.md @@ -0,0 +1,69 @@ +--- +ui_doc_type: component +component_id: install-cta +status: 구현됨 +source_evidence: + - type: code + path: lib/src/features/builds/builds_page.dart + notes: "_InstallCta와 _DownloadState" + - type: docs + path: README.md + notes: "APK 다운로드 및 adb install handoff scope" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# Install CTA + +Component ID: `install-cta` + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/builds/builds_page.dart` | `_InstallCta`와 `_DownloadState` | +| docs | `README.md` | APK 다운로드 및 `adb install` handoff scope | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +선택한 APK artifact를 다운로드/stage하고 디바이스 설치 흐름으로 넘긴다. + +## Used By + +- `builds`: `builds.install-cta` + +## Anatomy + +- state icon +- title/status label +- artifact/build metadata +- download progress label and linear progress +- cancel/retry/install button + +## Variants + +- idle: 설치 준비 또는 다운로드 취소됨 +- downloading: received/total bytes와 cancel action +- verified: staged APK path와 install action +- failed: error message와 retry action + +## States + +- default +- loading +- empty: 해당 없음 +- error +- disabled + +## Rules + +- downloader/stager가 있으면 먼저 다운로드를 수행하고, 검증된 staged APK만 install handoff에 넘긴다. +- 다운로드 실패 메시지는 한 줄로 줄이고 retry action을 유지한다. + +## Decision History + +- 2026-06-25: APK download/install handoff CTA를 component로 기록했다. diff --git a/agent-ui/definition/components/jenkins-credential-panel/index.md b/agent-ui/definition/components/jenkins-credential-panel/index.md new file mode 100644 index 0000000..8ee0e1d --- /dev/null +++ b/agent-ui/definition/components/jenkins-credential-panel/index.md @@ -0,0 +1,76 @@ +--- +ui_doc_type: component +component_id: jenkins-credential-panel +status: 구현됨 +source_evidence: + - type: code + path: lib/src/features/settings/settings_page.dart + notes: "Jenkins card와 _WebLoginSection" + - type: docs + path: agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md + notes: "사용자별 token과 WebView token 자동화 검토 맥락" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# Jenkins Credential Panel + +Component ID: `jenkins-credential-panel` + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/settings/settings_page.dart` | Jenkins card와 `_WebLoginSection` | +| docs | `agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md` | 사용자별 token과 WebView token 자동화 검토 맥락 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +Jenkins base URL과 credential lifecycle action을 한 카드 안에서 관리한다. + +## Used By + +- `settings`: `settings.jenkins-card` +- `settings`: `settings.web-login-controls` + +## Anatomy + +- Jenkins section title +- Base URL field with validation +- default job field +- auth mode segmented control +- Web Login button +- Credential 삭제 button +- loading indicators +- token/login/clear success labels +- error labels + +## Variants + +- default: Web Login mode +- busy: login/token save/session clear 진행 중 +- error: login/token save/session clear error +- saved: token 저장 완료 +- cleared: credential 삭제 완료 + +## States + +- default +- loading +- empty +- error +- disabled + +## Rules + +- Web Login action은 base URL이 valid http/https이고 busy 상태가 아닐 때만 활성화한다. +- credential 삭제는 session clearer가 있고 busy 상태가 아닐 때만 활성화한다. +- token 값이나 credential 원문은 UI definition이나 tracked 문서에 기록하지 않는다. + +## Decision History + +- 2026-06-25: Jenkins credential 카드와 Web Login controls를 component로 기록했다. diff --git a/agent-ui/definition/components/job-list/index.md b/agent-ui/definition/components/job-list/index.md new file mode 100644 index 0000000..30b6715 --- /dev/null +++ b/agent-ui/definition/components/job-list/index.md @@ -0,0 +1,69 @@ +--- +ui_doc_type: component +component_id: job-list +status: 구현됨 +source_evidence: + - type: code + path: lib/src/features/builds/builds_page.dart + notes: "_buildJobList, _JobRow, _JobStatus" + - type: docs + path: README.md + notes: "Jenkins job/build/artifact 조회 scope" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# Job List + +Component ID: `job-list` + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/builds/builds_page.dart` | `_buildJobList`, `_JobRow`, `_JobStatus` | +| docs | `README.md` | Jenkins job/build/artifact 조회 scope | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +Jenkins job/folder 후보를 검색하고 선택하게 한다. + +## Used By + +- `builds`: `builds.job-search` +- `builds`: `builds.job-list` + +## Anatomy + +- search TextField +- job/folder icon +- job name +- optional fullName +- chevron affordance +- status empty/error/permission view + +## Variants + +- default: loaded job list +- status: connection, empty, forbidden, failure 상태 안내 + +## States + +- default +- loading +- empty +- error +- disabled + +## Rules + +- 검색은 job name, fullName, URL 문자열을 대상으로 한다. +- credential이 없을 때는 list 대신 연결 상태 안내를 우선 표시한다. + +## Decision History + +- 2026-06-25: Jenkins job selector를 component로 기록했다. diff --git a/agent-ui/definition/components/logcat-viewer/index.md b/agent-ui/definition/components/logcat-viewer/index.md new file mode 100644 index 0000000..ce10dff --- /dev/null +++ b/agent-ui/definition/components/logcat-viewer/index.md @@ -0,0 +1,67 @@ +--- +ui_doc_type: component +component_id: logcat-viewer +status: 구현됨 +source_evidence: + - type: code + path: lib/src/features/console/console_page.dart + notes: "dark DecoratedBox log output, _LogcatLevel color mapping" + - type: docs + path: README.md + notes: "adb logcat 콘솔 뷰어 scope" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# Logcat Viewer + +Component ID: `logcat-viewer` + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/console/console_page.dart` | dark `DecoratedBox` log output, `_LogcatLevel` color mapping | +| docs | `README.md` | `adb logcat` 콘솔 뷰어 scope | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +logcat line을 고정폭 글꼴과 level별 색상으로 보여주고, 긴 stream을 스크롤 가능한 목록으로 유지한다. + +## Used By + +- `console`: `console.log-output` + +## Anatomy + +- dark rounded output surface +- loading/error center state +- scrollable log line list +- level-based text color + +## Variants + +- live: stream line list +- loading: session 시작 indicator +- error: error message + +## States + +- default +- loading +- empty +- error +- disabled + +## Rules + +- log line은 Menlo 계열 monospace와 13px 기준으로 표시한다. +- error/fatal line은 error color 계열로 표시한다. + +## Decision History + +- 2026-06-25: logcat 출력 surface를 component로 기록했다. diff --git a/agent-ui/definition/components/shell-navigation/index.md b/agent-ui/definition/components/shell-navigation/index.md new file mode 100644 index 0000000..0509e3f --- /dev/null +++ b/agent-ui/definition/components/shell-navigation/index.md @@ -0,0 +1,63 @@ +--- +ui_doc_type: component +component_id: shell-navigation +status: 구현됨 +source_evidence: + - type: code + path: lib/src/features/app_shell.dart + notes: "_BrandHeader와 NavigationRail destination mapping" + - type: docs + path: README.md + notes: "Current Scaffold feature 목록" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# Shell Navigation + +Component ID: `shell-navigation` + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/app_shell.dart` | `_BrandHeader`와 `NavigationRail` destination mapping | +| docs | `README.md` | Current Scaffold feature 목록 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +AppSok brand와 네 개의 primary destination을 항상 보이게 제공한다. + +## Used By + +- `app-shell`: `app-shell.nav` + +## Anatomy + +- AppSok icon mark +- AppSok title과 `Jenkins to USB` subtitle +- extended NavigationRail +- destination icon, selected icon, label + +## Variants + +- default: desktop/macOS sidebar width 196 + +## States + +- default +- selected +- disabled: 없음 + +## Rules + +- destination은 shell이 소유한 `_pages` 순서를 따른다. +- label은 현재 화면의 top bar title과 동일해야 한다. + +## Decision History + +- 2026-06-25: shell NavigationRail을 공통 component로 기록했다. diff --git a/agent-ui/definition/components/status-pill/index.md b/agent-ui/definition/components/status-pill/index.md new file mode 100644 index 0000000..7dc2de1 --- /dev/null +++ b/agent-ui/definition/components/status-pill/index.md @@ -0,0 +1,65 @@ +--- +ui_doc_type: component +component_id: status-pill +status: 구현됨 +source_evidence: + - type: code + path: lib/src/features/app_shell.dart + notes: "_TopBar와 _StatusPill" + - type: docs + path: agent-ops/rules/project/rules.md + notes: "Jenkins credential과 ADB runtime이 주요 외부 상태" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# Status Pill + +Component ID: `status-pill` + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/app_shell.dart` | `_TopBar`와 `_StatusPill` | +| docs | `agent-ops/rules/project/rules.md` | Jenkins credential과 ADB runtime이 주요 외부 상태 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +Jenkins와 ADB 같은 외부 연결 상태를 top bar에서 짧게 표시한다. + +## Used By + +- `app-shell`: `app-shell.top-bar` + +## Anatomy + +- tooltip icon +- short label +- outlined white container + +## Variants + +- jenkins: key icon, `Jenkins 대기` +- adb: USB icon, `ADB 대기` + +## States + +- default +- loading: 현재 별도 구현 없음 +- empty: 대기 상태 +- error: 현재 별도 구현 없음 +- disabled: 없음 + +## Rules + +- label은 한 줄 ellipsis 없이 pill 안에 들어갈 만큼 짧아야 한다. +- tooltip은 label보다 구체적인 상태 설명을 제공한다. + +## Decision History + +- 2026-06-25: top bar 상태 pill을 공통 component로 기록했다. diff --git a/agent-ui/definition/index.md b/agent-ui/definition/index.md new file mode 100644 index 0000000..d5b82ae --- /dev/null +++ b/agent-ui/definition/index.md @@ -0,0 +1,83 @@ +--- +ui_doc_type: definition-index +surface_type: ops-dev +source_evidence: + - type: code + path: lib/src/features/app_shell.dart + notes: "NavigationRail 기반 shell과 builds/devices/console/settings page 연결" + - type: code + path: lib/src/features/builds/builds_page.dart + notes: "Jenkins job/build 탐색과 APK download/install handoff UI" + - type: code + path: lib/src/features/devices/devices_page.dart + notes: "ADB device grid, pending install, install result UI" + - type: code + path: lib/src/features/console/console_page.dart + notes: "logcat filter, level segmented control, log viewer UI" + - type: code + path: lib/src/features/settings/settings_page.dart + notes: "Jenkins credential, Web Login, ADB diagnostics UI" + - type: code + path: lib/src/features/settings/jenkins_web_login_page.dart + notes: "fullscreen Jenkins WebView login dialog" + - type: docs + path: README.md + notes: "Jenkins artifact, ADB install, logcat, deep link scope" + - type: docs + path: agent-ops/rules/project/rules.md + notes: "Flutter macOS 앱 구조와 feature/service 분리 기준" + - type: docs + path: agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md + notes: "Jenkins WebView token 자동화와 credential 수명주기 검토 맥락" + - type: user + path: null + notes: "agent-ui 생성 요청" +--- + +# UI Definition + +## Purpose + +AppSok의 현재 Flutter macOS 화면 구조를 코드 근거와 동기화한다. 이 정의는 Jenkins artifact 탐색, APK 설치 handoff, ADB device 관리, logcat 확인, Jenkins/ADB 설정을 다루는 ops/dev UI 기준이다. + +## Surface Type + +- Type: ops-dev +- Notes: 현재는 내부 개발/운영 도구 UI 기준이다. product UI 레이어가 필요해지면 브랜드/콘텐츠/asset/tokens/motion 문서를 추가한다. + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/app_shell.dart` | NavigationRail 기반 shell과 builds/devices/console/settings page 연결 | +| code | `lib/src/features/builds/builds_page.dart` | Jenkins job/build 탐색과 APK download/install handoff UI | +| code | `lib/src/features/devices/devices_page.dart` | ADB device grid, pending install, install result UI | +| code | `lib/src/features/console/console_page.dart` | logcat filter, level segmented control, log viewer UI | +| code | `lib/src/features/settings/settings_page.dart` | Jenkins credential, Web Login, ADB diagnostics UI | +| code | `lib/src/features/settings/jenkins_web_login_page.dart` | fullscreen Jenkins WebView login dialog | +| docs | `README.md` | Jenkins artifact, ADB install, logcat, deep link scope | +| docs | `agent-ops/rules/project/rules.md` | Flutter macOS 앱 구조와 feature/service 분리 기준 | +| docs | `agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md` | Jenkins WebView token 자동화와 credential 수명주기 검토 맥락 | +| user | 없음 | agent-ui 생성 요청 | + +## Structure + +- `views/`: 화면 또는 업무 단위 정의 +- `components/`: 반복 UI 구성요소 정의 +- `archive/`: 현재 기준이 아닌 과거 정의/결정 로그 + +## Reading Rules + +- 현재 UI 동기화는 이 디렉터리의 활성 문서를 기준으로 한다. +- `archive/**`는 과거 비교, 복원, 특정 근거 확인 요청이 있을 때만 읽는다. + +## Sync Rules + +- frame-view가 있으면 view region id와 frame region id는 동일해야 한다. +- view에서 참조한 component id는 `components/` 아래에 정의되어야 한다. +- frame은 definition을 대체하지 않는다. +- `구현됨`, `계획`, `가정`, `불명확` 상태를 구현 근거 없이 섞어 쓰지 않는다. + +## Decision History + +- 2026-06-25: 기존 Flutter UI 코드와 README/로드맵 근거를 바탕으로 `code-first` agent-ui 초안을 생성했다. diff --git a/agent-ui/definition/views/app-shell/index.md b/agent-ui/definition/views/app-shell/index.md new file mode 100644 index 0000000..cd9b168 --- /dev/null +++ b/agent-ui/definition/views/app-shell/index.md @@ -0,0 +1,88 @@ +--- +ui_doc_type: view +view_id: app-shell +status: 구현됨 +frame: null +source_evidence: + - type: code + path: lib/src/features/app_shell.dart + notes: "AppSokShell, _BrandHeader, _TopBar, _StatusPill, _pages" + - type: docs + path: README.md + notes: "Current Scaffold feature 목록" + - type: user + path: null + notes: "agent-ui 생성 요청" +regions: + - app-shell.nav + - app-shell.top-bar + - app-shell.content +--- + +# App Shell + +View ID: `app-shell` + +Frame: +- 없음 + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/app_shell.dart` | `AppSokShell`, `_BrandHeader`, `_TopBar`, `_StatusPill`, `_pages` | +| docs | `README.md` | Current Scaffold feature 목록 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +AppSok의 primary navigation과 현재 feature page를 호스팅한다. shell은 pending install handoff, console target device, install result 같은 cross-page 상태를 소유한다. + +## Primary Users + +- Android artifact를 Mac에서 설치하고 확인하는 개발자 또는 QA 담당자 + +## Primary Tasks + +- 빌드, 디바이스, 콘솔, 설정 화면으로 전환한다. +- Jenkins/ADB 상태를 top bar에서 확인한다. +- 빌드 화면에서 준비한 APK를 디바이스 화면으로 넘긴다. + +## Information Priority + +1. 현재 선택된 feature page의 제목과 업무 영역 +2. NavigationRail의 AppSok brand 및 주요 화면 목록 +3. Jenkins/ADB 상태 pill + +## Regions + +| Region ID | Purpose | Component | Priority | Notes | +|-----------|---------|-----------|----------|-------| +| `app-shell.nav` | AppSok brand와 네 개의 primary destination 제공 | `shell-navigation` | high | `빌드`, `디바이스`, `콘솔`, `설정` | +| `app-shell.top-bar` | 현재 page title과 Jenkins/ADB status 표시 | `status-pill` | medium | 현재 구현은 대기 상태 pill 두 개를 고정 표시 | +| `app-shell.content` | 선택된 feature page 렌더링 | 없음 | high | `_pages[_selectedIndex].child` | + +## Actions + +| Action ID | Trigger | Result | Guard | +|-----------|---------|--------|-------| +| `app-shell.select-page` | NavigationRail destination 선택 | 선택 page를 content region에 표시 | 없음 | +| `app-shell.handoff-install` | build artifact 설치 요청 | pending install 상태를 만들고 `devices`로 이동 | staged APK가 있음 | +| `app-shell.open-console` | device tile의 logcat action | console target device를 설정하고 `console`로 이동 | device가 ready | + +## States + +- loading: child page가 자체 loading state를 표시한다. +- empty: child page가 자체 empty state를 표시한다. +- error: child page가 자체 error state를 표시한다. +- permission-denied: Jenkins credential 문제는 `builds`와 `settings`에서 표시한다. + +## Open Questions + +- 없음 + +## Decision History + +- 2026-06-25: `AppSokShell` 구현을 shell view 기준으로 기록했다. diff --git a/agent-ui/definition/views/builds/index.md b/agent-ui/definition/views/builds/index.md new file mode 100644 index 0000000..c12120a --- /dev/null +++ b/agent-ui/definition/views/builds/index.md @@ -0,0 +1,100 @@ +--- +ui_doc_type: view +view_id: builds +status: 구현됨 +frame: null +source_evidence: + - type: code + path: lib/src/features/builds/builds_page.dart + notes: "BuildsPage, _JobSelected, _JobRow, _BuildRow, _InstallCta" + - type: docs + path: README.md + notes: "Jenkins job/build/artifact 조회 scope" + - type: user + path: null + notes: "agent-ui 생성 요청" +regions: + - builds.connection-state + - builds.job-search + - builds.job-list + - builds.build-search + - builds.build-list + - builds.install-cta +--- + +# Builds + +View ID: `builds` + +Frame: +- 없음 + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/builds/builds_page.dart` | `BuildsPage`, `_JobSelected`, `_JobRow`, `_BuildRow`, `_InstallCta` | +| docs | `README.md` | Jenkins job/build/artifact 조회 scope | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +Jenkins job을 검색하고 build 목록에서 APK artifact를 골라 download/stage한 뒤 디바이스 설치 흐름으로 넘긴다. + +## Primary Users + +- 특정 Jenkins build artifact를 Mac에 내려받아 Android device에 설치하려는 개발자 또는 QA 담당자 + +## Primary Tasks + +- Jenkins job을 검색하고 선택한다. +- 선택한 job의 build를 검색하고 선택한다. +- APK artifact를 다운로드하거나 설치 handoff를 시작한다. + +## Information Priority + +1. Jenkins credential/connection 상태 또는 job/build 목록 +2. build result, branch/flavor/requestedBy/artifact metadata +3. selected build의 download/install CTA 상태 + +## Regions + +| Region ID | Purpose | Component | Priority | Notes | +|-----------|---------|-----------|----------|-------| +| `builds.connection-state` | credential 없음, 재로그인, 네트워크/서버 실패, 권한 없음 상태 표시 | 없음 | high | `_JobStatus`, `_BuildStatus` | +| `builds.job-search` | Jenkins job 검색 입력 | `job-list` | high | `job-search-field` | +| `builds.job-list` | job/folder 목록과 selection affordance | `job-list` | high | `_JobRow` | +| `builds.build-search` | 선택 job 안의 build 검색 입력 | `build-row` | medium | `build-search-field` | +| `builds.build-list` | build row 목록과 선택 상태 표시 | `build-row` | high | `_BuildRow`, `_StateBadge` | +| `builds.install-cta` | APK download/progress/retry/install handoff | `install-cta` | high | `_InstallCta` | + +## Actions + +| Action ID | Trigger | Result | Guard | +|-----------|---------|--------|-------| +| `builds.filter-jobs` | Job 검색 입력 변경 | job list를 name/fullName/url 기준으로 필터링 | job loader loaded | +| `builds.select-job` | job row 클릭 | build list mode로 전환 | job 선택 가능 | +| `builds.back-to-jobs` | 목록으로 icon button | job selector mode로 복귀 | 선택 job 있음 | +| `builds.filter-builds` | Build 검색 입력 변경 | build list를 metadata 기준으로 필터링 | build loader loaded | +| `builds.select-build` | build row 클릭 | selected build와 install CTA 표시 | APK artifact 있음 | +| `builds.download-artifact` | 다운로드 button | artifact download/stage 진행률 표시 | downloader/stager 있음 | +| `builds.cancel-download` | 취소 button | download를 취소 상태로 전환 | downloading | +| `builds.retry-download` | 재시도 button | failed download를 다시 시작 | failed | +| `builds.request-install` | 설치 button | pending install을 shell로 전달하고 devices로 이동 | staged APK 있음 | + +## States + +- loading: job/build loader 실행 중 `CircularProgressIndicator`를 표시한다. +- empty: 접근 가능한 job 없음, APK artifact 없음, 검색 결과 없음. +- error: Jenkins 조회 실패, download 실패, 네트워크/서버 실패. +- permission-denied: Jenkins 인증 필요, 재로그인 필요, job/build 접근 권한 없음. + +## Open Questions + +- 없음 + +## Decision History + +- 2026-06-25: Jenkins job/build 탐색과 install CTA를 `builds` view로 기록했다. diff --git a/agent-ui/definition/views/console/index.md b/agent-ui/definition/views/console/index.md new file mode 100644 index 0000000..1a496d7 --- /dev/null +++ b/agent-ui/definition/views/console/index.md @@ -0,0 +1,94 @@ +--- +ui_doc_type: view +view_id: console +status: 구현됨 +frame: null +source_evidence: + - type: code + path: lib/src/features/console/console_page.dart + notes: "ConsolePage, logcat filter controls, _LogcatLevelFilter, log viewer" + - type: docs + path: README.md + notes: "adb logcat 콘솔 뷰어 scope" + - type: user + path: null + notes: "agent-ui 생성 요청" +regions: + - console.device-context + - console.filter-controls + - console.stream-actions + - console.log-output +--- + +# Console + +View ID: `console` + +Frame: +- 없음 + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/console/console_page.dart` | `ConsolePage`, logcat filter controls, `_LogcatLevelFilter`, log viewer | +| docs | `README.md` | `adb logcat` 콘솔 뷰어 scope | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +선택된 Android device의 logcat stream을 보고, text/level filter와 pause/clear/copy action으로 설치 후 문제를 빠르게 확인한다. + +## Primary Users + +- 설치 후 앱 실행 로그를 확인하는 개발자 또는 QA 담당자 + +## Primary Tasks + +- device 선택 여부를 확인한다. +- 패키지, 태그, 텍스트 기준으로 log line을 필터링한다. +- ALL/DEBUG/INFO/WARN/ERROR level을 선택한다. +- log stream을 일시정지/재개, 지우기, 복사한다. + +## Information Priority + +1. 현재 선택 device 또는 device 미선택 상태 +2. filter/level/action controls +3. dark log output region과 error/loading state + +## Regions + +| Region ID | Purpose | Component | Priority | Notes | +|-----------|---------|-----------|----------|-------| +| `console.device-context` | 현재 device displayName/serial 또는 미선택 상태 표시 | 없음 | medium | `console-selected-device-label`, `console-no-device-label` | +| `console.filter-controls` | text filter와 level segmented control | 없음 | high | filter TextField, `_LogcatLevelFilter` | +| `console.stream-actions` | pause/resume, clear, copy visible logs | 없음 | high | icon button group | +| `console.log-output` | level-colored log line list | `logcat-viewer` | high | dark `DecoratedBox` 안의 `ListView.builder` | + +## Actions + +| Action ID | Trigger | Result | Guard | +|-----------|---------|--------|-------| +| `console.filter-text` | filter TextField 변경 | visible log lines를 text 기준으로 필터링 | 없음 | +| `console.clear-filter` | suffix close icon | filter text 초기화 | 없음 | +| `console.filter-level` | level segmented control 선택 | selected level 이상/해당 log 표시 | 없음 | +| `console.pause-toggle` | pause/play icon | stream 반영을 일시정지 또는 재개 | 없음 | +| `console.clear-logs` | delete icon | 현재 log lines 제거 | 없음 | +| `console.copy-visible-logs` | copy icon | visible log lines를 clipboard로 복사 | live logs 있음 | + +## States + +- loading: logcat session 시작 중 indicator를 표시한다. +- empty: device가 없거나 log line이 없으면 빈 log viewer 상태가 된다. +- error: logcat starter error를 log output 중앙에 표시한다. +- permission-denied: device 접근 문제는 error state로 표시한다. + +## Open Questions + +- 없음 + +## Decision History + +- 2026-06-25: logcat 제어와 출력 영역을 `console` view로 기록했다. diff --git a/agent-ui/definition/views/devices/index.md b/agent-ui/definition/views/devices/index.md new file mode 100644 index 0000000..ff7fc97 --- /dev/null +++ b/agent-ui/definition/views/devices/index.md @@ -0,0 +1,95 @@ +--- +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로 기록했다. diff --git a/agent-ui/definition/views/index.md b/agent-ui/definition/views/index.md new file mode 100644 index 0000000..dc95ded --- /dev/null +++ b/agent-ui/definition/views/index.md @@ -0,0 +1,48 @@ +--- +ui_doc_type: views-index +views: + - app-shell + - builds + - devices + - console + - settings + - jenkins-web-login +--- + +# View Definitions + +## View Tree + +| View ID | Status | Evidence | Description | +|---------|--------|----------|-------------| +| `app-shell` | 구현됨 | `lib/src/features/app_shell.dart` | AppSok 브랜드, NavigationRail, top bar, 현재 page host | +| `builds` | 구현됨 | `lib/src/features/builds/builds_page.dart` | Jenkins job/build 탐색과 APK download/install handoff | +| `devices` | 구현됨 | `lib/src/features/devices/devices_page.dart` | ADB device 목록, pending install 실행, 설치 결과 표시 | +| `console` | 구현됨 | `lib/src/features/console/console_page.dart` | 선택 device의 logcat 스트림 확인과 필터링 | +| `settings` | 구현됨 | `lib/src/features/settings/settings_page.dart` | Jenkins credential/Web Login, ADB path, diagnostics 설정 | +| `jenkins-web-login` | 구현됨 | `lib/src/features/settings/jenkins_web_login_page.dart` | Jenkins 로그인 WebView와 token bridge 진행 상태 | + +## Navigation + +- `app-shell` -> `builds`: NavigationRail `빌드` +- `app-shell` -> `devices`: NavigationRail `디바이스` +- `app-shell` -> `console`: NavigationRail `콘솔`, 또는 device tile `logcat` action +- `app-shell` -> `settings`: NavigationRail `설정` +- `settings` -> `jenkins-web-login`: Web Login action이 fullscreen dialog를 연다. +- `builds` -> `devices`: APK download/stage 완료 후 install handoff가 pending install 상태로 전환한다. + +## Common States + +- loading: Jenkins job/build, ADB device, logcat, diagnostics, WebView load 중 표시 +- empty: 접근 가능한 job 없음, APK artifact 없음, device 없음, 검색 결과 없음 +- error: Jenkins 조회 실패, ADB load 실패, logcat error, token 저장/삭제 실패, WebView error +- permission-denied: Jenkins 권한 없음 또는 재로그인 필요 + +## Common Permissions + +- Jenkins credential: `builds`의 job/build 조회와 artifact download에 필요하다. +- ADB runtime: `devices` refresh/install, `console` logcat, `settings` diagnostics에 필요하다. + +## Open Questions + +- 없음 diff --git a/agent-ui/definition/views/jenkins-web-login/index.md b/agent-ui/definition/views/jenkins-web-login/index.md new file mode 100644 index 0000000..5b74a69 --- /dev/null +++ b/agent-ui/definition/views/jenkins-web-login/index.md @@ -0,0 +1,88 @@ +--- +ui_doc_type: view +view_id: jenkins-web-login +status: 구현됨 +frame: null +source_evidence: + - type: code + path: lib/src/features/settings/jenkins_web_login_page.dart + notes: "JenkinsWebLoginPage, AppBar, WebViewWidget, error overlay" + - type: docs + path: agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md + notes: "WebView 로그인 후 token 자동 발급 후보 검토" + - type: user + path: null + notes: "agent-ui 생성 요청" +regions: + - jenkins-web-login.app-bar + - jenkins-web-login.webview + - jenkins-web-login.error-overlay +--- + +# Jenkins Web Login + +View ID: `jenkins-web-login` + +Frame: +- 없음 + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/settings/jenkins_web_login_page.dart` | `JenkinsWebLoginPage`, `AppBar`, `WebViewWidget`, error overlay | +| docs | `agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md` | WebView 로그인 후 token 자동 발급 후보 검토 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +Jenkins 로그인 페이지를 fullscreen WebView로 열고, 로그인 확인 및 API token bridge를 진행한다. + +## Primary Users + +- Jenkins credential을 앱에 저장하기 위해 Web Login을 수행하는 사용자 + +## Primary Tasks + +- Jenkins 로그인 WebView에서 인증을 완료한다. +- 로딩/token issue 진행 상태를 확인한다. +- 오류 발생 시 reload를 시도하거나 dialog를 닫는다. + +## Information Priority + +1. Jenkins 로그인 WebView +2. AppBar title/close action과 loading/token issue indicator +3. error overlay와 retry action + +## Regions + +| Region ID | Purpose | Component | Priority | Notes | +|-----------|---------|-----------|----------|-------| +| `jenkins-web-login.app-bar` | dialog title, close action, loading indicator | 없음 | high | `Jenkins 로그인` | +| `jenkins-web-login.webview` | Jenkins login page 표시와 JS bridge 실행 | 없음 | high | `WebViewWidget` | +| `jenkins-web-login.error-overlay` | page/probe/token 오류와 retry action | 없음 | high | `_errorMessage`가 있을 때 표시 | + +## Actions + +| Action ID | Trigger | Result | Guard | +|-----------|---------|--------|-------| +| `jenkins-web-login.close` | AppBar close icon | dialog 종료 | 없음 | +| `jenkins-web-login.reload` | 다시 시도 button | error message를 지우고 WebView reload | error message 있음 | +| `jenkins-web-login.complete-token` | 내부 token bridge 성공 | result를 settings page로 반환 | Jenkins user/token 확인 완료 | + +## States + +- loading: page load 또는 token issue 중 AppBar indicator를 표시한다. +- empty: 해당 없음. +- error: error overlay와 다시 시도 action을 표시한다. +- permission-denied: Jenkins 로그인 실패/anonymous 상태는 error 또는 WebView 인증 화면으로 남는다. + +## Open Questions + +- 없음 + +## Decision History + +- 2026-06-25: fullscreen Jenkins WebView login dialog를 별도 view로 기록했다. diff --git a/agent-ui/definition/views/settings/index.md b/agent-ui/definition/views/settings/index.md new file mode 100644 index 0000000..7445fc1 --- /dev/null +++ b/agent-ui/definition/views/settings/index.md @@ -0,0 +1,97 @@ +--- +ui_doc_type: view +view_id: settings +status: 구현됨 +frame: null +source_evidence: + - type: code + path: lib/src/features/settings/settings_page.dart + notes: "SettingsPage, _WebLoginSection, _AdbDiagnosticsSection" + - type: docs + path: README.md + notes: "사용자별 Jenkins API token 저장과 ADB 설정 scope" + - type: docs + path: agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md + notes: "WebView token 자동 발급과 credential 정책 검토 맥락" + - type: user + path: null + notes: "agent-ui 생성 요청" +regions: + - settings.jenkins-card + - settings.web-login-controls + - settings.adb-card + - settings.adb-diagnostics +--- + +# Settings + +View ID: `settings` + +Frame: +- 없음 + +Status: `구현됨` + +## Source Evidence + +| Type | Path | Notes | +|------|------|-------| +| code | `lib/src/features/settings/settings_page.dart` | `SettingsPage`, `_WebLoginSection`, `_AdbDiagnosticsSection` | +| docs | `README.md` | 사용자별 Jenkins API token 저장과 ADB 설정 scope | +| docs | `agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md` | WebView token 자동 발급과 credential 정책 검토 맥락 | +| user | 없음 | agent-ui 생성 요청 | + +## Purpose + +Jenkins base URL과 credential 흐름, ADB path/update option, ADB runtime diagnostics를 관리한다. + +## Primary Users + +- Jenkins credential과 ADB runtime 상태를 준비하는 개발자 또는 QA 담당자 + +## Primary Tasks + +- Jenkins base URL을 입력하고 Web Login을 시작한다. +- token 저장/credential 삭제 결과를 확인한다. +- ADB path와 설치 전 update option을 확인한다. +- ADB runtime source/path/version/hash diagnostics를 새로고침한다. + +## Information Priority + +1. Jenkins URL validation과 Web Login/Credential 삭제 actions +2. token 저장/삭제 결과와 오류 feedback +3. ADB path/update option과 diagnostics rows + +## Regions + +| Region ID | Purpose | Component | Priority | Notes | +|-----------|---------|-----------|----------|-------| +| `settings.jenkins-card` | Jenkins base URL, default job, auth mode selector 표시 | `jenkins-credential-panel` | high | Base URL validation 포함 | +| `settings.web-login-controls` | Web Login, Credential 삭제, 저장/삭제 결과 feedback | `jenkins-credential-panel` | high | `_WebLoginSection` | +| `settings.adb-card` | adb path field, 찾기 button, install update switch | 없음 | medium | 현재 일부 control은 placeholder action | +| `settings.adb-diagnostics` | ADB runtime diagnostics row와 refresh action | `adb-diagnostics` | medium | diagnostics loader가 있을 때 표시 | + +## Actions + +| Action ID | Trigger | Result | Guard | +|-----------|---------|--------|-------| +| `settings.edit-base-url` | Base URL 입력 | URL validation error 표시 여부 갱신 | 없음 | +| `settings.open-web-login` | Web Login button | Jenkins Web Login dialog 시작 | base URL이 유효하고 busy 아님 | +| `settings.clear-credential` | Credential 삭제 button | 저장된 session 삭제 시도 | clearer 있음, busy 아님 | +| `settings.refresh-adb-diagnostics` | diagnostics refresh icon | ADB runtime diagnostics reload | diagnostics loader 있음 | +| `settings.pick-adb-path` | 찾기 button | 현재 구현은 placeholder | 없음 | + +## States + +- loading: Web Login, token 저장, session 삭제, diagnostics loading 상태를 indicator로 표시한다. +- empty: diagnostics 없음 또는 optional diagnostics loader 없음. +- error: URL validation error, 로그인 오류, token 저장 실패, credential 삭제 실패, diagnostics load 실패. +- permission-denied: Jenkins 재인증 필요 상태는 `builds`에서 사용자를 설정으로 유도한다. + +## Open Questions + +- 없음 + +## Decision History + +- 2026-06-25: Jenkins credential과 ADB diagnostics UI를 `settings` view로 기록했다. diff --git a/agent-ui/frame/index.md b/agent-ui/frame/index.md new file mode 100644 index 0000000..f0cb52f --- /dev/null +++ b/agent-ui/frame/index.md @@ -0,0 +1,23 @@ +--- +ui_doc_type: frame-index +frames: [] +--- + +# UI Frames + +## Purpose + +이 디렉터리는 visual source가 있는 view의 wireframe과 definition 연결 정보를 보관한다. + +## Frame Sources + +- 현재 visual source가 없으므로 view별 frame 문서는 만들지 않는다. +- `views//index.md`: visual source가 있는 view의 frame 연결 문서 +- `views//wire.excalidraw`: 선택 visual source + +## Rules + +- frame은 definition을 대체하지 않는다. +- visual source가 있으면 대응되는 frame index에 기록한다. +- visual source가 없으면 `views//`를 만들지 않는다. +- frame-view가 있으면 frame region id는 definition region id와 동일해야 한다.