oto/agent-ui/definition/index.md

---
ui_doc_type: definition-index
surface_type: ops-dev
source_evidence:
  - type: code
    path: packages/flutter/oto_console/lib/src/oto_console_shell.dart
    notes: "OtoConsoleShell, rail navigation, fallback section surface 구현"
  - type: code
    path: apps/client/lib/src/app/oto_client_app.dart
    notes: "Host MaterialApp이 overview/runners/pipelines/executions/artifacts surface를 mount"
  - type: docs
    path: agent-roadmap/phase/control-plane-product-surface/milestones/control-plane-security-audit-surface.md
    notes: "운영 보안, 감사, UI 노출 범위가 현재 Milestone에 정의됨"
  - type: docs
    path: agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md
    notes: "auth token reference, action outcome, 감사 metadata 노출/마스킹 기준"
  - type: user
    path: null
    notes: "agent-ui 생성 요청"
---

# UI Definition

## Purpose

OTO Control Plane Flutter 콘솔의 운영 화면, 반복 component, 상태 표현, write action 결과 표면을 agent와 사람이 같은 기준으로 읽을 수 있게 고정한다.

## Surface Type

- Type: ops-dev
- Notes: 현재는 운영자용 Control Plane 콘솔을 다룬다. product UI 레이어는 요청될 때 brand/content/assets/tokens/motion 문서로 확장한다.

## Source Evidence

| Type | Path | Notes |
|------|------|-------|
| code | `packages/flutter/oto_console/lib/src/oto_console_shell.dart` | `OtoConsoleShell`, rail navigation, fallback section surface 구현 |
| code | `apps/client/lib/src/app/oto_client_app.dart` | host app이 콘솔 section surface를 실제 mount |
| docs | `agent-roadmap/phase/control-plane-product-surface/milestones/control-plane-security-audit-surface.md` | 운영 보안, 감사, UI 노출 범위 |
| docs | `agent-roadmap/sdd/control-plane-product-surface/control-plane-security-audit-surface/SDD.md` | auth token reference와 audit metadata 노출/마스킹 기준 |
| user | 없음 | agent-ui 생성 요청 |

## External Reference Baseline

이 화면정의서는 pixel parity가 아니라 정보 구조를 Jenkins 최신 UI 기준으로 맞추는 structural gate로 참조한다. `러프 정렬`은 충족 기준이 아니며, 아래 `Jenkins IA gate` 항목이 테스트로 확인될 때만 대상 view/component를 `구현됨`으로 둔다.

| Reference | 확인일 | 적용 기준 |
|-----------|--------|-----------|
| Jenkins weekly `2.571` changelog | 2026-07-02 | 최신 weekly 기준. breadcrumb, System Log, task UI, dialog/apply animation 같은 운영 UI 보정이 계속 반영되는 기준으로 본다. URL: https://www.jenkins.io/changelog/ |
| Jenkins LTS `2.555.3` changelog | 2026-07-02 | 안정 배포 기준. Java 21+, permission/API token/security UI 변화와 LTS 호환 범위를 확인하는 기준으로 본다. URL: https://www.jenkins.io/changelog-stable/ |
| Jenkins refreshed design `2.516.1+` | 2026-07-02 | 통합 header/breadcrumb/action, 접근성 대비, 테마, responsive action 배치를 러프 레이아웃 참조로 삼는다. URL: https://www.jenkins.io/blog/2025/07/24/redesigning-jenkins-part-two/ |
| Pipeline Graph View | 2026-07-02 | Pipeline/run 상세의 active reference이자 필수 기준. stage graph, stage list, logs를 한 화면에서 다루는 구조는 executions view의 Jenkins IA gate 필수 항목이다. URL: https://plugins.jenkins.io/pipeline-graph-view/ |
| Blue Ocean | 2026-07-02 | 2026년 7월 deprecation 예정이므로 신규 기준이 아니라 legacy comparison으로만 사용한다. URL: https://www.jenkins.io/doc/book/blueocean/getting-started/ |

