?view=home：进入工具集首页。?view=replay：进入回放提取器。?view=leaderboard：进入排行榜。?view=boost：进入陪练与打手申请。?view=extended：进入 Rating V2 解析。?view=profile：进入个人中心。?view=admin-users：进入管理员用户管理（需wotbtools-admin角色）。
《坦克世界闪击战》（World of Tanks Blitz）工具集。
已上线工具：从 .wotbreplay 回放文件中提取战斗数据导出 Excel、在线伤害排行榜、Keycloak 认证。
| 目标 | 技术方向 | 状态 |
|---|---|---|
| Web 版 | Spring Boot 4 + Vue 3 + PostgreSQL + Docker + Keycloak | ✅ 已完成 |
| 工具集主页 | Vue SPA 游戏工具站风格入口 + 主题切换 + 三语 i18n | ✅ 已完成 |
版本历史见 CHANGELOG.md，任务拆分见 TODO.md。
| 版本 | 技术栈 | 入口 | 适用场景 |
|---|---|---|---|
| Java Web 版 | Java 21 + Spring Boot 4 + Vue 3 + Docker | docker\online\ 本地开发；CI/CD → GHCR backend/frontend/keycloak 三镜像 |
浏览器上传、在线预览、排行榜、REST API、Keycloak 认证 |
文档入口：
- 本文件：项目概览、Java 版使用与构建。
- HANDOVER.md：交接 / AI 工具迁移总入口（环境坑、CI/CD、部署、约定一站式）。
- java/README.md：Java / Web 版运行、接口、部署。
- CHANGELOG.md：版本历史（对外）。
- TODO.md：待办事项。
- DEVELOPER_GUIDE.md：维护上下文、架构、回放格式、i18n、测试策略。
- docs/replay-data.md：data.wotreplay 事件流格式、protobuf 字段表、死亡时间推算。
- docs/rating-system.md：评分算法、参数、展示。
- 品牌展示：logo 与 favicon（
common/assets/单一来源，Docker 构建时分发至首页与前端） - 解析单个
.wotbreplay中的 14 名玩家战斗数据。 - 读取
meta.json战斗信息、battle_results.datpickle + protobuf、data.wotreplay事件流。 - 使用
tankopedia.json将车辆 ID 映射为车辆名、等级、类型、国家和炮伤。 - 单场导出 Excel：
战斗信息、玩家数据、原始字段。 - 多场导出 Excel：按
arenaUniqueId去重，生成汇总、明细、战斗列表。 - 存活时间列：基于伤害事件的秒级估算。
- 自包含表现评分：按车型基准归一化（类 WN8，1000=同型平均），单场「评分」、汇总「场均评分」。
- 评分徽章：回放预览中最高评分显示奖牌，最低评分显示金 shit，支持
0分最低值。 - Rating V2 分析页：主站
?view=extended与独立入口/extended均可进入，额外展示扩展字段与本次上传实时 rating。 - 扩展字段：
alpha_damage、rank已接入 API/导出/扩展页，原回放页面不默认展示；xp、credits仅解析保留，不作为战绩字段展示。 - 潜在伤害字段：
potential_damage/potential_damage_supplement/potential_damage_detail，优先从回放 direct HP damage 事件推断逐击杀目标；事件缺失、映射失败或特殊伤害未覆盖时保守等于实际伤害。 - 地图名共享字典：
common/map_names.json现提供zh/en/ru三语映射，网页按当前语言显示，导出继续使用中文。 - 空白元数据兜底：回放里仅含空格的录像者、昵称、版本号、地图翻译或时间戳会按缺失值处理，避免污染排行榜记录、汇总昵称和时间解析。
- GUI 支持选择文件或文件夹、预览数据、合并汇总或逐场导出。
- 回放预览列选择器会把单场/汇总的列可见性与排序分别记到
localStorage，新增列会自动补到当前顺序末尾。 - Java / Web 版提供
/api/preview、/api/export、/api/columns、/api/rating、/api/health。 - 回放上传限制为单文件 20 MiB、最多 100 个文件、请求合计 200 MiB；解析器还限制 ZIP 解压、pickle/protobuf 分配和单实例并发，容量满时返回
REPLAY_BUSY。 - 排行榜：通过排行榜上传入口记录随机战斗录像者的单场伤害，
/api/leaderboard/top-damage等端点查询。 - 工具集首页首屏展示排行榜当前最高单场伤害记录；排行榜暂无数据或接口不可用时显示
--。 - Keycloak 认证：
https://auth.wotbtools.comKeycloak 容器，realmwotbtools，clientwotbtools-web。前端check-sso游客模式 + 登录/登出，注册入口由 Keycloak realm 托管。 - 个人中心：
/profile页面显示用户名、登出按钮、排行榜记录；若当前用户是打手，还会展示进行中订单、历史订单，并可直接暂停/恢复接收新订单。未登录时展示"登入"按钮触发 Keycloak OIDC 流程。 - 陪练与打手申请：
?view=boost页面支持玩家提交打手资格申请，管理员在资格审批中查看截图、联系方式和在线时间，审批通过后自动关联 Keycloakboosterrole 与打手资料。数据库约束会先 flush，realm role 变更在事务回滚时自动补偿。打手管理页会分别显示资格状态（status）和接单状态（由available + activeAssignmentCount推导为可接单/忙碌/暂停接单），分配时会优先推荐可接单且匹配度更高的打手；打手本人可在工作台接单、开始、提交完成或拒单，个人中心可回看历史订单，并通过站内通知提醒相关用户。 - 工具集主页：Vue SPA 内
HomePage.vue（卡片入口 + 版本历史），版本历史数据来自frontend/src/data/versions.json。 - 赞助页面：首页保留三语赞助入口；运行时读取同源
/sponsor-config.json，二维码由 VPS/opt/wotb/config/sponsor/只读挂载，不进入仓库或镜像。 - 域名统一：
wotbtools.com和www.wotbtools.com，去除replay.wotbtools.com子域名。 - 管理员用户管理：
/api/admin/usersAPI 搜索/查看/删除用户，Keycloak Admin API 集成，审计日志admin_user_log表，wotbtools-admin角色权限控制。 - API 国际化契约：后端只返回英文 raw enum、
code/error与数据；可读状态、成功和错误文案统一由前端中/英/俄词典渲染。 - 权限默认拒绝：未声明的
/api/**不开放；boost-manager仅管理/api/admin/boost/**，用户管理等其他后台接口只允许wotbtools-admin。 - 移动端顶栏：回放解析、排行榜、个人中心、陪练和管理员页面共享同一套响应式顶栏；主题/语言/账号入口自动换行，不压缩主题切换器。
- 上传区图标：回放解析与排行榜上传区共用描边 SVG 图标样式，原生文件控件隐藏在自定义按钮内。
排行榜支持按车辆筛选（点击车辆名查看专属伤害榜），URL 参数
?view=leaderboard可直接跳转排行榜视图。
需要 JDK 21、Maven、Node.js；完整运行还需要 Docker Desktop。
cd java
set JAVA_HOME=%USERPROFILE%\.jdks\jdk-21.0.1
mvn -s settings.xml -pl wotb-core,wotb-web -am install
cd ..\docker\online
docker compose up -d --build后端始终依赖 PostgreSQL、Flyway 与 Keycloak，不能在无数据库环境直接运行 JAR。Windows 默认
java也可能是 JDK 8，执行 Maven 前先把JAVA_HOME指向 JDK 21。
车辆库 common/tankopedia.json 是单一来源，由 update_tankopedia.py
从 blitzkit 的 tanks.pb 转换生成，包含车辆基础信息和 alphaDamage。游戏新增车辆后重新拉取即可（需要网络）：
cd common/python
python update_tankopedia.py无需手动同步：wotb-core 构建时会自动把 common/tankopedia.json 复制到 classpath。
Java 侧：
cd java
set JAVA_HOME=%USERPROFILE%\.jdks\jdk-21.0.1
mvn -s settings.xml test前端：
cd frontend
npm test
npm run build- 部署前自动备份
wotb与keycloak；database-backup.yml每日香港时间 03:15 再备份一次。 - 归档分别保存在
/opt/wotb/backups/wotb/、/opt/wotb/backups/keycloak/，完整读取校验后保留 7 天。 - 恢复只允许 SSH 手动执行
deploy/postgres-restore.sh，文件必须位于对应数据库目录，并显式传入--confirm RESTORE-wotb或RESTORE-keycloak；恢复前会再做安全备份。
| 路径 | 说明 |
|---|---|
common/ |
共享资源：tankopedia.json、rating.json、map_names.json、assets/（logo/favicon 单一来源）、data/（示例回放） |
common/python/ |
车辆库更新脚本（update_tankopedia.py） |
java/ |
Java 主线（wotb-core + wotb-web） |
java/wotb-core/ |
共享核心库：解析、protobuf 解码、pickle 读取、汇总、POI 导出 |
java/wotb-web/ |
Spring Boot 4 应用：REST API + Leaderboard + Flyway |
frontend/ |
Vue 3 前端（含工具集主页 HomePage.vue、三语 locale、共享主题变量） |
frontend/src/data/ |
纯前端数据（版本历史 versions.json） |
docker/online/ |
开发者本地：docker compose up -d --build 编译启动（四容器含 keycloak） |
docker/ |
Dockerfile.backend / Dockerfile.frontend / keycloak (realm) |
deploy/ |
nginx、初始化 SQL、PostgreSQL 双库备份/检查/恢复脚本 |
.github/workflows/ |
测试门禁、增量部署、每日数据库备份与线上诊断 |
.wotbreplay 本质是 zip 包，当前工具使用其中的：
meta.json：地图、版本、开始时间、时长、录像者等基础信息。battle_results.dat：pickle 包装的(arenaId, protobufBytes)，其中 protobuf 包含玩家战绩。data.wotreplay：BigWorld 事件流，用于存活时间推算（Type 8 EntityMethod 伤害事件）。
项目不解析完整战斗过程流，因此不会输出逐帧轨迹、每发炮弹弹道等事件级数据。