Files
word-market/backend/README.md
T
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

117 lines
4.2 KiB
Markdown

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