feat(admin): 实现只读词库管理后台
- 新增 Spring Boot 3 后端:JWT 认证、六个业务模块查询接口、Caffeine 聚合缓存与只读事务约束 - 新增 Vue 3 管理前端:登录、概览、词书、词条、词根词族、近反义词与数据质量 - 补充前后端 README、环境变量示例与本地构建部署说明 - 同步 OpenSpec 变更文档与任务进度(64/65,只读数据库账号待确认) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
1 parent
131c2b6353
commit
4e68ba3890
137 files changed
+15423
-10
No files matched your search
+113
-4
@@ -1,7 +1,116 @@
|
||||
# backend — 单词管理后端
|
||||
# backend — 词库只读管理后端
|
||||
|
||||
占位目录,技术栈待定。
|
||||
Spring Boot 3.3 + Java 17 + MyBatis-Plus,只读连接 MySQL `word_market`,为 `frontend/` 提供查询接口。
|
||||
|
||||
用途:为 `frontend` 提供词书、词条及关联数据的查询与编辑接口,数据来源为 `importer` 生成的数据库。
|
||||
## 只读约束
|
||||
|
||||
后续确定技术栈与目录结构后在此实现。
|
||||
- 所有业务接口只执行 `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 文件。数据质量模块会列出仍引用该文件键的词书关联;如后续补齐文件或更换数据快照,调整该配置即可。
|
||||
Reference in new issue
Block a user