外观
架构总览
「玩家设定 →」
本文档基于 emberfall-server（Spring Boot 3 / Java 17 / Maven）与 emberfall-web（Vue 3.5 / TypeScript / Vite 6）实际代码整理，部署形态可参考仓库根目录旧文档 docs/00_系统总览与集成.md（以当前代码为准，该文档内容已落后）。
1. 后端模块划分
包根：com.emberfall（emberfall-server/src/main/java/com/emberfall/）
| 包 | 职责 | 代表类 |
|---|---|---|
auth/ | 登录鉴权：JWT 签发/校验、会话存储（内存 or Redis 可切换） | AuthController、JwtService、JwtAuthenticationFilter、AuthSessionStore、RedisAuthSessionStore、InMemoryAuthSessionStore、LoginAttemptService、CurrentUserService |
controller/ | 41 个 REST Controller（/api/**），玩法入口 | MapController、CombatController、EmberTrialController、SecretRealmController、GoldDungeonController、ShopController… |
service/ | 业务逻辑：结算、调度器、缓存、引擎 | CombatService、SettlementService、MapService、TrialBalanceConfig、GrowthTowerService、WorldBossScheduler… |
domain/ | 领域模型与数值常量类（*Rules.java、*Config.java、枚举） | Realm、Equipment、TitleRules、CompanionGrowthRules、MonsterTier、trial/*、combat/* |
balance/ | 全局数值平衡注册表（300D_V1） | BalanceConfigRegistry、BalanceConfigService、RealmBalance、SystemGrowthBalance、CombatAnchor、MonsterTierBalance、BalanceTrack |
config/ | @ConfigurationProperties 与基础设施配置 | LongBattleProperties、NoticeProperties、SecretRealmBuffConfig、SecretRealmEventConfig、TrialTimedEquipmentRedisConfiguration、SecurityConfig、WebConfig |
stage/ | 阶段开放开关（V66 起，运营可调） | StageConfigCache、EffectiveStageConfig、StageConfigService（admin）、StageConfigRepository |
admin/ | 管理后台（独立 JWT、RBAC、发奖、公告、阶段配置） | AdminAuthController、AdminUserController、AdminItemGrantController、AdminWorldBossController、StageConfigController、AdminPermissionAspect |
common/ | 统一响应/异常/分布式锁/数学工具 | ApiResponse、BusinessException、GlobalExceptionHandler、DistributedLockService、math/GameMath |
dto/ | 请求/响应记录（含 dto/trial/v2/、dto/secretrealm/ 子包） | — |
repository/ | JdbcTemplate 数据访问（GameRepository 为最大仓储，16 万字节） | GameRepository、EmberTrialRunRepository、SecretRealmRepository、TradeRepository… |
2. 三层调用链
Controller（校验参数 / 鉴权）
→ Service（业务规则 / 结算 / 调度 / 缓存 / 锁）
→ domain 常量类（数值规则，只读）
→ balance 注册表（300D_V1 全局数值）
→ repository（JdbcTemplate / Redis）
→ MySQL（Flyway 迁移 V1~V92）1
2
3
4
5
6
2
3
4
5
6
- 鉴权链：
JwtAuthenticationFilter解析 token →CurrentUserService.requirePlayerId()取当前玩家（管理端走AdminJwtAuthenticationFilter+AdminCurrentUserService） - 数值链：业务 Service 读
BalanceConfigService（DB 最终态）或 domain 常量类；不在 Service 中硬编码玩法数值（试炼场 v2 强制） - 调度器：
@Scheduled家族——WorldBossScheduler（20:00 结算）、GrowthTowerAutoAdvanceScheduler、EmberTrialSettlementScheduler、EmberTrialWeeklyRewardScheduler、SecretRealmCleanupScheduler、RankingScheduler、GoldBattleScheduler、LimitedDungeonAutoStopScheduler等 - 分布式锁：
DistributedLockService（结算/调度并发保护）
3. Flyway 迁移体系
- SQL 迁移：
resources/db/migration/V1__init_auth_save.sql~V92__trial_weekly_ranking_reward.sql（92 个版本，约 90 张业务表；版本号不连续，无 V6 相邻的 SQL——V5/V6/V9/V12 为 Java 迁移） - Java 迁移 4 个（
src/main/java/db/migration/）：V5__ensure_map_coach_target.java（教练怪数据补齐）V6__active_map_combat.java（地图战斗激活）V9__vip_total_recharge.java（VIP 累计充值列迁移）V12__unique_player_name.java（玩家名唯一约束）
- 配置：
spring.flyway.enabled=true、baseline-on-migrate=true、baseline-version=0 - 另有两套初始化脚本：
resources/db/init.sql（业务表完整 DDL + seed，含tower_config、server_message等幂等 upsert）、resources/db/admin/admin_init.sql（管理后台 6 表） - 数值权威机制：
V47__balance_300d_v1.sql建game_balance_version（300D_V1）与 7 张配置表；BalanceConfigService.loadActiveVersion()启动时读is_active=1版本覆盖BalanceConfigRegistry内置默认 → DB 最终态是全局数值权威（校验失败拒绝启动）
4. 配置分层
| 文件 | 用途 |
|---|---|
application.yml | 默认配置：emberfall.* 玩法配置（trial.v2 全量、notice、ranking、growth-tower 调度）、JWT、springdoc 关闭 |
application-dev.yml | 本地开发：本机 MySQL/Redis、固定 JWT secret、long-battle.time-scale: 1 |
application-prod.yml | 生产：环境变量注入（EMBERFALL_MYSQL_URL、EMBERFALL_JWT_SECRET、EMBERFALL_ADMIN_JWT_SECRET、EMBERFALL_TRIAL_V2_ENABLED 默认 false、EMBERFALL_TRIAL_PREVIEW_TOKEN_SECRET 必填） |
application-test.yml | 测试环境 |
覆盖机制：game_balance_version=300D_V1 由 BalanceConfigService 启动加载（@PostConstruct），BalanceConfigRegistry.validate 强校验（10 境齐备、总天数 300、渡劫门槛 783,619,427、锚点 ≥ 2×门槛/4×血、成长轨道 1% 内闭合）。调参 = 改配置表 seed + 升版本号，不回写文档（trial.v2.balance-version 注释明示）。
5. 前端结构（emberfall-web）
src/router/index.ts：41 个路由；/training→ redirect/maps、/damage-trial→ redirect/body-tempering；DamageGrowthView复用 4 区（body-tempering / realm-abyss / stone-strength / law）src/views/：41 个视图（TrainingView.vue存在但路由不可达；TrialHubView为烬塔 v2 主页）src/api/：gameApi.ts、emberTrialApi.ts、noticeApi.ts、authApi.ts、client.tssrc/stores/：authStore等 Pinia store- 技术栈：Vue 3.5 + TypeScript + Vite 6 + vue-router + Pinia；另有管理端
emberfall-admin-web/（独立工程）
6. 部署架构
- 单机部署：Nginx（静态前端 + 反代
/api）→ Spring Boot（8080）→ MySQL + Redis - 前后端分离：
emberfall-web构建产物部署于 Nginx；后端application-prod.yml通过环境变量注入连接串与密钥 - 管理后台：
emberfall-admin-web+emberfall-server的admin/**接口（独立 JWT secret、RBAC 权限切面AdminPermissionAspect） - 文档站：
emberfall-docs（VitePress 静态站）独立部署于/emberfall-docs/子路径