《原神》文字战斗模拟系统 —— 重构计划（供 AI 执行阅读）

本文档面向执行 AI。语言：简明中文 + 结构化清单。目标：只改结构，不改功能/数值/UI。源项目根目录：E:\C\cDownKeShe（默认包，javac src/*.java 编译，java -cp bin;mysql-connector-j-8.0.33.jar Main 运行）。重构产出目录：E:\AI\zcode\object\ke-she（你正在此目录工作）。

0. 一句话目标

把”23 个平铺在 src/ 的 .java 文件、默认包、单文件多类、800 行大文件”重组成按 Java 规范分包 + 单文件单类 + 每个按钮事件就地写清”调用什么/做什么” + 每个方法补注释的版本，保证逐字节等价的功能与数值，让初学者能顺着读。

1. 不可变更的”红线”（违反即失败）

重构禁止改动以下内容（否则功能/表现会变）：

包结构是否可用默认包：原项目是默认包（无 package 声明）。重构后改为显式分包 com.genshin.xxx，需要同步修改 run.bat 与 .iml，并验证能编译运行（详见第 8 节）。
ElementType 枚举顺序：DB 用 ElementType.values()[element列] 还原，顺序必须保持 ANEMO, GEO, HYDRO, PYRO, CRYO, ELECTRO, DENDRO, PHYSICAL（索引 0..7）。一个都不能换。
ReactionType 枚举常量名与顺序。
所有数值公式：calcDefMultiplier、calcResMultiplier、getLevelBaseDmg、calcEmBonus、世界等级缩放（(worldLevel-1)*0.6/0.4/0.3）、奖励金币 50*wl*85、经验 100*wl*85、奖励掉落（鸡×2 蛋×1 书×2）、战斗失败回血 HP/能量 → 50%、仙跳墙 ATK+20% 暴击+12% 3回合、经验书 +5000EXP、买书 -200金币、升级 HP/ATK/DEF 增量 50*i / 5*i / 2.5*i、深渊法师/岩盔王护盾数值与减伤比例、狂暴激怒 HP<30% ATK*1.5、超导 -40%物抗 8回合、护盾吸收倍率 2.5/1.0 等。所有数字、系数、阈值原样搬运。
技能特例判定（靠角色 id 硬编码）：
- id==1 可莉 / id==3 莫娜 / id==6 甘雨 / id==8 纳西妲 → 普攻带元素
- id==7 刻晴 E 技能给雷附魔 2 回合
- id==5 迪卢克 大招给火附魔 3 回合
- id==8 纳西妲 大招 +250 精通 3 回合
- id==4 琴 且 skill.id==12 大招按 ATK*1.2+3000 全队回血
- 怪物 specialType 1..6 的 AI 行为（见 Enemy.takeTurn）
关卡-怪物配置（MainFrame.startWave）：1~5 关、第 2/3/4 关分波次、深渊法师按出现顺序命名为火/水/冰法师，第 5 关 3 个法师。配置顺序与索引不动。
管理员后台密码："klee is comming"（提示语 klee is c...）。
MySQL 自动启动路径：E:\SQL\mysql\bin\mysqld.exe、E:\SQL\mysql\my.ini、工作目录 E:\SQL、Thread.sleep(4000)、密码候选 ["", "root", "123456"]、连接串 jdbc:mysql://localhost:3306/...、库名 genshin_rpg、表结构与 seed 数据。离线 fallback 的静态数据也要原样保留。
UI 视觉：所有颜色（如 new Color(30,30,30) 暗底、255,190,40 金、47,85,151 蓝）、字体（Microsoft YaHei）、尺寸、布局、中文文案、JOptionPane 提示框文字。一字不改。
行为流程：登录自动保存、切页 showPanel 自动 saveUserProgress 并 refresh、战斗内 useItem 同步进度、注销时 initGameData() 重置、战报存文件 battle_log_level_X_<时间戳>.txt 等。
存档键约束：user_characters/user_items 的 PK 与外键、ON DUPLICATE KEY UPDATE 写法。

⚠️ 任何”顺手优化”（如把 for 改 stream、把魔法数字提成常量、改 buff 叠加逻辑、合并重复 switch）一律不做。本任务只搬不改。

2. 现状（重构前）

E:\C\cDownKeShe\
├─ src\               ← 23 个 .java，全部默认包，平铺
│   ├─ Main.java                      程序入口
│   ├─ MainFrame.java                 ★ 主窗口 + 游戏全局状态 + 关卡/战斗流程（313 行，过载）
│   ├─ LoginPanel.java                登录/注册/管理员入口
│   ├─ MainMenuPanel.java             主菜单
│   ├─ LevelPanel.java                关卡选择
│   ├─ BattlePanel.java               战斗界面（599 行，含大量 HTML 渲染 + 按钮事件）
│   ├─ TeamPanel.java                 编队
│   ├─ UpgradePanel.java              养成/买书/用书
│   ├─ BagPanel.java                  背包/食物
│   ├─ AdminPanel.java                管理员 CRUD（411 行）
│   ├─ Stats.java                     数值容器
│   ├─ Character.java                 抽象基类（文件顶部还塞了 class ElementAttach）
│   ├─ Player.java / Enemy.java       extends Character
│   ├─ Item.java / User.java / SkillData.java   小数据类
│   ├─ Inventory.java                 背包逻辑（useItem 大 switch）
│   ├─ Skill.java                     ★ 一个文件里 5 个类：Skill抽象 + NormalAttack/ElementalSkill/ElementalBurst + SkillSystem
│   ├─ CombatSystem.java              ★ 战斗核心（705 行）
│   ├─ StorageManager.java            ★ 数据库连接+建表+所有 DAO+CRUD+内嵌 AdminCharData/AdminItemData（877 行）
│   ├─ ElementType.java / ReactionType.java    枚举
├─ bin\               编译产物（重构后需清空重建）
├─ db\genshin_rpg.sql  建库脚本（不动）
├─ mysql-connector-j-8.0.33.jar       驱动（不动）
├─ run.bat                            编译运行脚本（需改包路径）
├─ cDownKeShe.iml                     IDEA 模块（需改）
└─ GENSHIN_SIMULATOR_TUTORIAL.md      教学文档（不动，可选更新）

主要痛点

默认包、23 文件平铺，看不出职责分层。
MainFrame 身兼窗口+全局状态+关卡/战斗编排，难读。
Skill.java 一个文件塞 5 个类；Character.java 顶部塞 ElementAttach。
StorageManager 把连接、建表、seed、登录注册、存档、管理员 CRUD 全揉一起，877 行。
元素中文名/颜色 switch 在 4 个文件里各抄一份（TeamPanel/UpgradePanel/BattlePanel/CombatSystem/Character）。
多数按钮事件分散在 triggerXxx/handleXxx 私有方法里，要跳转才能看懂。

3. 目标架构（重构后）

包结构（顶层包 com.genshin.rpg）：

src\
└─ com\genshin\rpg\
    ├─ Main.java                              【启动】不变逻辑，改 package + 调用
    │
    ├─ app\
    │   ├─ MainFrame.java                     窗口骨架 + 卡片切换 + 登录/注销/关卡/战斗流程编排
    │   └─ GameContext.java                   【新增】游戏运行期全局状态（allCharacters/activeTeam/
    │                                         inventory/worldLevel/currentLevelProgress/loggedInUser/
    │                                         activeBattle/currentLevelId/currentWave）+ getter/setter
    │                                         ★ 把 MainFrame 里的 8 个 public 字段抽到这里，
    │                                           MainFrame 持有一个 context 引用，Panel 通过
    │                                           context 访问数据。Panel 不再依赖 MainFrame 字段。
    │
    ├─ view\
    │   ├─ LoginPanel.java
    │   ├─ MainMenuPanel.java
    │   ├─ LevelPanel.java
    │   ├─ BattlePanel.java
    │   ├─ TeamPanel.java
    │   ├─ UpgradePanel.java
    │   ├─ BagPanel.java
    │   ├─ AdminPanel.java
    │   └─ ui\
    │       └─ ElementStyle.java              【新增】集中元素→中文/颜色映射：
    │                                         getElementChinese(ElementType)、getElementColorHex、
    │                                         getElementColor(java.awt.Color)、getReactionChinese、
    │                                         getHtmlColor。替换原来散落的 5 处重复 switch。
    │                                         ★ 唯一允许的"合并"，因为是纯查表、零行为差异。
    │
    ├─ model\
    │   ├─ Stats.java
    │   ├─ ElementAttach.java                 【拆】从 Character.java 顶部独立出来
    │   ├─ Character.java                     只剩抽象基类
    │   ├─ Player.java
    │   ├─ Enemy.java
    │   ├─ Item.java
    │   ├─ User.java
    │   ├─ SkillData.java
    │   ├─ Inventory.java
    │   └─ enums\
    │       ├─ ElementType.java
    │       └─ ReactionType.java
    │
    ├─ service\
    │   ├─ CombatSystem.java                  战斗核心（逻辑原样搬运，拆几个私有段、补注释）
    │   ├─ SkillSystem.java                   【拆】单例 + 缓存（从 Skill.java 移出）
    │   └─ skill\
    │       ├─ Skill.java                     抽象基类
    │       ├─ NormalAttack.java
    │       ├─ ElementalSkill.java
    │       └─ ElementalBurst.java
    │
    └─ dao\
        ├─ DBConnector.java                   【拆】连接 + 自动启动 MySQL（connectDB/tryConnect）
        ├─ StorageManager.java                单例门面：对外 API 名字/签名**不变**
        │                                     （loadCharacters/loadEnemies/loadSkills/loginUser/
        │                                      registerUser/loadUserProgress/saveUserProgress/
        │                                      getAllUsers/addUser/updateUser/deleteUser/
        │                                      getUserCharacters/updateUserCharacter/getUserItems/
        │                                      updateUserItem/saveBattleLog + 内部 hold 的
        │                                      AdminCharData/AdminItemData 静态内部类保留）
        ├─ TableInitializer.java              【拆】initTables + seed（角色/技能/怪物）
        └─ UserData.java                      【新增】DTO，承载 AdminPanel 的 AdminCharData/
                                              AdminItemData（也可保留为 StorageManager 内部静态类
                                              以减少改动；二选一，推荐独立文件更清晰）

关于 GameContext：这是唯一新增的业务结构（不是新功能），目的是让各 Panel 不再”伸手进 MainFrame 的 public 字段”，职责更清晰。MainFrame 内部把 loginAsUser/logout/showPanel/startLevelChallenge/startWave/createScaledEnemy/handleBattleEnd 这些方法逐行搬到 MainFrame 仍然 OK——只要逻辑等价。若你判断 GameContext 反而增加跳转、不利于”逻辑集中”，可以放弃 GameContext，仍由 MainFrame 持状态（见第 9 节”可选简化”）。推荐采用简化方案，因为用户明确要求”减少不必要的封装和抽象”。

4. 文件→文件搬迁映射表

原文件	→ 目标	说明
`Main.java`	`com/genshin/rpg/Main.java`	加 `package`，`new MainFrame()` 改全限定名/同包
`MainFrame.java`	`app/MainFrame.java`	拆关卡编排可选；推荐保留为单文件，仅补注释
各 `*Panel.java`	`view/*.java`	仅加 package + 引入 ElementStyle，删除本地元素 switch
`Stats.java`	`model/Stats.java`	原样
`Character.java`(+ElementAttach)	`model/Character.java` + `model/ElementAttach.java`	拆分
`Player.java`/`Enemy.java`	`model/`	原样
`Item.java`/`User.java`/`SkillData.java`	`model/`	原样
`Inventory.java`	`model/Inventory.java`	原样
`ElementType.java`/`ReactionType.java`	`model/enums/`	原样
`Skill.java`(5 类)	`service/skill/Skill.java` + `NormalAttack`+`ElementalSkill`+`ElementalBurst` + `service/SkillSystem.java`	拆
`CombatSystem.java`	`service/CombatSystem.java`	原样，补注释
`StorageManager.java`	`dao/StorageManager.java` + `DBConnector.java` + `TableInitializer.java` (+`UserData.java`)	拆

5. 注释规范（每个方法必须补）

每个方法（含构造、私有、匿名内部类方法除外但鼓励）补一段 Javadoc 或行注释，至少包含：

作用：一句话说清做什么。
输入：参数含义（无参写”无”）。
输出/副作用：返回值含义，或”修改了哪些字段/写库/改 UI”。

示例（保持原数值，只加注释）：

/**
 * 计算防御力减伤系数。
 * 作用：根据攻击者与目标等级、目标防御减免/无视，得出 0~1 的乘数。
 * 输入：charLv 攻击者等级；enemyLv 目标等级；defReduction 目标防御减免；
 *       defIgnore 防御无视比例。
 * 输出：防御乘数（数值越小，目标越硬）。
 */
