# Phase 4 — 원격 시즌 배포 + 분석 추상화 구현 계획

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 앱 스토어 업데이트 없이 새 시즌이 등장한다 — 정적 호스팅의 manifest.json을 확인해 새 팩을 SHA256 검증 후 원자적으로 캐시하고, 오프라인이면 캐시→번들 시즌1로 폴백한다. 분석 이벤트는 백엔드 추상화(디버그 로거)로 먼저 깔고 Firebase는 오너 작업 후 연결한다.

**Architecture:** `ContentDownloader`(HTTP fetch + SHA256 + temp-write-then-rename)가 캐시 디렉터리를 채우고, `ContentRepository`가 캐시+번들을 병합해 시즌 목록을 제공한다. 다운로더/캐시 디렉터리/HTTP 클라이언트는 전부 생성자 주입이라 테스트에서 실제 네트워크·path_provider가 필요 없다. 활성 시즌 = 목록의 마지막(seasonId 오름차순 최신). 분석은 `AnalyticsBackend` 인터페이스 뒤에 숨긴다.

**Tech Stack:** Flutter 3.35 / Riverpod 2 plain Notifier / 신규 패키지: `http`, `crypto`, `path_provider` (전부 Dart/Flutter 1st-party). Firebase는 이번 플랜에 없음 (오너의 `flutterfire configure` 후 후속).

**Spec:** `~/.claude/plans/jolly-waddling-meadow.md`의 Phase 4 섹션 + "시즌 콘텐츠 파이프라인" 섹션.

**확인된 사실 (구현자 참고):**
- `tool/stage_generator/generate.dart`는 spec의 `theme`를 `SeasonTheme.fromJson`으로 파싱(확장 비주얼 필드 호환)하고 `copyToAssets`는 옵셔널(`as String?`) — 시즌2는 이 키를 빼서 번들에 복사하지 않는다.
- `SeasonPack.fromJson`은 `schemaVersion > 1`이면 FormatException — 다운로더가 아닌 Repository 로드 단계에서 자연 거부됨.
- 모든 명령은 `/Volumes/Macintosh 2nd/Project/My_Game_Project/BlockSeasons` 안에서, 경로 공백 주의.
- 테스트 개수 보고는 최종 `+N: All tests passed!` 라인 기준.

---

### Task 1: 의존성 + RemoteManifest 모델

**Files:**
- Modify: `pubspec.yaml`
- Create: `lib/data/remote/manifest.dart`
- Test: `test/data/remote/manifest_test.dart`

- [ ] **Step 1: 패키지 추가**

```bash
flutter pub add http crypto path_provider
```
Expected: pubspec.yaml dependencies에 3개 추가, `flutter pub get` 성공.

- [ ] **Step 2: 실패하는 테스트** — `test/data/remote/manifest_test.dart`:

```dart
import 'package:block_seasons/data/remote/manifest.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  final json = {
    'schemaVersion': 1,
    'minAppBuild': 1,
    'current': 'season_002',
    'seasons': [
      {
        'seasonId': 'season_001',
        'version': 1,
        'packUrl': 'seasons/season_001/pack.json',
        'sha256': 'abc123',
      },
      {
        'seasonId': 'season_002',
        'version': 3,
        'packUrl': 'seasons/season_002/pack.json',
        'sha256': 'def456',
      },
    ],
  };

  test('round-trips through json', () {
    final manifest = RemoteManifest.fromJson(json);
    expect(manifest.schemaVersion, 1);
    expect(manifest.minAppBuild, 1);
    expect(manifest.current, 'season_002');
    expect(manifest.seasons, hasLength(2));
    expect(manifest.seasons[1].seasonId, 'season_002');
    expect(manifest.seasons[1].version, 3);
    expect(manifest.seasons[1].packUrl, 'seasons/season_002/pack.json');
    expect(manifest.seasons[1].sha256, 'def456');
    expect(RemoteManifest.fromJson(manifest.toJson()).toJson(),
        manifest.toJson());
  });

  test('rejects unsupported schema', () {
    expect(
      () => RemoteManifest.fromJson({...json, 'schemaVersion': 99}),
      throwsFormatException,
    );
  });

  test('missing current falls back to last season id', () {
    final m = RemoteManifest.fromJson({...json}..remove('current'));
    expect(m.current, 'season_002');
  });
}
```

- [ ] **Step 3: 실패 확인**

Run: `flutter test test/data/remote/manifest_test.dart`
Expected: FAIL (파일 없음).

- [ ] **Step 4: 구현** — `lib/data/remote/manifest.dart`:

```dart
/// Index of remotely available seasons, served as a static JSON next to the
/// pack files. The client compares (seasonId, version) against its cache.
class RemoteManifest {
  const RemoteManifest({
    required this.schemaVersion,
    required this.minAppBuild,
    required this.current,
    required this.seasons,
  });

  static const int supportedSchema = 1;

  factory RemoteManifest.fromJson(Map<String, dynamic> json) {
    final schema = json['schemaVersion'] as int;
    if (schema > supportedSchema) {
      throw FormatException('Unsupported manifest schema: $schema');
    }
    final seasons = [
      for (final s in json['seasons'] as List)
        ManifestSeason.fromJson(s as Map<String, dynamic>),
    ];
    return RemoteManifest(
      schemaVersion: schema,
      minAppBuild: (json['minAppBuild'] as int?) ?? 1,
      current: (json['current'] as String?) ??
          (seasons.isNotEmpty ? seasons.last.seasonId : ''),
      seasons: seasons,
    );
  }

  final int schemaVersion;
  final int minAppBuild;
  final String current;
  final List<ManifestSeason> seasons;

  Map<String, dynamic> toJson() => {
        'schemaVersion': schemaVersion,
        'minAppBuild': minAppBuild,
        'current': current,
        'seasons': [for (final s in seasons) s.toJson()],
      };
}

class ManifestSeason {
  const ManifestSeason({
    required this.seasonId,
    required this.version,
    required this.packUrl,
    required this.sha256,
  });

  factory ManifestSeason.fromJson(Map<String, dynamic> json) =>
      ManifestSeason(
        seasonId: json['seasonId'] as String,
        version: json['version'] as int,
        packUrl: json['packUrl'] as String,
        sha256: json['sha256'] as String,
      );

  final String seasonId;
  final int version;
  final String packUrl;
  final String sha256;

  Map<String, dynamic> toJson() => {
        'seasonId': seasonId,
        'version': version,
        'packUrl': packUrl,
        'sha256': sha256,
      };
}
```

