# 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 哈希: ```bash htpasswd -bnBC 10 "" 'your-password' | tr -d ':\n' # 或 python -c "import bcrypt; print(bcrypt.hashpw(b'your-password', bcrypt.gensalt()).decode())" ``` ## 启动 ```bash cd backend mvn spring-boot:run ``` 或构建后运行: ```bash 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 条。 ## 测试 ```bash cd backend mvn test ``` 覆盖分页边界、认证成功/失败、404、空状态与缓存刷新行为。 ## 部署 后端产出可执行 jar,前端由 Nginx 托管并反向代理 `/api`。示例: ```nginx 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 文件。数据质量模块会列出仍引用该文件键的词书关联;如后续补齐文件或更换数据快照,调整该配置即可。