public double calcDefMultiplier(int charLv, int enemyLv, double defReduction, double defIgnore) { ... }

按钮事件就地注释：“点击后：① 调 xxx ② 改 yyy ③ 刷新 UI”，紧贴在 addActionListener 之上。

6. 逐文件改造要点

6.1 Main.java

加 package com.genshin.rpg;，import com.genshin.rpg.app.MainFrame;。
主体逻辑（系统外观、invokeLater）一行不改。

6.2 MainFrame.java（app/）

package + import 调整。
推荐：保留全部状态字段与方法（简化方案，不引 GameContext）。
给 initGameData / showPanel / loginAsUser / logout / startLevelChallenge / startWave / createScaledEnemy / handleBattleEnd 逐个补注释，标明”输入/输出/副作用（是否写库、是否切页）”。
数值（50*worldLevel*85 等）、关卡-怪物索引、奖励掉落 id 映射原样。

6.3 八个 Panel（view/）

每个 Panel 构造里 parent 字段保留（指向 MainFrame），便于就地调用，符合”不要跳转”。
按钮事件集中在本文件内：把原本散在 triggerXxx/handleXxx 的私有方法就近写在事件里或紧邻方法，并加”①②③”注释。不强求把多行逻辑塞进 lambda——可保留独立方法，但要在方法体顶部用注释串起来，让读者一眼看清调用链。
删除 Panel 内重复的元素 switch（getElementChinese/getElementColorHex），统一调 view.ui.ElementStyle。BattlePanel 里的 getElementColor(返回 Color) 同样收口。
AdminPanel 的 AdminCharData/AdminItemData 引用改为 StorageManager.AdminCharData（若拆出 UserData 则改对应类型）——保持名字不变，减少改动面。

