鸣潮人物介绍网站（Spring Boot + Vue3）

项目结构

• backend/wuwa-site：后端（Spring Boot + MyBatis Plus + MySQL + Redis + JWT）
• frontend：前端（Vue 3 + Element Plus，前台与管理端同项目）

运行环境（本机需要）

环境	说明
JDK 21	与 backend/wuwa-site/pom.xml 中 java.version 一致
Maven 3.6+	编译与运行后端：mvn spring-boot:run
MySQL 8.x（或兼容版本）	业务库；账号见 application.yml，密码放在本地 application-local.yml（勿提交）
Redis	角色列表/详情缓存；建议本地启动默认端口
Node.js 18+（建议 LTS）	前端：npm install / npm run dev
浏览器	访问 Vite 开发地址（如 http://localhost:5173）

整体在做什么（架构）

• 前台：只读展示角色列表与详情（调用公开 GET /api/characters 等）。
• 管理端：JWT 登录 → 角色 CRUD → 触发 MainMenu 采集 或 Wiki 导入，查看任务与日志。
• 后端：Spring Boot 访问 MySQL；Redis 缓存列表/详情；Flyway 迁移库表；OkHttp + Jsoup 负责爬虫与 HTML 解析。

推荐实现顺序（开发时先后端再前端）

典型顺序与原因：先有接口与数据模型，前端再对接。

1. 后端：pom.xml → WuwaSiteApplication + application.yml → Flyway V1/V2 SQL → entity + mapper → ApiResponse、各类 config（含 Security、JWT）→ AuthService / AdminAuthController / 默认管理员初始化 → CharacterService → CharacterController（公开）与 AdminCharacterController（管理）→ CrawlerService + AdminCrawlerController → HealthController。
2. 前端：package.json + vite.config.js + index.html → main.js、App.vue、style.css → router → api/client.js、stores/auth → PublicLayout + 列表/详情页 → AdminLogin + AdminLayout + 管理角色/采集页。

后端主要文件（backend/wuwa-site）

路径均相对于 backend/wuwa-site/src/main/java/com/wuwa/site/（资源文件在 src/main/resources/）。

