Files
voidandClaude Sonnet 4.6 4e68ba3890 feat(admin): 实现只读词库管理后台
- 新增 Spring Boot 3 后端:JWT 认证、六个业务模块查询接口、Caffeine 聚合缓存与只读事务约束
- 新增 Vue 3 管理前端:登录、概览、词书、词条、词根词族、近反义词与数据质量
- 补充前后端 README、环境变量示例与本地构建部署说明
- 同步 OpenSpec 变更文档与任务进度(64/65,只读数据库账号待确认)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-11-08 22:55:15 +08:00
..

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 文件。数据质量模块会列出仍引用该文件键的词书关联;如后续补齐文件或更换数据快照,调整该配置即可。