注释计划

目标目录：E:\AI\zcode\object\ke-she\refactored\src\com\genshin\rpg\ 性质：纯注释增强，禁止改动任何代码逻辑、数值、UI、import、方法签名。 目的：让初学者从任意一个按钮出发，顺着注释就能一路看懂”点下去之后，程序到底怎么运转”。

---

0. 背景与现状

上一轮重构已经把项目分包、拆类、加了方法级 Javadoc。但按钮→运转的可读性还不够：

• 按钮上方的注释只写了”这一行在干嘛”，没写”它会跳到哪些方法、数据流向哪里”。
• 方法级 Javadoc 写了”作用/输入/输出”，但没写”我是被谁调用的”，读者跳进去之后不知道自己从哪来。
• 跨文件调用（Panel → MainFrame → CombatSystem/StorageManager）缺少”路标”。

本计划要做的事：给每个按钮加一张 ASCII 调用链路图，给每个被按钮（间接）调用的方法加一行【被谁调用】标记。

---

1. 唯一原则

只加注释，不改代码。

• 不许改任何一行可执行代码（包括空格、换行位置）。
• 不许改 import、package、方法签名、字段。
• 不许”顺手优化”或重命名。
• 注释一律用中文，编码 UTF-8。
• 改完必须能 javac -encoding UTF-8 零 error 编译通过。

---

2. 注释模板规范

模板 A：按钮上方的【调用链路图】（用在每个 addActionListener 之上）

格式固定为带框线的块，箭头 → 表示调用顺序，括号内注明所在类：

// ╔═══════ 按钮：<按钮中文名> ═══════╗
// 链路：
//   本按钮(<当前类>)
//     → <方法名>(<类>)           // 一句话说明这一步做什么
//     → <方法名>(<类>)           // 一句话
//     → ...直到副作用落地（写库/扣血/切页/弹窗）
// 一句话总览：<点下去最终发生了什么>
// ╚══════════════════════════════════╝
btnXxx.addActionListener(e -> ...);

要求：

• 链路图必须完整到副作用落地为止（写库/改血量/切页/弹提示框），不能停在中间方法。
• 跨类调用要标明类名，例如 → playerAction(CombatSystem)。
• 每行用 // 一句话 说明该步在做什么，让读者不用跳进去也大致明白。
• 若按钮逻辑极简（如直接 parent.showPanel("menu")），链路图可缩为两三行，但必须有框线头尾。

模板 B：方法顶部的【被谁调用】标记（加在已有 Javadoc 之后、方法体之前）

