- 新增 Spring Boot 3 后端:JWT 认证、六个业务模块查询接口、Caffeine 聚合缓存与只读事务约束 - 新增 Vue 3 管理前端:登录、概览、词书、词条、词根词族、近反义词与数据质量 - 补充前后端 README、环境变量示例与本地构建部署说明 - 同步 OpenSpec 变更文档与任务进度(64/65,只读数据库账号待确认) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
backend — 词库只读管理后端
Spring Boot 3.3 + Java 17 + MyBatis-Plus,只读连接 MySQL word_market,为 frontend/ 提供查询接口。
只读约束
- 所有业务接口只执行
SELECT,代码中不存在任何写 Mapper。 - 所有 Service 标注
@Transactional(readOnly = true)。 - HikariCP 设置
read-only: true。 - 数据库侧建议使用仅具备
SELECT权限的账号;创建只读账号属于运维动作,需要单独确认后执行。
环境要求
- JDK 17
- Maven 3.9+
- 可访问的 MySQL
word_market数据库
配置
复制 .env.example 或参考 src/main/resources/application.example.yml。所有敏感值通过环境变量注入,仓库不保存真实凭据。
| 变量 | 必填 | 说明 |
|---|---|---|
DB_URL |
否 | JDBC 地址,默认 jdbc:mysql://s1.void01.com:3306/word_market?... |
DB_USERNAME |
是 | 数据库用户名 |
DB_PASSWORD |
是 | 数据库密码 |
DB_POOL_SIZE |
否 | Hikari 最大连接数,默认 15 |
ADMIN_USERNAME |
是 | 管理员用户名 |
ADMIN_PASSWORD_HASH |
是 | 管理员密码的 BCrypt 哈希 |
JWT_SECRET |
是 | HS256 签名密钥,至少 32 字节 |
ADMIN_TOKEN_TTL_HOURS |
否 | token 有效期,默认 8 小时 |
CORS_ALLOWED_ORIGINS |
否 | 逗号分隔的前端来源,默认 http://localhost:5173,http://127.0.0.1:5173 |
COVER_BASE_URL |
否 | 封面 CDN 前缀,默认 https://static.beingfine.cn |
CACHE_TTL_MINUTES |
否 | 聚合缓存时长,默认 10 分钟 |
CACHE_MAXIMUM_SIZE |
否 | 聚合缓存条目上限,默认 200 |
KNOWN_MISSING_ZPK_KEYS |
否 | 已知缺失的 zpk 文件键,逗号分隔 |
SERVER_PORT |
否 | 服务端口,默认 8080 |
缺少 ADMIN_USERNAME、ADMIN_PASSWORD_HASH 或 JWT_SECRET 时应用会拒绝启动并输出缺失项;JWT_SECRET 少于 32 字节同样拒绝启动。
生成 BCrypt 哈希:
htpasswd -bnBC 10 "" 'your-password' | tr -d ':\n'
# 或
python -c "import bcrypt; print(bcrypt.hashpw(b'your-password', bcrypt.gensalt()).decode())"
启动
cd backend
mvn spring-boot:run
或构建后运行:
mvn -DskipTests package
java -jar target/word-market-admin-0.1.0.jar
API
统一前缀 /api,响应结构 { code, message, data };分页为 { items, total, page, size };数值 ID 以字符串返回。
| 模块 | 接口 |
|---|---|
| 认证 | POST /api/auth/login |
| 概览 | GET /api/dashboard/summary、/exam-distribution、/book-size-top、/pos-distribution |
| 词书 | GET /api/books、/api/books/{id}、/api/books/{id}/entries、/api/exams |
| 词条 | GET /api/entries、/api/entries/{id}、/{id}/senses、/phrases、/examples、/confusables、/variants、/books |
| 词根词族 | GET /api/morphemes、/api/morphemes/{id}、/api/cards、/api/cards/{id}、/api/families、/api/families/{id}、/api/families/{id}/tree |
| 近反义词 | GET /api/synonyms、/api/synonyms/{wordId}、/api/synonyms/group-size-distribution |
| 数据质量 | GET /api/quality/summary、/declared-vs-actual、/missing-references、/cross-domain-coverage |
概览与质量聚合接口支持 ?refresh=true 跳过缓存并重新计算。分页默认每页 20 条,最大 100 条。
测试
cd backend
mvn test
覆盖分页边界、认证成功/失败、404、空状态与缓存刷新行为。
部署
后端产出可执行 jar,前端由 Nginx 托管并反向代理 /api。示例:
server {
listen 80;
server_name example.com;
root /srv/word-market/frontend/dist;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_read_timeout 60s;
}
}
生产环境必须使用 HTTPS,并按需收紧 CORS_ALLOWED_ORIGINS。
已知数据异常
KNOWN_MISSING_ZPK_KEYS 默认登记 0_53785_101_1775241011,对应 importer 导出时缺失的一个 zpk 文件。数据质量模块会列出仍引用该文件键的词书关联;如后续补齐文件或更换数据快照,调整该配置即可。