注释计划

This plan outlines the pure comment enhancement for the refactored Genshin RPG project. We will add visual call chain diagrams above action listeners (Template A) and caller tracking tags above pivot methods (Template B) to help beginners trace the program execution flow from any button.

User Review Required

[!IMPORTANT]

• Zero Logic Change: We will not modify any executable code, imports, package declarations, method signatures, variables, or whitespace structures. Only comment additions will be performed.
• Coding Standard: All comments will be in Chinese (UTF-8).
• Verify Compile: We will verify that the project compiles with no errors (0 error) by running run.bat after clean.

Proposed Changes

We will modify the target Java source files to insert annotations without affecting code functionality.

---

UI Panels (view package)

We will add Template A comments above button listeners and Template B comments above helper handler methods.

[MODIFY] LoginPanel.java

• Add Template A for:
  • rbtnUserLogin/rbtnUserRegister/rbtnAdminLogin
  • btnSubmit (covering 3 branches: Player Login, Player Register, Admin Login)
• Add Template B for:
  • updateUIForMode
  • handleSubmit

[MODIFY] MainMenuPanel.java

• Add Template A for:
  • btnChallenge
  • btnTeam
  • btnUpgrade
  • btnBag
  • btnExit

[MODIFY] LevelPanel.java

• Add Template A for:
  • Level Buttons (1 to 5)
  • btnBack
• Add Template B for:
  • startChallenge

[MODIFY] TeamPanel.java

• Add Template A for:
  • btnApply
  • btnBack
• Add Template B for:
  • applyTeamChanges

[MODIFY] UpgradePanel.java

• Add Template A for:
  • btnUseBook
  • btnBuyBook
  • btnBack
• Add Template B for:
  • useExpBook
  • buyExpBook
  • updateDetails
  • onCharacterSelected

[MODIFY] BagPanel.java

• Add Template A for:
  • btnUse
  • btnBack
• Add Template B for:
  • useItem
  • updateDetails
  • onItemSelected

[MODIFY] AdminPanel.java

• Add Template A for:
  • btnRefresh
  • btnAddUser
  • btnDeleteUser
  • btnSave
  • btnLogout
  • tblUsers Selection Listener (ListSelectionListener)
  • btnConfirm (inside JDialog)
• Add Template B for:
  • refreshUserList
  • triggerAddUserDialog
  • triggerDeleteUser
  • triggerSaveChanges
  • loadSelectedUserData
  • clearRightPanel

[MODIFY] BattlePanel.java

• Add Template A for:
  • btnNormalAttack (A)
  • btnElementalSkill (E)
  • btnElementalBurst (Q)
  • btnSwap
  • btnUseItem
• Add Template B for:
  • handleAttackAction
  • handleSwapAction
  • handleUseItemAction
  • showTargetCharacterMenuForFood
  • checkBattleEnd
  • refreshGUI
  • initBattle

---

Core Pivot Files (app, service, dao, model)

We will add Template B comments above the pivot/core methods to trace their callers and downstream calls.

[MODIFY] MainFrame.java

• Add Template B for:
  • showPanel
  • loginAsUser
  • logout
  • startLevelChallenge
  • startWave
  • createScaledEnemy
  • handleBattleEnd
  • initGameData

[MODIFY] CombatSystem.java

• Add Template B for:
  • startBattle
  • playerAction
  • executeTurn
  • triggerReaction
  • calculateFinalDamage
  • applyTransformativeReaction
  • isTeamDefeated
  • isAllEnemiesDefeated
  • saveLogToFile

[MODIFY] StorageManager.java

• Add Template B for:
  • initTables
  • loadCharacters
  • loadEnemies
  • loadSkills
  • loginUser
  • registerUser
  • loadUserProgress
  • saveUserProgress
  • getAllUsers
  • addUser
  • updateUser
  • deleteUser
  • getUserCharacters
  • updateUserCharacter
  • getUserItems
  • updateUserItem
  • saveBattleLog

[MODIFY] Inventory.java

• Add Template B for:
  • useItem

[MODIFY] NormalAttack.java

• Add Template B for execute

[MODIFY] ElementalSkill.java

• Add Template B for execute

[MODIFY] ElementalBurst.java

• Add Template B for execute

[MODIFY] Skill.java

• Add Template B for execute (as an abstract method)

---

Verification Plan

We will perform automated and manual verification to ensure code stability and correct execution.

Automated Tests

1. Compilation: Clean the existing compilation output directory, compile all source files using run.bat (which internally does javac -encoding UTF-8 -d bin @sources.txt), and verify it finishes with exit code 0.
2. Git Diff: Perform dry-runs/git diff (via standard diff tools or custom verification scripts) to verify that only lines starting with // (comments) or * (javadoc updates) have been modified.

Manual Verification

1. Run run.bat to launch the game interface.
2. Confirm the Login Dialog operates properly by logging in and navigating to the main menu.
3. Confirm that no class behaviors or UI functions were altered by the comment additions.