diff --git a/.gitignore b/.gitignore
index f53d388..67b9ae0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,11 +22,13 @@ htmlcov/
node_modules/
dist/
build/
+target/
.next/
coverage/
*.tsbuildinfo
.env
.env.*
+!.env.example
# ---- importer:本地数据、产物与大文件(不进 Git) ----
/importer/output/
diff --git a/README.md b/README.md
index 0b4d33d..05f93f0 100644
--- a/README.md
+++ b/README.md
@@ -5,11 +5,13 @@
| 目录 | 项目 | 状态 | 说明 |
|---|---|---|---|
| `importer/` | 单词导入 | 已有 | 从 Lexis 导出词书与词条,建库并导入 SQLite/PostgreSQL/MySQL |
-| `frontend/` | 单词管理前端 | 占位 | 待定技术栈 |
-| `backend/` | 单词管理后端 | 占位 | 待定技术栈 |
+| `backend/` | 管理后台后端 | 已有 | Spring Boot 3 + MyBatis-Plus,只读查询 MySQL `word_market` |
+| `frontend/` | 管理后台前端 | 已有 | Vue 3 + Vite + TypeScript + Element Plus + ECharts |
## 快速开始
+### 1. 导入数据
+
单词导入流程见 [`importer/README.md`](importer/README.md)。命令需在 `importer/` 目录下执行:
```powershell
@@ -17,6 +19,38 @@ cd importer
python run.py
```
+### 2. 启动后端
+
+准备数据库连接、管理员账号和 JWT 密钥(见 [`backend/README.md`](backend/README.md)):
+
+```powershell
+cd backend
+$env:DB_USERNAME = 'your_user'
+$env:DB_PASSWORD = 'your_password'
+$env:ADMIN_USERNAME = 'admin'
+$env:ADMIN_PASSWORD_HASH = '$2a$10$...'
+$env:JWT_SECRET = 'at-least-32-bytes-random-secret'
+mvn spring-boot:run
+```
+
+默认监听 `http://127.0.0.1:8080`。
+
+### 3. 启动前端
+
+```powershell
+cd frontend
+npm install
+npm run dev
+```
+
+默认地址 `http://127.0.0.1:5173`,开发服务器代理 `/api` 到后端。
+
+## 管理后台
+
+只读管理后台覆盖六个模块:概览、词书、词条、词根词族、近反义词、数据质量。所有接口仅执行 `SELECT`,应用层启用只读事务,建议数据库侧使用只读账号。
+
+生产部署方式为后端可执行 jar + 前端 `dist` 静态资源,由 Nginx 托管并反向代理 `/api`。
+
## 数据与产物
`importer/` 下的数据与研究产物不纳入 Git(见 `.gitignore`),仅保留在本机:
@@ -30,6 +64,8 @@ Git 只跟踪源码、文档与配置。
## 文档
+- 管理后端:[`backend/README.md`](backend/README.md)
+- 管理前端:[`frontend/README.md`](frontend/README.md)
- 导入流程与算法:[`importer/README.md`](importer/README.md)
- 数据实体关系模型:[`importer/docs/DATA-MODEL.md`](importer/docs/DATA-MODEL.md)
- ZPK 解密内容分析:[`importer/docs/zpk-decrypted-content-analysis.md`](importer/docs/zpk-decrypted-content-analysis.md)
diff --git a/backend/.env.example b/backend/.env.example
new file mode 100644
index 0000000..8208502
--- /dev/null
+++ b/backend/.env.example
@@ -0,0 +1,18 @@
+# 复制为 .env 或直接在运行环境中设置;不要提交真实值。
+DB_URL=jdbc:mysql://s1.void01.com:3306/word_market?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true&connectTimeout=10000&socketTimeout=30000
+DB_USERNAME=your_read_only_user
+DB_PASSWORD=your_password
+DB_POOL_SIZE=15
+
+ADMIN_USERNAME=admin
+# BCrypt 哈希,可用 htpasswd 生成:htpasswd -bnBC 10 "" 'your-password' | tr -d ':\n'
+ADMIN_PASSWORD_HASH=$2a$10$replace_with_a_real_bcrypt_hash
+JWT_SECRET=replace_with_a_random_secret_at_least_32_characters
+ADMIN_TOKEN_TTL_HOURS=8
+
+CORS_ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
+COVER_BASE_URL=https://static.beingfine.cn
+CACHE_TTL_MINUTES=10
+CACHE_MAXIMUM_SIZE=200
+KNOWN_MISSING_ZPK_KEYS=0_53785_101_1775241011
+SERVER_PORT=8080
diff --git a/backend/README.md b/backend/README.md
index 58ebe97..ee8a462 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -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 文件。数据质量模块会列出仍引用该文件键的词书关联;如后续补齐文件或更换数据快照,调整该配置即可。
diff --git a/backend/pom.xml b/backend/pom.xml
new file mode 100644
index 0000000..9b9ff09
--- /dev/null
+++ b/backend/pom.xml
@@ -0,0 +1,94 @@
+
+
+ 4.0.0
+
+
+ org.springframework.boot
+ spring-boot-starter-parent
+ 3.3.5
+
+
+
+ com.wordmarket
+ word-market-admin
+ 0.1.0
+ word-market-admin
+ 只读词库管理后台
+
+
+ 17
+ 3.5.7
+ 0.12.6
+
+
+
+
+ org.springframework.boot
+ spring-boot-starter-web
+
+
+ org.springframework.boot
+ spring-boot-starter-security
+
+
+ org.springframework.boot
+ spring-boot-starter-validation
+
+
+ org.springframework.boot
+ spring-boot-starter-cache
+
+
+ com.github.ben-manes.caffeine
+ caffeine
+
+
+ com.baomidou
+ mybatis-plus-spring-boot3-starter
+ ${mybatis-plus.version}
+
+
+ com.mysql
+ mysql-connector-j
+ runtime
+
+
+ io.jsonwebtoken
+ jjwt-api
+ ${jjwt.version}
+
+
+ io.jsonwebtoken
+ jjwt-impl
+ ${jjwt.version}
+ runtime
+
+
+ io.jsonwebtoken
+ jjwt-jackson
+ ${jjwt.version}
+ runtime
+
+
+ org.springframework.boot
+ spring-boot-starter-test
+ test
+
+
+ org.springframework.security
+ spring-security-test
+ test
+
+
+
+
+
+
+ org.springframework.boot
+ spring-boot-maven-plugin
+
+
+
+
diff --git a/backend/src/main/java/com/wordmarket/admin/AdminApplication.java b/backend/src/main/java/com/wordmarket/admin/AdminApplication.java
new file mode 100644
index 0000000..e4d8a6b
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/AdminApplication.java
@@ -0,0 +1,17 @@
+package com.wordmarket.admin;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.boot.autoconfigure.security.servlet.UserDetailsServiceAutoConfiguration;
+import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
+import org.springframework.cache.annotation.EnableCaching;
+
+@SpringBootApplication(exclude = UserDetailsServiceAutoConfiguration.class)
+@ConfigurationPropertiesScan
+@EnableCaching
+public class AdminApplication {
+
+ public static void main(String[] args) {
+ SpringApplication.run(AdminApplication.class, args);
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/common/ApiResponse.java b/backend/src/main/java/com/wordmarket/admin/common/ApiResponse.java
new file mode 100644
index 0000000..9bf1938
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/common/ApiResponse.java
@@ -0,0 +1,12 @@
+package com.wordmarket.admin.common;
+
+public record ApiResponse(int code, String message, T data) {
+
+ public static ApiResponse ok(T data) {
+ return new ApiResponse<>(0, "ok", data);
+ }
+
+ public static ApiResponse error(int code, String message) {
+ return new ApiResponse<>(code, message, null);
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/common/BizException.java b/backend/src/main/java/com/wordmarket/admin/common/BizException.java
new file mode 100644
index 0000000..ffe6b64
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/common/BizException.java
@@ -0,0 +1,29 @@
+package com.wordmarket.admin.common;
+
+import org.springframework.http.HttpStatus;
+
+public class BizException extends RuntimeException {
+
+ private final HttpStatus status;
+
+ public BizException(HttpStatus status, String message) {
+ super(message);
+ this.status = status;
+ }
+
+ public HttpStatus getStatus() {
+ return status;
+ }
+
+ public static BizException badRequest(String message) {
+ return new BizException(HttpStatus.BAD_REQUEST, message);
+ }
+
+ public static BizException unauthorized(String message) {
+ return new BizException(HttpStatus.UNAUTHORIZED, message);
+ }
+
+ public static BizException notFound(String message) {
+ return new BizException(HttpStatus.NOT_FOUND, message);
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/common/GlobalExceptionHandler.java b/backend/src/main/java/com/wordmarket/admin/common/GlobalExceptionHandler.java
new file mode 100644
index 0000000..c4c3317
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/common/GlobalExceptionHandler.java
@@ -0,0 +1,45 @@
+package com.wordmarket.admin.common;
+
+import jakarta.validation.ConstraintViolationException;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.ResponseEntity;
+import org.springframework.http.converter.HttpMessageNotReadableException;
+import org.springframework.validation.FieldError;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
+
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+ private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
+
+ @ExceptionHandler(BizException.class)
+ public ResponseEntity> handleBiz(BizException ex) {
+ return ResponseEntity.status(ex.getStatus())
+ .body(ApiResponse.error(ex.getStatus().value(), ex.getMessage()));
+ }
+
+ @ExceptionHandler(MethodArgumentNotValidException.class)
+ public ResponseEntity> handleValidation(MethodArgumentNotValidException ex) {
+ FieldError fieldError = ex.getBindingResult().getFieldError();
+ String message = fieldError == null
+ ? "请求参数不合法"
+ : "缺少或非法字段: " + fieldError.getField();
+ return ResponseEntity.badRequest().body(ApiResponse.error(400, message));
+ }
+
+ @ExceptionHandler({ConstraintViolationException.class, MethodArgumentTypeMismatchException.class,
+ HttpMessageNotReadableException.class})
+ public ResponseEntity> handleBadRequest(Exception ex) {
+ return ResponseEntity.badRequest().body(ApiResponse.error(400, "请求参数不合法"));
+ }
+
+ @ExceptionHandler(Exception.class)
+ public ResponseEntity> handleUnexpected(Exception ex) {
+ log.error("Unhandled exception", ex);
+ return ResponseEntity.internalServerError().body(ApiResponse.error(500, "服务暂时不可用"));
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/common/Items.java b/backend/src/main/java/com/wordmarket/admin/common/Items.java
new file mode 100644
index 0000000..e956cd7
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/common/Items.java
@@ -0,0 +1,10 @@
+package com.wordmarket.admin.common;
+
+import java.util.List;
+
+public record Items(List items) {
+
+ public static Items of(List items) {
+ return new Items<>(items);
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/common/PageResult.java b/backend/src/main/java/com/wordmarket/admin/common/PageResult.java
new file mode 100644
index 0000000..95447d0
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/common/PageResult.java
@@ -0,0 +1,10 @@
+package com.wordmarket.admin.common;
+
+import java.util.List;
+
+public record PageResult(List items, long total, int page, int size) {
+
+ public static PageResult of(List items, long total, int page, int size) {
+ return new PageResult<>(items, total, page, size);
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/common/Pages.java b/backend/src/main/java/com/wordmarket/admin/common/Pages.java
new file mode 100644
index 0000000..df604e4
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/common/Pages.java
@@ -0,0 +1,26 @@
+package com.wordmarket.admin.common;
+
+public final class Pages {
+
+ private static final int DEFAULT_SIZE = 20;
+ private static final int MAX_SIZE = 100;
+
+ private Pages() {
+ }
+
+ public static int page(Integer page) {
+ return page == null || page < 1 ? 1 : page;
+ }
+
+ public static int size(Integer size) {
+ if (size == null || size < 1) {
+ return DEFAULT_SIZE;
+ }
+ return Math.min(size, MAX_SIZE);
+ }
+
+ public static int offset(int page, int size) {
+ long offset = (long) (page - 1) * size;
+ return (int) Math.min(offset, Integer.MAX_VALUE);
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/common/RequestLogFilter.java b/backend/src/main/java/com/wordmarket/admin/common/RequestLogFilter.java
new file mode 100644
index 0000000..8178f58
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/common/RequestLogFilter.java
@@ -0,0 +1,34 @@
+package com.wordmarket.admin.common;
+
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.core.Ordered;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+import java.io.IOException;
+
+@Component
+@Order(Ordered.HIGHEST_PRECEDENCE)
+public class RequestLogFilter extends OncePerRequestFilter {
+
+ private static final Logger log = LoggerFactory.getLogger(RequestLogFilter.class);
+
+ @Override
+ protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+ FilterChain filterChain) throws ServletException, IOException {
+ long started = System.currentTimeMillis();
+ try {
+ filterChain.doFilter(request, response);
+ } finally {
+ long elapsed = System.currentTimeMillis() - started;
+ log.info("{} {} -> {} ({} ms)", request.getMethod(), request.getRequestURI(),
+ response.getStatus(), elapsed);
+ }
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/config/AdminProperties.java b/backend/src/main/java/com/wordmarket/admin/config/AdminProperties.java
new file mode 100644
index 0000000..8182db6
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/config/AdminProperties.java
@@ -0,0 +1,76 @@
+package com.wordmarket.admin.config;
+
+import org.springframework.beans.factory.InitializingBean;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+import java.util.ArrayList;
+import java.util.List;
+
+@ConfigurationProperties(prefix = "admin")
+public class AdminProperties implements InitializingBean {
+
+ private String username;
+ private String passwordHash;
+ private String jwtSecret;
+ private int tokenTtlHours = 8;
+
+ @Override
+ public void afterPropertiesSet() {
+ List missing = new ArrayList<>();
+ if (isBlank(username)) {
+ missing.add("ADMIN_USERNAME / admin.username");
+ }
+ if (isBlank(passwordHash)) {
+ missing.add("ADMIN_PASSWORD_HASH / admin.password-hash");
+ }
+ if (isBlank(jwtSecret)) {
+ missing.add("JWT_SECRET / admin.jwt-secret");
+ }
+ if (!missing.isEmpty()) {
+ throw new IllegalStateException("缺少管理员配置: " + String.join(", ", missing));
+ }
+ if (jwtSecret.getBytes(java.nio.charset.StandardCharsets.UTF_8).length < 32) {
+ throw new IllegalStateException("JWT_SECRET 至少需要 32 字节(当前 "
+ + jwtSecret.getBytes(java.nio.charset.StandardCharsets.UTF_8).length + " 字节)");
+ }
+ if (tokenTtlHours <= 0) {
+ throw new IllegalStateException("ADMIN_TOKEN_TTL_HOURS 必须大于 0");
+ }
+ }
+
+ private static boolean isBlank(String value) {
+ return value == null || value.isBlank();
+ }
+
+ public String getUsername() {
+ return username;
+ }
+
+ public void setUsername(String username) {
+ this.username = username;
+ }
+
+ public String getPasswordHash() {
+ return passwordHash;
+ }
+
+ public void setPasswordHash(String passwordHash) {
+ this.passwordHash = passwordHash;
+ }
+
+ public String getJwtSecret() {
+ return jwtSecret;
+ }
+
+ public void setJwtSecret(String jwtSecret) {
+ this.jwtSecret = jwtSecret;
+ }
+
+ public int getTokenTtlHours() {
+ return tokenTtlHours;
+ }
+
+ public void setTokenTtlHours(int tokenTtlHours) {
+ this.tokenTtlHours = tokenTtlHours;
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/config/AppProperties.java b/backend/src/main/java/com/wordmarket/admin/config/AppProperties.java
new file mode 100644
index 0000000..6e3ddf0
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/config/AppProperties.java
@@ -0,0 +1,77 @@
+package com.wordmarket.admin.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+@ConfigurationProperties(prefix = "app")
+public class AppProperties {
+
+ private final Cors cors = new Cors();
+ private final Cache cache = new Cache();
+ private final Quality quality = new Quality();
+ private String coverBaseUrl = "https://static.beingfine.cn";
+
+ public static class Cors {
+ private String allowedOrigins = "http://localhost:5173";
+
+ public String getAllowedOrigins() {
+ return allowedOrigins;
+ }
+
+ public void setAllowedOrigins(String allowedOrigins) {
+ this.allowedOrigins = allowedOrigins;
+ }
+ }
+
+ public static class Cache {
+ private long ttlMinutes = 10;
+ private long maximumSize = 200;
+
+ public long getTtlMinutes() {
+ return ttlMinutes;
+ }
+
+ public void setTtlMinutes(long ttlMinutes) {
+ this.ttlMinutes = ttlMinutes;
+ }
+
+ public long getMaximumSize() {
+ return maximumSize;
+ }
+
+ public void setMaximumSize(long maximumSize) {
+ this.maximumSize = maximumSize;
+ }
+ }
+
+ public static class Quality {
+ private String knownMissingZpkKeys = "";
+
+ public String getKnownMissingZpkKeys() {
+ return knownMissingZpkKeys;
+ }
+
+ public void setKnownMissingZpkKeys(String knownMissingZpkKeys) {
+ this.knownMissingZpkKeys = knownMissingZpkKeys;
+ }
+ }
+
+ public Cors getCors() {
+ return cors;
+ }
+
+ public Cache getCache() {
+ return cache;
+ }
+
+ public Quality getQuality() {
+ return quality;
+ }
+
+ public String getCoverBaseUrl() {
+ return coverBaseUrl;
+ }
+
+ public void setCoverBaseUrl(String coverBaseUrl) {
+ this.coverBaseUrl = coverBaseUrl;
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/config/CacheConfig.java b/backend/src/main/java/com/wordmarket/admin/config/CacheConfig.java
new file mode 100644
index 0000000..84d9adc
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/config/CacheConfig.java
@@ -0,0 +1,20 @@
+package com.wordmarket.admin.config;
+
+import com.github.benmanes.caffeine.cache.Cache;
+import com.github.benmanes.caffeine.cache.Caffeine;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import java.time.Duration;
+
+@Configuration
+public class CacheConfig {
+
+ @Bean
+ public Cache caffeineAggregateCache(AppProperties properties) {
+ return Caffeine.newBuilder()
+ .expireAfterWrite(Duration.ofMinutes(properties.getCache().getTtlMinutes()))
+ .maximumSize(properties.getCache().getMaximumSize())
+ .build();
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/config/MybatisPlusConfig.java b/backend/src/main/java/com/wordmarket/admin/config/MybatisPlusConfig.java
new file mode 100644
index 0000000..dc9e6d7
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/config/MybatisPlusConfig.java
@@ -0,0 +1,20 @@
+package com.wordmarket.admin.config;
+
+import com.baomidou.mybatisplus.annotation.DbType;
+import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
+import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class MybatisPlusConfig {
+
+ @Bean
+ public MybatisPlusInterceptor mybatisPlusInterceptor() {
+ MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
+ PaginationInnerInterceptor pagination = new PaginationInnerInterceptor(DbType.MYSQL);
+ pagination.setMaxLimit(100L);
+ interceptor.addInnerInterceptor(pagination);
+ return interceptor;
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/config/SecurityConfig.java b/backend/src/main/java/com/wordmarket/admin/config/SecurityConfig.java
new file mode 100644
index 0000000..ea6c4bc
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/config/SecurityConfig.java
@@ -0,0 +1,79 @@
+package com.wordmarket.admin.config;
+
+import com.wordmarket.admin.security.JwtAuthFilter;
+import com.wordmarket.admin.security.RestAuthEntryPoint;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.http.HttpMethod;
+import org.springframework.security.config.Customizer;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
+import org.springframework.security.config.http.SessionCreationPolicy;
+import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
+import org.springframework.web.cors.CorsConfiguration;
+import org.springframework.web.cors.CorsConfigurationSource;
+import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
+
+import java.util.Arrays;
+import java.util.List;
+
+@Configuration
+@EnableWebSecurity
+public class SecurityConfig {
+
+ private final JwtAuthFilter jwtAuthFilter;
+ private final RestAuthEntryPoint restAuthEntryPoint;
+ private final AppProperties appProperties;
+
+ public SecurityConfig(JwtAuthFilter jwtAuthFilter, RestAuthEntryPoint restAuthEntryPoint,
+ AppProperties appProperties) {
+ this.jwtAuthFilter = jwtAuthFilter;
+ this.restAuthEntryPoint = restAuthEntryPoint;
+ this.appProperties = appProperties;
+ }
+
+ @Bean
+ public PasswordEncoder passwordEncoder() {
+ return new BCryptPasswordEncoder();
+ }
+
+ @Bean
+ public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
+ return http
+ .csrf(AbstractHttpConfigurer::disable)
+ .cors(Customizer.withDefaults())
+ .sessionManagement(session ->
+ session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+ .authorizeHttpRequests(authorize -> authorize
+ .requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()
+ .requestMatchers("/api/auth/login", "/error").permitAll()
+ .anyRequest().authenticated())
+ .exceptionHandling(handling ->
+ handling.authenticationEntryPoint(restAuthEntryPoint))
+ .addFilterBefore(jwtAuthFilter, UsernamePasswordAuthenticationFilter.class)
+ .httpBasic(AbstractHttpConfigurer::disable)
+ .formLogin(AbstractHttpConfigurer::disable)
+ .logout(AbstractHttpConfigurer::disable)
+ .build();
+ }
+
+ @Bean
+ public CorsConfigurationSource corsConfigurationSource() {
+ CorsConfiguration configuration = new CorsConfiguration();
+ List origins = Arrays.stream(appProperties.getCors().getAllowedOrigins().split(","))
+ .map(String::trim)
+ .filter(value -> !value.isEmpty())
+ .toList();
+ configuration.setAllowedOrigins(origins);
+ configuration.setAllowedMethods(List.of("GET", "POST", "OPTIONS"));
+ configuration.setAllowedHeaders(List.of("Authorization", "Content-Type"));
+ configuration.setMaxAge(3600L);
+ UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+ source.registerCorsConfiguration("/api/**", configuration);
+ return source;
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/controller/AuthController.java b/backend/src/main/java/com/wordmarket/admin/controller/AuthController.java
new file mode 100644
index 0000000..09c463d
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/controller/AuthController.java
@@ -0,0 +1,27 @@
+package com.wordmarket.admin.controller;
+
+import com.wordmarket.admin.common.ApiResponse;
+import com.wordmarket.admin.dto.AuthDtos.LoginRequest;
+import com.wordmarket.admin.dto.AuthDtos.LoginResponse;
+import com.wordmarket.admin.service.AuthService;
+import jakarta.validation.Valid;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api/auth")
+public class AuthController {
+
+ private final AuthService authService;
+
+ public AuthController(AuthService authService) {
+ this.authService = authService;
+ }
+
+ @PostMapping("/login")
+ public ApiResponse login(@Valid @RequestBody LoginRequest request) {
+ return ApiResponse.ok(authService.login(request));
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/controller/BookController.java b/backend/src/main/java/com/wordmarket/admin/controller/BookController.java
new file mode 100644
index 0000000..e5cf355
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/controller/BookController.java
@@ -0,0 +1,58 @@
+package com.wordmarket.admin.controller;
+
+import com.wordmarket.admin.common.ApiResponse;
+import com.wordmarket.admin.common.Items;
+import com.wordmarket.admin.common.PageResult;
+import com.wordmarket.admin.dto.BookDtos.BookDetail;
+import com.wordmarket.admin.dto.BookDtos.BookEntryItem;
+import com.wordmarket.admin.dto.BookDtos.BookListItem;
+import com.wordmarket.admin.dto.BookDtos.ExamOption;
+import com.wordmarket.admin.service.BookService;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+@RestController
+@RequestMapping("/api")
+public class BookController {
+
+ private final BookService bookService;
+
+ public BookController(BookService bookService) {
+ this.bookService = bookService;
+ }
+
+ @GetMapping("/books")
+ public ApiResponse> list(
+ @RequestParam(required = false) Integer page,
+ @RequestParam(required = false) Integer size,
+ @RequestParam(required = false) Long examId,
+ @RequestParam(required = false) String keyword,
+ @RequestParam(required = false) Boolean hasFile) {
+ return ApiResponse.ok(bookService.list(page, size, examId, keyword, hasFile));
+ }
+
+ @GetMapping("/books/{id}")
+ public ApiResponse detail(@PathVariable long id) {
+ return ApiResponse.ok(bookService.detail(id));
+ }
+
+ @GetMapping("/books/{id}/entries")
+ public ApiResponse> entries(
+ @PathVariable long id,
+ @RequestParam(required = false) Integer page,
+ @RequestParam(required = false) Integer size,
+ @RequestParam(required = false) String keyword) {
+ return ApiResponse.ok(bookService.entries(id, page, size, keyword));
+ }
+
+ @GetMapping("/exams")
+ public ApiResponse> exams() {
+ List options = bookService.exams();
+ return ApiResponse.ok(Items.of(options));
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/controller/DashboardController.java b/backend/src/main/java/com/wordmarket/admin/controller/DashboardController.java
new file mode 100644
index 0000000..c8f3fd9
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/controller/DashboardController.java
@@ -0,0 +1,48 @@
+package com.wordmarket.admin.controller;
+
+import com.wordmarket.admin.common.ApiResponse;
+import com.wordmarket.admin.common.Items;
+import com.wordmarket.admin.dto.DashboardDtos.ExamStat;
+import com.wordmarket.admin.dto.DashboardDtos.PosStat;
+import com.wordmarket.admin.dto.DashboardDtos.Summary;
+import com.wordmarket.admin.dto.DashboardDtos.TopBook;
+import com.wordmarket.admin.service.DashboardService;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api/dashboard")
+public class DashboardController {
+
+ private final DashboardService dashboardService;
+
+ public DashboardController(DashboardService dashboardService) {
+ this.dashboardService = dashboardService;
+ }
+
+ @GetMapping("/summary")
+ public ApiResponse summary(
+ @RequestParam(defaultValue = "false") boolean refresh) {
+ return ApiResponse.ok(dashboardService.summary(refresh));
+ }
+
+ @GetMapping("/exam-distribution")
+ public ApiResponse> examDistribution(
+ @RequestParam(defaultValue = "false") boolean refresh) {
+ return ApiResponse.ok(Items.of(dashboardService.examDistribution(refresh)));
+ }
+
+ @GetMapping("/book-size-top")
+ public ApiResponse> bookSizeTop(
+ @RequestParam(defaultValue = "false") boolean refresh) {
+ return ApiResponse.ok(Items.of(dashboardService.topBooks(refresh)));
+ }
+
+ @GetMapping("/pos-distribution")
+ public ApiResponse> posDistribution(
+ @RequestParam(defaultValue = "false") boolean refresh) {
+ return ApiResponse.ok(Items.of(dashboardService.posDistribution(refresh)));
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/controller/EntryController.java b/backend/src/main/java/com/wordmarket/admin/controller/EntryController.java
new file mode 100644
index 0000000..0af36e3
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/controller/EntryController.java
@@ -0,0 +1,87 @@
+package com.wordmarket.admin.controller;
+
+import com.wordmarket.admin.common.ApiResponse;
+import com.wordmarket.admin.common.Items;
+import com.wordmarket.admin.common.PageResult;
+import com.wordmarket.admin.dto.EntryDtos.ConfusableItem;
+import com.wordmarket.admin.dto.EntryDtos.EntryBookItem;
+import com.wordmarket.admin.dto.EntryDtos.EntryDetail;
+import com.wordmarket.admin.dto.EntryDtos.EntryListItem;
+import com.wordmarket.admin.dto.EntryDtos.ExampleGroupItem;
+import com.wordmarket.admin.dto.EntryDtos.PhraseItem;
+import com.wordmarket.admin.dto.EntryDtos.SenseItem;
+import com.wordmarket.admin.dto.EntryDtos.SpellingVariantItem;
+import com.wordmarket.admin.service.EntryService;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+@RestController
+@RequestMapping("/api/entries")
+public class EntryController {
+
+ private final EntryService entryService;
+
+ public EntryController(EntryService entryService) {
+ this.entryService = entryService;
+ }
+
+ @GetMapping
+ public ApiResponse> list(
+ @RequestParam(required = false) Integer page,
+ @RequestParam(required = false) Integer size,
+ @RequestParam(required = false) String keyword) {
+ return ApiResponse.ok(entryService.list(page, size, keyword));
+ }
+
+ @GetMapping("/{id}")
+ public ApiResponse detail(@PathVariable long id) {
+ return ApiResponse.ok(entryService.detail(id));
+ }
+
+ @GetMapping("/{id}/senses")
+ public ApiResponse> senses(@PathVariable long id) {
+ List items = entryService.senses(id);
+ return ApiResponse.ok(Items.of(items));
+ }
+
+ @GetMapping("/{id}/phrases")
+ public ApiResponse> phrases(
+ @PathVariable long id,
+ @RequestParam(required = false) Integer page,
+ @RequestParam(required = false) Integer size) {
+ return ApiResponse.ok(entryService.phrases(id, page, size));
+ }
+
+ @GetMapping("/{id}/examples")
+ public ApiResponse> examples(
+ @PathVariable long id,
+ @RequestParam(required = false) Integer page,
+ @RequestParam(required = false) Integer size) {
+ return ApiResponse.ok(entryService.examples(id, page, size));
+ }
+
+ @GetMapping("/{id}/confusables")
+ public ApiResponse> confusables(@PathVariable long id) {
+ List items = entryService.confusables(id);
+ return ApiResponse.ok(Items.of(items));
+ }
+
+ @GetMapping("/{id}/variants")
+ public ApiResponse> variants(@PathVariable long id) {
+ List items = entryService.spellingVariants(id);
+ return ApiResponse.ok(Items.of(items));
+ }
+
+ @GetMapping("/{id}/books")
+ public ApiResponse> books(
+ @PathVariable long id,
+ @RequestParam(required = false) Integer page,
+ @RequestParam(required = false) Integer size) {
+ return ApiResponse.ok(entryService.books(id, page, size));
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/controller/MorphologyController.java b/backend/src/main/java/com/wordmarket/admin/controller/MorphologyController.java
new file mode 100644
index 0000000..3523f33
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/controller/MorphologyController.java
@@ -0,0 +1,77 @@
+package com.wordmarket.admin.controller;
+
+import com.wordmarket.admin.common.ApiResponse;
+import com.wordmarket.admin.common.PageResult;
+import com.wordmarket.admin.dto.MorphologyDtos.CardDetail;
+import com.wordmarket.admin.dto.MorphologyDtos.CardItem;
+import com.wordmarket.admin.dto.MorphologyDtos.FamilyDetail;
+import com.wordmarket.admin.dto.MorphologyDtos.FamilyItem;
+import com.wordmarket.admin.dto.MorphologyDtos.MorphemeDetail;
+import com.wordmarket.admin.dto.MorphologyDtos.MorphemeItem;
+import com.wordmarket.admin.dto.MorphologyDtos.TreePage;
+import com.wordmarket.admin.service.MorphologyService;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api")
+public class MorphologyController {
+
+ private final MorphologyService morphologyService;
+
+ public MorphologyController(MorphologyService morphologyService) {
+ this.morphologyService = morphologyService;
+ }
+
+ @GetMapping("/morphemes")
+ public ApiResponse> morphemes(
+ @RequestParam(required = false) String type,
+ @RequestParam(required = false) String keyword,
+ @RequestParam(required = false) Integer page,
+ @RequestParam(required = false) Integer size) {
+ return ApiResponse.ok(morphologyService.morphemes(type, keyword, page, size));
+ }
+
+ @GetMapping("/morphemes/{id}")
+ public ApiResponse morpheme(@PathVariable long id) {
+ return ApiResponse.ok(morphologyService.morpheme(id));
+ }
+
+ @GetMapping("/cards")
+ public ApiResponse> cards(
+ @RequestParam(required = false) String keyword,
+ @RequestParam(required = false) Integer page,
+ @RequestParam(required = false) Integer size) {
+ return ApiResponse.ok(morphologyService.cards(keyword, page, size));
+ }
+
+ @GetMapping("/cards/{id}")
+ public ApiResponse card(@PathVariable long id) {
+ return ApiResponse.ok(morphologyService.card(id));
+ }
+
+ @GetMapping("/families")
+ public ApiResponse> families(
+ @RequestParam(required = false) String keyword,
+ @RequestParam(required = false) Integer page,
+ @RequestParam(required = false) Integer size) {
+ return ApiResponse.ok(morphologyService.families(keyword, page, size));
+ }
+
+ @GetMapping("/families/{id}")
+ public ApiResponse family(@PathVariable long id) {
+ return ApiResponse.ok(morphologyService.family(id));
+ }
+
+ @GetMapping("/families/{id}/tree")
+ public ApiResponse tree(
+ @PathVariable long id,
+ @RequestParam(required = false) String nodeType,
+ @RequestParam(required = false) Integer page,
+ @RequestParam(required = false) Integer size) {
+ return ApiResponse.ok(morphologyService.tree(id, nodeType, page, size));
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/controller/QualityController.java b/backend/src/main/java/com/wordmarket/admin/controller/QualityController.java
new file mode 100644
index 0000000..966b2be
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/controller/QualityController.java
@@ -0,0 +1,53 @@
+package com.wordmarket.admin.controller;
+
+import com.wordmarket.admin.common.ApiResponse;
+import com.wordmarket.admin.common.Items;
+import com.wordmarket.admin.dto.QualityDtos.Coverage;
+import com.wordmarket.admin.dto.QualityDtos.DeclaredDiff;
+import com.wordmarket.admin.dto.QualityDtos.MissingReference;
+import com.wordmarket.admin.dto.QualityDtos.QualitySummary;
+import com.wordmarket.admin.service.QualityService;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+@RestController
+@RequestMapping("/api/quality")
+public class QualityController {
+
+ private final QualityService qualityService;
+
+ public QualityController(QualityService qualityService) {
+ this.qualityService = qualityService;
+ }
+
+ @GetMapping("/summary")
+ public ApiResponse summary(
+ @RequestParam(defaultValue = "false") boolean refresh) {
+ return ApiResponse.ok(qualityService.summary(refresh));
+ }
+
+ @GetMapping("/declared-vs-actual")
+ public ApiResponse> declaredVsActual(
+ @RequestParam(defaultValue = "false") boolean refresh) {
+ List items = qualityService.declaredVsActual(refresh);
+ return ApiResponse.ok(Items.of(items));
+ }
+
+ @GetMapping("/missing-references")
+ public ApiResponse> missingReferences(
+ @RequestParam(defaultValue = "false") boolean refresh) {
+ List items = qualityService.missingReferences(refresh);
+ return ApiResponse.ok(Items.of(items));
+ }
+
+ @GetMapping("/cross-domain-coverage")
+ public ApiResponse> crossDomainCoverage(
+ @RequestParam(defaultValue = "false") boolean refresh) {
+ List items = qualityService.crossDomainCoverage(refresh);
+ return ApiResponse.ok(Items.of(items));
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/controller/SynonymController.java b/backend/src/main/java/com/wordmarket/admin/controller/SynonymController.java
new file mode 100644
index 0000000..1315038
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/controller/SynonymController.java
@@ -0,0 +1,46 @@
+package com.wordmarket.admin.controller;
+
+import com.wordmarket.admin.common.ApiResponse;
+import com.wordmarket.admin.common.Items;
+import com.wordmarket.admin.common.PageResult;
+import com.wordmarket.admin.dto.SynonymDtos.SizeBucket;
+import com.wordmarket.admin.dto.SynonymDtos.WordDetail;
+import com.wordmarket.admin.dto.SynonymDtos.WordItem;
+import com.wordmarket.admin.service.SynonymService;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+
+@RestController
+@RequestMapping("/api/synonyms")
+public class SynonymController {
+
+ private final SynonymService synonymService;
+
+ public SynonymController(SynonymService synonymService) {
+ this.synonymService = synonymService;
+ }
+
+ @GetMapping
+ public ApiResponse> list(
+ @RequestParam(required = false) Integer page,
+ @RequestParam(required = false) Integer size,
+ @RequestParam(required = false) String keyword) {
+ return ApiResponse.ok(synonymService.list(page, size, keyword));
+ }
+
+ @GetMapping("/group-size-distribution")
+ public ApiResponse> distribution() {
+ List items = synonymService.groupSizeDistribution();
+ return ApiResponse.ok(Items.of(items));
+ }
+
+ @GetMapping("/{wordId}")
+ public ApiResponse detail(@PathVariable long wordId) {
+ return ApiResponse.ok(synonymService.detail(wordId));
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/dto/AuthDtos.java b/backend/src/main/java/com/wordmarket/admin/dto/AuthDtos.java
new file mode 100644
index 0000000..e887a1a
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/dto/AuthDtos.java
@@ -0,0 +1,16 @@
+package com.wordmarket.admin.dto;
+
+import jakarta.validation.constraints.NotBlank;
+
+public final class AuthDtos {
+
+ private AuthDtos() {
+ }
+
+ public record LoginRequest(@NotBlank(message = "用户名不能为空") String username,
+ @NotBlank(message = "密码不能为空") String password) {
+ }
+
+ public record LoginResponse(String token, String expiresAt, String username) {
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/dto/BookDtos.java b/backend/src/main/java/com/wordmarket/admin/dto/BookDtos.java
new file mode 100644
index 0000000..9395695
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/dto/BookDtos.java
@@ -0,0 +1,31 @@
+package com.wordmarket.admin.dto;
+
+public final class BookDtos {
+
+ private BookDtos() {
+ }
+
+ public record ExamOption(String id, String code, String name) {
+ }
+
+ public record BookListItem(String id, String code, String name, String examId, String examName,
+ Long declared, long actual, boolean hasFile, String coverPath) {
+ }
+
+ public record BookDetail(String id, String code, String name, String description, String examId,
+ String examName, Long declared, long actual, Integer contentVersion,
+ Integer schemaVersion, String coverPath, String packageUrl, boolean hasFile,
+ Long sortAt, String labels, boolean mismatch) {
+ }
+
+ public record BookDetailRow(String id, String code, String name, String description, String examId,
+ String examName, Long declared, long actual, Integer contentVersion,
+ Integer schemaVersion, String coverPath, String packageUrl,
+ boolean hasFile, Long sortAt, String labels) {
+ }
+
+ public record BookEntryItem(String entryId, String displayWord, String headwordText,
+ Integer seqBook, Integer seqAz, Integer seqFreq, String headword,
+ String indexWord) {
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/dto/DashboardDtos.java b/backend/src/main/java/com/wordmarket/admin/dto/DashboardDtos.java
new file mode 100644
index 0000000..480192d
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/dto/DashboardDtos.java
@@ -0,0 +1,32 @@
+package com.wordmarket.admin.dto;
+
+import java.util.List;
+
+public final class DashboardDtos {
+
+ private DashboardDtos() {
+ }
+
+ public record Kpi(String key, String label, long value, String note, String tone) {
+ }
+
+ public record QualityItem(String key, String label, long value, String unit, String level,
+ String target) {
+ }
+
+ public record CoverageItem(String name, long hit, long total, double pct) {
+ }
+
+ public record Summary(List kpis, List quality, List coverage) {
+ }
+
+ public record ExamStat(String name, String code, long books, long entries) {
+ }
+
+ public record TopBook(String id, String name, String code, String exam, Long declared,
+ long actual, String coverPath) {
+ }
+
+ public record PosStat(String name, long value) {
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/dto/EntryDtos.java b/backend/src/main/java/com/wordmarket/admin/dto/EntryDtos.java
new file mode 100644
index 0000000..a3ee72c
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/dto/EntryDtos.java
@@ -0,0 +1,111 @@
+package com.wordmarket.admin.dto;
+
+import java.util.List;
+
+public final class EntryDtos {
+
+ private EntryDtos() {
+ }
+
+ public record ExamRef(String id, String code, String name) {
+ }
+
+ public record EntryListItem(String id, String headword, String indexWord, String pronunciation,
+ String definition, long senseCount, long bookCount) {
+ }
+
+ public record EntryDetail(String id, String headword, String indexWord, String usPronunciation,
+ String ukPronunciation, String definitionText, String dataVersion,
+ String bookExamId, String bookExamName, Integer occurrenceCount,
+ boolean hasListeningExamples, String sourceZpkKey) {
+ }
+
+ public record SenseRelation(String type, Integer position, String targetMeaningId,
+ String targetEntryId) {
+ }
+
+ public record SenseItem(String senseId, Integer senseNo, String partOfSpeech, String glossZh,
+ List exams, List relations) {
+ }
+
+ public record PhraseOrder(String examId, String examName, Integer groupType, Integer position) {
+ }
+
+ public record PhraseItem(String id, String textEn, String textZh, Integer groupType,
+ String meaningId, List exams, List orders) {
+ }
+
+ public record ExampleSentenceItem(String id, String textEn, String textZh, String sourceTitle,
+ String audioUrl, boolean listening) {
+ }
+
+ public record ExampleUsageItem(String id, String patternId, String patternText, Integer position,
+ List sentences) {
+ }
+
+ public record ExampleGroupItem(String id, Integer groupKind, String partOfSpeech,
+ String entryKindCode, String headForm, String definitionEn,
+ String definitionZh, List exams,
+ List usages,
+ List directSentences, long sentenceCount) {
+ }
+
+ public record ConfusableItem(String id, String wordText, String glossZh, Integer posCode,
+ String spellingFlag, Integer position) {
+ }
+
+ public record SpellingVariantItem(Integer position, String variant) {
+ }
+
+ public record EntryBookItem(String bookId, String bookName, String bookCode, String displayWord,
+ Integer seqBook) {
+ }
+
+ public record SenseExamRow(String senseId, String id, String code, String name) {
+ }
+
+ public record SenseRelationRow(String senseId, String type, Integer position, String targetMeaningId,
+ String targetEntryId) {
+ }
+
+ public record GroupExamRow(String groupId, String id, String code, String name) {
+ }
+
+ public record UsageRow(String id, String groupId, String patternId, String patternText,
+ Integer position) {
+ }
+
+ public record SentenceRow(String id, String groupId, String usageId, String textEn, String textZh,
+ String sourceTitle, String audioUrl, boolean listening) {
+ }
+
+ public record PhraseExamRow(String phraseId, String id, String code, String name) {
+ }
+
+ public record PhraseOrderRow(String examId, String examName, Integer groupType, Integer position,
+ String phraseId) {
+ }
+
+ public record SenseRow(String senseId, Integer senseNo, String partOfSpeech, String glossZh) {
+ }
+
+ public record PhraseRow(String id, String textEn, String textZh, Integer groupType,
+ String meaningId) {
+ }
+
+ public record ExampleGroupRow(String id, Integer groupKind, String partOfSpeech,
+ String entryKindCode, String headForm, String definitionEn,
+ String definitionZh) {
+ }
+
+ public record ConfusableRow(String id, String wordText, String glossZh, Integer posCode,
+ String spellingFlag, Integer position) {
+ }
+
+ public record VariantRow(Integer position, String variant) {
+ }
+
+ public record EntryBookRow(String bookId, String bookName, String bookCode, String displayWord,
+ Integer seqBook) {
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/dto/MorphologyDtos.java b/backend/src/main/java/com/wordmarket/admin/dto/MorphologyDtos.java
new file mode 100644
index 0000000..59dafa0
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/dto/MorphologyDtos.java
@@ -0,0 +1,109 @@
+package com.wordmarket.admin.dto;
+
+import java.util.List;
+
+public final class MorphologyDtos {
+
+ private MorphologyDtos() {
+ }
+
+ public record ExamRef(String id, String code, String name) {
+ }
+
+ public record MorphemeItem(String id, String type, String form, String displayText, String meaningEn,
+ String meaningZh, String note) {
+ }
+
+ public record CardBrief(String id, String word, String memoryNote, String exampleText) {
+ }
+
+ public record CardRow(String id, String word, String highlightedWord, String memoryNote,
+ String exampleText, boolean hidden, String prefixMorphemeId,
+ String rootMorphemeId, String suffixMorphemeId, String defaultFamilyRef) {
+ }
+
+ public record CardItemRow(String id, String word, String memoryNote, String highlightedWord) {
+ }
+
+ public record FamilyRow(String id, String word, String topFamilyId, String topWord,
+ String interpretation, Integer groupLevel1, Integer groupLevel2,
+ Integer groupLevel3) {
+ }
+
+ public record FamilyLinkRow(String id, Integer groupNo, String familyRef, boolean hidden) {
+ }
+
+ public record MorphemeDetail(String id, String type, String form, String displayText,
+ String meaningEn, String meaningZh, String note,
+ List cards, long cardCount) {
+ }
+
+ public record CardItem(String id, String word, String memoryNote, String highlightedWord,
+ List exams) {
+ }
+
+ public record CardFamilyLink(String linkId, Integer groupNo, String familyRef, boolean hidden) {
+ }
+
+ public record CardDetail(String id, String word, String highlightedWord, String memoryNote,
+ String exampleText, boolean hidden, String prefixMorphemeId, String prefixForm,
+ String rootMorphemeId, String rootForm, String suffixMorphemeId,
+ String suffixForm, String defaultFamilyRef, List exams,
+ List familyLinks) {
+ }
+
+ public record FamilyItem(String id, String word, String topFamilyId, String topWord,
+ String interpretation, Integer groupLevel1, Integer groupLevel2,
+ Integer groupLevel3, List exams) {
+ }
+
+ public record FamilyVariantItem(String id, String variantWord, String interpretation,
+ long memberCount) {
+ }
+
+ public record FamilyMemberItem(String familyEntryId, String word, Integer position) {
+ }
+
+ public record MiniGroupItem(String id, Integer size, List members) {
+ }
+
+ public record FamilyDetail(String id, String word, String topFamilyId, String topWord,
+ String interpretation, Integer groupLevel1, Integer groupLevel2,
+ Integer groupLevel3, List exams,
+ List variants, List miniGroups) {
+ }
+
+ public record TreeNode(String nodeType, String id, String label, String subtitle, long memberCount,
+ boolean leaf) {
+ }
+
+ public record TreePage(List nodes, long total, int page, int size) {
+ }
+
+ public record LinkExamRow(String cardId, String id, String code, String name) {
+ }
+
+ public record FamilyExamRow(String familyEntryId, String id, String code, String name) {
+ }
+
+ public record MorphemeRefRow(String id, String form, String type, String meaningZh) {
+ }
+
+ public record FamilyWordRow(String id, String word, String interpretation) {
+ }
+
+ public record VariantRow(String id, String variantWord, String interpretation, long memberCount) {
+ }
+
+ public record MiniGroupRow(String id, Integer size) {
+ }
+
+ public record MemberRow(String familyEntryId, String word, Integer position) {
+ }
+
+ public record CountRow(long count) {
+ }
+
+ public record TreeCounts(long variantCount, long groupCount) {
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/dto/QualityDtos.java b/backend/src/main/java/com/wordmarket/admin/dto/QualityDtos.java
new file mode 100644
index 0000000..901e3c1
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/dto/QualityDtos.java
@@ -0,0 +1,36 @@
+package com.wordmarket.admin.dto;
+
+import java.util.List;
+
+public final class QualityDtos {
+
+ private QualityDtos() {
+ }
+
+ public record SummaryItem(String key, String label, long value, String unit, String level,
+ String description) {
+ }
+
+ public record QualitySummary(List items) {
+ }
+
+ public record DeclaredDiff(String bookId, String bookName, String bookCode, String examName,
+ long declared, long actual, long diff) {
+ }
+
+ public record MissingReference(String type, String identifier, String source, String detail,
+ String bookId) {
+ }
+
+ public record Coverage(String key, String name, long hit, long total, double pct) {
+ }
+
+ public record MissingBook(String bookId, String bookCode, String bookName) {
+ }
+
+ public record MissingZpk(String sourceKey, long rowCount, String bookIds) {
+ }
+
+ public record CountPair(long total, long hit) {
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/dto/SynonymDtos.java b/backend/src/main/java/com/wordmarket/admin/dto/SynonymDtos.java
new file mode 100644
index 0000000..2b5ab26
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/dto/SynonymDtos.java
@@ -0,0 +1,55 @@
+package com.wordmarket.admin.dto;
+
+import java.util.List;
+
+public final class SynonymDtos {
+
+ private SynonymDtos() {
+ }
+
+ public record WordItem(String wordId, String word, long senseCount, boolean hasRelation) {
+ }
+
+ public record WordRow(String wordId, String word) {
+ }
+
+ public record SenseRow(String senseId, String partOfSpeech, String glossZh) {
+ }
+
+ public record MemberItem(String wordId, String word, Integer position) {
+ }
+
+ public record GroupItem(String examId, String examName, String canonicalWordId, String canonicalWord,
+ Integer memberCount, List members, boolean truncated) {
+ }
+
+ public record AntonymItem(String examId, String examName, List words) {
+ }
+
+ public record SenseItem(String senseId, String partOfSpeech, String glossZh, List groups,
+ List antonyms) {
+ }
+
+ public record WordDetail(String wordId, String word, List senses) {
+ }
+
+ public record SizeBucket(String label, long count, double pct) {
+ }
+
+ public record GroupRow(String senseId, String examId, String examName, String canonicalWordId,
+ String canonicalWord, Integer memberCount) {
+ }
+
+ public record MemberRow(String senseId, String examId, String wordId, String word, Integer position) {
+ }
+
+ public record AntonymRow(String senseId, String examId, String examName, String wordId, String word,
+ Integer position) {
+ }
+
+ public record ExamRow(String examId, String examName) {
+ }
+
+ public record BucketRow(String label, long count) {
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/mapper/BookMapper.java b/backend/src/main/java/com/wordmarket/admin/mapper/BookMapper.java
new file mode 100644
index 0000000..a84988c
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/mapper/BookMapper.java
@@ -0,0 +1,129 @@
+package com.wordmarket.admin.mapper;
+
+import com.wordmarket.admin.dto.BookDtos.BookDetailRow;
+import com.wordmarket.admin.dto.BookDtos.BookEntryItem;
+import com.wordmarket.admin.dto.BookDtos.BookListItem;
+import com.wordmarket.admin.dto.BookDtos.ExamOption;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+import java.util.List;
+
+@Mapper
+public interface BookMapper {
+
+ @Select("""
+
+ """)
+ long countBooks(@Param("examId") Long examId, @Param("keyword") String keyword,
+ @Param("hasFile") Boolean hasFile);
+
+ @Select("""
+
+ """)
+ List listBooks(@Param("examId") Long examId, @Param("keyword") String keyword,
+ @Param("hasFile") Boolean hasFile, @Param("offset") int offset,
+ @Param("limit") int limit);
+
+ @Select("""
+ SELECT b.book_id AS id,
+ b.book_code AS code,
+ b.book_name AS name,
+ b.description,
+ b.exam_id AS exam_id,
+ e.exam_name_zh AS exam_name,
+ b.declared_entry_count AS declared,
+ (SELECT COUNT(*) FROM book_entry be WHERE be.book_id = b.book_id) AS actual,
+ b.content_version,
+ b.schema_version,
+ b.cover_url AS cover_path,
+ b.package_url,
+ b.has_wordbook_file AS has_file,
+ b.sort_at,
+ b.labels
+ FROM book b
+ LEFT JOIN exam e ON e.exam_id = b.exam_id
+ WHERE b.book_id = #{id}
+ """)
+ BookDetailRow findBook(@Param("id") long id);
+
+ @Select("""
+
+ """)
+ long countBookEntries(@Param("bookId") long bookId, @Param("keyword") String keyword);
+
+ @Select("""
+
+ """)
+ List listBookEntries(@Param("bookId") long bookId,
+ @Param("keyword") String keyword,
+ @Param("offset") int offset, @Param("limit") int limit);
+
+ @Select("""
+ SELECT exam_id AS id, exam_code AS code, exam_name_zh AS name
+ FROM exam
+ WHERE is_pseudo = 0
+ ORDER BY exam_id
+ """)
+ List listExams();
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/mapper/DashboardMapper.java b/backend/src/main/java/com/wordmarket/admin/mapper/DashboardMapper.java
new file mode 100644
index 0000000..042d4fc
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/mapper/DashboardMapper.java
@@ -0,0 +1,87 @@
+package com.wordmarket.admin.mapper;
+
+import com.wordmarket.admin.dto.DashboardDtos.ExamStat;
+import com.wordmarket.admin.dto.DashboardDtos.PosStat;
+import com.wordmarket.admin.dto.DashboardDtos.TopBook;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Select;
+
+import java.util.List;
+
+@Mapper
+public interface DashboardMapper {
+
+ @Select("SELECT COUNT(*) FROM book")
+ long countBooks();
+
+ @Select("SELECT COUNT(*) FROM book WHERE has_wordbook_file = 0")
+ long countBooksWithoutFile();
+
+ @Select("SELECT COUNT(*) FROM word_entry")
+ long countEntries();
+
+ @Select("SELECT COUNT(DISTINCT index_word) FROM word_entry")
+ long countIndexWords();
+
+ @Select("SELECT COUNT(*) FROM book_entry")
+ long countBookEntries();
+
+ @Select("SELECT COUNT(*) FROM example_sentence")
+ long countExampleSentences();
+
+ @Select("SELECT COUNT(*) FROM example_usage")
+ long countExampleUsages();
+
+ @Select("SELECT COUNT(*) FROM word_family")
+ long countFamilies();
+
+ @Select("SELECT COUNT(DISTINCT top_family_id) FROM word_family")
+ long countTopFamilies();
+
+ @Select("SELECT COUNT(*) FROM synonym_word")
+ long countSynonymWords();
+
+ @Select("SELECT COUNT(*) FROM synonym_sense")
+ long countSynonymSenses();
+
+ @Select("""
+
+ """)
+ List examDistribution();
+
+ @Select("""
+ SELECT b.book_id AS id,
+ b.book_name AS name,
+ b.book_code AS code,
+ e.exam_name_zh AS exam,
+ b.declared_entry_count AS declared,
+ (SELECT COUNT(*) FROM book_entry be WHERE be.book_id = b.book_id) AS actual,
+ b.cover_url AS cover_path
+ FROM book b
+ LEFT JOIN exam e ON e.exam_id = b.exam_id
+ ORDER BY actual DESC, b.book_id
+ LIMIT 10
+ """)
+ List topBooks();
+
+ @Select("""
+ SELECT COALESCE(NULLIF(part_of_speech, ''), '未标注') AS name,
+ COUNT(*) AS value
+ FROM word_sense
+ GROUP BY part_of_speech
+ ORDER BY value DESC, name
+ LIMIT 10
+ """)
+ List posDistribution();
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/mapper/EntryMapper.java b/backend/src/main/java/com/wordmarket/admin/mapper/EntryMapper.java
new file mode 100644
index 0000000..40f53e8
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/mapper/EntryMapper.java
@@ -0,0 +1,232 @@
+package com.wordmarket.admin.mapper;
+
+import com.wordmarket.admin.dto.EntryDtos.ConfusableRow;
+import com.wordmarket.admin.dto.EntryDtos.EntryBookRow;
+import com.wordmarket.admin.dto.EntryDtos.EntryDetail;
+import com.wordmarket.admin.dto.EntryDtos.EntryListItem;
+import com.wordmarket.admin.dto.EntryDtos.ExampleGroupRow;
+import com.wordmarket.admin.dto.EntryDtos.GroupExamRow;
+import com.wordmarket.admin.dto.EntryDtos.PhraseExamRow;
+import com.wordmarket.admin.dto.EntryDtos.PhraseOrderRow;
+import com.wordmarket.admin.dto.EntryDtos.PhraseRow;
+import com.wordmarket.admin.dto.EntryDtos.SenseExamRow;
+import com.wordmarket.admin.dto.EntryDtos.SenseRelationRow;
+import com.wordmarket.admin.dto.EntryDtos.SenseRow;
+import com.wordmarket.admin.dto.EntryDtos.SentenceRow;
+import com.wordmarket.admin.dto.EntryDtos.UsageRow;
+import com.wordmarket.admin.dto.EntryDtos.VariantRow;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+import java.util.List;
+
+@Mapper
+public interface EntryMapper {
+
+ @Select("""
+
+ """)
+ long countEntries(@Param("keyword") String keyword);
+
+ @Select("""
+
+ """)
+ List listEntries(@Param("keyword") String keyword, @Param("offset") int offset,
+ @Param("limit") int limit);
+
+ @Select("""
+ SELECT e.entry_id AS id,
+ e.headword,
+ e.index_word,
+ e.us_pronunciation,
+ e.uk_pronunciation,
+ e.definition_text,
+ e.data_version,
+ e.book_exam_id AS book_exam_id,
+ ex.exam_name_zh AS book_exam_name,
+ e.occurrence_count,
+ e.has_listening_examples,
+ e.source_zpk_key
+ FROM word_entry e
+ LEFT JOIN exam ex ON ex.exam_id = e.book_exam_id
+ WHERE e.entry_id = #{id}
+ """)
+ EntryDetail findEntry(@Param("id") long id);
+
+ @Select("""
+ SELECT sense_id, sense_no, part_of_speech, gloss_zh
+ FROM word_sense
+ WHERE entry_id = #{entryId}
+ ORDER BY sense_no, sense_id
+ """)
+ List listSenses(@Param("entryId") long entryId);
+
+ @Select("""
+
+ """)
+ List listSenseExams(@Param("ids") List ids);
+
+ @Select("""
+
+ """)
+ List listSenseRelations(@Param("ids") List ids);
+
+ @Select("SELECT COUNT(*) FROM phrase WHERE entry_id = #{entryId}")
+ long countPhrases(@Param("entryId") long entryId);
+
+ @Select("""
+ SELECT phrase_id AS id, text_en, text_zh, group_type, meaning_id
+ FROM phrase
+ WHERE entry_id = #{entryId}
+ ORDER BY phrase_id
+ LIMIT #{limit} OFFSET #{offset}
+ """)
+ List listPhrases(@Param("entryId") long entryId, @Param("offset") int offset,
+ @Param("limit") int limit);
+
+ @Select("""
+
+ """)
+ List listPhraseExams(@Param("ids") List ids);
+
+ @Select("""
+ SELECT p.exam_id, ex.exam_name_zh AS exam_name, p.group_type, p.position, p.phrase_id
+ FROM phrase_exam_order p
+ JOIN exam ex ON ex.exam_id = p.exam_id
+ WHERE p.entry_id = #{entryId}
+ ORDER BY p.exam_id, p.group_type, p.position
+ """)
+ List listPhraseOrders(@Param("entryId") long entryId);
+
+ @Select("SELECT COUNT(*) FROM example_group WHERE entry_id = #{entryId}")
+ long countExampleGroups(@Param("entryId") long entryId);
+
+ @Select("""
+ SELECT example_group_id AS id, group_kind, part_of_speech, entry_kind_code, head_form,
+ definition_en, definition_zh
+ FROM example_group
+ WHERE entry_id = #{entryId}
+ ORDER BY group_kind, example_group_id
+ LIMIT #{limit} OFFSET #{offset}
+ """)
+ List listExampleGroups(@Param("entryId") long entryId,
+ @Param("offset") int offset, @Param("limit") int limit);
+
+ @Select("""
+
+ """)
+ List listExampleGroupExams(@Param("ids") List ids);
+
+ @Select("""
+
+ """)
+ List listExampleUsages(@Param("ids") List ids);
+
+ @Select("""
+
+ """)
+ List listExampleSentences(@Param("ids") List ids);
+
+ @Select("""
+ SELECT confusable_id AS id, word_text, gloss_zh, pos_code, spelling_flag, position
+ FROM confusable_word
+ WHERE entry_id = #{entryId}
+ ORDER BY position, confusable_id
+ """)
+ List listConfusables(@Param("entryId") long entryId);
+
+ @Select("""
+ SELECT position, variant
+ FROM word_spelling_variant
+ WHERE entry_id = #{entryId}
+ ORDER BY position
+ """)
+ List listSpellingVariants(@Param("entryId") long entryId);
+
+ @Select("SELECT COUNT(*) FROM book_entry WHERE entry_id = #{entryId}")
+ long countEntryBooks(@Param("entryId") long entryId);
+
+ @Select("""
+ SELECT be.book_id AS book_id, b.book_name, b.book_code, be.display_word, be.seq_book
+ FROM book_entry be
+ JOIN book b ON b.book_id = be.book_id
+ WHERE be.entry_id = #{entryId}
+ ORDER BY b.book_id
+ LIMIT #{limit} OFFSET #{offset}
+ """)
+ List listEntryBooks(@Param("entryId") long entryId, @Param("offset") int offset,
+ @Param("limit") int limit);
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/mapper/MorphologyMapper.java b/backend/src/main/java/com/wordmarket/admin/mapper/MorphologyMapper.java
new file mode 100644
index 0000000..7291f66
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/mapper/MorphologyMapper.java
@@ -0,0 +1,326 @@
+package com.wordmarket.admin.mapper;
+
+import com.wordmarket.admin.dto.MorphologyDtos.CardBrief;
+import com.wordmarket.admin.dto.MorphologyDtos.CardRow;
+import com.wordmarket.admin.dto.MorphologyDtos.FamilyExamRow;
+import com.wordmarket.admin.dto.MorphologyDtos.FamilyLinkRow;
+import com.wordmarket.admin.dto.MorphologyDtos.FamilyRow;
+import com.wordmarket.admin.dto.MorphologyDtos.FamilyWordRow;
+import com.wordmarket.admin.dto.MorphologyDtos.LinkExamRow;
+import com.wordmarket.admin.dto.MorphologyDtos.MemberRow;
+import com.wordmarket.admin.dto.MorphologyDtos.MiniGroupRow;
+import com.wordmarket.admin.dto.MorphologyDtos.MorphemeItem;
+import com.wordmarket.admin.dto.MorphologyDtos.MorphemeRefRow;
+import com.wordmarket.admin.dto.MorphologyDtos.TreeNode;
+import com.wordmarket.admin.dto.MorphologyDtos.TreeCounts;
+import com.wordmarket.admin.dto.MorphologyDtos.VariantRow;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+import java.util.List;
+
+@Mapper
+public interface MorphologyMapper {
+
+ @Select("""
+
+ """)
+ long countMorphemes(@Param("type") String type, @Param("keyword") String keyword);
+
+ @Select("""
+
+ """)
+ List listMorphemes(@Param("type") String type, @Param("keyword") String keyword,
+ @Param("offset") int offset, @Param("limit") int limit);
+
+ @Select("""
+ SELECT morpheme_id AS id, morpheme_type AS type, form, display_text, meaning_en, meaning_zh,
+ note
+ FROM morpheme
+ WHERE morpheme_id = #{id}
+ """)
+ MorphemeItem findMorpheme(@Param("id") long id);
+
+ @Select("""
+ SELECT COUNT(*) FROM card
+ WHERE prefix_morpheme_id = #{id} OR root_morpheme_id = #{id} OR suffix_morpheme_id = #{id}
+ """)
+ long countCardsByMorpheme(@Param("id") long id);
+
+ @Select("""
+ SELECT card_id AS id, word, memory_note, example_text
+ FROM card
+ WHERE prefix_morpheme_id = #{id} OR root_morpheme_id = #{id} OR suffix_morpheme_id = #{id}
+ ORDER BY card_id
+ LIMIT 100
+ """)
+ List listCardsByMorpheme(@Param("id") long id);
+
+ @Select("""
+
+ """)
+ long countCards(@Param("keyword") String keyword);
+
+ @Select("""
+
+ """)
+ List listCards(@Param("keyword") String keyword,
+ @Param("offset") int offset,
+ @Param("limit") int limit);
+
+ @Select("""
+ SELECT card_id AS id, word, highlighted_word, memory_note, example_text, is_hidden AS hidden,
+ prefix_morpheme_id, root_morpheme_id, suffix_morpheme_id, default_family_ref
+ FROM card
+ WHERE card_id = #{id}
+ """)
+ CardRow findCard(@Param("id") long id);
+
+ @Select("""
+
+ """)
+ List listCardExams(@Param("ids") List ids);
+
+ @Select("""
+
+ """)
+ List listMorphemeRefs(@Param("ids") List ids);
+
+ @Select("""
+ SELECT link_id AS id, group_no, family_ref, is_hidden AS hidden
+ FROM card_family_link
+ WHERE card_id = #{cardId}
+ ORDER BY group_no, link_id
+ """)
+ List listCardFamilyLinks(@Param("cardId") long cardId);
+
+ @Select("""
+
+ """)
+ long countFamilies(@Param("keyword") String keyword);
+
+ @Select("""
+
+ """)
+ List listFamilies(@Param("keyword") String keyword, @Param("offset") int offset,
+ @Param("limit") int limit);
+
+ @Select("""
+ SELECT f.family_entry_id AS id, f.word, f.top_family_id AS top_family_id,
+ t.word AS top_word, f.interpretation,
+ f.group_level_1, f.group_level_2, f.group_level_3
+ FROM word_family f
+ LEFT JOIN word_family t ON t.family_entry_id = f.top_family_id
+ WHERE f.family_entry_id = #{id}
+ """)
+ FamilyRow findFamily(@Param("id") long id);
+
+ @Select("""
+
+ """)
+ List listFamilyExams(@Param("ids") List ids);
+
+ @Select("""
+ SELECT v.variant_id AS id, v.variant_word, v.interpretation,
+ (SELECT COUNT(*) FROM word_family_variant_member m
+ WHERE m.variant_id = v.variant_id) AS member_count
+ FROM word_family_variant v
+ WHERE v.top_family_id = #{topId}
+ ORDER BY v.variant_id
+ """)
+ List listVariants(@Param("topId") long topId);
+
+ @Select("""
+ SELECT mg.mini_group_id AS id, mg.size
+ FROM word_family_mini_group mg
+ WHERE EXISTS (
+ SELECT 1
+ FROM word_family_mini_group_member m
+ JOIN word_family f ON f.family_entry_id = m.family_entry_id
+ WHERE m.mini_group_id = mg.mini_group_id AND f.top_family_id = #{topId}
+ )
+ ORDER BY mg.mini_group_id
+ LIMIT 200
+ """)
+ List listMiniGroups(@Param("topId") long topId);
+
+ @Select("""
+ SELECT m.family_entry_id, f.word, m.position
+ FROM word_family_mini_group_member m
+ JOIN word_family f ON f.family_entry_id = m.family_entry_id
+ WHERE m.mini_group_id = #{miniGroupId}
+ ORDER BY m.position
+ LIMIT 50
+ """)
+ List listMiniGroupMembers(@Param("miniGroupId") long miniGroupId);
+
+ @Select("""
+ SELECT (SELECT COUNT(*) FROM word_family_variant v WHERE v.top_family_id = #{topId})
+ AS variant_count,
+ (SELECT COUNT(*) FROM word_family_mini_group mg WHERE EXISTS (
+ SELECT 1
+ FROM word_family_mini_group_member m
+ JOIN word_family f ON f.family_entry_id = m.family_entry_id
+ WHERE m.mini_group_id = mg.mini_group_id AND f.top_family_id = #{topId}))
+ AS group_count
+ """)
+ TreeCounts countTopChildren(@Param("topId") long topId);
+
+ @Select("""
+ SELECT * FROM (
+ SELECT 'variant' AS node_type,
+ CAST(v.variant_id AS CHAR) AS id,
+ v.variant_word AS label,
+ v.interpretation AS subtitle,
+ (SELECT COUNT(*) FROM word_family_variant_member m
+ WHERE m.variant_id = v.variant_id) AS member_count,
+ 0 AS leaf
+ FROM word_family_variant v
+ WHERE v.top_family_id = #{topId}
+ UNION ALL
+ SELECT 'miniGroup' AS node_type,
+ CAST(mg.mini_group_id AS CHAR) AS id,
+ CONCAT('小组 #', mg.mini_group_id) AS label,
+ CONCAT('成员 ', mg.size) AS subtitle,
+ mg.size AS member_count,
+ 0 AS leaf
+ FROM word_family_mini_group mg
+ WHERE EXISTS (
+ SELECT 1
+ FROM word_family_mini_group_member m
+ JOIN word_family f ON f.family_entry_id = m.family_entry_id
+ WHERE m.mini_group_id = mg.mini_group_id AND f.top_family_id = #{topId}
+ )
+ ) t
+ ORDER BY node_type, id
+ LIMIT #{limit} OFFSET #{offset}
+ """)
+ List listTopChildren(@Param("topId") long topId, @Param("offset") int offset,
+ @Param("limit") int limit);
+
+ @Select("SELECT COUNT(*) FROM word_family_variant_member WHERE variant_id = #{variantId}")
+ long countVariantMembers(@Param("variantId") long variantId);
+
+ @Select("""
+ SELECT 'member' AS node_type,
+ CONCAT('word:', vm.member_word, ':', vm.exam_id, ':', vm.position) AS id,
+ vm.member_word AS label,
+ CONCAT(COALESCE(ex.exam_name_zh, CONCAT('考试 ', vm.exam_id)), ' · 第 ',
+ vm.position, ' 位') AS subtitle,
+ 0 AS member_count,
+ 1 AS leaf
+ FROM word_family_variant_member vm
+ LEFT JOIN exam ex ON ex.exam_id = vm.exam_id
+ WHERE vm.variant_id = #{variantId}
+ ORDER BY vm.exam_id, vm.position
+ LIMIT #{limit} OFFSET #{offset}
+ """)
+ List listVariantMemberNodes(@Param("variantId") long variantId,
+ @Param("offset") int offset, @Param("limit") int limit);
+
+ @Select("SELECT COUNT(*) FROM word_family_mini_group_member WHERE mini_group_id = #{miniGroupId}")
+ long countMiniGroupMembers(@Param("miniGroupId") long miniGroupId);
+
+ @Select("""
+ SELECT 'member' AS node_type,
+ CONCAT('family:', m.family_entry_id) AS id,
+ f.word AS label,
+ CONCAT('词族内位置 ', m.position) AS subtitle,
+ 0 AS member_count,
+ 1 AS leaf
+ FROM word_family_mini_group_member m
+ JOIN word_family f ON f.family_entry_id = m.family_entry_id
+ WHERE m.mini_group_id = #{miniGroupId}
+ ORDER BY m.position
+ LIMIT #{limit} OFFSET #{offset}
+ """)
+ List listMiniGroupMemberNodes(@Param("miniGroupId") long miniGroupId,
+ @Param("offset") int offset, @Param("limit") int limit);
+
+ @Select("""
+
+ """)
+ List listFamilyWords(@Param("ids") List ids);
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/mapper/QualityMapper.java b/backend/src/main/java/com/wordmarket/admin/mapper/QualityMapper.java
new file mode 100644
index 0000000..fdc2d8c
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/mapper/QualityMapper.java
@@ -0,0 +1,112 @@
+package com.wordmarket.admin.mapper;
+
+import com.wordmarket.admin.dto.QualityDtos.DeclaredDiff;
+import com.wordmarket.admin.dto.QualityDtos.MissingBook;
+import com.wordmarket.admin.dto.QualityDtos.MissingZpk;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+import java.util.List;
+
+@Mapper
+public interface QualityMapper {
+
+ @Select("""
+ SELECT COUNT(*)
+ FROM book b
+ WHERE b.declared_entry_count IS NOT NULL
+ AND b.declared_entry_count <> (SELECT COUNT(*) FROM book_entry be WHERE be.book_id = b.book_id)
+ """)
+ long countDeclaredMismatch();
+
+ @Select("""
+ SELECT b.book_id AS book_id,
+ b.book_name,
+ b.book_code,
+ e.exam_name_zh AS exam_name,
+ b.declared_entry_count AS declared,
+ (SELECT COUNT(*) FROM book_entry be WHERE be.book_id = b.book_id) AS actual,
+ (SELECT COUNT(*) FROM book_entry be WHERE be.book_id = b.book_id)
+ - b.declared_entry_count AS diff
+ FROM book b
+ LEFT JOIN exam e ON e.exam_id = b.exam_id
+ WHERE b.declared_entry_count IS NOT NULL
+ AND b.declared_entry_count <> (SELECT COUNT(*) FROM book_entry be WHERE be.book_id = b.book_id)
+ ORDER BY ABS(diff) DESC, b.book_id
+ """)
+ List listDeclaredMismatch();
+
+ @Select("SELECT COUNT(*) FROM book WHERE has_wordbook_file = 0")
+ long countMissingFiles();
+
+ @Select("SELECT book_id AS book_id, book_code, book_name FROM book WHERE has_wordbook_file = 0")
+ List listMissingFileBooks();
+
+ @Select("""
+
+ """)
+ List listKnownMissingZpk(@Param("keys") List keys);
+
+ @Select("""
+ SELECT COUNT(*)
+ FROM word_entry e
+ WHERE NOT EXISTS (SELECT 1 FROM word_sense s WHERE s.entry_id = e.entry_id)
+ """)
+ long countEntriesWithoutSense();
+
+ @Select("""
+ SELECT COUNT(*)
+ FROM synonym_word w
+ WHERE NOT EXISTS (SELECT 1 FROM synonym_sense s WHERE s.word_id = w.word_id)
+ """)
+ long countSynonymWordsWithoutSense();
+
+ @Select("SELECT COUNT(*) FROM book WHERE exam_id IS NULL")
+ long countBooksWithoutExam();
+
+ @Select("SELECT COUNT(*) FROM book WHERE cover_url IS NULL OR cover_url = ''")
+ long countBooksWithoutCover();
+
+ @Select("SELECT book_id AS book_id, book_code, book_name FROM book WHERE cover_url IS NULL OR cover_url = ''")
+ List listBooksWithoutCover();
+
+ @Select("SELECT COUNT(DISTINCT LOWER(TRIM(word))) FROM card")
+ long cardTotal();
+
+ @Select("""
+ SELECT COUNT(DISTINCT LOWER(TRIM(c.word)))
+ FROM card c
+ WHERE EXISTS (SELECT 1 FROM word_entry e WHERE e.index_word = LOWER(TRIM(c.word)))
+ """)
+ long cardHit();
+
+ @Select("SELECT COUNT(DISTINCT LOWER(TRIM(word))) FROM word_family")
+ long familyTotal();
+
+ @Select("""
+ SELECT COUNT(DISTINCT LOWER(TRIM(f.word)))
+ FROM word_family f
+ WHERE EXISTS (SELECT 1 FROM word_entry e WHERE e.index_word = LOWER(TRIM(f.word)))
+ """)
+ long familyHit();
+
+ @Select("SELECT COUNT(DISTINCT LOWER(TRIM(word))) FROM synonym_word")
+ long synonymTotal();
+
+ @Select("""
+ SELECT COUNT(DISTINCT LOWER(TRIM(s.word)))
+ FROM synonym_word s
+ WHERE EXISTS (SELECT 1 FROM word_entry e WHERE e.index_word = LOWER(TRIM(s.word)))
+ """)
+ long synonymHit();
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/mapper/SynonymMapper.java b/backend/src/main/java/com/wordmarket/admin/mapper/SynonymMapper.java
new file mode 100644
index 0000000..a54b247
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/mapper/SynonymMapper.java
@@ -0,0 +1,119 @@
+package com.wordmarket.admin.mapper;
+
+import com.wordmarket.admin.dto.SynonymDtos.AntonymRow;
+import com.wordmarket.admin.dto.SynonymDtos.BucketRow;
+import com.wordmarket.admin.dto.SynonymDtos.GroupRow;
+import com.wordmarket.admin.dto.SynonymDtos.MemberRow;
+import com.wordmarket.admin.dto.SynonymDtos.WordItem;
+import com.wordmarket.admin.dto.SynonymDtos.WordRow;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+import java.util.List;
+
+@Mapper
+public interface SynonymMapper {
+
+ @Select("""
+
+ """)
+ long countWords(@Param("keyword") String keyword);
+
+ @Select("""
+
+ """)
+ List listWords(@Param("keyword") String keyword, @Param("offset") int offset,
+ @Param("limit") int limit);
+
+ @Select("SELECT word_id AS word_id, word FROM synonym_word WHERE word_id = #{id}")
+ WordRow findWord(@Param("id") long id);
+
+ @Select("""
+ SELECT sense_id, part_of_speech, gloss_zh
+ FROM synonym_sense
+ WHERE word_id = #{wordId}
+ ORDER BY sense_id
+ """)
+ List listSenses(@Param("wordId") long wordId);
+
+ @Select("""
+
+ """)
+ List listGroups(@Param("ids") List ids);
+
+ @Select("""
+
+ """)
+ List listMembers(@Param("ids") List ids);
+
+ @Select("""
+
+ """)
+ List listAntonyms(@Param("ids") List ids);
+
+ @Select("""
+ SELECT CASE
+ WHEN member_count <= 1 THEN '1'
+ WHEN member_count = 2 THEN '2'
+ WHEN member_count = 3 THEN '3'
+ WHEN member_count = 4 THEN '4'
+ WHEN member_count <= 6 THEN '5-6'
+ WHEN member_count <= 10 THEN '7-10'
+ ELSE '11+'
+ END AS label,
+ COUNT(*) AS count
+ FROM synonym_group
+ GROUP BY label
+ ORDER BY MIN(member_count)
+ """)
+ List groupSizeDistribution();
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/security/JwtAuthFilter.java b/backend/src/main/java/com/wordmarket/admin/security/JwtAuthFilter.java
new file mode 100644
index 0000000..fd2b153
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/security/JwtAuthFilter.java
@@ -0,0 +1,63 @@
+package com.wordmarket.admin.security;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.wordmarket.admin.common.ApiResponse;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.MediaType;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.stereotype.Component;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+
+@Component
+public class JwtAuthFilter extends OncePerRequestFilter {
+
+ private final JwtService jwtService;
+ private final ObjectMapper objectMapper;
+
+ public JwtAuthFilter(JwtService jwtService, ObjectMapper objectMapper) {
+ this.jwtService = jwtService;
+ this.objectMapper = objectMapper;
+ }
+
+ @Override
+ protected boolean shouldNotFilter(HttpServletRequest request) {
+ if ("OPTIONS".equalsIgnoreCase(request.getMethod())) {
+ return true;
+ }
+ return "/api/auth/login".equals(request.getRequestURI());
+ }
+
+ @Override
+ protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+ FilterChain filterChain) throws ServletException, IOException {
+ String header = request.getHeader(HttpHeaders.AUTHORIZATION);
+ if (header == null || !header.startsWith("Bearer ")) {
+ filterChain.doFilter(request, response);
+ return;
+ }
+ try {
+ String username = jwtService.parseSubject(header.substring(7));
+ var authentication = new UsernamePasswordAuthenticationToken(
+ username, null, List.of(new SimpleGrantedAuthority("ROLE_ADMIN")));
+ SecurityContextHolder.getContext().setAuthentication(authentication);
+ filterChain.doFilter(request, response);
+ } catch (RuntimeException ex) {
+ SecurityContextHolder.clearContext();
+ response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
+ response.setCharacterEncoding(StandardCharsets.UTF_8.name());
+ response.setContentType(MediaType.APPLICATION_JSON_VALUE);
+ objectMapper.writeValue(response.getWriter(),
+ ApiResponse.error(401, "登录状态无效或已过期"));
+ }
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/security/JwtService.java b/backend/src/main/java/com/wordmarket/admin/security/JwtService.java
new file mode 100644
index 0000000..f157244
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/security/JwtService.java
@@ -0,0 +1,55 @@
+package com.wordmarket.admin.security;
+
+import com.wordmarket.admin.common.BizException;
+import com.wordmarket.admin.config.AdminProperties;
+import io.jsonwebtoken.Claims;
+import io.jsonwebtoken.JwtException;
+import io.jsonwebtoken.Jwts;
+import io.jsonwebtoken.security.Keys;
+import org.springframework.stereotype.Component;
+
+import javax.crypto.SecretKey;
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
+import java.util.Date;
+
+@Component
+public class JwtService {
+
+ private final SecretKey key;
+ private final int ttlHours;
+
+ public JwtService(AdminProperties properties) {
+ this.key = Keys.hmacShaKeyFor(properties.getJwtSecret().getBytes(StandardCharsets.UTF_8));
+ this.ttlHours = properties.getTokenTtlHours();
+ }
+
+ public IssuedToken issue(String username) {
+ Instant now = Instant.now();
+ Instant expiresAt = now.plus(ttlHours, ChronoUnit.HOURS);
+ String token = Jwts.builder()
+ .subject(username)
+ .issuedAt(Date.from(now))
+ .expiration(Date.from(expiresAt))
+ .signWith(key)
+ .compact();
+ return new IssuedToken(token, expiresAt);
+ }
+
+ public String parseSubject(String token) {
+ try {
+ Claims claims = Jwts.parser()
+ .verifyWith(key)
+ .build()
+ .parseSignedClaims(token)
+ .getPayload();
+ return claims.getSubject();
+ } catch (JwtException | IllegalArgumentException ex) {
+ throw BizException.unauthorized("登录状态无效或已过期");
+ }
+ }
+
+ public record IssuedToken(String token, Instant expiresAt) {
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/security/RestAuthEntryPoint.java b/backend/src/main/java/com/wordmarket/admin/security/RestAuthEntryPoint.java
new file mode 100644
index 0000000..f1e59dc
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/security/RestAuthEntryPoint.java
@@ -0,0 +1,32 @@
+package com.wordmarket.admin.security;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.wordmarket.admin.common.ApiResponse;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.springframework.http.MediaType;
+import org.springframework.security.core.AuthenticationException;
+import org.springframework.security.web.AuthenticationEntryPoint;
+import org.springframework.stereotype.Component;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+@Component
+public class RestAuthEntryPoint implements AuthenticationEntryPoint {
+
+ private final ObjectMapper objectMapper;
+
+ public RestAuthEntryPoint(ObjectMapper objectMapper) {
+ this.objectMapper = objectMapper;
+ }
+
+ @Override
+ public void commence(HttpServletRequest request, HttpServletResponse response,
+ AuthenticationException authException) throws IOException {
+ response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
+ response.setCharacterEncoding(StandardCharsets.UTF_8.name());
+ response.setContentType(MediaType.APPLICATION_JSON_VALUE);
+ objectMapper.writeValue(response.getWriter(), ApiResponse.error(401, "未认证或登录已过期"));
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/service/AggregateCache.java b/backend/src/main/java/com/wordmarket/admin/service/AggregateCache.java
new file mode 100644
index 0000000..de05e77
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/service/AggregateCache.java
@@ -0,0 +1,33 @@
+package com.wordmarket.admin.service;
+
+import com.github.benmanes.caffeine.cache.Cache;
+import org.springframework.stereotype.Component;
+
+import java.util.function.Supplier;
+
+@Component
+public class AggregateCache {
+
+ private final Cache cache;
+
+ public AggregateCache(Cache aggregateCache) {
+ this.cache = aggregateCache;
+ }
+
+ @SuppressWarnings("unchecked")
+ public T get(String key, boolean refresh, Supplier loader) {
+ if (!refresh) {
+ Object cached = cache.getIfPresent(key);
+ if (cached != null) {
+ return (T) cached;
+ }
+ }
+ T value = loader.get();
+ cache.put(key, value);
+ return value;
+ }
+
+ public void clear() {
+ cache.invalidateAll();
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/service/AuthService.java b/backend/src/main/java/com/wordmarket/admin/service/AuthService.java
new file mode 100644
index 0000000..ff1a96c
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/service/AuthService.java
@@ -0,0 +1,35 @@
+package com.wordmarket.admin.service;
+
+import com.wordmarket.admin.common.BizException;
+import com.wordmarket.admin.config.AdminProperties;
+import com.wordmarket.admin.dto.AuthDtos.LoginRequest;
+import com.wordmarket.admin.dto.AuthDtos.LoginResponse;
+import com.wordmarket.admin.security.JwtService;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.stereotype.Service;
+
+@Service
+public class AuthService {
+
+ private final AdminProperties adminProperties;
+ private final PasswordEncoder passwordEncoder;
+ private final JwtService jwtService;
+
+ public AuthService(AdminProperties adminProperties, PasswordEncoder passwordEncoder,
+ JwtService jwtService) {
+ this.adminProperties = adminProperties;
+ this.passwordEncoder = passwordEncoder;
+ this.jwtService = jwtService;
+ }
+
+ public LoginResponse login(LoginRequest request) {
+ boolean usernameMatches = adminProperties.getUsername().equals(request.username());
+ boolean passwordMatches = passwordEncoder.matches(request.password(),
+ adminProperties.getPasswordHash());
+ if (!usernameMatches || !passwordMatches) {
+ throw BizException.unauthorized("用户名或密码错误");
+ }
+ JwtService.IssuedToken issued = jwtService.issue(request.username());
+ return new LoginResponse(issued.token(), issued.expiresAt().toString(), request.username());
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/service/BookService.java b/backend/src/main/java/com/wordmarket/admin/service/BookService.java
new file mode 100644
index 0000000..2a61965
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/service/BookService.java
@@ -0,0 +1,63 @@
+package com.wordmarket.admin.service;
+
+import com.wordmarket.admin.common.BizException;
+import com.wordmarket.admin.common.PageResult;
+import com.wordmarket.admin.common.Pages;
+import com.wordmarket.admin.dto.BookDtos.BookDetail;
+import com.wordmarket.admin.dto.BookDtos.BookDetailRow;
+import com.wordmarket.admin.dto.BookDtos.BookEntryItem;
+import com.wordmarket.admin.dto.BookDtos.BookListItem;
+import com.wordmarket.admin.dto.BookDtos.ExamOption;
+import com.wordmarket.admin.mapper.BookMapper;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+
+@Service
+@Transactional(readOnly = true)
+public class BookService {
+
+ private final BookMapper bookMapper;
+
+ public BookService(BookMapper bookMapper) {
+ this.bookMapper = bookMapper;
+ }
+
+ public PageResult list(Integer pageParam, Integer sizeParam, Long examId,
+ String keyword, Boolean hasFile) {
+ int page = Pages.page(pageParam);
+ int size = Pages.size(sizeParam);
+ long total = bookMapper.countBooks(examId, keyword, hasFile);
+ List items = bookMapper.listBooks(examId, keyword, hasFile,
+ Pages.offset(page, size), size);
+ return PageResult.of(items, total, page, size);
+ }
+
+ public BookDetail detail(long id) {
+ BookDetailRow detail = bookMapper.findBook(id);
+ if (detail == null) {
+ throw BizException.notFound("词书不存在");
+ }
+ boolean mismatch = detail.declared() != null && detail.declared() != detail.actual();
+ return new BookDetail(detail.id(), detail.code(), detail.name(), detail.description(),
+ detail.examId(), detail.examName(), detail.declared(), detail.actual(),
+ detail.contentVersion(), detail.schemaVersion(), detail.coverPath(),
+ detail.packageUrl(), detail.hasFile(), detail.sortAt(), detail.labels(), mismatch);
+ }
+
+ public PageResult entries(long bookId, Integer pageParam, Integer sizeParam,
+ String keyword) {
+ detail(bookId);
+ int page = Pages.page(pageParam);
+ int size = Pages.size(sizeParam);
+ long total = bookMapper.countBookEntries(bookId, keyword);
+ List items = bookMapper.listBookEntries(bookId, keyword,
+ Pages.offset(page, size), size);
+ return PageResult.of(items, total, page, size);
+ }
+
+ public List exams() {
+ return bookMapper.listExams();
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/service/DashboardService.java b/backend/src/main/java/com/wordmarket/admin/service/DashboardService.java
new file mode 100644
index 0000000..64c4ce4
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/service/DashboardService.java
@@ -0,0 +1,82 @@
+package com.wordmarket.admin.service;
+
+import com.wordmarket.admin.dto.DashboardDtos.CoverageItem;
+import com.wordmarket.admin.dto.DashboardDtos.ExamStat;
+import com.wordmarket.admin.dto.DashboardDtos.Kpi;
+import com.wordmarket.admin.dto.DashboardDtos.PosStat;
+import com.wordmarket.admin.dto.DashboardDtos.QualityItem;
+import com.wordmarket.admin.dto.DashboardDtos.Summary;
+import com.wordmarket.admin.dto.DashboardDtos.TopBook;
+import com.wordmarket.admin.mapper.DashboardMapper;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+
+@Service
+@Transactional(readOnly = true)
+public class DashboardService {
+
+ private final DashboardMapper dashboardMapper;
+ private final QualityService qualityService;
+ private final AggregateCache cache;
+
+ public DashboardService(DashboardMapper dashboardMapper, QualityService qualityService,
+ AggregateCache cache) {
+ this.dashboardMapper = dashboardMapper;
+ this.qualityService = qualityService;
+ this.cache = cache;
+ }
+
+ public Summary summary(boolean refresh) {
+ return cache.get("dashboard:summary", refresh, this::loadSummary);
+ }
+
+ private Summary loadSummary() {
+ long books = dashboardMapper.countBooks();
+ long entries = dashboardMapper.countEntries();
+ long links = dashboardMapper.countBookEntries();
+ long sentences = dashboardMapper.countExampleSentences();
+ long families = dashboardMapper.countFamilies();
+ long synonymWords = dashboardMapper.countSynonymWords();
+
+ long averagePerBook = books == 0 ? 0 : Math.round(links * 1.0 / books);
+
+ List kpis = List.of(
+ new Kpi("books", "词书", books,
+ dashboardMapper.countBooksWithoutFile() + " 本无清单文件", "blue"),
+ new Kpi("entries", "词条", entries,
+ String.format("%,d 个索引词", dashboardMapper.countIndexWords()), "green"),
+ new Kpi("links", "词书词条关联", links,
+ String.format("平均每本 %,d 条", averagePerBook), "violet"),
+ new Kpi("sentences", "例句", sentences,
+ String.format("含使用模式 %,d", dashboardMapper.countExampleUsages()), "amber"),
+ new Kpi("families", "词族", families,
+ String.format("顶层族 %,d", dashboardMapper.countTopFamilies()), "cyan"),
+ new Kpi("synonyms", "近义词头", synonymWords,
+ String.format("义项 %,d", dashboardMapper.countSynonymSenses()), "rose"));
+
+ List quality = qualityService.loadSummaryItems().stream()
+ .map(item -> new QualityItem(item.key(), item.label(), item.value(), item.unit(),
+ item.level(), QualityService.targetOf(item.key())))
+ .toList();
+
+ List coverage = qualityService.loadCoverage().stream()
+ .map(item -> new CoverageItem(item.name(), item.hit(), item.total(), item.pct()))
+ .toList();
+
+ return new Summary(kpis, quality, coverage);
+ }
+
+ public List examDistribution(boolean refresh) {
+ return cache.get("dashboard:exam", refresh, dashboardMapper::examDistribution);
+ }
+
+ public List topBooks(boolean refresh) {
+ return cache.get("dashboard:top", refresh, dashboardMapper::topBooks);
+ }
+
+ public List posDistribution(boolean refresh) {
+ return cache.get("dashboard:pos", refresh, dashboardMapper::posDistribution);
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/service/EntryService.java b/backend/src/main/java/com/wordmarket/admin/service/EntryService.java
new file mode 100644
index 0000000..1bb4249
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/service/EntryService.java
@@ -0,0 +1,251 @@
+package com.wordmarket.admin.service;
+
+import com.wordmarket.admin.common.BizException;
+import com.wordmarket.admin.common.PageResult;
+import com.wordmarket.admin.common.Pages;
+import com.wordmarket.admin.dto.EntryDtos.ConfusableItem;
+import com.wordmarket.admin.dto.EntryDtos.EntryBookItem;
+import com.wordmarket.admin.dto.EntryDtos.EntryBookRow;
+import com.wordmarket.admin.dto.EntryDtos.EntryDetail;
+import com.wordmarket.admin.dto.EntryDtos.EntryListItem;
+import com.wordmarket.admin.dto.EntryDtos.ExamRef;
+import com.wordmarket.admin.dto.EntryDtos.ExampleGroupItem;
+import com.wordmarket.admin.dto.EntryDtos.ExampleGroupRow;
+import com.wordmarket.admin.dto.EntryDtos.ExampleSentenceItem;
+import com.wordmarket.admin.dto.EntryDtos.ExampleUsageItem;
+import com.wordmarket.admin.dto.EntryDtos.GroupExamRow;
+import com.wordmarket.admin.dto.EntryDtos.PhraseExamRow;
+import com.wordmarket.admin.dto.EntryDtos.PhraseItem;
+import com.wordmarket.admin.dto.EntryDtos.PhraseOrder;
+import com.wordmarket.admin.dto.EntryDtos.PhraseOrderRow;
+import com.wordmarket.admin.dto.EntryDtos.PhraseRow;
+import com.wordmarket.admin.dto.EntryDtos.SenseExamRow;
+import com.wordmarket.admin.dto.EntryDtos.SenseItem;
+import com.wordmarket.admin.dto.EntryDtos.SenseRelation;
+import com.wordmarket.admin.dto.EntryDtos.SenseRelationRow;
+import com.wordmarket.admin.dto.EntryDtos.SenseRow;
+import com.wordmarket.admin.dto.EntryDtos.SentenceRow;
+import com.wordmarket.admin.dto.EntryDtos.SpellingVariantItem;
+import com.wordmarket.admin.dto.EntryDtos.UsageRow;
+import com.wordmarket.admin.mapper.EntryMapper;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+@Service
+@Transactional(readOnly = true)
+public class EntryService {
+
+ private static final int DEFINITION_PREVIEW = 120;
+
+ private final EntryMapper entryMapper;
+
+ public EntryService(EntryMapper entryMapper) {
+ this.entryMapper = entryMapper;
+ }
+
+ public PageResult list(Integer pageParam, Integer sizeParam, String keyword) {
+ int page = Pages.page(pageParam);
+ int size = Pages.size(sizeParam);
+ long total = entryMapper.countEntries(keyword);
+ List items = entryMapper.listEntries(keyword, Pages.offset(page, size), size)
+ .stream()
+ .map(item -> new EntryListItem(item.id(), item.headword(), item.indexWord(),
+ item.pronunciation(), preview(item.definition()), item.senseCount(),
+ item.bookCount()))
+ .toList();
+ return PageResult.of(items, total, page, size);
+ }
+
+ public EntryDetail detail(long id) {
+ EntryDetail detail = entryMapper.findEntry(id);
+ if (detail == null) {
+ throw BizException.notFound("词条不存在");
+ }
+ return detail;
+ }
+
+ public List senses(long entryId) {
+ detail(entryId);
+ List rows = entryMapper.listSenses(entryId);
+ if (rows.isEmpty()) {
+ return List.of();
+ }
+ List ids = rows.stream().map(row -> Long.parseLong(row.senseId())).toList();
+ Map> exams = groupExams(entryMapper.listSenseExams(ids));
+ Map> relations = groupRelations(entryMapper.listSenseRelations(ids));
+ List items = new ArrayList<>(rows.size());
+ for (SenseRow row : rows) {
+ long senseId = Long.parseLong(row.senseId());
+ items.add(new SenseItem(row.senseId(), row.senseNo(), row.partOfSpeech(), row.glossZh(),
+ exams.getOrDefault(senseId, List.of()),
+ relations.getOrDefault(senseId, List.of())));
+ }
+ return items;
+ }
+
+ public PageResult phrases(long entryId, Integer pageParam, Integer sizeParam) {
+ detail(entryId);
+ int page = Pages.page(pageParam);
+ int size = Pages.size(sizeParam);
+ long total = entryMapper.countPhrases(entryId);
+ List rows = entryMapper.listPhrases(entryId, Pages.offset(page, size), size);
+ if (rows.isEmpty()) {
+ return PageResult.of(List.of(), total, page, size);
+ }
+ List ids = rows.stream().map(row -> Long.parseLong(row.id())).toList();
+ Map> exams = groupPhraseExams(entryMapper.listPhraseExams(ids));
+ Map> orders = new HashMap<>();
+ for (PhraseOrderRow order : entryMapper.listPhraseOrders(entryId)) {
+ orders.computeIfAbsent(Long.parseLong(order.phraseId()), key -> new ArrayList<>())
+ .add(new PhraseOrder(order.examId(), order.examName(), order.groupType(),
+ order.position()));
+ }
+ List items = rows.stream()
+ .map(row -> {
+ long phraseId = Long.parseLong(row.id());
+ return new PhraseItem(row.id(), row.textEn(), row.textZh(), row.groupType(),
+ row.meaningId(), exams.getOrDefault(phraseId, List.of()),
+ orders.getOrDefault(phraseId, List.of()));
+ })
+ .toList();
+ return PageResult.of(items, total, page, size);
+ }
+
+ public PageResult examples(long entryId, Integer pageParam, Integer sizeParam) {
+ detail(entryId);
+ int page = Pages.page(pageParam);
+ int size = Pages.size(sizeParam);
+ long total = entryMapper.countExampleGroups(entryId);
+ List rows = entryMapper.listExampleGroups(entryId,
+ Pages.offset(page, size), size);
+ if (rows.isEmpty()) {
+ return PageResult.of(List.of(), total, page, size);
+ }
+ List ids = rows.stream().map(row -> Long.parseLong(row.id())).toList();
+ Map> exams = groupExampleExams(entryMapper.listExampleGroupExams(ids));
+ Map> usages = new HashMap<>();
+ for (UsageRow usage : entryMapper.listExampleUsages(ids)) {
+ usages.computeIfAbsent(Long.parseLong(usage.groupId()), key -> new ArrayList<>())
+ .add(usage);
+ }
+ Map> sentencesByGroup = new HashMap<>();
+ Map> sentencesByUsage = new HashMap<>();
+ for (SentenceRow sentence : entryMapper.listExampleSentences(ids)) {
+ sentencesByGroup.computeIfAbsent(Long.parseLong(sentence.groupId()),
+ key -> new ArrayList<>()).add(sentence);
+ if (sentence.usageId() != null) {
+ sentencesByUsage.computeIfAbsent(Long.parseLong(sentence.usageId()),
+ key -> new ArrayList<>()).add(sentence);
+ }
+ }
+ List items = new ArrayList<>(rows.size());
+ for (ExampleGroupRow row : rows) {
+ long groupId = Long.parseLong(row.id());
+ List usageItems = usages.getOrDefault(groupId, List.of()).stream()
+ .map(usage -> new ExampleUsageItem(usage.id(), usage.patternId(),
+ usage.patternText(), usage.position(), toSentenceItems(
+ sentencesByUsage.getOrDefault(Long.parseLong(usage.id()), List.of()))))
+ .toList();
+ List groupSentences = sentencesByGroup.getOrDefault(groupId, List.of());
+ List direct = groupSentences.stream()
+ .filter(sentence -> sentence.usageId() == null)
+ .map(EntryService::toSentenceItem)
+ .toList();
+ items.add(new ExampleGroupItem(row.id(), row.groupKind(), row.partOfSpeech(),
+ row.entryKindCode(), row.headForm(), row.definitionEn(), row.definitionZh(),
+ exams.getOrDefault(groupId, List.of()), usageItems, direct, groupSentences.size()));
+ }
+ return PageResult.of(items, total, page, size);
+ }
+
+ public List confusables(long entryId) {
+ detail(entryId);
+ return entryMapper.listConfusables(entryId).stream()
+ .map(row -> new ConfusableItem(row.id(), row.wordText(), row.glossZh(), row.posCode(),
+ row.spellingFlag(), row.position()))
+ .toList();
+ }
+
+ public List spellingVariants(long entryId) {
+ detail(entryId);
+ return entryMapper.listSpellingVariants(entryId).stream()
+ .map(row -> new SpellingVariantItem(row.position(), row.variant()))
+ .toList();
+ }
+
+ public PageResult books(long entryId, Integer pageParam, Integer sizeParam) {
+ detail(entryId);
+ int page = Pages.page(pageParam);
+ int size = Pages.size(sizeParam);
+ long total = entryMapper.countEntryBooks(entryId);
+ List items = entryMapper.listEntryBooks(entryId, Pages.offset(page, size), size)
+ .stream()
+ .map(row -> new EntryBookItem(row.bookId(), row.bookName(), row.bookCode(),
+ row.displayWord(), row.seqBook()))
+ .toList();
+ return PageResult.of(items, total, page, size);
+ }
+
+ private static Map> groupExams(List rows) {
+ Map> map = new HashMap<>();
+ for (SenseExamRow row : rows) {
+ map.computeIfAbsent(Long.parseLong(row.senseId()), key -> new ArrayList<>())
+ .add(new ExamRef(row.id(), row.code(), row.name()));
+ }
+ return map;
+ }
+
+ private static Map> groupRelations(List rows) {
+ Map> map = new HashMap<>();
+ for (SenseRelationRow row : rows) {
+ map.computeIfAbsent(Long.parseLong(row.senseId()), key -> new ArrayList<>())
+ .add(new SenseRelation(row.type(), row.position(), row.targetMeaningId(),
+ row.targetEntryId()));
+ }
+ return map;
+ }
+
+ private static Map> groupPhraseExams(List rows) {
+ Map> map = new LinkedHashMap<>();
+ for (PhraseExamRow row : rows) {
+ map.computeIfAbsent(Long.parseLong(row.phraseId()), key -> new ArrayList<>())
+ .add(new ExamRef(row.id(), row.code(), row.name()));
+ }
+ return map;
+ }
+
+ private static Map> groupExampleExams(List rows) {
+ Map> map = new HashMap<>();
+ for (GroupExamRow row : rows) {
+ map.computeIfAbsent(Long.parseLong(row.groupId()), key -> new ArrayList<>())
+ .add(new ExamRef(row.id(), row.code(), row.name()));
+ }
+ return map;
+ }
+
+ private static List toSentenceItems(List rows) {
+ return rows.stream().map(EntryService::toSentenceItem).toList();
+ }
+
+ private static ExampleSentenceItem toSentenceItem(SentenceRow row) {
+ return new ExampleSentenceItem(row.id(), row.textEn(), row.textZh(), row.sourceTitle(),
+ row.audioUrl(), row.listening());
+ }
+
+ private static String preview(String text) {
+ if (text == null) {
+ return null;
+ }
+ String trimmed = text.trim();
+ if (trimmed.length() <= DEFINITION_PREVIEW) {
+ return trimmed;
+ }
+ return trimmed.substring(0, DEFINITION_PREVIEW) + "…";
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/service/MorphologyService.java b/backend/src/main/java/com/wordmarket/admin/service/MorphologyService.java
new file mode 100644
index 0000000..b5353e2
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/service/MorphologyService.java
@@ -0,0 +1,227 @@
+package com.wordmarket.admin.service;
+
+import com.wordmarket.admin.common.BizException;
+import com.wordmarket.admin.common.PageResult;
+import com.wordmarket.admin.common.Pages;
+import com.wordmarket.admin.dto.MorphologyDtos.CardBrief;
+import com.wordmarket.admin.dto.MorphologyDtos.CardDetail;
+import com.wordmarket.admin.dto.MorphologyDtos.CardFamilyLink;
+import com.wordmarket.admin.dto.MorphologyDtos.CardItem;
+import com.wordmarket.admin.dto.MorphologyDtos.CardItemRow;
+import com.wordmarket.admin.dto.MorphologyDtos.CardRow;
+import com.wordmarket.admin.dto.MorphologyDtos.ExamRef;
+import com.wordmarket.admin.dto.MorphologyDtos.FamilyDetail;
+import com.wordmarket.admin.dto.MorphologyDtos.FamilyExamRow;
+import com.wordmarket.admin.dto.MorphologyDtos.FamilyItem;
+import com.wordmarket.admin.dto.MorphologyDtos.FamilyLinkRow;
+import com.wordmarket.admin.dto.MorphologyDtos.FamilyMemberItem;
+import com.wordmarket.admin.dto.MorphologyDtos.FamilyRow;
+import com.wordmarket.admin.dto.MorphologyDtos.FamilyVariantItem;
+import com.wordmarket.admin.dto.MorphologyDtos.LinkExamRow;
+import com.wordmarket.admin.dto.MorphologyDtos.MemberRow;
+import com.wordmarket.admin.dto.MorphologyDtos.MiniGroupItem;
+import com.wordmarket.admin.dto.MorphologyDtos.MiniGroupRow;
+import com.wordmarket.admin.dto.MorphologyDtos.MorphemeDetail;
+import com.wordmarket.admin.dto.MorphologyDtos.MorphemeItem;
+import com.wordmarket.admin.dto.MorphologyDtos.MorphemeRefRow;
+import com.wordmarket.admin.dto.MorphologyDtos.TreeCounts;
+import com.wordmarket.admin.dto.MorphologyDtos.TreeNode;
+import com.wordmarket.admin.dto.MorphologyDtos.TreePage;
+import com.wordmarket.admin.dto.MorphologyDtos.VariantRow;
+import com.wordmarket.admin.mapper.MorphologyMapper;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+@Service
+@Transactional(readOnly = true)
+public class MorphologyService {
+
+ private static final Set MORPHEME_TYPES = Set.of("prefix", "root", "suffix");
+ private static final int MEMBER_PREVIEW = 50;
+
+ private final MorphologyMapper morphologyMapper;
+
+ public MorphologyService(MorphologyMapper morphologyMapper) {
+ this.morphologyMapper = morphologyMapper;
+ }
+
+ public PageResult morphemes(String type, String keyword, Integer pageParam,
+ Integer sizeParam) {
+ if (type != null && !type.isBlank() && !MORPHEME_TYPES.contains(type)) {
+ throw BizException.badRequest("词素类型必须为 prefix、root 或 suffix");
+ }
+ int page = Pages.page(pageParam);
+ int size = Pages.size(sizeParam);
+ long total = morphologyMapper.countMorphemes(type, keyword);
+ List items = morphologyMapper.listMorphemes(type, keyword,
+ Pages.offset(page, size), size);
+ return PageResult.of(items, total, page, size);
+ }
+
+ public MorphemeDetail morpheme(long id) {
+ MorphemeItem item = morphologyMapper.findMorpheme(id);
+ if (item == null) {
+ throw BizException.notFound("词素不存在");
+ }
+ List cards = morphologyMapper.listCardsByMorpheme(id);
+ return new MorphemeDetail(item.id(), item.type(), item.form(), item.displayText(),
+ item.meaningEn(), item.meaningZh(), item.note(), cards,
+ morphologyMapper.countCardsByMorpheme(id));
+ }
+
+ public PageResult cards(String keyword, Integer pageParam, Integer sizeParam) {
+ int page = Pages.page(pageParam);
+ int size = Pages.size(sizeParam);
+ long total = morphologyMapper.countCards(keyword);
+ List rows = morphologyMapper.listCards(keyword, Pages.offset(page, size), size);
+ if (rows.isEmpty()) {
+ return PageResult.of(List.of(), total, page, size);
+ }
+ List ids = rows.stream().map(row -> Long.parseLong(row.id())).toList();
+ Map> exams = groupCardExams(morphologyMapper.listCardExams(ids));
+ List items = rows.stream()
+ .map(row -> new CardItem(row.id(), row.word(), row.memoryNote(), row.highlightedWord(),
+ exams.getOrDefault(Long.parseLong(row.id()), List.of())))
+ .toList();
+ return PageResult.of(items, total, page, size);
+ }
+
+ public CardDetail card(long id) {
+ CardRow row = morphologyMapper.findCard(id);
+ if (row == null) {
+ throw BizException.notFound("单词卡片不存在");
+ }
+ Map> exams = groupCardExams(
+ morphologyMapper.listCardExams(List.of(id)));
+ List morphemeIds = new ArrayList<>();
+ addPositive(morphemeIds, row.prefixMorphemeId());
+ addPositive(morphemeIds, row.rootMorphemeId());
+ addPositive(morphemeIds, row.suffixMorphemeId());
+ Map refs = new HashMap<>();
+ if (!morphemeIds.isEmpty()) {
+ for (MorphemeRefRow ref : morphologyMapper.listMorphemeRefs(morphemeIds)) {
+ refs.put(Long.parseLong(ref.id()), ref);
+ }
+ }
+ List links = morphologyMapper.listCardFamilyLinks(id).stream()
+ .map(link -> new CardFamilyLink(link.id(), link.groupNo(), link.familyRef(),
+ link.hidden()))
+ .toList();
+ return new CardDetail(row.id(), row.word(), row.highlightedWord(), row.memoryNote(),
+ row.exampleText(), row.hidden(),
+ morphemeId(row.prefixMorphemeId()), formOf(refs, row.prefixMorphemeId()),
+ morphemeId(row.rootMorphemeId()), formOf(refs, row.rootMorphemeId()),
+ morphemeId(row.suffixMorphemeId()), formOf(refs, row.suffixMorphemeId()),
+ row.defaultFamilyRef(), exams.getOrDefault(id, List.of()), links);
+ }
+
+ public PageResult families(String keyword, Integer pageParam, Integer sizeParam) {
+ int page = Pages.page(pageParam);
+ int size = Pages.size(sizeParam);
+ long total = morphologyMapper.countFamilies(keyword);
+ List rows = morphologyMapper.listFamilies(keyword, Pages.offset(page, size), size);
+ if (rows.isEmpty()) {
+ return PageResult.of(List.of(), total, page, size);
+ }
+ List ids = rows.stream().map(row -> Long.parseLong(row.id())).toList();
+ Map> exams = groupFamilyExams(morphologyMapper.listFamilyExams(ids));
+ List items = rows.stream()
+ .map(row -> new FamilyItem(row.id(), row.word(), row.topFamilyId(), row.topWord(),
+ row.interpretation(), row.groupLevel1(), row.groupLevel2(), row.groupLevel3(),
+ exams.getOrDefault(Long.parseLong(row.id()), List.of())))
+ .toList();
+ return PageResult.of(items, total, page, size);
+ }
+
+ public FamilyDetail family(long id) {
+ FamilyRow row = morphologyMapper.findFamily(id);
+ if (row == null) {
+ throw BizException.notFound("词族不存在");
+ }
+ Map> exams = groupFamilyExams(
+ morphologyMapper.listFamilyExams(List.of(id)));
+ long topId = Long.parseLong(row.topFamilyId());
+ List variants = morphologyMapper.listVariants(topId).stream()
+ .map(variant -> new FamilyVariantItem(variant.id(), variant.variantWord(),
+ variant.interpretation(), variant.memberCount()))
+ .toList();
+ List miniGroups = new ArrayList<>();
+ for (MiniGroupRow group : morphologyMapper.listMiniGroups(topId)) {
+ List members = morphologyMapper
+ .listMiniGroupMembers(Long.parseLong(group.id())).stream()
+ .map(member -> new FamilyMemberItem(member.familyEntryId(), member.word(),
+ member.position()))
+ .toList();
+ miniGroups.add(new MiniGroupItem(group.id(), group.size(), members));
+ }
+ return new FamilyDetail(row.id(), row.word(), row.topFamilyId(), row.topWord(),
+ row.interpretation(), row.groupLevel1(), row.groupLevel2(), row.groupLevel3(),
+ exams.getOrDefault(id, List.of()), variants, miniGroups);
+ }
+
+ public TreePage tree(long id, String nodeType, Integer pageParam, Integer sizeParam) {
+ int page = Pages.page(pageParam);
+ int size = Pages.size(sizeParam);
+ String type = nodeType == null || nodeType.isBlank() ? "top" : nodeType;
+ return switch (type) {
+ case "top" -> {
+ if (morphologyMapper.findFamily(id) == null) {
+ throw BizException.notFound("词族不存在");
+ }
+ TreeCounts counts = morphologyMapper.countTopChildren(id);
+ List nodes = morphologyMapper.listTopChildren(id, Pages.offset(page, size),
+ size);
+ yield new TreePage(nodes, counts.variantCount() + counts.groupCount(), page, size);
+ }
+ case "variant" -> new TreePage(
+ morphologyMapper.listVariantMemberNodes(id, Pages.offset(page, size), size),
+ morphologyMapper.countVariantMembers(id), page, size);
+ case "miniGroup" -> new TreePage(
+ morphologyMapper.listMiniGroupMemberNodes(id, Pages.offset(page, size), size),
+ morphologyMapper.countMiniGroupMembers(id), page, size);
+ default -> throw BizException.badRequest("不支持的树节点类型");
+ };
+ }
+
+ private static Map> groupCardExams(List rows) {
+ Map> map = new HashMap<>();
+ for (LinkExamRow row : rows) {
+ map.computeIfAbsent(Long.parseLong(row.cardId()), key -> new ArrayList<>())
+ .add(new ExamRef(row.id(), row.code(), row.name()));
+ }
+ return map;
+ }
+
+ private static Map> groupFamilyExams(List rows) {
+ Map> map = new HashMap<>();
+ for (FamilyExamRow row : rows) {
+ map.computeIfAbsent(Long.parseLong(row.familyEntryId()), key -> new ArrayList<>())
+ .add(new ExamRef(row.id(), row.code(), row.name()));
+ }
+ return map;
+ }
+
+ private static void addPositive(List ids, String value) {
+ if (value != null && !value.isBlank() && !"0".equals(value)) {
+ ids.add(Long.parseLong(value));
+ }
+ }
+
+ private static String morphemeId(String value) {
+ return value == null || "0".equals(value) ? null : value;
+ }
+
+ private static String formOf(Map refs, String id) {
+ if (id == null || "0".equals(id)) {
+ return null;
+ }
+ MorphemeRefRow ref = refs.get(Long.parseLong(id));
+ return ref == null ? null : ref.form();
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/service/QualityService.java b/backend/src/main/java/com/wordmarket/admin/service/QualityService.java
new file mode 100644
index 0000000..06c555f
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/service/QualityService.java
@@ -0,0 +1,150 @@
+package com.wordmarket.admin.service;
+
+import com.wordmarket.admin.config.AppProperties;
+import com.wordmarket.admin.dto.QualityDtos.Coverage;
+import com.wordmarket.admin.dto.QualityDtos.DeclaredDiff;
+import com.wordmarket.admin.dto.QualityDtos.MissingBook;
+import com.wordmarket.admin.dto.QualityDtos.MissingReference;
+import com.wordmarket.admin.dto.QualityDtos.MissingZpk;
+import com.wordmarket.admin.dto.QualityDtos.QualitySummary;
+import com.wordmarket.admin.dto.QualityDtos.SummaryItem;
+import com.wordmarket.admin.mapper.QualityMapper;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+@Service
+@Transactional(readOnly = true)
+public class QualityService {
+
+ private static final String KEY_MISMATCH = "mismatch";
+ private static final String KEY_NO_FILE = "nofile";
+ private static final String KEY_NO_ZPK = "nozpk";
+ private static final String KEY_NO_SENSE = "nosense";
+ private static final String KEY_NO_SYN_SENSE = "nosyn";
+ private static final String KEY_NO_EXAM = "noexam";
+ private static final String KEY_NO_COVER = "nocover";
+
+ private final QualityMapper qualityMapper;
+ private final AggregateCache cache;
+ private final AppProperties appProperties;
+
+ public QualityService(QualityMapper qualityMapper, AggregateCache cache, AppProperties appProperties) {
+ this.qualityMapper = qualityMapper;
+ this.cache = cache;
+ this.appProperties = appProperties;
+ }
+
+ public QualitySummary summary(boolean refresh) {
+ return cache.get("quality:summary", refresh, () -> new QualitySummary(loadSummaryItems()));
+ }
+
+ public List loadSummaryItems() {
+ List items = new ArrayList<>();
+ items.add(new SummaryItem(KEY_MISMATCH, "声明与实际词条数不一致",
+ qualityMapper.countDeclaredMismatch(), "本", "warn",
+ "口径:book.declared_entry_count 与 book_entry 实际行数不一致的词书。"));
+ items.add(new SummaryItem(KEY_NO_FILE, "缺失词书清单文件",
+ qualityMapper.countMissingFiles(), "本", "bad",
+ "口径:目录中存在但磁盘缺少清单文件的词书(book.has_wordbook_file = 0)。"));
+ items.add(new SummaryItem(KEY_NO_ZPK, "缺失 zpk 引用",
+ missingZpkRows().size(), "个", "bad",
+ "口径:配置中登记的缺失 zpk 文件键,仍被 book_entry.source_zpk_key 引用的去重数量。"));
+ items.add(new SummaryItem(KEY_NO_SENSE, "无结构化义项的词条",
+ qualityMapper.countEntriesWithoutSense(), "条", "warn",
+ "口径:word_sense 中完全没有记录的词条。"));
+ items.add(new SummaryItem(KEY_NO_SYN_SENSE, "无义项的近义词头",
+ qualityMapper.countSynonymWordsWithoutSense(), "个", "warn",
+ "口径:synonym_sense 中完全没有记录的近义词头。"));
+ items.add(new SummaryItem(KEY_NO_EXAM, "未设置考试的词书",
+ qualityMapper.countBooksWithoutExam(), "本", "info",
+ "口径:book.exam_id 为空的词书,通常为非考试类或未归类。"));
+ items.add(new SummaryItem(KEY_NO_COVER, "无封面词书",
+ qualityMapper.countBooksWithoutCover(), "本", "info",
+ "口径:book.cover_url 为空的词书,前端展示统一占位图。"));
+ return items;
+ }
+
+ public List declaredVsActual(boolean refresh) {
+ return cache.get("quality:declared", refresh, qualityMapper::listDeclaredMismatch);
+ }
+
+ public List missingReferences(boolean refresh) {
+ return cache.get("quality:missing", refresh, this::loadMissingReferences);
+ }
+
+ private List loadMissingReferences() {
+ List items = new ArrayList<>();
+ for (MissingBook book : qualityMapper.listMissingFileBooks()) {
+ items.add(new MissingReference("book_file", book.bookCode(),
+ "book.has_wordbook_file", book.bookName(), book.bookId()));
+ }
+ List keys = configuredZpkKeys();
+ if (!keys.isEmpty()) {
+ for (MissingZpk zpk : qualityMapper.listKnownMissingZpk(keys)) {
+ items.add(new MissingReference("zpk", zpk.sourceKey(), "book_entry.source_zpk_key",
+ "影响 " + zpk.rowCount() + " 行词书关联;词书 ID: " + zpk.bookIds(), null));
+ }
+ }
+ for (MissingBook book : qualityMapper.listBooksWithoutCover()) {
+ items.add(new MissingReference("cover", book.bookCode(), "book.cover_url",
+ book.bookName(), book.bookId()));
+ }
+ return items;
+ }
+
+ public List crossDomainCoverage(boolean refresh) {
+ return cache.get("quality:coverage", refresh, this::loadCoverage);
+ }
+
+ public List loadCoverage() {
+ List items = new ArrayList<>();
+ items.add(coverage("card", "单词卡片", qualityMapper.cardHit(), qualityMapper.cardTotal()));
+ items.add(coverage("family", "词族", qualityMapper.familyHit(), qualityMapper.familyTotal()));
+ items.add(coverage("synonym", "近义词头", qualityMapper.synonymHit(), qualityMapper.synonymTotal()));
+ return items;
+ }
+
+ private List missingZpkRows() {
+ List keys = configuredZpkKeys();
+ if (keys.isEmpty()) {
+ return List.of();
+ }
+ return qualityMapper.listKnownMissingZpk(keys);
+ }
+
+ private List configuredZpkKeys() {
+ String raw = appProperties.getQuality().getKnownMissingZpkKeys();
+ if (raw == null || raw.isBlank()) {
+ return List.of();
+ }
+ return Arrays.stream(raw.split(","))
+ .map(String::trim)
+ .filter(value -> !value.isEmpty())
+ .toList();
+ }
+
+ private static Coverage coverage(String key, String name, long hit, long total) {
+ double pct = total == 0 ? 0 : Math.round(hit * 1000.0 / total) / 10.0;
+ return new Coverage(key, name, hit, total, pct);
+ }
+
+ public static String levelOf(String key) {
+ return switch (key) {
+ case KEY_NO_FILE, KEY_NO_ZPK -> "bad";
+ case KEY_MISMATCH, KEY_NO_SENSE, KEY_NO_SYN_SENSE -> "warn";
+ default -> "info";
+ };
+ }
+
+ public static String targetOf(String key) {
+ return switch (key) {
+ case KEY_NO_SENSE, KEY_NO_ZPK -> "词条";
+ case KEY_NO_SYN_SENSE -> "近义词";
+ default -> "词书";
+ };
+ }
+}
diff --git a/backend/src/main/java/com/wordmarket/admin/service/SynonymService.java b/backend/src/main/java/com/wordmarket/admin/service/SynonymService.java
new file mode 100644
index 0000000..215e524
--- /dev/null
+++ b/backend/src/main/java/com/wordmarket/admin/service/SynonymService.java
@@ -0,0 +1,121 @@
+package com.wordmarket.admin.service;
+
+import com.wordmarket.admin.common.BizException;
+import com.wordmarket.admin.common.PageResult;
+import com.wordmarket.admin.common.Pages;
+import com.wordmarket.admin.dto.SynonymDtos.AntonymItem;
+import com.wordmarket.admin.dto.SynonymDtos.AntonymRow;
+import com.wordmarket.admin.dto.SynonymDtos.GroupItem;
+import com.wordmarket.admin.dto.SynonymDtos.GroupRow;
+import com.wordmarket.admin.dto.SynonymDtos.MemberItem;
+import com.wordmarket.admin.dto.SynonymDtos.MemberRow;
+import com.wordmarket.admin.dto.SynonymDtos.SenseItem;
+import com.wordmarket.admin.dto.SynonymDtos.SenseRow;
+import com.wordmarket.admin.dto.SynonymDtos.SizeBucket;
+import com.wordmarket.admin.dto.SynonymDtos.WordDetail;
+import com.wordmarket.admin.dto.SynonymDtos.WordItem;
+import com.wordmarket.admin.dto.SynonymDtos.WordRow;
+import com.wordmarket.admin.mapper.SynonymMapper;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+@Service
+@Transactional(readOnly = true)
+public class SynonymService {
+
+ private static final int MEMBER_LIMIT = 50;
+
+ private final SynonymMapper synonymMapper;
+
+ public SynonymService(SynonymMapper synonymMapper) {
+ this.synonymMapper = synonymMapper;
+ }
+
+ public PageResult list(Integer pageParam, Integer sizeParam, String keyword) {
+ int page = Pages.page(pageParam);
+ int size = Pages.size(sizeParam);
+ long total = synonymMapper.countWords(keyword);
+ List items = synonymMapper.listWords(keyword, Pages.offset(page, size), size);
+ return PageResult.of(items, total, page, size);
+ }
+
+ public WordDetail detail(long wordId) {
+ WordRow word = synonymMapper.findWord(wordId);
+ if (word == null) {
+ throw BizException.notFound("近义词词头不存在");
+ }
+ List senses = synonymMapper.listSenses(wordId);
+ if (senses.isEmpty()) {
+ return new WordDetail(word.wordId(), word.word(), List.of());
+ }
+ List ids = senses.stream().map(sense -> Long.parseLong(sense.senseId())).toList();
+ Map> groupsBySense = new HashMap<>();
+ for (GroupRow group : synonymMapper.listGroups(ids)) {
+ groupsBySense.computeIfAbsent(group.senseId(), key -> new ArrayList<>()).add(group);
+ }
+ Map> membersByGroup = new HashMap<>();
+ for (MemberRow member : synonymMapper.listMembers(ids)) {
+ membersByGroup.computeIfAbsent(member.senseId() + ":" + member.examId(),
+ key -> new ArrayList<>()).add(member);
+ }
+ Map