## Target Layout Status

- Shell/jobs 범위는 통합 header/breadcrumb/action, Dashboard-level `New Item`/`Build History` menu, pipelines dashboard job table, job context `Status`/`Build History`/`Stages` primitive가 코드와 widget 테스트로 확인되어 구현 근거를 갖는다.
- Executions/runners/settings 범위의 run stage graph, `Console Output`, Nodes/Agents, `Manage OTO` 구조는 03 구현에서 코드와 widget 테스트로 확인되어 구현 근거를 갖는다.
- 목표는 pixel parity가 아니라 header/action/status/list/detail/log/artifact의 정보 배치와 운영 밀도를 Jenkins 최신 UI 흐름에 맞추는 것이다.
- 보안/감사 source of truth처럼 문서 계획만 있는 항목은 계속 `계획` 상태로 두며, Jenkins IA gate 미충족 항목과 섞지 않는다.

### Jenkins IA gate

Jenkins 정렬 대상 view/component는 아래 structural primitive가 코드와 widget 테스트로 확인될 때만 `구현됨`으로 승격한다. 하나라도 미충족이면 `계획`으로 둔다.

| Gate primitive | 확인 대상 | 충족 기준 |
|----------------|-----------|-----------|
| 통합 header/breadcrumb/action | `console-shell` | Jenkins `2.516+` 통합 header, breadcrumb stack, action 영역이 shell/header에 존재한다. |
| dashboard job table | `pipelines` + `record-list` | Jenkins Dashboard job/build history 수준의 dense table/list 구조로 job과 status를 스캔한다. |
| run stage graph | `executions` + `execution-action-toolbar` | Pipeline Graph View 스타일 Pipeline Overview / Stage Graph가 run detail primary region에 존재한다. |
| node/manage 구조 | `runners`, `settings` | Nodes/Agents 목록과 Manage OTO(Manage Jenkins 대응) 관리 category 구조가 존재한다. |
| global/context menu 모델 | `console-rail` | New Item, Build History, Nodes, Artifacts, Manage OTO global menu와 job/run context menu가 분리 구현된다. |

## 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을 대체하지 않는다.
- 문서 계획만 있는 보안/감사 항목은 `구현됨` 상태로 쓰지 않는다.
- 기본 코드 동기화는 `.sync-state.json` 기준 이후 변경분만 대상으로 한다.
- 전체 동기화는 사용자가 명시한 경우에만 수행한다.

## Decision History

- 2026-06-24: Flutter 콘솔 구현을 기준으로 `code-first` agent-ui scaffold를 생성했다.
- 2026-07-02: Jenkins 최신 weekly/LTS와 `2.516+` refreshed UI를 러프 레이아웃 참조 기준선으로 추가했다.
- 2026-07-03: Jenkins 정렬 레이아웃 패스 구현과 검증 근거를 바탕으로 대상 view/component status를 `구현됨`으로 갱신했다.
- 2026-07-03: Jenkins reference를 러프 정렬에서 `Jenkins IA gate` structural acceptance로 강화하고, gate 미충족 대상 view/component status를 `계획`으로 정정했다. 후속 구현(02/03)이 primitive를 테스트로 확인하면 `구현됨`으로 승격한다.
- 2026-07-03: 02 shell/jobs 구현에서 통합 header/breadcrumb/action, `New Item`/`Build History` menu, pipelines dashboard job table과 job context menu primitive를 코드와 widget 테스트로 확인했다. Executions/runners/settings primitive는 03 범위로 남겼다.
- 2026-07-03: 03 executions/ops 구현에서 run context menu(`Pipeline Overview`, `Console Output`, `Artifacts`, `Build History`), `Stage Graph`, Nodes/Agents table, `Manage OTO` category surface를 코드와 widget 테스트로 확인했다.