跳转到内容
课设作品集与展示

注释提示词

使用说明（给人看）：把下面【正文】整段复制粘贴给另一个 AI。 该 AI 会就地修改 E:\AI\zcode\object\ke-she\refactored\src\ 下的源文件（只加注释，不改代码）。 执行 AI 需要：能读写本地文件、能跑 javac。同目录《链路注释计划书.md》是详细版，应一并读取。

正文（以下整段复制 ↓↓↓）

Section titled “正文（以下整段复制 ↓↓↓）”

你是一名 Java 工程师，现在要给一个已经重构好的学生课设项目做纯注释增强，让初学者从任意按钮出发，顺着注释就能一路看懂程序怎么运转。

工作目录与必读

Section titled “工作目录与必读”
  • 目标源码根：E:\AI\zcode\object\ke-she\refactored\src\com\genshin\rpg\
  • 必读：先用工具读取该目录下全部 .java 文件，以及同目录上级的《链路注释计划书.md》（含完整按钮链路清单与模板）。
  • 项目包结构：com.genshin.rpg.{app, view, view.ui, model, model.enums, service, service.skill, dao}。

铁律（违反即失败）

Section titled “铁律（违反即失败）”
  1. 只加注释，不改任何代码。不许动可执行代码行、import、package、方法签名、字段、空格、数值、UI、文案。改动前后用 diff 自查：除注释行外必须零差异。
  2. 注释一律中文、UTF-8，不能出现乱码。
  3. 不许顺手优化、重命名、合并方法。
  4. 全程不动 E:\C\cDownKeShe\（那是原版，只读参考）。

任务

Section titled “任务”

给项目补两类注释，让”按钮→运转”可读：

模板 A：每个按钮 addActionListener 上方，加一张带框线的调用链路图。 格式：

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

要求：链路必须画到副作用落地为止；跨类调用要标类名（缩写：MainFrame=MF, CombatSystem=CS, StorageManager=SM, Inventory=Inv, SkillSystem=SS）；每行 ≤80 字符，超长折行续写。

模板 B：被按钮直接或间接调用的方法，在 Javadoc */ 之后、方法签名之前，加一行【被谁调用】。 格式：

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

被多处调用要列全；入口/Swing 回调写 // 【被谁调用】入口方法 / 由 Swing 回调触发。

（可选、少用）模板 C：方法体内关键落地动作上加 // ▶ 落地：...，每条链路最多 1~2 处。

全量按钮链路（照此画图，类名/方法名必须与代码一字不差）

Section titled “全量按钮链路（照此画图，类名/方法名必须与代码一字不差）”

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