- [ ] **Step 5: 통과 + 커밋**

Run: `flutter test test/data/remote/manifest_test.dart && flutter analyze`
Expected: PASS, 0 issues.

```bash
git add pubspec.yaml pubspec.lock lib/data/remote/manifest.dart test/data/remote/manifest_test.dart
git commit -m "feat: remote manifest model and content dependencies"
```

---

### Task 2: ContentDownloader — fetch + SHA256 + 원자적 캐시

**Files:**
- Create: `lib/data/remote/content_downloader.dart`
- Test: `test/data/remote/content_downloader_test.dart`

캐시 레이아웃: `<cacheDir>/seasons/<seasonId>/pack.json` + `<cacheDir>/cache_index.json` (`{seasonId: version}`).

- [ ] **Step 1: 실패하는 테스트** — `test/data/remote/content_downloader_test.dart`:

```dart
import 'dart:convert';
import 'dart:io';

import 'package:block_seasons/data/remote/content_downloader.dart';
import 'package:crypto/crypto.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:http/http.dart' as http;
import 'package:http/testing.dart';

void main() {
  late Directory tmp;

  setUp(() async {
    tmp = await Directory.systemTemp.createTemp('bs_cache_');
  });

  tearDown(() async {
    if (await tmp.exists()) await tmp.delete(recursive: true);
  });

  String shaOf(String body) => sha256.convert(utf8.encode(body)).toString();

  // Minimal valid-enough pack body (repository parses later; downloader
  // only verifies bytes).
  const packBody = '{"schemaVersion":1,"seasonId":"season_002"}';

  Map<String, dynamic> manifestJson({String? sha, int version = 1}) => {
        'schemaVersion': 1,
        'minAppBuild': 1,
        'current': 'season_002',
        'seasons': [
          {
            'seasonId': 'season_002',
            'version': version,
            'packUrl': 'seasons/season_002/pack.json',
            'sha256': sha ?? shaOf(packBody),
          },
        ],
      };

  MockClient okClient({String? sha, int version = 1}) =>
      MockClient((request) async {
        if (request.url.path.endsWith('manifest.json')) {
          return http.Response(
            jsonEncode(manifestJson(sha: sha, version: version)),
            200,
            headers: {'content-type': 'application/json'},
          );
        }
        if (request.url.path.endsWith('pack.json')) {
          return http.Response(packBody, 200);
        }
        return http.Response('not found', 404);
      });

  test('downloads, verifies, and caches a new season', () async {
    final downloader = ContentDownloader(
      baseUrl: 'https://example.com/content',
      cacheDir: tmp,
      client: okClient(),
    );
    final updated = await downloader.sync();
    expect(updated, isTrue);
    final cached =
        File('${tmp.path}/seasons/season_002/pack.json');
    expect(await cached.readAsString(), packBody);
    expect(downloader.cachedVersion('season_002'), 1);
  });

  test('second sync with same version is a no-op', () async {
    final downloader = ContentDownloader(
      baseUrl: 'https://example.com/content',
      cacheDir: tmp,
      client: okClient(),
    );
    await downloader.sync();
    expect(await downloader.sync(), isFalse);
  });

  test('checksum mismatch rejects the pack and keeps cache clean', () async {
    final downloader = ContentDownloader(
      baseUrl: 'https://example.com/content',
      cacheDir: tmp,
      client: okClient(sha: 'deadbeef'),
    );
    final updated = await downloader.sync();
    expect(updated, isFalse);
    expect(
      File('${tmp.path}/seasons/season_002/pack.json').existsSync(),
      isFalse,
    );
    // No stray temp files left behind.
    final leftovers = tmp
        .listSync(recursive: true)
        .whereType<File>()
        .where((f) => f.path.endsWith('.tmp'));
    expect(leftovers, isEmpty);
  });

  test('network failure leaves existing cache untouched', () async {
    final good = ContentDownloader(
      baseUrl: 'https://example.com/content',
      cacheDir: tmp,
      client: okClient(),
    );
    await good.sync();

    final offline = ContentDownloader(
      baseUrl: 'https://example.com/content',
      cacheDir: tmp,
      client: MockClient((_) async => throw const SocketException('off')),
    );
    expect(await offline.sync(), isFalse);
    expect(
      File('${tmp.path}/seasons/season_002/pack.json').existsSync(),
      isTrue,
    );
  });

  test('version bump re-downloads', () async {
    await ContentDownloader(
      baseUrl: 'https://example.com/content',
      cacheDir: tmp,
      client: okClient(version: 1),
    ).sync();
    final updated = await ContentDownloader(
      baseUrl: 'https://example.com/content',
      cacheDir: tmp,
      client: okClient(version: 2),
    ).sync();
    expect(updated, isTrue);
  });
}
```

