기록서가 건 잠금만 눌러 봐야 알 수 있던 것을 카드에 미리 적음

전투 카드의 잠금은 다 미리 말한다. 집중력이 모자라면 `집중 부족`, 재사용
대기면 `재사용 2`, 레벨이 모자라면 `Lv.9 해금`, 고를 후보가 비면 `지금은 고를
것이 없어요`. 그 자리에 사유를 넣은 코드에도 `눌러 본 뒤 거절당하는 대신 왜 못
쓰는지 슬롯에서 바로 읽히게 한다`고 적혀 있다.

기록서가 건 잠금 넷만 그 규칙 밖에 있었다. 발아 시계의 태엽(1라운드 스킬),
고리수 기록부(전투 내내 지키기), 아홉 꼬리의 잔상(그 라운드 지키기), 마음결
대백과(교체한 라운드 스킬)는 카드가 멀쩡히 열려 있다가 누르면 그제야 서버가
거절했다. 문장 자체는 친절한데, 고르기 전에 알아야 할 정보를 고른 뒤에 준다.

`guardian_battle_payload`가 킷을 만들 때 같은 상태를 읽어 사유를 함께 싣는다.
판정은 그대로 `_apply_action`이 한다 - 여기서 하는 일은 말해 주는 것뿐이라
두 곳이 어긋날 여지를 두지 않으려고 상태를 같은 곳에서 읽는다.

**이미 잠긴 칸은 건드리지 않는다.** 레벨이나 후보 없음처럼 더 오래가는 사유가
있으면 그쪽이 더 쓸모 있다. 실제로 발아 시계는 자기가 꽂힌 칸에 이미
`때가 되면 스스로 펼쳐져요`를 달고 있어서, 덮었다면 그 말이 사라졌다.

앱은 고칠 게 없었다. `lockReason`을 읽고 없을 때만 레벨 문구로 떨어지는 코드가
이미 있었다 - 사유를 안 보내 주고 있었을 뿐이다. 대신 앱 쪽에도 테스트를 붙여
레벨 문구로 바꿔 말하지 않는 것을 고정했다.

Author: easygap

app/test/expedition_models_test.dart

@@ -1517,6 +1517,57 @@ void main() {
     await tester.pumpWidget(const SizedBox.shrink());
   });
 
