feat(runtime): add knockout review controller

This commit is contained in:
2026-08-25 19:01:40 +08:00
parent 72723db5d4
commit a7d7d05931
2 changed files with 391 additions and 0 deletions
@@ -0,0 +1,241 @@
class_name ABGKnockoutReviewPageController
extends RefCounted
## UI-independent OUT-002 Knockout Review view-data assembly.
##
## BattleService remains responsible for settlement, reward, recovery and
## persistence. This controller only validates/copies the settled knockout
## facts and exposes the existing acknowledgement route eligibility.
func snapshot(
company: Dictionary,
battle: Dictionary,
result: Dictionary = {},
notice := "",
locale := "zh_CN"
) -> Dictionary:
if company.is_empty():
return {"ok": false, "code": "COMPANY_REQUIRED"}
var raw_recruits = company.get("owned_recruits", [])
if not raw_recruits is Array:
return {"ok": false, "code": "KNOCKOUT_COMPANY_INVALID"}
var raw_contract = company.get("active_contract", {})
if not raw_contract is Dictionary or Dictionary(raw_contract).is_empty():
return {"ok": false, "code": "KNOCKOUT_CONTRACT_REQUIRED"}
if battle.is_empty():
return {"ok": false, "code": "KNOCKOUT_BATTLE_REQUIRED"}
if String(battle.get("status", "")) != "result":
return {"ok": false, "code": "KNOCKOUT_BATTLE_NOT_SETTLED"}
var operation_id := String(battle.get("operation_id", ""))
if operation_id.is_empty():
return {"ok": false, "code": "KNOCKOUT_OPERATION_REQUIRED"}
var members := _members_by_id(raw_recruits)
if members.is_empty():
return {"ok": false, "code": "KNOCKOUT_COMPANY_EMPTY"}
var contract: Dictionary = Dictionary(raw_contract).duplicate(true)
var sourced_result := result
if sourced_result.is_empty():
sourced_result = battle.get("result", {})
if not sourced_result is Dictionary or Dictionary(sourced_result).is_empty():
return {"ok": false, "code": "KNOCKOUT_RESULT_REQUIRED"}
var copied_result: Dictionary = Dictionary(sourced_result).duplicate(true)
var persisted_result = battle.get("result", {})
if persisted_result is Dictionary and not Dictionary(persisted_result).is_empty():
var persisted_hash := String(Dictionary(persisted_result).get("result_hash", ""))
var supplied_hash := String(copied_result.get("result_hash", ""))
if not persisted_hash.is_empty() and not supplied_hash.is_empty() and persisted_hash != supplied_hash:
return {"ok": false, "code": "KNOCKOUT_RESULT_IDENTITY_MISMATCH"}
var result_operation_id := String(copied_result.get("operation_id", ""))
if not result_operation_id.is_empty() and result_operation_id != operation_id:
return {"ok": false, "code": "KNOCKOUT_RESULT_OPERATION_MISMATCH"}
var receipt_state := _settlement_receipt(contract, battle, operation_id)
if not bool(receipt_state.get("ok", false)):
return receipt_state
var raw_knockouts = copied_result.get("knocked_out_ids", battle.get("knocked_out_ids", []))
if not raw_knockouts is Array:
return {"ok": false, "code": "KNOCKOUT_IDS_INVALID"}
var ids: Array = []
var id_set := {}
var identities: Array = []
var front_to_rear: Array = _copy_array(battle.get("front_to_rear_ids", []))
for raw_id in raw_knockouts:
var recruit_id := String(raw_id)
if recruit_id.is_empty() or not members.has(recruit_id):
return {"ok": false, "code": "KNOCKOUT_RECRUIT_UNKNOWN"}
if id_set.has(recruit_id):
return {"ok": false, "code": "KNOCKOUT_RECRUIT_DUPLICATE"}
id_set[recruit_id] = true
ids.append(recruit_id)
var recruit: Dictionary = Dictionary(members[recruit_id]).duplicate(true)
identities.append({
"recruit_id": recruit_id,
"position": front_to_rear.find(recruit_id),
"recruit": recruit,
"battle_local": true,
"deleted": false,
"returns_next_stage": true,
})
var battle_knockouts = battle.get("knocked_out_ids", [])
if battle_knockouts is Array and not battle_knockouts.is_empty() and ids != battle_knockouts:
return {"ok": false, "code": "KNOCKOUT_IDENTITY_MISMATCH"}
var reward_state := _reward_state(battle.get("reward_draft", {}))
if not bool(reward_state.get("ok", false)):
return reward_state
var reward_pending := bool(reward_state.pending)
var acknowledgement_target := "battle_reward_choice" if reward_pending else "battle_recovery"
var copied_battle: Dictionary = battle.duplicate(true)
var copied_events: Array = _copy_array(battle.get("phase_events", []))
var copied_contract: Dictionary = {
"contract_id": String(contract.get("contract_id", "")),
"run_id": String(contract.get("run_id", "")),
"status": String(contract.get("status", "result")),
"difficulty": String(contract.get("difficulty", "standard")),
"coin": int(contract.get("coin", copied_result.get("coin_after", 0))),
"line_capacity": int(contract.get("line_capacity", front_to_rear.size())),
"contract_hash": String(contract.get("contract_hash", "")),
}
var copied_reward: Dictionary = Dictionary(reward_state.draft).duplicate(true)
var receipt: Dictionary = Dictionary(receipt_state.receipt).duplicate(true)
return {
"ok": true,
"page_id": "knockout_review",
"locale": String(locale),
"company": {
"company_id": String(company.get("company_id", "")),
"owned_count": members.size(),
"line_capacity": int(contract.get("line_capacity", front_to_rear.size())),
"recruits": _copy_array(raw_recruits),
},
"contract": copied_contract,
"battle": {
"operation_id": operation_id,
"battle_hash": String(battle.get("battle_hash", "")),
"status": String(battle.get("status", "")),
"snapshot_id": String(battle.get("snapshot_id", "")),
"snapshot_hash": String(battle.get("snapshot_hash", "")),
"phase_index": int(battle.get("phase_index", copied_events.size())),
"total_phases": int(battle.get("total_phases", copied_events.size())),
"front_to_rear_ids": front_to_rear,
"enemy_ids": _copy_array(battle.get("enemy_ids", [])),
"phase_events": copied_events,
"knocked_out_ids": ids.duplicate(true),
"copy": copied_battle,
},
"result": copied_result,
"knockouts": {
"ids": ids.duplicate(true),
"count": ids.size(),
"identities": identities,
"battle_local": true,
"deleted": false,
"returns_next_stage": true,
},
"gap": {
"state": "battle_local_absence" if not ids.is_empty() else "no_knockout",
"battle_local": true,
"company_identity_preserved": true,
"return_rule": "returns_next_stage_same_identity",
},
"reward": {
"draft": copied_reward,
"present": bool(reward_state.present),
"status": String(reward_state.status),
"pending": reward_pending,
"options": _copy_array(copied_reward.get("options", [])),
"options_count": Array(copied_reward.get("options", [])).size(),
},
"receipt": {
"settlement": receipt,
"operation_id": operation_id,
"receipt_hash": String(receipt.get("receipt_hash", "")),
"duplicate_safe": bool(receipt_state.duplicate_safe),
},
"acknowledgement": {
"eligible": true,
"target": acknowledgement_target,
"reward_pending": reward_pending,
"reason": "reward_pending" if reward_pending else "recovery_ready",
"notice": String(notice),
},
"commands": {
"back_enabled": true,
"acknowledge_enabled": true,
"settings_enabled": true,
"reward_review_enabled": reward_pending,
"recovery_enabled": not reward_pending,
},
}
func _settlement_receipt(contract: Dictionary, battle: Dictionary, operation_id: String) -> Dictionary:
var matches: Array = []
var raw_receipts = contract.get("battle_settlement_receipts", [])
if raw_receipts is Array:
for raw_receipt in raw_receipts:
if raw_receipt is Dictionary and String(raw_receipt.get("operation_id", "")) == operation_id:
matches.append(Dictionary(raw_receipt).duplicate(true))
if matches.is_empty():
var battle_receipt = battle.get("settlement_receipt", {})
if battle_receipt is Dictionary and not Dictionary(battle_receipt).is_empty() and String(battle_receipt.get("operation_id", operation_id)) == operation_id:
matches.append(Dictionary(battle_receipt).duplicate(true))
if matches.is_empty():
return {"ok": false, "code": "KNOCKOUT_SETTLEMENT_RECEIPT_REQUIRED"}
if matches.size() > 1:
return {"ok": false, "code": "KNOCKOUT_SETTLEMENT_RECEIPT_DUPLICATE"}
var receipt: Dictionary = matches[0]
var battle_id := String(receipt.get("battle_operation_id", operation_id))
if not battle_id.is_empty() and battle_id != operation_id:
return {"ok": false, "code": "KNOCKOUT_RECEIPT_OPERATION_MISMATCH"}
return {"ok": true, "receipt": receipt, "duplicate_safe": true}
func _reward_state(raw_draft) -> Dictionary:
if raw_draft == null:
raw_draft = {}
if not raw_draft is Dictionary:
return {"ok": false, "code": "KNOCKOUT_REWARD_DRAFT_INVALID"}
var draft: Dictionary = Dictionary(raw_draft).duplicate(true)
if draft.is_empty():
return {"ok": true, "present": false, "pending": false, "status": "none", "draft": {}}
var options = draft.get("options", [])
if not options is Array:
return {"ok": false, "code": "KNOCKOUT_REWARD_OPTIONS_INVALID"}
var option_ids := {}
for option in options:
if not option is Dictionary:
return {"ok": false, "code": "KNOCKOUT_REWARD_OPTION_INVALID"}
var reward_id := String(option.get("reward_id", ""))
if reward_id.is_empty():
return {"ok": false, "code": "KNOCKOUT_REWARD_ID_INVALID"}
if option_ids.has(reward_id):
return {"ok": false, "code": "KNOCKOUT_REWARD_ID_DUPLICATE"}
option_ids[reward_id] = true
var status := String(draft.get("status", "open"))
return {"ok": true, "present": true, "pending": status == "open", "status": status, "draft": draft}
func _members_by_id(values) -> Dictionary:
var result := {}
if not values is Array:
return result
for value in values:
if value is Dictionary:
var copied: Dictionary = Dictionary(value).duplicate(true)
var recruit_id := String(copied.get("recruit_id", ""))
if not recruit_id.is_empty():
result[recruit_id] = copied
return result
func _copy_array(values) -> Array:
var result: Array = []
if not values is Array:
return result
for value in values:
result.append(value.duplicate(true) if value is Dictionary or value is Array else value)
return result
@@ -0,0 +1,150 @@
extends SceneTree
const Controller = preload("res://entry/knockout_review_page_controller.gd")
var failures: Array[String] = []
func _initialize() -> void:
call_deferred("run_test")
func run_test() -> void:
var controller := Controller.new()
var company := _fixture_company()
var battle := _fixture_battle()
var open: Dictionary = controller.snapshot(company, battle, battle.result, "review", "en")
expect(open.ok and open.page_id == "knockout_review", "snapshot identifies Knockout Review")
expect(open.company.owned_count == 4 and open.contract.coin == 51, "snapshot copies Company and Contract facts")
expect(open.battle.status == "result" and open.battle.operation_id == "battle-op-001", "snapshot copies settled Battle identity")
expect(open.knockouts.ids == ["r-1"] and open.knockouts.count == 1, "snapshot copies knockout IDs")
expect(open.knockouts.identities[0].recruit.recruit_id == "r-1" and open.knockouts.identities[0].position == 0, "snapshot binds stable Recruit identity and position")
expect(open.gap.battle_local and open.gap.company_identity_preserved and open.gap.return_rule == "returns_next_stage_same_identity", "snapshot exposes battle-local return rule")
expect(open.reward.pending and open.acknowledgement.target == "battle_reward_choice", "open reward routes acknowledgement to Reward Choice")
expect(open.commands.acknowledge_enabled and open.commands.back_enabled, "acknowledgement and Back remain enabled")
expect(open.receipt.duplicate_safe and open.receipt.receipt_hash == "settlement-hash-001", "settlement receipt identity is duplicate-safe")
var copied_recruit: Dictionary = open.knockouts.identities[0].recruit
copied_recruit.rendered_name_snapshot.display_name = "changed"
open.reward.draft.options[0].reward_id = "changed"
open.battle.copy.phase_events[0].caption_id = "changed"
expect(String(company.owned_recruits[0].rendered_name_snapshot.display_name) == "Ari", "Recruit identity is deeply copied")
expect(String(battle.reward_draft.options[0].reward_id) == "reward-1", "reward draft is deeply copied")
expect(String(battle.phase_events[0].caption_id) == "opening", "Battle facts are deeply copied")
var no_reward := battle.duplicate(true)
no_reward.reward_draft = {}
var recovery: Dictionary = controller.snapshot(company, no_reward, no_reward.result)
expect(recovery.ok and not recovery.reward.pending and recovery.acknowledgement.target == "battle_recovery", "closed reward routes acknowledgement to Recovery")
var no_knockout := battle.duplicate(true)
no_knockout.knocked_out_ids = []
no_knockout.result = battle.result.duplicate(true)
no_knockout.result.knocked_out_ids = []
var empty_review: Dictionary = controller.snapshot(company, no_knockout, no_knockout.result)
expect(empty_review.ok and empty_review.knockouts.count == 0 and empty_review.gap.state == "no_knockout", "empty knockout review remains explicit and valid")
var missing: Dictionary = controller.snapshot({}, battle, battle.result)
expect(not missing.ok and missing.code == "COMPANY_REQUIRED", "missing Company is rejected")
var active := battle.duplicate(true)
active.status = "active"
var unsettled: Dictionary = controller.snapshot(company, active, battle.result)
expect(not unsettled.ok and unsettled.code == "KNOCKOUT_BATTLE_NOT_SETTLED", "unsettled Battle is rejected")
var unknown := battle.duplicate(true)
unknown.result = battle.result.duplicate(true)
unknown.result.knocked_out_ids = ["missing"]
unknown.knocked_out_ids = ["missing"]
var unknown_result: Dictionary = controller.snapshot(company, unknown, unknown.result)
expect(not unknown_result.ok and unknown_result.code == "KNOCKOUT_RECRUIT_UNKNOWN", "unknown knockout identity is rejected")
var duplicate := battle.duplicate(true)
duplicate.result = battle.result.duplicate(true)
duplicate.result.knocked_out_ids = ["r-1", "r-1"]
duplicate.knocked_out_ids = ["r-1", "r-1"]
var duplicate_result: Dictionary = controller.snapshot(company, duplicate, duplicate.result)
expect(not duplicate_result.ok and duplicate_result.code == "KNOCKOUT_RECRUIT_DUPLICATE", "duplicate knockout identity is rejected")
var missing_receipt_company := company.duplicate(true)
missing_receipt_company.active_contract.battle_settlement_receipts = []
var missing_receipt_battle := battle.duplicate(true)
missing_receipt_battle.erase("settlement_receipt")
var missing_receipt: Dictionary = controller.snapshot(missing_receipt_company, missing_receipt_battle, missing_receipt_battle.result)
expect(not missing_receipt.ok and missing_receipt.code == "KNOCKOUT_SETTLEMENT_RECEIPT_REQUIRED", "missing settlement receipt is rejected")
if failures.is_empty():
print("ABG_M28_KNOCKOUT_REVIEW_CONTROLLER_OK company=4 settled=result knockout=r-1 battle_local=true return=same_identity reward=open,none acknowledge=reward,recovery empty=true copies=true receipt=duplicate_safe")
quit(0)
else:
for failure in failures:
push_error(failure)
quit(1)
func _fixture_company() -> Dictionary:
return {
"company_id": "company-001",
"owned_recruits": [
{"recruit_id": "r-1", "rendered_name_snapshot": {"display_name": "Ari"}, "profession_id": "PF-B01", "level": 1, "xp": 0},
{"recruit_id": "r-2", "rendered_name_snapshot": {"display_name": "Bram"}, "profession_id": "PF-B05", "level": 1, "xp": 16},
{"recruit_id": "r-3", "rendered_name_snapshot": {"display_name": "Cera"}, "profession_id": "PF-B07", "level": 1, "xp": 16},
{"recruit_id": "r-4", "rendered_name_snapshot": {"display_name": "Dain"}, "profession_id": "PF-B03", "level": 1, "xp": 16},
],
"active_contract": {
"contract_id": "CTR-R1-01",
"run_id": "run-001",
"status": "result",
"coin": 51,
"line_capacity": 4,
"contract_hash": "contract-hash-001",
"battle_settlement_receipts": [_fixture_receipt()],
},
}
func _fixture_battle() -> Dictionary:
return {
"status": "result",
"operation_id": "battle-op-001",
"battle_hash": "battle-hash-001",
"snapshot_id": "snapshot-001",
"snapshot_hash": "snapshot-hash-001",
"front_to_rear_ids": ["r-1", "r-2", "r-3", "r-4"],
"enemy_ids": ["enemy-1", "enemy-2", "enemy-3"],
"phase_index": 9,
"total_phases": 9,
"phase_events": [{"event_id": "event-0", "event_hash": "event-hash-0", "kind": "opening", "caption_id": "opening"}],
"knocked_out_ids": ["r-1"],
"result": {
"outcome": "victory",
"outcome_cause": "enemy_line_broken",
"reward_coin": 27,
"xp_award": 48,
"coin_before": 24,
"coin_after": 51,
"knocked_out_ids": ["r-1"],
"result_hash": "result-hash-001",
},
"reward_draft": {
"draft_id": "draft-001",
"status": "open",
"options": [
{"reward_id": "reward-1", "kind": "equipment"},
{"reward_id": "reward-2", "kind": "coin", "amount": 8},
],
},
"settlement_receipt": _fixture_receipt(),
}
func _fixture_receipt() -> Dictionary:
return {
"operation_id": "battle-op-001",
"battle_operation_id": "battle-op-001",
"receipt_hash": "settlement-hash-001",
"outcome_hash": "outcome-hash-001",
"outcome": "victory",
}
func expect(condition: bool, message: String) -> void:
if not condition:
failures.append("M28 Knockout Review Controller: %s" % message)