6.4 模型层（model/）

ElementAttach 从 Character.java 顶部抽成独立 public 类（原本是包级 class ElementAttach，要改成 public，因为跨包）。
其余原样加 package。

6.5 服务层（service/）

SkillSystem 独立成 public class，原为包级；提供 getInstance/loadSkillsForCharacter/getSkillsForCharacter/resetCooldowns，签名不变。
CombatSystem 原样搬运，补注释。getHTMLColorString/getElementChineseName/getReactionChineseName 可改为调 ElementStyle（行为等价）。

6.6 DAO 层（dao/）

DBConnector：connectDB/tryConnect（含自动启动 MySQL 的全部副作用）原样；暴露 Connection getConnection() 与 boolean isConnected()。
TableInitializer：initTables + 所有 seed INSERT 原样，依赖 DBConnector。
StorageManager：保持单例 + 同名同参 API；内部委托给 DBConnector/TableInitializer；保留静态内部类 AdminCharData/AdminItemData（名字不变）。
- 所有 SQL 字符串、表名、列名、ON DUPLICATE KEY UPDATE、RETURN_GENERATED_KEYS、fallback 静态数据逐行搬运。

7. 交付物清单

src\com\genshin\rpg\** 全部新源文件（按第 3 节结构）。
改好的 run.bat：javac -encoding UTF-8 -d bin $(find src -name '*.java') 或等价 glob；java -cp "bin;mysql-connector-j-8.0.33.jar" com.genshin.rpg.Main。
改好的 cDownKeShe.iml：<sourceFolder> 仍指 src 即可（IDEA 会自动识别包）。
REFACTOR_NOTE.md：列出”原文件 → 新文件”对照表 + 红线确认清单 + 编译运行验证步骤，便于答辩讲解。
清空旧 bin\，用新 run.bat 重新编译，贴出编译成功输出。