- [ ] **Step 2: 실패 확인**

Run: `flutter test test/data/remote/content_downloader_test.dart`
Expected: FAIL (파일 없음).

- [ ] **Step 3: 구현** — `lib/data/remote/content_downloader.dart`:

```dart
import 'dart:convert';
import 'dart:io';

import 'package:crypto/crypto.dart';
import 'package:http/http.dart' as http;

import 'manifest.dart';

/// Pulls the remote season manifest and downloads new/updated packs into
/// [cacheDir] with SHA256 verification and atomic (temp + rename) writes.
/// All failures are swallowed into a `false` return — remote content is an
/// enhancement, never a crash source.
class ContentDownloader {
  ContentDownloader({
    required this.baseUrl,
    required this.cacheDir,
    http.Client? client,
  }) : _client = client ?? http.Client() {
    _loadIndex();
  }

  final String baseUrl;
  final Directory cacheDir;
  final http.Client _client;
  final Map<String, int> _index = {};

  File get _indexFile => File('${cacheDir.path}/cache_index.json');

  void _loadIndex() {
    try {
      if (_indexFile.existsSync()) {
        final json =
            jsonDecode(_indexFile.readAsStringSync()) as Map<String, dynamic>;
        json.forEach((k, v) => _index[k] = v as int);
      }
    } catch (_) {
      // Corrupt index: treat as empty; packs will re-download.
      _index.clear();
    }
  }

  Future<void> _saveIndex() async {
    await cacheDir.create(recursive: true);
    await _indexFile.writeAsString(jsonEncode(_index));
  }

  int? cachedVersion(String seasonId) => _index[seasonId];

  /// Checks the manifest and downloads anything new. Returns true when at
  /// least one pack was added or updated.
  Future<bool> sync() async {
    final RemoteManifest manifest;
    try {
      final res = await _client
          .get(Uri.parse('$baseUrl/manifest.json'))
          .timeout(const Duration(seconds: 10));
      if (res.statusCode != 200) return false;
      manifest =
          RemoteManifest.fromJson(jsonDecode(res.body) as Map<String, dynamic>);
    } catch (_) {
      return false;
    }

    var changed = false;
    for (final season in manifest.seasons) {
      if (_index[season.seasonId] == season.version) continue;
      if (await _downloadPack(season)) changed = true;
    }
    return changed;
  }

  Future<bool> _downloadPack(ManifestSeason season) async {
    try {
      final res = await _client
          .get(Uri.parse('$baseUrl/${season.packUrl}'))
          .timeout(const Duration(seconds: 30));
      if (res.statusCode != 200) return false;

      final digest = sha256.convert(res.bodyBytes).toString();
      if (digest != season.sha256) return false;

      final dir = Directory('${cacheDir.path}/seasons/${season.seasonId}');
      await dir.create(recursive: true);
      final tmp = File('${dir.path}/pack.json.tmp');
      await tmp.writeAsBytes(res.bodyBytes, flush: true);
      await tmp.rename('${dir.path}/pack.json');

      _index[season.seasonId] = season.version;
      await _saveIndex();
      return true;
    } catch (_) {
      return false;
    }
  }
}
```

- [ ] **Step 4: 통과 + 커밋**

Run: `flutter test test/data/remote/ && flutter analyze`
Expected: PASS, 0 issues.

```bash
git add lib/data/remote/content_downloader.dart test/data/remote/content_downloader_test.dart
git commit -m "feat: content downloader with sha256 verify and atomic cache"
```

---

### Task 3: ContentRepository — 캐시 병합 + 번들 폴백 + refresh

**Files:**
- Modify: `lib/data/content_repository.dart` (전면 확장)
- Modify: `lib/state/providers.dart` (contentRepositoryProvider 주입 변경)
- Modify: `lib/main.dart` (캐시 디렉터리 준비)
- Test: `test/data/content_repository_test.dart` (확장)

- [ ] **Step 1: 실패하는 테스트** — `test/data/content_repository_test.dart`에 추가 (기존 테스트는 유지하되 ContentRepository 생성이 새 시그니처면 같이 갱신):

```dart
// 파일 상단 import 추가:
// import 'dart:convert';
// import 'dart:io';
// import 'package:block_seasons/game/models/season.dart';

group('cache merge and fallback', () {
  late Directory tmp;

  setUp(() async {
    tmp = await Directory.systemTemp.createTemp('bs_repo_');
  });

  tearDown(() async {
    if (await tmp.exists()) await tmp.delete(recursive: true);
  });

  Map<String, dynamic> packJson(String id) => {
        'schemaVersion': 1,
        'seasonId': id,
        'version': 1,
        'title': {'en': id},
        'theme': const SeasonTheme().toJson(),
        'stages': [
          {
            'id': '${id}_001',
            'seed': 1,
            'moveLimit': 10,
            'preset': [],
            'objectives': [
              {'type': 'reachScore', 'target': 100}
            ],
            'stars': {
              'two': {'movesLeft': 2},
              'three': {'movesLeft': 4}
            },
            'generatorProfile': 'mid',
          }
        ],
      };

  Future<void> putCachedSeason(String id) async {
    final dir = Directory('${tmp.path}/seasons/$id');
    await dir.create(recursive: true);
    await File('${dir.path}/pack.json')
        .writeAsString(jsonEncode(packJson(id)));
  }

  test('merges cached seasons after bundled ones, sorted by id', () async {
    TestWidgetsFlutterBinding.ensureInitialized();
    await putCachedSeason('season_002');
    final repo = ContentRepository(cacheDir: tmp);
    final seasons = await repo.availableSeasons();
    expect(seasons.map((s) => s.seasonId).toList(),
        ['season_001', 'season_002']);
  });

  test('cached copy of a bundled season wins over the bundle', () async {
    TestWidgetsFlutterBinding.ensureInitialized();
    await putCachedSeason('season_001');
    final repo = ContentRepository(cacheDir: tmp);
    final seasons = await repo.availableSeasons();
    // Cached fake has exactly 1 stage; the bundled real one has 60.
    expect(seasons.single.stages, hasLength(1));
  });

  test('corrupt cached pack falls back to bundle silently', () async {
    TestWidgetsFlutterBinding.ensureInitialized();
    final dir = Directory('${tmp.path}/seasons/season_001');
    await dir.create(recursive: true);
    await File('${dir.path}/pack.json').writeAsString('{not json');
    final repo = ContentRepository(cacheDir: tmp);
    final seasons = await repo.availableSeasons();
    expect(seasons.single.stages, hasLength(60));
  });
});
```

