MatchRPG new_player_defaults Fallback Alignment¶
概念概覽
問題根因¶
核心知識¶
問題根因¶
new_player_defaults 是新玩家初始化的 fallback，其每個欄位必須與 FixedValueConfig.xlsx 保持一致。如果 hardcode 值與常數表不一致，不會報錯，只會產生靜默的數值錯誤（例如前端讀到 staminaMax=30，但常數表設定為 100）。
一次性資料修正策略¶
直接下 SQL 修正既有玩家記錄優於建立 migration 檔案： - Migration 適合 schema 變更，不適合純資料更新 - 一次性資料修正使用 SQL 較快，避免過度工程化
Hardcode 值三分法¶
系統性掃描 hardcode 值後，必須區分：
1. (a) 錯誤 fallback：與常數表衝突 → 需修正對齊
2. (b) 有設計依據的保護上限：設計文件明確規定 → 需加文件引用，合理 hardcode
3. © 待企劃確認的 TODO：key 未定義 → 改為 // TODO: 待企劃定義對應常數表 key
錯誤 key 比沒有 key 更危險¶
若在 code 中寫了不存在的常數 key 作為註解（如 ExciteTarget=1000 // key: 99960000027），會給人「已接入常數表」的假象，實際上 key 根本不存在。應移除並改為 TODO。
經驗教訓¶
-
new_player_defaults 的每個欄位都需要有對應常數表來源，禁止與常數表衝突的 hardcode 值
-
靜默錯誤比顯性錯誤更危險，發現數值異常時優先追查初始化 fallback 路徑
-
只改 fallback 設定值不需要 rebuild，重啟即可；改 code 邏輯才需要重新 build
-
錯誤的常數 key 註解比沒有註解更危險，應改為明確的 TODO
常見陷阱¶
-
hardcode 值與常數表不一致不會報錯，屬於靜默錯誤，難以發現
-
為一次性資料修正建立 migration 檔案屬於過度工程化
-
在 code 中填寫未經企劃確認的常數 key，製造「已接入」的假象
最佳實踐¶
-
定期 grep codebase 中的數字 literal，確認初始化相關的 hardcode 值都有對應常數表設定
-
一次性資料修正直接下 SQL，不建立 migration 檔
-
未定義的常數 key 一律改為
// TODO: 待企劃定義對應常數表 key
相關概念¶
- gamedata-flag-boolean----dangling---
- MatchRPG Unlimited Constants DB Cap Strategy
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-02 | 45b7e5f8-50d6-4529-afa9-e872dd553db2 | 揭示 new_player_defaults fallback 與常數表不一致會產生靜默錯誤（數值錯但不報錯），並建立系統性分類框架 |