Music Shake 첫 박 시각 · 카운트다운 · 옛 일시 정지 판 정리

app/lib/features/quest/quest_data.dart

@@ -370,6 +370,7 @@ class QuestSession {
     this.position = Duration.zero,
     this.hits = const [],
     this.judgement,
+    this.firstBeat,
   });
 
   /// [QuestStage.inProgress] · [QuestStage.paused] · [QuestStage.completed] 중 하나.
@@ -384,6 +385,16 @@ class QuestSession {
   /// Music Shake 를 멈춘 영상 시각 — 「이어하기」 시작점.
   final Duration position;
 
+  /// 이 일시 정지가 지금 운영값([setup])의 박 위치로 이어질 수 있는지. 첫 박이나 판 길이가 바뀌었으면 false.
+  bool fitsShake(MusicShakeSetup setup) => fits(setup.firstBeat, setup.segments);
+
+  /// [fitsShake] 와 같은 비교 — 운영값만 아는 곳(목록 · HOME · 캡슐은 퀘스트 문서를 읽는다)용.
+  bool fits(Duration firstBeat, int segments) =>
+      this.firstBeat == firstBeat && total == segments;
+
+  /// Music Shake 판을 시작할 때의 첫 박(`quests.firstBeatMs`). 없으면 첫 박 도입 전에 저장된 판이다.
+  final Duration? firstBeat;
+
   /// Music Shake 박마다 가장 가까운 흔들기의 거리(박 비율). 흔들기가 없으면 -1.
   final List<double> hits;
 
@@ -414,6 +425,7 @@ class QuestCard {
     this.publishState = '',
     this.authorName = '',
     this.session,
+    this.staleShake = false,
   });
 
   final String id;
@@ -423,6 +435,10 @@ class QuestCard {
   /// 서버에 남은 진행 세션(진행중 · 일시 정지 · 진행완료) — 원장 C-83. 없으면 null.
   final QuestSession? session;
 
+  /// 운영값(첫 박 · 판 길이)이 바뀌어 이어갈 수 없는 Music Shake 세션이 서버에 남아 있다.
+  /// 이때 [session] 은 null 이고 카드는 「시작하기」로 보인다 — 시작하면 안내를 한 번 띄운다.
+  final bool staleShake;
+
   /// 만든 사람의 공개 닉네임(`quests.authorName`). 운영 Quest 는 빈 값이다.
   /// 신고하기 「신고 정보 영역 — 작성자 닉네임」(Figma `548:21389`)에 쓴다.
   final String authorName;
@@ -473,6 +489,7 @@ class QuestCard {
   /// 상태·진행도만 바꾼 사본. [QuestCard] 는 불변이라 갈아 끼운다.
   QuestCard copyWith({QuestStage? stage, int? progress}) => QuestCard(
     session: session,
+    staleShake: staleShake,
     id: id,
     title: title,
     categoryName: categoryName,
@@ -500,7 +517,9 @@ class MusicShakeSetup {
     required this.title,
     required this.bpm,
     required this.segments,
+    this.firstBeat = Duration.zero,
     this.windows = const ShakeWindows(),
+    this.leadIn = const Duration(seconds: 3),
   });
 
   /// 지정 공식 YouTube 영상(PRD-04 MVP 수용 기준) — `quests.link.url` 에서 꺼낸 ID.
@@ -512,9 +531,19 @@ class MusicShakeSetup {
   /// `quests.bpm` — Figma 「목표BPM」. 🟡 의미 · 입력 주체 회신 대기(Q-MS-01 · Q-MS-02).
   final double bpm;
 
-  /// `quests.totalSegments` — 판정 박 수. 🟡 구간 패턴 정의 회신 대기(Q-MS-02).
+  /// `quests.totalSegments` — 판정 박 수. 곡 전체를 덮도록 운영자가 정한다. 🟡 회신 대기(Q-MS-02).
   final int segments;
+
+  /// `quests.firstBeatMs` — 영상에서 첫 박 시각. 🟡 임시값 — 회신 대기(Q-MS-02 · Q-MS-03). 없으면 0.
+  final Duration firstBeat;
   final ShakeWindows windows;
+
+  /// 첫 박 몇 초 전부터 영상을 트는가 — `config/policy.musicShake.leadInMs`(없으면 3초).
+  /// 🟡 임시값 — 회신 대기(해석 확인 요청서 MusicShake 「재생 시작 위치」 B안).
+  final Duration leadIn;
+
+  /// 새 판의 영상 시작 시각 — 첫 박 [leadIn] 전(0 아래로는 가지 않는다). 이어하기는 저장 위치다.
+  Duration get startAt => firstBeat > leadIn ? firstBeat - leadIn : Duration.zero;
 }
 
 class QuestDetail {