8. 验证标准（重构完成的判据）

run.bat 能一次性编译通过，无 error（warning 可接受）。
启动后：登录界面 → 注册新号 → 登录 → 主菜单 → 编队 → 关卡 1 → 普攻/技能/大招/切人/用食物 → 胜利领奖 → 养成买书用书 → 注销，全流程与原版表现一致。
管理员后台（密码 klee is comming）能增删改玩家、改角色等级/经验/金币、改物品数量并保存。
重新登录同一账号，存档（等级/经验/金币/物品/世界等级/关卡进度）正确还原。
战斗数值抽查：超载/超导/感电/蒸发/融化/冻结/绽放/烈绽放/超绽放/激化系列、结晶盾、深渊法师破盾、狂暴激怒、岩盔王减伤——与原版一致。
每个方法都有注释；每个按钮事件可在一屏内读懂”调用谁/做什么”。

9. 可选简化（若引入抽象违背”初学者友好”）

放弃 GameContext：MainFrame 直接持状态（最贴近原版，跳转最少）。推荐。
放弃拆 DAO：若你只想”分包 + 单文件单类 + 注释”，可以让 StorageManager 仍是单文件（仅加 package），不拆 DBConnector/TableInitializer。拆与不拆都合规；拆了更清晰，不拆更稳。建议：至少拆出 DBConnector（连接逻辑独立），TableInitializer 可并入 StorageManager。
UserData.java 可不拆，保留 StorageManager.AdminCharData/AdminItemData 内部静态类。

10. 风险点提示

跨包可见性：原 class ElementAttach、SkillSystem、NormalAttack/ElementalSkill/ElementalBurst 是包级类（无 public），跨包后必须加 public，否则编译失败。重点检查。
反射/枚举索引：ElementType.values()[rs.getInt("element")] 依赖枚举顺序，移动枚举文件不影响顺序，但不要重排常量。
StorageManager.getInstance() 被多处调用：拆分后单例仍只应有一个 Connection；确保 DBConnector 也单例或由 StorageManager 持有唯一实例。
中文文案/HTML 标签：BattlePanel、CombatSystem 大量 <font color=...>、emoji（🎉☠️）原样保留，-encoding UTF-8 必须保留。
MySQL 路径硬编码 E:\SQL\...：保留，这是作者本机约定。
.class 旧产物：原 bin\ 里有按”默认包类名”生成的 .class，分包后会冲突。必须清空 bin\ 再编译。

（计划完。执行 AI 请配合同目录《执行提示词.md》使用。）