- [ ] **Step 2: 실패 확인**

Run: `flutter test test/data/content_repository_test.dart`
Expected: FAIL (`cacheDir` 파라미터 없음).

- [ ] **Step 3: 구현** — `lib/data/content_repository.dart` 전체 교체:

```dart
import 'dart:convert';
import 'dart:io';

import 'package:flutter/services.dart';

import '../game/models/season.dart';
import 'remote/content_downloader.dart';

/// Resolves season content: bundled season 1 is always available offline;
/// remotely synced packs in [cacheDir] extend or override it. Load errors on
/// any single pack never break the list — worst case the player sees the
/// bundled content.
class ContentRepository {
  ContentRepository({this.cacheDir, ContentDownloader? downloader})
      : _downloader = downloader;

  static const bundledSeasonIds = ['season_001'];

  final Directory? cacheDir;
  final ContentDownloader? _downloader;
  bool _syncedThisSession = false;

  Future<SeasonPack> loadBundledSeason(String seasonId) async {
    final raw =
        await rootBundle.loadString('assets/seasons/$seasonId/pack.json');
    return SeasonPack.fromJson(jsonDecode(raw) as Map<String, dynamic>);
  }

  SeasonPack? _loadCachedSeason(Directory dir) {
    try {
      final file = File('${dir.path}/pack.json');
      if (!file.existsSync()) return null;
      return SeasonPack.fromJson(
          jsonDecode(file.readAsStringSync()) as Map<String, dynamic>);
    } catch (_) {
      return null; // Corrupt or future-schema pack: ignore.
    }
  }

  /// All playable seasons, sorted by seasonId. Cached packs win over the
  /// bundled copy of the same season (they may carry balance fixes).
  Future<List<SeasonPack>> availableSeasons() async {
    final byId = <String, SeasonPack>{};
    for (final id in bundledSeasonIds) {
      try {
        byId[id] = await loadBundledSeason(id);
      } catch (_) {
        // Bundled pack should never fail; if it does, skip rather than crash.
      }
    }

    final seasonsDir =
        cacheDir == null ? null : Directory('${cacheDir!.path}/seasons');
    if (seasonsDir != null && seasonsDir.existsSync()) {
      for (final entry in seasonsDir.listSync().whereType<Directory>()) {
        final pack = _loadCachedSeason(entry);
        if (pack != null) byId[pack.seasonId] = pack;
      }
    }

    final list = byId.values.toList()
      ..sort((a, b) => a.seasonId.compareTo(b.seasonId));
    return list;
  }

  /// Fire-once-per-session remote sync. Returns true when new content
  /// arrived (callers then re-read [availableSeasons]).
  Future<bool> refresh() async {
    final downloader = _downloader;
    if (downloader == null || _syncedThisSession) return false;
    _syncedThisSession = true;
    return downloader.sync();
  }
}
```

- [ ] **Step 4: providers.dart 주입 + main.dart 캐시 준비**

`lib/state/providers.dart` — 기존 `contentRepositoryProvider`를 교체:

```dart
/// Overridden in main() with the real cache directory + downloader; tests
/// override with in-memory fixtures or keep the bundled-only default.
final contentRepositoryProvider =
    Provider<ContentRepository>((ref) => ContentRepository());
```
(시그니처가 기본 생성자 호환이라 선언 자체는 그대로여도 됨 — 변경 없으면 이 파일은 건드리지 않는다.)

`lib/main.dart` — runApp 전에 캐시 디렉터리와 다운로더를 준비해 override:

```dart
import 'dart:io';

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:path_provider/path_provider.dart';

import 'app.dart';
import 'data/content_repository.dart';
import 'data/remote/content_downloader.dart';
import 'data/save_repository.dart';
import 'state/providers.dart';

/// Remote content origin. Swap per environment with
/// --dart-define=CONTENT_BASE_URL=...; the default points at the production
/// Firebase Hosting site (configured in Phase 4 owner setup).
const contentBaseUrl = String.fromEnvironment(
  'CONTENT_BASE_URL',
  defaultValue: 'https://block-seasons.web.app/content',
);

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final saveRepository = await SaveRepository.open();

  ContentRepository contentRepository;
  try {
    final support = await getApplicationSupportDirectory();
    final cacheDir = Directory('${support.path}/content');
    contentRepository = ContentRepository(
      cacheDir: cacheDir,
      downloader: ContentDownloader(
        baseUrl: contentBaseUrl,
        cacheDir: cacheDir,
      ),
    );
  } catch (e) {
    debugPrint('content cache unavailable, bundled only: $e');
    contentRepository = ContentRepository();
  }

  runApp(ProviderScope(
    overrides: [
      saveRepositoryProvider.overrideWithValue(saveRepository),
      contentRepositoryProvider.overrideWithValue(contentRepository),
    ],
    child: const BlockSeasonsApp(),
  ));
}
```
(기존 main의 다른 내용은 유지하면서 위 구조로 합칠 것.)

