appsok/agent-ops/rules/project/domain/app-shell/rules.md

domain	last_rule_review_commit	last_rule_updated_at
app-shell	c1c4c41886	2026-06-14

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을 과도하게 추가하지 않는다.