凡是被按钮直接或间接调用的方法，在 Javadoc */ 之后、方法签名之前，插入一行：

     */
    // 【被谁调用】来自 <调用方类>.<调用方方法>（按钮：<按钮名>）；本方法还会调用：<下游方法(类)>, ...
    public/private ... methodName(...) {

若一个方法被多处调用，用顿号或”或”列全；若无任何调用方（入口/回调），写 // 【被谁调用】入口方法 / 由 Swing 回调触发。

模板 C：单行就地补充（可选，少用）

在方法体内某个关键步骤上方，若该步骤是链路图里点名的”落地动作”（如真正扣血、真正写库、真正切页），加一行 // ▶ 落地：...。每条链路最多标 1~2 个落地点，避免泛滥。

---

3. 全量按钮链路清单（执行 AI 必须照此画图）

下面列出全部 8 个界面的每个按钮，及其真实调用链。执行 AI 把”链路图原文”照抄进按钮上方注释即可（括号内的类名要准确）。

约定：MF=MainFrame，CS=CombatSystem，SM=StorageManager，Inv=Inventory，SS=SkillSystem。

3.1 LoginPanel（登录/注册/管理员）

• 单选按钮 rbtnUserLogin / rbtnUserRegister / rbtnAdminLogin
  • 链路：本按钮(LoginPanel) → updateUIForMode(LoginPanel) → 切换用户名输入框可见性 + 改提交按钮文字颜色
  • 一句话：切换登录模式（玩家登录/注册/管理员），刷新输入区样式。
• btnSubmit 提交
  • 玩家登录分支链路： 本按钮 → handleSubmit(LoginPanel) → SM.loginUser(SM, 读库 users 表) → MF.loginAsUser(MF) → SM.loadUserProgress(SM, 读 user_characters/user_items) → MF.showPanel("menu")(MF, 会触发自动存档) → MainMenuPanel.refresh 一句话：核对账号密码→加载该玩家存档→进入主菜单。
  • 玩家注册分支链路： 本按钮 → handleSubmit(LoginPanel) → SM.registerUser(SM, 写 users + 初始化 user_characters/user_items) → 切回登录模式 一句话：新建账号并为其生成默认角色与背包。
  • 管理员分支链路： 本按钮 → handleSubmit(LoginPanel) → 比对硬编码密码 "klee is comming" → MF.showPanel("admin")(MF) → AdminPanel 一句话：密码正确则进入管理员后台。

3.2 MainMenuPanel（主菜单）

• btnChallenge 开启挑战
  • 本按钮 → MF.showPanel("menu") 的兄弟卡 "level"(MF, 切页时自动存档) → LevelPanel.refresh
  • 一句话：跳转到关卡选择页。
• btnTeam 调整出战阵容
  • 本按钮 → MF.showPanel("team")(MF, 自动存档) → TeamPanel.refresh
• btnUpgrade 角色面板与升级
  • 本按钮 → MF.showPanel("upgrade")(MF, 自动存档) → UpgradePanel.refresh
• btnBag 整理食物补给背包
  • 本按钮 → MF.showPanel("bag")(MF, 自动存档) → BagPanel.refresh
• btnExit 注销并返回登录
  • 本按钮 → MF.logout(MF) → SM.saveUserProgress(SM, 写库存档) → MF.initGameData(MF, 重置内存数据) → MF.showPanel("login")(MF) → LoginPanel
  • 一句话：保存当前进度→清空内存角色数据→回登录页。

3.3 LevelPanel（关卡选择）

• btn(第N关) N=1..5
  • 本按钮 → startChallenge(LevelPanel, lvlId) → MF.startLevelChallenge(MF, 记录 currentLevelId/波次=1) → MF.startWave(MF) → SM.loadEnemies(SM, 读 enemies 表) → 按 currentLevelId 取模板生成怪物 → new CombatSystem().startBattle(CS, 初始化法师/王护盾) → BattlePanel.initBattle(BattlePanel) → MF.showPanel("battle")(MF, 自动存档)
  • 一句话：选定关卡→按配置生怪→进入战斗界面。
• btnBack 返回主菜单
  • 本按钮 → MF.showPanel("menu")(MF, 自动存档)

3.4 TeamPanel（编队）

• btnApply 确认更换队伍
  • 本按钮 → applyTeamChanges(TeamPanel) → 校验 1~4 人 → 写入 MF.activeTeam → MF.showPanel("menu")(MF, 自动存档)
  • 一句话：把勾选的角色设为出战队伍，回主菜单。
• btnBack 返回主菜单
  • 本按钮 → MF.showPanel("menu")(MF, 自动存档)

3.5 UpgradePanel（养成）

• btnUseBook 使用经验书
  • 本按钮 → useExpBook(UpgradePanel) → Inv.useItem(4, 目标角色, Inv, 扣 1 本书 + 目标.addExp(5000) + 可能升级) → SM.saveUserProgress(SM, 写 user_characters/user_items) → 本面板 refresh+updateDetails
  • 一句话：消耗 1 本经验书给选中角色加 5000 经验，可能升级，并立即存档。
• btnBuyBook 购买经验书
  • 本按钮 → buyExpBook(UpgradePanel) → 校验金币≥200 → 全队 gold-=200(共享金币) → 经验书 count+1 → SM.saveUserProgress(SM) → updateDetails
  • 一句话：花 200 共享金币买 1 本经验书，立即存档。
• btnBack 返回主菜单
  • 本按钮 → MF.showPanel("menu")(MF, 自动存档)

3.6 BagPanel（背包）

• btnUse 使用食物
  • 本按钮 → useItem(BagPanel) → Inv.useItem(itemId, 目标角色, 队伍, inBattle=false)(Inv, 按物品类型回血/复活/加buff) → SM.saveUserProgress(SM) → refresh
  • 一句话：对选中角色使用选中食物（鸡回血/蛋复活/仙跳墙全队buff），立即存档。
• btnBack 返回主菜单
  • 本按钮 → MF.showPanel("menu")(MF, 自动存档)

3.7 AdminPanel（管理员后台）

• btnRefresh 刷新列表
  • 本按钮 → refreshUserList(AdminPanel) → SM.getAllUsers(SM, 读 users 表) → 填左表 → clearRightPanel
• btnAddUser 添加新玩家
  • 本按钮 → triggerAddUserDialog(AdminPanel, 弹 JDialog) → 点对话框"确认添加" → SM.addUser(SM, 写 users + 初始化角色/物品) → refreshUserList
• btnDeleteUser 删除账号
  • 本按钮 → triggerDeleteUser(AdminPanel) → 二次确认 → SM.deleteUser(SM, 级联删 user_characters/user_items) → refreshUserList
• btnSave 保存玩家数据修改
  • 本按钮 → triggerSaveChanges(AdminPanel) → SM.updateUser(SM, 写 users) → 逐行 SM.updateUserCharacter(SM, 写 user_characters) → 逐行 SM.updateUserItem(SM, 写 user_items) → refreshUserList
• btnLogout 退出管理员后台
  • 本按钮 → (内联) 清空选中 → MF.showPanel("login")(MF) → LoginPanel
• （AdminPanel 左表行选中 ListSelectionListener）
  • 本表格选中行 → loadSelectedUserData(AdminPanel) → 读行 id → SM.getUserCharacters(SM) + SM.getUserItems(SM) → 填右侧角色/物品子表
• （对话框内 btnConfirm 确认添加）见 btnAddUser 链路尾部。

3.8 BattlePanel（战斗，最复杂）

• btnNormalAttack 普通攻击 A
  • 链路： 本按钮(BattlePanel) → handleAttackAction(0)(BattlePanel) → CS.playerAction(0, 目标)(CS) → CS.executeTurn(攻击者, 目标, 普攻技能)(CS) → 普攻技能.execute(Skill子类, 附元素+返回倍率) → CS.triggerReaction(CS, 判定元素反应) → CS.calculateFinalDamage(CS, 算暴击/防御/抗性/反应加成) → ▶落地：Enemy.takeDamageWithLog(Enemy, 扣怪血+写日志) → 随后敌方回合：Enemy.takeTurn(Enemy, 怪还手) → 各单位 updateStates(状态回合-1) → 返回 BattlePanel → refreshGUI(BattlePanel, 刷新画面) → checkBattleEnd(BattlePanel) → 若胜负已定 → MF.handleBattleEnd(MF, 发奖励/回血/切页)
  • 一句话：选目标→算伤害扣怪血→触发可能的元素反应→所有怪轮流还手→刷新画面→判胜负。
• btnElementalSkill 技能 E
  • 同上，唯一区别：handleAttackAction(1) → 战技技能.execute（会进 CD、刻晴附雷魔）。
• btnElementalBurst 大招 Q
  • 同上，区别：handleAttackAction(2) → 大招技能.execute（清空能量、迪卢克附火/纳西妲加精通/琴回血）。
• btnSwap 切换角色
  • 本按钮(BattlePanel) → handleSwapAction(BattlePanel, 弹 JPopupMenu) → 点某角色菜单项 → 改 CS.activePlayerIndex → CS.addLog(写切人日志) → CS.playerAction(-1, null)(CS, 不攻击但耗一回合+触发敌方回合) → refreshGUI → checkBattleEnd
  • 一句话：弹出后台角色菜单，选中后换人并消耗一回合（怪会还手）。
• btnUseItem 使用食物（战斗内）
  • 本按钮(BattlePanel) → handleUseItemAction(BattlePanel, 弹食物菜单) → 若单体食物(鸡/蛋) → showTargetCharacterMenuForFood(BattlePanel, 再弹角色菜单) → Inv.useItem(..., inBattle=true)(Inv) → CS.addLog(写使用日志) → SM.saveUserProgress(SM) → CS.playerAction(-1, null)(耗回合) → refreshGUI → checkBattleEnd
  • 若群体食物(仙跳墙)：直接 Inv.useItem → CS.addLog → SM.saveUserProgress → playerAction(-1) → refreshGUI → checkBattleEnd
  • 一句话：战斗中吃食物（回血/复活/加buff），耗一回合，立即存档，刷新判胜负。

---

4. 跨层”枢纽方法”必须加【被谁调用】（执行 AI 重点处理）

这些方法是被多个按钮共用、读者最容易迷路的”枢纽”，必须补【被谁调用】+【下游】：

MainFrame（app/MainFrame.java）

• showPanel(String) ——【被谁调用】几乎所有 Panel 的按钮/返回；本方法先 SM.saveUserProgress(自动存档)，再调目标 Panel 的 refresh()，再 cardLayout.show。
• loginAsUser(User) ——【被谁调用】LoginPanel.handleSubmit(玩家登录按钮)；调 SM.loadUserProgress 后 showPanel("menu")。
• logout() ——【被谁调用】MainMenuPanel.btnExit；先存档再 initGameData 重置，再 showPanel("login")。
• startLevelChallenge(int) ——【被谁调用】LevelPanel.startChallenge(关卡按钮)；设关卡 id/波次后调 startWave。
• startWave() ——【被谁调用】MainFrame.startLevelChallenge 与 handleBattleEnd(下一波)；SM.loadEnemies 生怪→new CombatSystem().startBattle→BattlePanel.initBattle→showPanel("battle")。
• createScaledEnemy(Stats) ——【被谁调用】startWave（按世界等级缩放怪物三围）。
• handleBattleEnd(boolean) ——【被谁调用】BattlePanel.checkBattleEnd；发奖励/回血/判断下一波/世界等级提升/切回主菜单。
• initGameData() ——【被谁调用】构造函数 与 logout；SM.initTables+loadCharacters+SkillSystem.loadSkillsForCharacter+默认编队+inventory.initInventory。

CombatSystem（service/CombatSystem.java）

• startBattle(...) ——【被谁调用】MainFrame.startWave；初始化队伍/敌人/护盾。
• playerAction(int, Enemy) ——【被谁调用】BattlePanel.handleAttackAction(攻/技/大招按钮)、handleSwapAction(切人)、handleUseItemAction/handle内联(用食物)；是”我方一回合”总入口，内部：executeTurn→敌方 takeTurn→updateStates。
• executeTurn(...) ——【被谁调用】playerAction；执行单次技能：技能.execute→triggerReaction→calculateFinalDamage→takeDamageWithLog→反应后续效果。
• triggerReaction(...) ——【被谁调用】executeTurn；判定元素反应类型并算增幅/固伤加成。
• calculateFinalDamage(...) ——【被谁调用】executeTurn；算最终伤害（暴击/防御/抗性/反应）。
• applyTransformativeReaction(...) ——【被谁调用】executeTurn(超载/超导/感电/扩散/碎冰/燃烧/烈绽放/超绽放)；剧变反应伤害。
• isTeamDefeated() / isAllEnemiesDefeated() ——【被谁调用】BattlePanel.checkBattleEnd。
• saveLogToFile() ——【被谁调用】MainFrame.handleBattleEnd；导出 txt 战报 + SM.saveBattleLog。

各 Panel 的私有 handler（务必加【被谁调用】）

LoginPanel.handleSubmit/updateUIForMode；LevelPanel.startChallenge；TeamPanel.applyTeamChanges；UpgradePanel.useExpBook/buyExpBook/updateDetails/onCharacterSelected；BagPanel.useItem/updateDetails/onItemSelected；AdminPanel.refreshUserList/triggerAddUserDialog/triggerDeleteUser/triggerSaveChanges/loadSelectedUserData/clearRightPanel；BattlePanel.handleAttackAction/handleSwapAction/handleUseItemAction/showTargetCharacterMenuForFood/checkBattleEnd/refreshGUI/initBattle。

StorageManager 关键 API（dao/StorageManager.java，每个都加【被谁调用】）

• initTables ← MainFrame.initGameData
• loadCharacters/loadEnemies/loadSkills ← MainFrame.initGameData / startWave / SkillSystem.loadSkillsForCharacter
• loginUser/registerUser ← LoginPanel.handleSubmit
• loadUserProgress ← MainFrame.loginAsUser
• saveUserProgress ← MainFrame.showPanel(自动存档)/logout；UpgradePanel/BagPanel/BattlePanel 用物后
• getAllUsers/addUser/updateUser/deleteUser ← AdminPanel 各按钮
• getUserCharacters/updateUserCharacter/getUserItems/updateUserItem ← AdminPanel.loadSelectedUserData/triggerSaveChanges
• saveBattleLog ← CombatSystem.saveLogToFile

Inventory.useItem（model/Inventory.java）

• 【被谁调用】UpgradePanel.useExpBook(itemId=4)；BagPanel.useItem(id=1/2/3)；BattlePanel 战斗用食物(id=1/2/3)。

Skill 各子类 execute（service/skill/*.java）

• 【被谁调用】CombatSystem.executeTurn；返回技能倍率并附元素/附魔。

---

5. 工作量与做法

1. 按界面顺序处理：Login → MainMenu → Level → Team → Upgrade → Bag → Admin → Battle。
2. 每个界面：先在每个按钮的 addActionListener 上方插入【链路图】（模板 A），内容照抄第 3 节对应条目。
3. 再在该界面每个 handler 私有方法顶部加【被谁调用】（模板 B）。
4. 处理 MainFrame、CombatSystem、StorageManager、Inventory、Skill 子类的枢纽方法，补【被谁调用】。
5. 不动任何代码行。只加注释。
6. 全部完成后，清空 bin\，运行 run.bat 重新编译，确认 0 error。

---

6. 完成判据

• 全部 8 个界面的所有按钮上方都有带框线的【调用链路图】，链路终止于副作用落地（写库/扣血/切页/弹窗）。
• 所有被按钮直接或间接调用的方法顶部都有【被谁调用】标记（含跨类）。
• 第 4 节列出的全部枢纽方法都已标注。
• 代码逻辑零改动（可用 diff 对照确认：除注释行外无任何差异）。
• javac -encoding UTF-8 重新编译 0 error。
• 写一份 CHAIN_NOTE.md：说明本次新增的注释规范（模板 A/B/C）+ 抽查 3 个按钮的完整链路示例。

---

7. 风险提示

• 链路图里的类名/方法名必须与现有代码一字不差（如 handleAttackAction 不能写成 handleAttack）。
• 若某方法被多个按钮调用，【被谁调用】要列全，不要漏。
• 不要把链路图画得太长导致换行错乱；每行控制在 80 字符内，超长可折行用 // → ... 续行。
• UTF-8 编码务必保持，中文/emoji 不能乱码。

---

（计划书完。配合同目录《链路注释执行提示词.md》使用。）