LoginPanel

  • 单选 rbtnUserLogin/Register/AdminLogin：本按钮(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。总览：核对账号密码→加载存档→进主菜单。
  • btnSubmit 玩家注册：本按钮 → handleSubmit(LoginPanel) → SM.registerUser(SM,写 users+初始化角色/物品) → 切回登录模式。总览：建号并生成默认角色与背包。
  • btnSubmit 管理员：本按钮 → handleSubmit(LoginPanel) → 比对硬编码密码 "klee is comming" → MF.showPanel("admin")(MF)。总览：密码对则进后台。

MainMenuPanel

  • btnChallenge：本按钮 → MF.showPanel("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)。总览：存档→清内存→回登录。

LevelPanel

  • 第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 → MF.showPanel("battle")(MF)。总览：选关卡→生怪→进战斗。
  • btnBack：本按钮 → MF.showPanel("menu")(MF,自动存档)。

TeamPanel

  • btnApply：本按钮 → applyTeamChanges(TeamPanel) → 校验 1~4 人 → 写 MF.activeTeam → MF.showPanel("menu")(MF)。
  • btnBack：本按钮 → MF.showPanel("menu")(MF)。

UpgradePanel

  • btnUseBook：本按钮 → useExpBook(UpgradePanel) → Inv.useItem(4,目标,Inv,扣1本+目标.addExp(5000)+可能升级) → SM.saveUserProgress(SM) → refresh+updateDetails。
  • btnBuyBook：本按钮 → buyExpBook(UpgradePanel) → 校验金币≥200 → 全队 gold-=200 → 经验书 count+1 → SM.saveUserProgress(SM) → updateDetails。
  • btnBack：本按钮 → MF.showPanel("menu")(MF)。

BagPanel

  • btnUse：本按钮 → useItem(BagPanel) → Inv.useItem(itemId,目标,队伍,inBattle=false)(Inv,回血/复活/加buff) → SM.saveUserProgress(SM) → refresh。
  • btnBack：本按钮 → MF.showPanel("menu")(MF)。

AdminPanel

  • btnRefresh：本按钮 → refreshUserList(AdminPanel) → SM.getAllUsers(SM) → 填左表 → clearRightPanel。
  • btnAddUser：本按钮 → triggerAddUserDialog(AdminPanel,弹JDialog) → 对话框"确认添加" → SM.addUser(SM,写 users+初始化角色/物品) → refreshUserList。
  • btnDeleteUser：本按钮 → triggerDeleteUser(AdminPanel) → 二次确认 → SM.deleteUser(SM,级联删) → refreshUserList。
  • btnSave：本按钮 → triggerSaveChanges(AdminPanel) → SM.updateUser(SM) → 逐行 SM.updateUserCharacter(SM) → 逐行 SM.updateUserItem(SM) → refreshUserList。
  • btnLogout：本按钮 → (内联)清空选中 → MF.showPanel("login")(MF)。
  • 左表行选中(ListSelectionListener)：本表格选中行 → loadSelectedUserData(AdminPanel) → 读行id → SM.getUserCharacters(SM)+SM.getUserItems(SM) → 填右侧子表。
  • 对话框 btnConfirm：见 btnAddUser 链路尾部。

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 → 回 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。

必须加【被谁调用】的枢纽方法（列全调用方）

Section titled “必须加【被谁调用】的枢纽方法（列全调用方）”
  • app/MainFrame.java：showPanel（几乎所有Panel按钮；先 SM.saveUserProgress 自动存档→目标 Panel.refresh→cardLayout.show）、loginAsUser（LoginPanel.handleSubmit）、logout（MainMenuPanel.btnExit）、startLevelChallenge（LevelPanel.startChallenge）、startWave（startLevelChallenge 与 handleBattleEnd 下一波）、createScaledEnemy（startWave）、handleBattleEnd（BattlePanel.checkBattleEnd）、initGameData（构造函数与 logout）。
  • service/CombatSystem.java：startBattle（MainFrame.startWave）、playerAction（BattlePanel.handleAttackAction/handleSwapAction/handleUseItemAction 及其内联）、executeTurn（playerAction）、triggerReaction（executeTurn）、calculateFinalDamage（executeTurn）、applyTransformativeReaction（executeTurn）、isTeamDefeated/isAllEnemiesDefeated（BattlePanel.checkBattleEnd）、saveLogToFile（MainFrame.handleBattleEnd）。
  • 各 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。
  • dao/StorageManager.java：initTables←MainFrame.initGameData；loadCharacters/loadEnemies/loadSkills←MainFrame.initGameData/startWave/SkillSystem；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。
  • model/Inventory.java：useItem←UpgradePanel.useExpBook(id=4)/BagPanel.useItem(id=1/2/3)/BattlePanel 战斗用食物。
  • service/skill/*.java：各 execute←CombatSystem.executeTurn（返回倍率+附元素/附魔）。

工作顺序

Section titled “工作顺序”

Login → MainMenu → Level → Team → Upgrade → Bag → Admin → Battle；再做 MainFrame/CombatSystem/StorageManager/Inventory/Skill 子类的枢纽方法【被谁调用】。

完成判据

Section titled “完成判据”
  • 8 个界面所有按钮上方都有带框线链路图，终止于副作用落地。
  • 上述全部枢纽方法及各 handler 顶部都有【被谁调用】（被多处要列全）。
  • diff 自查：除注释行外代码零改动。
  • 清空 bin\，运行 run.bat 重新编译，0 error（贴编译输出）。
  • 写 refactored\CHAIN_NOTE.md：说明模板 A/B/C + 抽查 3 个按钮（如战斗普攻、登录提交、保存玩家修改）的完整链路示例。

交付

Section titled “交付”

就地修改 refactored\src\ 下源文件 + 新增 refactored\CHAIN_NOTE.md + 贴编译输出。

开始执行。先读全部源文件与《链路注释计划书.md》，再动手。

正文（以上整段复制 ↑↑↑）

Section titled “正文（以上整段复制 ↑↑↑）”