- [ ] **Step 5: 통과 + 커밋**

Run: `flutter test && flutter analyze`
Expected: 전체 PASS (기존 content_repository 테스트 포함), 0 issues.

```bash
git add lib/data/content_repository.dart lib/main.dart lib/state/providers.dart test/data/content_repository_test.dart
git commit -m "feat: content repository merges cached seasons with bundled fallback"
```

---

### Task 4: 시즌 갱신 트리거 + 활성 시즌 선택

**Files:**
- Modify: `lib/state/providers.dart` (seasonRefreshProvider)
- Modify: `lib/ui/screens/home_screen.dart` (refresh listen)
- Modify: `lib/ui/screens/season_map_screen.dart` (`list.first` → 활성 시즌)
- Modify: `lib/ui/screens/season_title_screen.dart` (`list.first` → 활성 시즌)
- Test: `test/state/season_refresh_test.dart`

- [ ] **Step 1: 실패하는 테스트** — `test/state/season_refresh_test.dart`:

```dart
import 'dart:io';

import 'package:block_seasons/data/content_repository.dart';
import 'package:block_seasons/state/providers.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:flutter_test/flutter_test.dart';

class _FakeRepo extends ContentRepository {
  _FakeRepo(this.result);
  final bool result;
  int calls = 0;

  @override
  Future<bool> refresh() async {
    calls++;
    return result;
  }
}

void main() {
  test('seasonRefreshProvider runs refresh once and exposes the result',
      () async {
    final repo = _FakeRepo(true);
    final container = ProviderContainer(
      overrides: [contentRepositoryProvider.overrideWithValue(repo)],
    );
    addTearDown(container.dispose);

    expect(await container.read(seasonRefreshProvider.future), isTrue);
    // Re-reading does not re-run (FutureProvider caches).
    expect(await container.read(seasonRefreshProvider.future), isTrue);
    expect(repo.calls, 1);
  });
}
```

- [ ] **Step 2: 실패 확인**

Run: `flutter test test/state/season_refresh_test.dart`
Expected: FAIL (`seasonRefreshProvider` 없음).

- [ ] **Step 3: 구현**

`lib/state/providers.dart`에 추가:

```dart
/// One background content sync per app session. Home listens and refreshes
/// the season list when new packs arrived.
final seasonRefreshProvider = FutureProvider<bool>(
  (ref) => ref.read(contentRepositoryProvider).refresh(),
);

/// The season players land in by default: the newest available.
SeasonPack activeSeason(List<SeasonPack> seasons) => seasons.last;
```
(`activeSeason`은 단순 헬퍼 — provider로 만들 필요 없음. providers.dart 하단에 top-level 함수로.)

`lib/ui/screens/home_screen.dart` — `build` 시작부에 추가:

```dart
ref.listen(seasonRefreshProvider, (_, next) {
  if (next.valueOrNull == true) ref.invalidate(seasonsProvider);
});
```

`lib/ui/screens/season_map_screen.dart` — `data: (list) => _JourneyMap(pack: list.first)` 를 `data: (list) => _JourneyMap(pack: activeSeason(list))` 로. (import는 providers.dart에 이미 있음.)

`lib/ui/screens/season_title_screen.dart` — `final pack = list.first;` 를 `final pack = activeSeason(list);` 로. (빈 리스트 가드는 그 위에 이미 있음 — 유지.)

- [ ] **Step 4: 통과 + 커밋**

Run: `flutter test && flutter analyze`
Expected: 전체 PASS, 0 issues.

```bash
git add lib/state/providers.dart lib/ui/screens test/state/season_refresh_test.dart
git commit -m "feat: session content sync trigger and newest-season selection"
```

---

### Task 5: AnalyticsService — 백엔드 추상화 + 게임 이벤트 배선

**Files:**
- Create: `lib/services/analytics_service.dart`
- Modify: `lib/state/providers.dart` (analyticsProvider)
- Modify: `lib/state/season_flow_notifier.dart` (stage_start)
- Modify: `lib/ui/screens/game_screen.dart` (stage_end / endless_end / rescue)
- Modify: `lib/ui/screens/home_screen.dart` (endless_start)
- Modify: `lib/state/tutorial_notifier.dart` (tutorial_done)
- Test: `test/services/analytics_service_test.dart`

- [ ] **Step 1: 실패하는 테스트** — `test/services/analytics_service_test.dart`:

```dart
import 'package:block_seasons/services/analytics_service.dart';
import 'package:flutter_test/flutter_test.dart';

class _RecordingBackend implements AnalyticsBackend {
  final events = <(String, Map<String, Object>)>[];

  @override
  void logEvent(String name, Map<String, Object> params) {
    events.add((name, params));
  }
}

void main() {
  test('typed helpers produce stable event names and params', () {
    final backend = _RecordingBackend();
    final analytics = AnalyticsService(backend);

    analytics.stageStart(seasonId: 'season_001', stageId: 's1');
    analytics.stageEnd(
      seasonId: 'season_001',
      stageId: 's1',
      won: true,
      stars: 3,
      score: 1200,
      movesUsed: 9,
    );
    analytics.endlessStart();
    analytics.endlessEnd(score: 500, isNewBest: true);
    analytics.rescueUsed(type: 'continue');
    analytics.tutorialFinished(skipped: false);

    expect(backend.events.map((e) => e.$1).toList(), [
      'stage_start',
      'stage_end',
      'endless_start',
      'endless_end',
      'rescue_used',
      'tutorial_finished',
    ]);
    expect(backend.events[1].$2, {
      'season_id': 'season_001',
      'stage_id': 's1',
      'won': 1,
      'stars': 3,
      'score': 1200,
      'moves_used': 9,
    });
    expect(backend.events[3].$2, {'score': 500, 'new_best': 1});
  });
}
```

