---
domain: app-shell
last_rule_review_commit: fea3860d011f006a058506cb1f054407a5975a87
last_rule_updated_at: 2026-06-24
---

# app-shell

## 목적 / 책임

AppSok의 전역 앱 구성, startup session restore wiring, navigation shell, theme, feature 간 진입/설치 상태 전달을 담당한다.

## 포함 경로

- `lib/main.dart` — Flutter 앱 실행 진입점
- `lib/src/app.dart` — `MaterialApp`과 전역 theme 연결
- `lib/src/features/app_shell.dart` — 빌드/디바이스/콘솔/설정 navigation shell
- `lib/src/models/pending_install.dart` — artifact-flow와 device-console 사이의 설치 대기 handoff 모델
- `lib/src/theme/` — 앱 전역 색상, typography, component theme

## 제외 경로

- `lib/src/features/builds/` — Jenkins artifact 조회/설치 흐름은 `artifact-flow` 책임
- `lib/src/features/devices/`, `lib/src/features/console/` — ADB device/logcat 흐름은 `device-console` 책임
- `lib/src/services/**` — 외부 연동과 runtime semantics는 각 service 소유 도메인 책임
- `macos/` — bundle, entitlement, URL scheme은 `macos-platform` 책임

## 주요 구성 요소

- `AppSokApp` — 앱 루트 widget
- `AppSokShell` — 좌측 navigation, 상단 상태 영역, feature 간 설치 대기/결과 상태 전달
- `PendingInstall` — staged APK를 device-console에 넘기는 cross-feature DTO
- `AppTheme` — AppSok Material 3 light theme

## 유지할 패턴

- 첫 화면은 실제 업무 화면이어야 하며 landing/marketing 화면으로 만들지 않는다.
- 사용자 표시명은 `AppSok`으로 통일한다. Dart package, URL scheme, bundle id처럼 소문자 식별자가 필요한 곳만 `appsok`을 유지한다.
- navigation item 추가 시 domain 경계를 먼저 정하고, shell에는 route/entry wiring만 둔다.
- shell은 Jenkins session, artifact staging, ADB loader/installer 같은 dependency를 주입·연결하되 실제 외부 호출 semantics는 service 도메인에 둔다.
- 설치 대기 상태, 설치 중 상태, 마지막 설치 시도 결과, staged file cleanup은 페이지 dispose에 끊기지 않도록 shell에서 소유한다.
- 버튼과 상태 표시는 icon을 우선 사용하고, 긴 설명성 문구는 화면 안에 넣지 않는다.
- 카드 반경은 8px 이하를 유지한다.

## 다른 도메인과의 경계

- **artifact-flow**: Jenkins 인증/빌드 목록/다운로드/staged APK 생성은 artifact-flow가 소유하고, shell은 loader와 install handoff만 연결한다.
- **device-console**: ADB 연결 상태, 설치 실행, 설치 결과 모델, logcat session은 device-console이 소유하고, shell은 device 선택, pending install 전달, 마지막 설치 결과 보관만 조율한다.
- **macos-platform**: 앱 이름, URL scheme, entitlement 변경은 platform 설정에서 처리한다.

## 금지 사항

- shell에서 Jenkins API, Keychain, ADB Process를 직접 호출하지 않는다.
- 전역 theme에 특정 feature만을 위한 색상/spacing을 과도하게 추가하지 않는다.