路径/文件	作用
WuwaSiteApplication.java	启动类；@MapperScan；@EnableAsync（采集后台任务）
resources/application.yml	可提交的默认配置（无真实密码）
application-local.yml.example	本地敏感配置模板；复制为 application-local.yml 使用
resources/db/migration/V1__init_schema.sql	初版表结构（角色、字典、采集日志等）
resources/db/migration/V2__wiki_fields.sql	Wiki 相关字段等增量迁移
pom.xml（模块根目录）	Maven 依赖与构建
common/ApiResponse.java	统一 JSON：code / message / data
config/*	MyBatis-Plus、Web/CORS、OkHttp、Security、JWT/Admin/Wiki 配置绑定
dto/*	登录、角色写入等请求/响应体
entity/*	与表对应的实体
mapper/*	MyBatis-Plus Mapper
security/JwtAuthenticationFilter.java	解析并校验 JWT
service/JwtService.java	签发/解析 Token
service/AuthService.java	登录校验
service/CharacterService.java	角色业务与 Redis 缓存、清缓存
service/CrawlerService.java	MainMenu 采集、Wiki 导入与解析、异步任务体
config/AdminInitializer.java	启动时初始化默认管理员（若不存在）
controller/HealthController.java	健康检查
controller/CharacterController.java	公开列表/详情 API
controller/AdminAuthController.java	管理端登录
controller/AdminCharacterController.java	管理端角色 CRUD
controller/AdminCrawlerController.java	采集任务、日志、Wiki 接口

根目录 .gitignore 已忽略 backend/wuwa-site/application-local.yml、target/、node_modules/ 及模块根目录下常见联调样例（MainMenu.json、wiki-raw*.json 等）。

本地配置（推 GitHub 前必读）

1. 在目录 backend/wuwa-site/ 下复制模板：
   application-local.yml.example → application-local.yml
2. 在 application-local.yml 中填写：MySQL 密码、管理端密码、JWT secret、Wiki devcode（若用 Wiki 导入）。
3. application-local.yml 已在 .gitignore 中，不会被 git add 进公开仓库。
4. 仓库里的 src/main/resources/application.yml 仅含占位默认值（如数据库密码 changeme），克隆后必须有 application-local.yml 或自行改环境变量才能连上真实数据库。

环境变量也可覆盖配置，例如：SPRING_DATASOURCE_PASSWORD、JWT_SECRET、WUWA_WIKI_DEVCODE（与 application.yml 中 ${...} 名称一致）。

推送到 GitHub（简要）

cd /path/to/鸣潮人物介绍网站
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/<你的用户名>/<仓库名>.git
git branch -M main
git push -u origin main

推送前可用 git status 确认没有 application-local.yml、target/、node_modules/。

前端主要文件（frontend）

路径相对于 frontend/。

路径	作用
package.json / package-lock.json	依赖：Vue3、Router、Pinia、Element Plus、Axios
vite.config.js	Vite 与开发代理（通常将 /api 转到后端）
index.html	HTML 入口
src/main.js	挂载应用，注册 Pinia、Router、Element Plus
src/App.vue	根组件
src/style.css	全局样式与主题
src/router/index.js	路由与登录守卫
src/api/client.js	Axios：baseURL: '/api'，附带 JWT
src/stores/auth.js	登录态与 token
src/views/PublicLayout.vue	前台布局
src/views/CharacterListPage.vue	角色列表
src/views/CharacterDetailPage.vue	角色详情
src/views/AdminLoginPage.vue	管理登录
src/views/AdminLayout.vue	管理端布局
src/views/AdminCharactersPage.vue	角色管理
src/views/AdminCrawlerPage.vue	采集任务与日志
dist/	npm run build 构建产物（开发时主要用 src/）

一次请求怎么走到数据库（简）

1. 浏览器访问页面 → Vue Router 渲染对应 .vue。
2. 页面通过 client 请求 /api/... → Vite 开发代理到后端（默认 8080）。
3. Controller 调用 Service；读列表/详情时可能先查 Redis，未命中再查 MySQL（MyBatis-Plus），再按需写回缓存。
4. 管理端需带 Authorization: Bearer <token>；采集由 AdminCrawlerController 入队异步任务，在 CrawlerService 中写库并清理相关缓存。

已实现功能

• 前台：
  • 角色列表：/characters
  • 角色详情：/characters/:slug
• 管理端：
  • 登录：/admin/login
  • 角色管理（增删改查）：/admin/characters
  • 采集任务与日志：/admin/crawler
• 后端接口：
  • GET /api/health
  • POST /api/admin/auth/login
  • GET /api/characters
  • GET /api/characters/{slug}
  • GET/POST/PUT/DELETE /api/admin/characters
  • POST /api/admin/crawler/run
  • GET /api/admin/crawler/jobs
  • GET /api/admin/crawler/logs?jobId=...

启动后端

1. 按上文 「本地配置」 准备好 backend/wuwa-site/application-local.yml（或设置等价环境变量）。
2. 确保 MySQL、Redis 可连接；库名默认 wuwa_site，用户默认 root（可在 application-local.yml 覆盖）。
3. 在 backend/wuwa-site 目录启动（保证能加载同目录下的 application-local.yml）：

cd backend/wuwa-site
mvn spring-boot:run

首次启动会自动执行 Flyway 建表，并自动初始化管理员账号（若库中不存在；账号密码来自配置中的 wuwa.admin）。

启动前端

cd frontend
npm install
npm run dev

访问：

• 前台：http://localhost:5173/characters
• 管理端：http://localhost:5173/admin/login

默认管理员

默认用户名 admin；密码以 application-local.yml（或环境变量 WUWA_ADMIN_PASSWORD）为准。模板里示例为 changeme_admin_password，请在本地文件中改成自己的密码。

JWT 密钥请设置 wuwa.jwt.secret（本地文件或 JWT_SECRET 环境变量），勿使用仓库里的占位默认值上线。

采集器说明

数据采集在哪些代码里？

能力	代码位置
管理端触发、任务列表、日志 API	backend/wuwa-site/src/main/java/com/wuwa/site/controller/AdminCrawlerController.java
MainMenu 官网 JSON 采集（MainMenu.json + article/{id}.json）	CrawlerService#crawlFromMainMenu、CrawlerService#executeCrawlJob（@Async 后台执行）
库街区 Wiki 导入（getEntryDetail + 解析入库）	CrawlerService#importWikiEntry、CrawlerService#parseWikiEntry 等
写入 characters 表（MainMenu 简易 upsert）	CrawlerService#upsertCharacter
Wiki 写入（含封面/技能等）	CrawlerService#insertCharacterWiki、mergeWikiIntoCharacter、replaceWikiImages 等
列表/详情 Redis 缓存清理	CharacterService#clearListCachePatterns、clearDetailCaches

行为说明（容易误解的点）

1. 你只在对话里提供了「琳奈」等 Wiki 信息，并不会限制 MainMenu 采集范围。
   MainMenu 采集会拉取库洛 CDN 上整份 MainMenu.json，按标题规则匹配多篇档案类文章，因此会出现多个人物，不是「你给错信息」导致的 bug。
   只导入某一个 Wiki 条目请用管理端或接口：POST /api/admin/crawler/wiki/import?entryId=...。

2. 「采集成功」但列表没变化：看任务 摘要 里的 upserted、skipped_unchanged、candidates。增量模式下 upserted=0 且 skipped_unchanged>0 表示数据未变被跳过。若 candidates=0，说明标题规则与官网当前标题不匹配，可把 application.yml 里 wuwa.crawler.main-menu-relaxed-titles 改为 true/false 对照尝试。

3. MySQL / Redis 未启动：任务一般会 failed，摘要里是异常信息；若库连不上，数据不会进表。

4. 武器：当前模型里是 weapon_type_id（武器类型字典，如迅刀/佩枪），没有单独的「武器图鉴」表或武器立绘字段；角色武器相关配图若在 Wiki 结构化数据里，可走 Wiki 导入与 character_images 等扩展（视解析实现而定）。

5. 前端按钮「不灵」：采集已在 后台异步执行，点运行后应 刷新任务列表 看 running → success；若未登录或后端未启动，会弹出错误提示。