- [ ] **Step 2: 실패 확인**

Run: `flutter test test/services/analytics_service_test.dart`
Expected: FAIL (파일 없음).

- [ ] **Step 3: 구현** — `lib/services/analytics_service.dart`:

```dart
import 'package:flutter/foundation.dart';

/// Where events land. Phase 4 ships the debug logger; the Firebase backend
/// plugs in here after the owner runs flutterfire configure.
abstract class AnalyticsBackend {
  void logEvent(String name, Map<String, Object> params);
}

class DebugAnalyticsBackend implements AnalyticsBackend {
  @override
  void logEvent(String name, Map<String, Object> params) {
    debugPrint('[analytics] $name $params');
  }
}

/// Typed event surface. Booleans are sent as 0/1 ints so every backend
/// (GA4 included) aggregates them the same way.
class AnalyticsService {
  AnalyticsService(this._backend);

  final AnalyticsBackend _backend;

  void stageStart({required String seasonId, required String stageId}) {
    _backend.logEvent('stage_start', {
      'season_id': seasonId,
      'stage_id': stageId,
    });
  }

  void stageEnd({
    required String seasonId,
    required String stageId,
    required bool won,
    required int stars,
    required int score,
    required int movesUsed,
  }) {
    _backend.logEvent('stage_end', {
      'season_id': seasonId,
      'stage_id': stageId,
      'won': won ? 1 : 0,
      'stars': stars,
      'score': score,
      'moves_used': movesUsed,
    });
  }

  void endlessStart() => _backend.logEvent('endless_start', const {});

  void endlessEnd({required int score, required bool isNewBest}) {
    _backend.logEvent('endless_end', {
      'score': score,
      'new_best': isNewBest ? 1 : 0,
    });
  }

  void rescueUsed({required String type}) {
    _backend.logEvent('rescue_used', {'type': type});
  }

  void tutorialFinished({required bool skipped}) {
    _backend.logEvent('tutorial_finished', {'skipped': skipped ? 1 : 0});
  }
}
```

- [ ] **Step 4: provider + 배선**

`lib/state/providers.dart`:

```dart
final analyticsProvider = Provider<AnalyticsService>(
  (ref) => AnalyticsService(DebugAnalyticsBackend()),
);
```
(+ `import '../services/analytics_service.dart';`)

`lib/state/season_flow_notifier.dart` — `startSeasonStage` 끝에:

```dart
ref.read(analyticsProvider).stageStart(
      seasonId: pack.seasonId,
      stageId: pack.stages[index].id,
    );
```

`lib/ui/screens/game_screen.dart` — `_onSessionChange`의 phase 전환 블록:
- won 분기 (`if (!next.endless)` recordWin 가드 안, recordWin 다음):

```dart
final flow = ref.read(seasonFlowProvider);
if (flow != null) {
  ref.read(analyticsProvider).stageEnd(
        seasonId: flow.pack.seasonId,
        stageId: flow.stage.id,
        won: true,
        stars: next.starsEarned,
        score: next.score,
        movesUsed: next.moveLimit - next.movesLeft,
      );
}
```

- lost 처리부: endless면 (`record(...)` 호출 뒤):

```dart
ref.read(analyticsProvider).endlessEnd(
      score: next.score,
      isNewBest: isNew,
    );
```
(`record(next.score).then((isNew) {...})` 콜백 안에서 호출.)

- lost && !endless (시즌 스테이지 패배):

```dart
final flow = ref.read(seasonFlowProvider);
if (flow != null) {
  ref.read(analyticsProvider).stageEnd(
        seasonId: flow.pack.seasonId,
        stageId: flow.stage.id,
        won: false,
        stars: 0,
        score: next.score,
        movesUsed: next.moveLimit - next.movesLeft,
      );
}
```

주의: 엔드리스의 movesLeft는 1<<30 센티널이고 moveLimit은 0 — 위 stageEnd 호출들은 모두 `flow != null`(시즌 컨텍스트)에서만 일어나므로 안전.

- rescue 두 곳: `_resultOverlay`의 `notifier.useContinue` / `notifier.addExtraMoves` onPressed에 각각:

```dart
ref.read(analyticsProvider).rescueUsed(type: 'continue');
// / type: 'extra_moves'
```
(onPressed를 블록으로 바꿔 분석 호출 후 기존 메서드 호출.)

`lib/ui/screens/home_screen.dart` — 클래식 onPressed의 startStage 직전:

```dart
ref.read(analyticsProvider).endlessStart();
```

`lib/state/tutorial_notifier.dart` — `_finish()`에 skipped 플래그가 필요하므로 시그니처 변경:

```dart
Future<void> dismissHud() async {
  if (state != TutorialStep.explainHud) return;
  await _finish(skipped: false);
}

Future<void> skip() async {
  if (state == null) return;
  await _finish(skipped: true);
}

Future<void> _finish({required bool skipped}) async {
  state = null;
  ref.read(analyticsProvider).tutorialFinished(skipped: skipped);
  await ref.read(saveRepositoryProvider).markTutorialDone();
}
```