+  testWidgets('기록서가 건 잠금은 눌러 보기 전에 카드에서 읽힌다', (tester) async {
+    // 이 화면의 다른 잠금은 다 미리 말한다 - `집중 부족`, `Lv.N 해금`.
+    // 기록서가 건 잠금만 눌러야 알 수 있었다.
+    await tester.binding.setSurfaceSize(const Size(390, 1100));
+    addTearDown(() => tester.binding.setSurfaceSize(null));
+    final raw = _battleSnapshotJson();
+    final battleJson = (raw['current_event'] as Map<String, dynamic>)['battle']
+        as Map<String, dynamic>;
+    // 집중력을 넉넉히 줘 `집중 부족`이 대신 뜨지 않게 한다.
+    battleJson['focus'] = 5;
+    final kitJson = ((battleJson['party'] as List).first
+        as Map<String, dynamic>)['kit'] as Map<String, dynamic>;
+    final unique = (kitJson['unique_skills'] as List).first
+        as Map<String, dynamic>;
+    unique
+      ..['available'] = false
+      ..['lock_reason'] = '태엽 감는 중';
+    (kitJson['guard'] as Map<String, dynamic>)
+      ..['available'] = false
+      ..['lock_reason'] = '고리수 세는 중';
+    final snapshot = ExpeditionSnapshot.fromJson(raw);
+
+    await tester.pumpWidget(
+      ProviderScope(
+        overrides: [
+          expeditionControllerProvider.overrideWith(
+            () => _FakeExpeditionController(
+              ExpeditionUiState(
+                loading: false,
+                expedition: snapshot,
+                selectedMemberId: 11,
+              ),
+            ),
+          ),
+        ],
+        child: MaterialApp(
+          theme: AppTheme.light(),
+          home: const ExpeditionScreen(),
+        ),
+      ),
+    );
+    await tester.pump();
+
+    // 레벨 문구로 바꿔 말하지 않는다 - 서버가 준 사유를 그대로 쓴다.
+    expect(find.text('태엽 감는 중'), findsWidgets);
+    expect(find.text('고리수 세는 중'), findsWidgets);
+    expect(find.textContaining('해금'), findsNothing);
+    expect(tester.takeException(), isNull);
+    await tester.pumpWidget(const SizedBox.shrink());
+  });
+
   testWidgets('잔향 읽기를 쓴 전투에서만 다음 라운드 예고가 보인다', (tester) async {
     // 이 책이 파는 것은 이 한 줄뿐이다. 늘 보이면 40씨앗짜리 책이 파는 게
     // 없어지고, 안 보이면 산 사람이 아무것도 못 받는다.

server/app/content/expeditions/combat.py

@@ -164,6 +164,8 @@ def member_battle_kit(
     choice_context: dict[str, dict[str, Any]] | None = None,
     enemy_guard_bp: int = 10_000,
     party_unique2_power: int = 0,
+    skill_lock_reason: str | None = None,
+    guard_lock_reason: str | None = None,
 ) -> dict[str, Any]:
     element_kels = element_kel_map(kel_map_version)
     snapshot = profile.get("snapshot", {})
@@ -440,7 +442,7 @@ def resolve_skill(
     basic_neutral_power = scaled_power(
         scaled_power(basic_raw_power, basic_scale), TIER_POWER_BP[tier]
     )
-    return {
+    kit = {
         "version": 8,
         "kel_map_version": int(kel_map_version),
         "level": level,
@@ -535,6 +537,42 @@ def resolve_skill(
             "cooldown_remaining": 0,
         },
     }
+    return _apply_state_locks(
+        kit,
+        skill_lock_reason=skill_lock_reason,
+        guard_lock_reason=guard_lock_reason,
+    )
+
+
+def _apply_state_locks(
+    kit: dict[str, Any],
+    *,
+    skill_lock_reason: str | None,
+    guard_lock_reason: str | None,
+) -> dict[str, Any]:
+    """기록서가 건 잠금을 슬롯에서 미리 읽히게 한다.
+
+    이 잠금들은 지금까지 `_apply_action`의 거절로만 존재했다. 즉 눌러 봐야
+    알 수 있었는데, 이 화면의 다른 잠금은 전부 미리 말한다 - 집중력이 모자라면
+    `집중 부족`, 레벨이 모자라면 `Lv.N 해금`이다. 기록서가 건 것만 예외일
+    이유가 없다(같은 파일의 `고를 것이 없어요`도 같은 이유로 미리 말한다).
+
+    **이미 잠긴 슬롯은 건드리지 않는다.** 레벨이나 후보 없음처럼 더 오래가는
+    사유가 이미 있으면 그쪽이 사용자에게 더 쓸모 있다. 판정은 그대로
+    `_apply_action`이 하며, 여기서 하는 일은 말해 주는 것뿐이다.
+    """
+
+    def lock(action: dict[str, Any], reason: str) -> None:
+        if action.get("available", True):
+            action["available"] = False
+            action["lock_reason"] = reason
+
+    if skill_lock_reason:
+        for action in [*kit["unique_skills"], *kit["selected_skills"]]:
+            lock(action, skill_lock_reason)
+    if guard_lock_reason:
+        lock(kit["guard"], guard_lock_reason)
+    return kit
 
 
 def _resolve_waves(
@@ -1093,6 +1131,9 @@ def guardian_battle_payload(
         if profile is None:
             continue
         snapshot = profile.get("snapshot", {})
+        skill_lock_reason, guard_lock_reason = _state_lock_reasons(
+            state, member_state
+        )
         party.append(
             {
                 **member_state,
@@ -1111,6 +1152,8 @@ def guardian_battle_payload(
                     round_number=int(state.get("round", 1)),
                     enemy_guard_bp=enemy_guard_bp,
                     party_unique2_power=party_unique2_power,
+                    skill_lock_reason=skill_lock_reason,
+                    guard_lock_reason=guard_lock_reason,
                     choice_context=_battle_choice_context(
                         state,
                         member_state=member_state,
@@ -1335,6 +1378,45 @@ def _target_members(
     return [living[0]]
 
 
+# 슬롯에 붙는 짧은 잠금 사유. 거절 문장과 같은 말을 쓰되 카드 배지 길이에
+# 맞춘다(`집중 부족`·`재사용 2`와 같은 자리다). 왜 잠겼는지 눌러 보기 전에
+# 읽히는 것이 목적이므로 원인을 지운 `사용 불가`로 뭉뜽그리지 않는다.
+SKILL_LOCK_WINDING = "태엽 감는 중"
+SKILL_LOCK_SWAPPING = "기록서 교체 중"
+GUARD_LOCK_RINGCOUNT = "고리수 세는 중"
+GUARD_LOCK_AFTERIMAGE = "잔상 받음"
+
+
+def _state_lock_reasons(
+    state: dict[str, Any], member_state: dict[str, Any]
+) -> tuple[str | None, str | None]:
+    """이 대원의 스킬·지키기가 지금 왜 잠겼는지. 안 잠겼으면 `(None, None)`.
+
+    판정은 `_apply_action`이 그대로 한다. 여기서 만드는 것은 화면에 미리
+    보여 줄 사유뿐이고, 두 곳이 어긋나지 않도록 같은 상태를 읽는다.
+    """
+
+    member_id = int(member_state.get("member_id", 0))
+    round_number = int(state.get("round", 1))
+    opening = state.get("skill_book_opening") or {}
+
+    skill_reason: str | None = None
+    if round_number <= 1 and member_id in {
+        int(value) for value in opening.get("first_round_skill_locked", [])
+    }:
+        skill_reason = SKILL_LOCK_WINDING
+    elif int(member_state.get("skill_blocked_round", 0)) == round_number:
+        skill_reason = SKILL_LOCK_SWAPPING
+
+    guard_reason: str | None = None
+    if member_id in {int(value) for value in opening.get("guard_locked", [])}:
+        guard_reason = GUARD_LOCK_RINGCOUNT
+    elif _retargeted_member_id(state) == member_id:
+        guard_reason = GUARD_LOCK_AFTERIMAGE
+
+    return skill_reason, guard_reason
+
+
 def _retargeted_member_id(state: dict[str, Any]) -> int | None:
     """이번 라운드에 예고를 넘겨받은 대원. 라운드가 지나면 저절로 풀린다."""
 

server/tests/unit/test_skill_books.py

@@ -560,6 +560,74 @@ def test_germination_gear_locks_skills_in_the_first_round():
     )
 
 
+def test_book_locks_are_announced_on_the_slot_before_the_tap():
+    """눌러 본 뒤 거절당하는 대신 슬롯에서 왜 못 쓰는지 먼저 읽힌다.
+
+    이 화면의 다른 잠금은 전부 미리 말한다 - 집중력이 모자라면 `집중 부족`,
+    레벨이 모자라면 `Lv.N 해금`이다. 기록서가 건 잠금만 예외였다.
+    """
+
+    from app.content.expeditions.combat import (
+        GUARD_LOCK_RINGCOUNT,
+        SKILL_LOCK_WINDING,
+        guardian_battle_payload,
+        new_guardian_battle,
+    )
+
+    encounter = _encounter_fixture()
+
+    # 발아 시계 — 1라운드에 스킬 넷이 잠기고 기본 공격·지키기는 열려 있다.
+    profiles = _party_with("germination_gear")
+    battle = new_guardian_battle("gear", encounter, profiles)
+    kit = guardian_battle_payload(battle, encounter, profiles)["party"][0]["kit"]
+    for action in kit["unique_skills"]:
+        assert action["available"] is False
+        assert action["lock_reason"] == SKILL_LOCK_WINDING
+    # 선택 칸도 잠기지만, 발아 시계 자신이 꽂힌 칸은 원래 사유를 지킨다
+    # (`때가 되면 스스로 펼쳐져요`). 더 오래가는 사유를 덮지 않는 규칙이다.
+    for action in kit["selected_skills"]:
+        assert action["available"] is False
+        assert action["lock_reason"]
+    # 밸런스 불변식 - 최소 한 행동은 언제나 열려 있어야 한다.
+    assert kit["basic"]["available"] is True
+    assert kit["guard"]["available"] is True
+
+    # 대가를 지지 않은 대원은 잠기지도, 사유가 붙지도 않는다.
+    other = guardian_battle_payload(battle, encounter, profiles)["party"][1]["kit"]
+    assert other["unique_skills"][0]["available"] is True
+    assert other["unique_skills"][0].get("lock_reason") is None
+
+    # 고리수 기록부 — 그 전투 내내 지키기가 잠긴다.
+    ring_profiles = _b2_party("ringcount_record")
+    ring = new_guardian_battle("ring", encounter, ring_profiles)
+    ring_kit = guardian_battle_payload(ring, encounter, ring_profiles)["party"][0][
+        "kit"
+    ]
+    assert ring_kit["guard"]["available"] is False
+    assert ring_kit["guard"]["lock_reason"] == GUARD_LOCK_RINGCOUNT
+
+
+def test_state_lock_does_not_overwrite_a_longer_lasting_reason():
+    """레벨처럼 더 오래가는 사유가 이미 있으면 그쪽을 남긴다."""
+
+    from app.content.expeditions.combat import _apply_state_locks
+
+    kit = {
+        "unique_skills": [
+            {"available": False, "lock_reason": None, "unlock_level": 7},
+            {"available": True},
+        ],
+        "selected_skills": [{"available": True}, {"available": True}],
+        "guard": {"available": True},
+    }
+    _apply_state_locks(kit, skill_lock_reason="태엽 감는 중", guard_lock_reason=None)
+
+    # 이미 잠긴 첫 칸은 그대로 두고, 열려 있던 칸에만 사유가 붙는다.
+    assert kit["unique_skills"][0]["lock_reason"] is None
+    assert kit["unique_skills"][1]["lock_reason"] == "태엽 감는 중"
+    assert kit["guard"]["available"] is True
+
+
 def test_germination_gear_lock_lifts_after_the_first_round():
     """반대급부는 1라운드까지다. 그 뒤에는 평소처럼 쓴다."""