asciinevrdie/doc/task-ext-ui-tech.md

UI 레이아웃/기술 상세

메인 문서: game-system-overhaul-index.md

---

1. UI 레이아웃/네비게이션

1.1 메인 게임 화면 레이아웃

┌─────────────────────────────────────────────────────────┐
│ [메뉴]  CodeSlayer Lv.25  💰 15,420  [알림] [설정]     │ ← 헤더
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─ 캐릭터 ─────┐  ┌─ 전투 영역 ──────────────────┐   │
│  │              │  │                               │   │
│  │   HP ████░░  │  │    ╔═══╗      ╔═══╗         │   │
│  │   MP ███░░░  │  │    ║ ☺ ║  VS  ║ ☠ ║         │   │
│  │              │  │    ╚═══╝      ╚═══╝         │   │
│  │  STR: 25     │  │                               │   │
│  │  CON: 20     │  │   Syntax Error Lv.24         │   │
│  │  DEX: 18     │  │   HP ██████░░░░              │   │
│  │  INT: 15     │  │                               │   │
│  │  WIS: 12     │  │   [45 데미지!]               │   │
│  │  CHA: 10     │  │                               │   │
│  └──────────────┘  └───────────────────────────────┘   │
│                                                         │
│  ┌─ 장비 ───────────────────────────────────────────┐  │
│  │ ⚔️ 디버거의 검  🛡️ 강철 갑옷  🎩 마법 투구 ...   │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
│  ┌─ 진행 상황 ──────────────────────────────────────┐  │
│  │ 🗡️ 버그 처치 중...                    [일시정지] │  │
│  │ ████████████████░░░░░░░░  60%                    │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
├─────────────────────────────────────────────────────────┤
│   [전투]    [인벤]    [스킬]    [퀘스트]    [더보기]   │ ← 탭 바
└─────────────────────────────────────────────────────────┘

1.2 화면 구성

화면	접근 방법	주요 기능
메인 (전투)	기본 화면	전투 진행, 스탯, 장비
인벤토리	탭 바	아이템 관리, 장착
스킬	탭 바	스킬 관리, 빌드
퀘스트	탭 바	퀘스트 목록, 진행
더보기	탭 바	도감, 업적, 통계, 상점 등
지역	더보기	월드맵, 던전
설정	헤더	게임 설정

1.3 네비게이션 흐름

graph TD
    A[앱 시작] --> B{세이브 존재?}
    B -->|No| C[세이브 슬롯 선택]
    B -->|Yes| D[세이브 슬롯 선택]
    C --> E[캐릭터 생성]
    D --> F{튜토리얼 완료?}
    E --> F
    F -->|No| G[튜토리얼]
    F -->|Yes| H[메인 게임]
    G --> H

    H --> I[인벤토리]
    H --> J[스킬]
    H --> K[퀘스트]
    H --> L[더보기]

    L --> M[도감]
    L --> N[업적]
    L --> O[통계]
    L --> P[상점]
    L --> Q[지역]
    L --> R[명예의 전당]

1.4 모달/오버레이

타입	사용 상황
풀스크린 모달	사망 화면, 레벨업, 업적 달성
바텀 시트	아이템 상세, 스킬 상세, 퀵 액션
다이얼로그	확인, 경고, 선택
토스트	간단한 알림, 획득 메시지
툴팁	스탯 설명, 효과 설명

1.5 반응형 레이아웃

class ResponsiveLayout extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return LayoutBuilder(
      builder: (context, constraints) {
        if (constraints.maxWidth < 360) {
          return CompactLayout();      // 소형 모바일
        } else if (constraints.maxWidth < 600) {
          return MobileLayout();       // 일반 모바일
        } else if (constraints.maxWidth < 900) {
          return TabletLayout();       // 태블릿
        } else {
          return DesktopLayout();      // 데스크톱
        }
      },
    );
  }
}

---

2. 기술적 상세

2.1 State Management

// Riverpod 사용 권장
final gameStateProvider = StateNotifierProvider<GameStateNotifier, GameState>(
  (ref) => GameStateNotifier(),
);

class GameStateNotifier extends StateNotifier<GameState> {
  GameStateNotifier() : super(GameState.initial());

  void tick() { /* 게임 틱 처리 */ }
  void attack() { /* 공격 처리 */ }
  void useSkill(String skillId) { /* 스킬 사용 */ }
  void equip(Equipment item) { /* 장비 장착 */ }
}

// 분리된 Provider들
final combatProvider = ...;      // 전투 상태
final inventoryProvider = ...;   // 인벤토리 상태
final questProvider = ...;       // 퀘스트 상태
final settingsProvider = ...;    // 설정 상태

2.2 에러 처리 전략

class AppException implements Exception {
  final String code;
  final String message;
  final dynamic originalError;

  AppException(this.code, this.message, [this.originalError]);
}

// 에러 타입
class SaveLoadException extends AppException { ... }
class MigrationException extends AppException { ... }
class NetworkException extends AppException { ... }  // 향후 온라인용

// 전역 에러 핸들러
void handleError(AppException e, StackTrace stack) {
  // 1. 로깅
  Logger.error(e.code, e.message, stack);

  // 2. 사용자 알림
  showErrorDialog(e.message);

  // 3. 복구 시도 (가능한 경우)
  attemptRecovery(e);
}

2.3 에러 UI

┌─────────────────────────────────────┐
│                                     │
│   ⚠️ 오류가 발생했습니다            │
│                                     │
│   세이브 데이터를 불러오는 중       │
│   문제가 발생했습니다.              │
│                                     │
│   오류 코드: SAVE_LOAD_001          │
│                                     │
│   [ 다시 시도 ]  [ 백업 복원 ]      │
│   [ 새 게임 ]    [ 문의하기 ]       │
│                                     │
└─────────────────────────────────────┘

2.4 로깅 전략

class Logger {
  static LogLevel currentLevel = kDebugMode
    ? LogLevel.debug
    : LogLevel.warning;

  static void debug(String message) { ... }
  static void info(String message) { ... }
  static void warning(String message) { ... }
  static void error(String code, String message, StackTrace? stack) { ... }
}

enum LogLevel { debug, info, warning, error }

// 로그 출력 예시
// [DEBUG] 2024-03-15 14:30:00 - Combat: Player attacks for 45 damage
// [INFO]  2024-03-15 14:30:01 - Level up: 24 -> 25
// [WARN]  2024-03-15 14:30:02 - Low HP warning: 15%
// [ERROR] 2024-03-15 14:30:03 - SAVE_001: Failed to save game

2.5 성능 모니터링

class PerformanceMonitor {
  /// FPS 측정
  double get currentFps => ...;

  /// 메모리 사용량
  int get memoryUsageMb => ...;

  /// 틱 처리 시간
  Duration get averageTickTime => ...;

  /// 성능 경고
  void checkPerformance() {
    if (currentFps < 30) {
      Logger.warning('Low FPS: $currentFps');
    }
    if (memoryUsageMb > 500) {
      Logger.warning('High memory usage: $memoryUsageMb MB');
    }
  }
}

---