- [ ] **Step 5: 통과 + 커밋**

Run: `flutter test && flutter analyze`
Expected: 전체 PASS (기존 tutorial_notifier_test 영향 없음 — 외부 동작 동일), 0 issues.

```bash
git add lib test/services
git commit -m "feat: analytics abstraction with debug backend and game event wiring"
```

---

### Task 6: 시즌 2 콘텐츠 생성 + manifest 생성 도구

**Files:**
- Create: `content/season_002/spec.json`
- Create: `tool/make_manifest.dart`
- Generated: `content/season_002/pack.json`, `content/season_002/report.md`, `content/manifest.json`

- [ ] **Step 1: 시즌 2 스펙 작성** — `content/season_002/spec.json`:

```json
{
  "seasonId": "season_002",
  "version": 1,
  "title": { "en": "Summer Tide", "ko": "여름 파도" },
  "theme": {
    "tileSet": "summer",
    "background": "",
    "backgroundGradient": [4278854704, 4279253322, 4280179302],
    "accentColor": 4285456885,
    "particleType": "petals"
  },
  "stageCount": 30,
  "baseSeed": 20260612,
  "runsPerStage": 80
}
```
(그라데이션 = 0xFF0A2430/0xFF10394A/0xFF1E5A66 딥 틸, accent = 0xFF6FCDF5 시안 — 비주얼 컴패니언에서 "여름에 어울림"으로 평가된 톤. `copyToAssets` 없음 = 번들 미포함, 원격 전용. int는 JSON이라 10진수 표기.)

주의: 4285456885 = 0xFF6FCDF5 확인 계산: 0xFF6FCDF5 = 4285713909. **구현 시 반드시 Dart로 검증**: `print(0xFF6FCDF5);` → 그 값을 spec에 쓸 것. (0xFF0A2430 = 4278920240, 0xFF10394A = 4279318858, 0xFF1E5A66 = 4280245862 — 역시 print로 검증 후 기입.)

- [ ] **Step 2: 시즌 2 생성**

```bash
dart run tool/stage_generator/generate.dart content/season_002/spec.json
```
Expected: `content/season_002/pack.json` + `report.md` 생성, 콘솔에 스테이지별 보정 로그. (60스테이지 시즌1이 ~10초였으므로 30스테이지는 ~5초.)

생성 후 확인:
```bash
dart -e "import 'dart:convert'; import 'dart:io'; void main(){ final p=jsonDecode(File('content/season_002/pack.json').readAsStringSync()); print(p['seasonId']); print((p['stages'] as List).length); print(p['theme']); }"
```
Expected: season_002 / 30 / theme에 backgroundGradient·accentColor 포함.

- [ ] **Step 3: make_manifest.dart 작성** — `tool/make_manifest.dart`:

```dart
import 'dart:convert';
import 'dart:io';

import 'package:crypto/crypto.dart';

/// Builds content/manifest.json from the season packs under content/.
/// Usage: dart run tool/make_manifest.dart
void main() {
  final contentDir = Directory('content');
  final seasons = <Map<String, dynamic>>[];

  final dirs = contentDir
      .listSync()
      .whereType<Directory>()
      .where((d) => File('${d.path}/pack.json').existsSync())
      .toList()
    ..sort((a, b) => a.path.compareTo(b.path));

  for (final dir in dirs) {
    final file = File('${dir.path}/pack.json');
    final bytes = file.readAsBytesSync();
    final pack = jsonDecode(utf8.decode(bytes)) as Map<String, dynamic>;
    seasons.add({
      'seasonId': pack['seasonId'],
      'version': pack['version'],
      'packUrl': 'seasons/${pack['seasonId']}/pack.json',
      'sha256': sha256.convert(bytes).toString(),
    });
  }

  final manifest = {
    'schemaVersion': 1,
    'minAppBuild': 1,
    'current': seasons.isEmpty ? '' : seasons.last['seasonId'],
    'seasons': seasons,
  };

  File('content/manifest.json')
      .writeAsStringSync('${const JsonEncoder.withIndent("  ").convert(manifest)}\n');
  stdout.writeln('manifest.json written with ${seasons.length} season(s).');
}
```

- [ ] **Step 4: manifest 생성 + 검증**

```bash
dart run tool/make_manifest.dart
cat content/manifest.json
```
Expected: season_001과 season_002 항목, current=season_002, 각 sha256 64자 hex.

주의: packUrl 규약은 `seasons/<id>/pack.json`인데 로컬 content/ 레이아웃은 `content/<id>/pack.json` — 배포 시 `seasons/` 하위로 올리는 구조다. Task 7의 로컬 서빙 단계에서 디렉터리를 그 레이아웃으로 구성한다 (스크립트 제공됨).

- [ ] **Step 5: 커밋**

```bash
git add content/season_002 content/manifest.json tool/make_manifest.dart
git commit -m "feat: season 2 'Summer Tide' content and manifest generator"
```

---

### Task 7: 통합 검증 — 로컬 서버로 원격 시즌 E2E + 오너 가이드

**Files:**
- Create: `docs/firebase-hosting-guide.md`
- 검증만: 시뮬레이터 E2E

- [ ] **Step 1: 전체 테스트 + analyze**

```bash
flutter analyze
flutter test
```
Expected: 0 issues, 전체 PASS. 최종 `+N` 라인 기록.

- [ ] **Step 2: 로컬 콘텐츠 서버 구성**

```bash
mkdir -p /tmp/bs_serve/content/seasons/season_001 /tmp/bs_serve/content/seasons/season_002
cp content/manifest.json /tmp/bs_serve/content/
cp content/season_001/pack.json /tmp/bs_serve/content/seasons/season_001/
cp content/season_002/pack.json /tmp/bs_serve/content/seasons/season_002/
cd /tmp/bs_serve && python3 -m http.server 8787 &
cd - 
curl -s http://localhost:8787/content/manifest.json | head -5
```
Expected: manifest JSON 출력.

- [ ] **Step 3: 시뮬레이터에서 원격 시즌 E2E**

```bash
xcrun simctl boot "iPhone 17 Pro" 2>/dev/null
flutter build ios --simulator --debug --dart-define=CONTENT_BASE_URL=http://localhost:8787/content
xcrun simctl install booted build/ios/iphonesimulator/Runner.app
xcrun simctl launch booted com.airkjw.blockseasons
```

수동 확인 (콜드 스타트 2회 — 1회차에 다운로드, listen이 invalidate하면 1회차에도 반영될 수 있음):
1. 홈 → 어드벤처: 시즌 맵이 **"Summer Tide / 여름 파도" 30스테이지 + 딥 틸 배경**으로 뜨면 성공 (= 스토어 업데이트 없이 시즌2 등장).
2. 시즌 카드도 SEASON 2 표시.
3. 스크린샷: `xcrun simctl io booted screenshot /tmp/sim_remote_s2.png` → `docs/screenshots/sim_remote_season2.png` 로 복사.

- [ ] **Step 4: 오프라인 폴백 E2E**

```bash
kill %1  # python http.server 종료
xcrun simctl uninstall booted com.airkjw.blockseasons   # 캐시 제거(신규 설치 시나리오)
xcrun simctl install booted build/ios/iphonesimulator/Runner.app
xcrun simctl launch booted com.airkjw.blockseasons
```
확인: 서버가 죽어 있어도 앱이 정상 구동하고 어드벤처 = 번들 시즌1 (First Bloom/첫 개화 60스테이지). 크래시·멈춤 없어야 함. (= 비행기 모드 시나리오)

- [ ] **Step 5: 오너 가이드 작성** — `docs/firebase-hosting-guide.md`:

```markdown
# Firebase Hosting 시즌 배포 가이드 (오너용)

## 1회 설정 (약 15분)

1. https://console.firebase.google.com → "프로젝트 추가" → 이름 `block-seasons`
   → Google Analytics **사용 설정** (분석 Phase에서 사용).
2. 터미널에서:
   ```bash
   npm install -g firebase-tools
   firebase login
   cd "/Volumes/Macintosh 2nd/Project/My_Game_Project/BlockSeasons"
   firebase init hosting   # 기존 프로젝트 block-seasons 선택, public 디렉터리: deploy
   ```
3. 생성된 호스팅 도메인(예: https://block-seasons.web.app)을 Claude에게 알려주면
   앱의 CONTENT_BASE_URL 기본값을 맞춰드립니다.

## 시즌 배포 (매 시즌 약 1분)

```bash
cd "/Volumes/Macintosh 2nd/Project/My_Game_Project/BlockSeasons"
dart run tool/make_manifest.dart
rm -rf deploy/content && mkdir -p deploy/content/seasons
cp content/manifest.json deploy/content/
for d in content/season_*/; do
  id=$(basename "$d")
  mkdir -p "deploy/content/seasons/$id"
  cp "$d/pack.json" "deploy/content/seasons/$id/"
done
firebase deploy --only hosting
```

배포 직후 모든 유저의 다음 콜드 스타트에서 새 시즌이 나타납니다.
앱 업데이트·심사 불필요.
```

- [ ] **Step 6: 스크린샷 + 최종 커밋 + 푸시**

```bash
git add docs
git commit -m "feat: phase 4 remote seasons verified end-to-end; owner hosting guide"
git push
```

- [ ] **Step 7: 오너 보고** — 시즌2가 원격으로 등장한 스크린샷 공유, Firebase 가이드 안내, Phase 5(수익화) 전 오너 선행 작업(AdMob 앱/광고단위 생성) 리마인드.

---

## 자체 검토 결과

- **Spec 커버리지**: manifest+SHA256+원자 캐시(T2), 캐시→번들 폴백(T3), 갱신 트리거(T4), 분석 이벤트(T5), 시즌2 콘텐츠+배포물(T6), "스토어 업데이트 없이 시즌2 등장"+"비행기 모드 시즌1 정상" 검증(T7), 오너 Firebase 가이드(T7). 스트릭 UI는 Phase 3에서 완료(범위 제외 명시). theme.zip은 보류 — 현재 테마는 pack.json 내 JSON 필드로 충분(이미지 에셋 도입 시 Phase 6에서 추가).
- **플레이스홀더**: 없음. 단 spec.json의 ARGB 10진수 값은 구현자가 Dart print로 검증 후 기입하도록 명시(계산 실수 방지).
- **타입 일관성**: `ContentDownloader(baseUrl:, cacheDir:, client:)` (T2 정의 → T3 main 사용), `ContentRepository(cacheDir:, downloader:)` (T3), `seasonRefreshProvider`/`activeSeason` (T4 정의 → T4 사용처), `AnalyticsService`/`AnalyticsBackend` (T5), manifest 필드명 (T1 ↔ T2 ↔ T6 make_manifest) 일치 확인.
- **Firebase 미포함 확인**: firebase_core/analytics 의존성 없음 — 오너 작업 완료 후 별도 태스크로 FirebaseAnalyticsBackend 추가 예정.