feat(admin): 实现只读词库管理后台

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

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
voidandClaude Sonnet 4.6 committed 2026-11-08 22:55:15 +08:00
1 parent 131c2b6353
commit 4e68ba3890
137 files changed
+15423 -10

No files matched your search

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-08
@@ -0,0 +1,3 @@
# add-admin-console
基于 Vue 3 + Spring Boot 3 的只读单词数据管理后台
@@ -0,0 +1,135 @@
## Context
词库数据已完整落库到 MySQL `word_market`(36 张表、约 364 万行、约 590MB),`importer/` 负责导入且不应被后台改动。`backend/` 与 `frontend/` 目前只有占位 README。本地环境为 Java 17 + Maven 3.9 + Node 24,没有 Docker;数据库在 `s1.void01.com`,需要跨网络访问。
需求与行为契约见 `proposal.md` 与 `specs/`,本文只记录实现层面的技术选择。
## Goals / Non-Goals
**Goals:**
- 用一套可维护的 Spring Boot 服务承载全部只读查询,接口足够稳定以支撑前端六个模块。
- 在远程数据库和 123 万行大表的前提下,保证看板首屏和列表页的响应可接受。
- 前后端分离部署,配置全部外部化,仓库不出现凭据。
- 明确的只读边界,从连接、事务和代码三个层面防止写入。
**Non-Goals:**
- 不做任何新增、修改、删除、导入触发功能。
- 不做多租户、多角色、权限矩阵。
- 不做实时推送、定时任务或数据同步。
- 不做移动端适配,首期以桌面端 1280px 以上为主。
- 不改造 `importer` 或数据库 schema。
## Decisions
### 1. 后端:Spring Boot 3 + Java 17 + MyBatis-Plus
- 采用 Spring Boot 3.3.x、Java 17、Maven 构建,与本地已安装版本一致。
- 持久层选 MyBatis-Plus:列表接口的筛选条件组合多、需要分页,MyBatis-Plus 的 `LambdaQueryWrapper` 和分页插件能显著减少样板 SQL;只读场景不需要 JPA 的实体生命周期和脏检查。
- 备选:`JdbcTemplate`(SQL 最透明,但动态筛选和分页要手写较多代码);Spring Data JPA(对纯读场景偏重)。
### 2. 只读保障三层
- 数据库侧:建议为后台创建仅 `SELECT` 权限的账号,通过环境变量配置;这是运维动作,执行前需单独确认。
- 连接池:HikariCP 设置 `read-only: true`。
- 应用侧:全部 Service 标注 `@Transactional(readOnly = true)`;不创建任何 `insert/update/delete` Mapper 方法;代码评审时以此为准。
### 3. 认证:单管理员 + JWT(HS256)
- 管理员用户名、BCrypt 密码哈希、JWT 密钥全部来自环境变量(`ADMIN_USERNAME`、`ADMIN_PASSWORD_HASH`、`JWT_SECRET`)。
- 启动时校验三项配置存在,缺失则启动失败并输出配置名,避免“能启动但登录不了”的隐性故障。
- token 有效期默认 8 小时,前端存内存 + localStorage;401 时清除并跳转登录页。
- 不建用户表,不引入 Spring Session 或 OAuth。备选 OAuth 需要外部身份提供方,超出本期范围。
### 4. 聚合缓存:Caffeine 本地缓存
- 概览与数据质量的聚合结果缓存 10 分钟;缓存 key 包含查询类型和参数。
- 提供 `refresh=true` 参数绕过缓存并回填。
- 列表、详情和子资源不做长缓存,避免看到过期内容;详情查询本身有主键索引。
- 单实例部署下本地缓存足够;未来横向扩容时再换 Redis。备选 Redis 现阶段会多一个运维组件。
### 5. API 约定
- 统一前缀 `/api`,响应结构 `{ code, message, data }`;分页数据为 `{ items, total, page, size }`。
- 时间统一返回 ISO-8601 字符串,数值 ID 以 string 返回,避免前端精度丢失(`bigint` 超过 `Number.MAX_SAFE_INTEGER` 的风险)。
- 全局异常处理:参数错误 400、未认证 401、未找到 404、服务异常 500,均返回统一结构。
- 主要接口:
| 模块 | 接口 |
|---|---|
| 认证 | `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` |
| 词条 | `GET /api/entries`、`/api/entries/{id}`、`/{id}/senses`、`/phrases`、`/examples`、`/confusables`、`/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` |
### 6. 前端:Vue 3 + Vite + TS + Element Plus + ECharts
- Vue 3 + Vite + TypeScript;状态管理只用于认证和布局,业务数据走页面级请求,不放进全局 store。
- Element Plus 提供表格、分页、树、标签页、抽屉等后台组件;ECharts 负责 KPI 之外的图表。
- Axios 封装统一注入 token、解包 `data`、处理 401;路由使用 `meta.requiresAuth` 做守卫。
- 页面结构:登录页 + 侧边栏布局 + 各模块列表页/详情页;详情页用 Tab 或锚点分区,避免单页过长。
- 词族树使用 Element Plus `el-tree` 的 `lazy` 模式,节点展开时按需请求子节点;成员节点分页,避免一次渲染上千成员。
### 7. 数据访问与性能
- 列表统一使用 `LIMIT/OFFSET` 分页,默认每页 20 条,最大 100 条。
- 详情页的子资源按各自索引查询:`book_entry(book_id, seq_book)`、`word_sense(entry_id, sense_no)`、`example_group(entry_id, group_kind)`、`phrase(entry_id)`、`synonym_sense(word_id)` 等。
- 详情页需要多个子资源时按 Tab 懒加载,避免一次请求全部关联表。
- `book_entry` 123 万行的全表 `COUNT(*)` 与分组只出现在概览/质量聚合中,统一走缓存;列表计数按筛选条件走索引。
- 跨域覆盖度需要文本交集,查询较重,缓存时间可长于其他指标;实现时优先用单条 SQL 的 `EXISTS`/`JOIN`,避免把两边的词表拉到应用层。
- 连接池大小按单实例 10–20 配置,并为查询设置超时,防止远程库抖动拖垮线程。
### 8. 封面与静态资源
- 封面地址 = `COVER_BASE_URL`(默认 `https://static.beingfine.cn`)+ `book.cover_url`。
- 前端图片组件统一处理加载失败,回退到本地占位图;27 本无封面词书使用同一占位图。
### 9. 部署与配置
- 后端产出可执行 jar,前端产出 `dist` 静态资源;生产环境由 Nginx 托管前端并反向代理 `/api`。
- 开发环境 Vite dev server 代理 `/api` 到后端,避免 CORS 配置复杂化;后端仍保留可配置的 CORS 白名单。
- 所有敏感配置通过环境变量注入,仓库只提供 `.env.example` 和 `application.example.yml`。
### 10. 概览页 UI 采用方案 A(经典后台)
- 采用 `frontend/prototype/` 中的方案 A:228px 白色左侧导航 + 顶部栏 + 六列 KPI 卡片 + 2:1 图表网格 + 词书排行表格与质量红绿灯/覆盖度侧栏。
- 理由:日常管理场景下信息层级最清晰,侧边栏框架可被词书、词条等模块直接复用;方案 B 的深色大屏偏监控、方案 C 的编辑式排版偏研报,都不匹配本期后台定位。
- 方案 B/C 保留在原型目录作为参考,正式实现只采用 A 的结构。
- 实现落点为 `/` 路由与 `OverviewView` 组件,数据走 `/api/dashboard/*`;后端未就绪时使用与接口同形的本地 mock,切换后端只改 API 层。
### 11. 词条详情使用右侧抽屉
- 词条列表点击行或“查看”时,在右侧 760px 抽屉中展示基本信息与义项/短语/例句/易混词/收录词书五个 Tab,列表保持可见。
- 抽屉使用非模态(`modal=false`、`lock-scroll=false`):打开时仍可点击其他词条切换内容,也可直接使用侧边栏切换模块。
- 词书详情中的“查看词条”跳转到词条列表并自动打开对应抽屉。
- 抽屉支持关闭按钮与 ESC;关闭时清除 URL 中的 `id`,直接访问带 `id` 的 URL 可恢复抽屉。
- 词书与近义词仍使用独立详情页;只有词条采用抽屉,便于在列表中快速对照多个词条。
- 正式实现使用 Element Plus `el-drawer`,`append-to-body`,桌面宽度 760px,窄屏 92vw。
## Risks / Trade-offs
- [远程数据库查询延迟] → 聚合走缓存、查询设置超时、列表强制分页;前端加载态与错误态必须明确。
- [聚合首次查询慢] → 缓存预热可在部署后手动触发刷新;必要时为高频聚合增加覆盖索引。
- [深分页性能下降] → 首期限定最大页码或最大 offset;后续可改 keyset 分页。
- [词族树节点过大] → 懒加载 + 成员分页;单节点成员上限由接口控制。
- [JWT 与管理员凭据泄漏] → 仅通过环境变量注入;生产必须 HTTPS;token 短期有效。
- [只读约束被绕过] → 数据库只读账号是最终防线;应用层禁止写 Mapper,并在评审中检查。
- [封面 CDN 不可用] → 占位图兜底,不阻塞页面。
- [中文乱码] → 数据库、JDBC URL、HTTP 响应统一 UTF-8;前端不使用 GBK 相关配置。
- [无真实趋势数据] → 不生成伪时间序列图;只做快照分布与排行。
## Migration Plan
1. 在数据库侧创建只读账号(需单独确认并执行授权语句)。
2. 配置后端环境变量,启动 jar 并验证登录与只读接口。
3. 构建前端静态资源,部署到 Nginx,配置 `/api` 反向代理。
4. 回滚:停止新服务并恢复上一版本 jar/dist;数据库无 schema 变更,无需回滚脚本。
## Open Questions
- 概览各图表的最终视觉形式(柱状/环形/横向条)在实现时按数据分布微调,不影响接口契约。
- 缓存 TTL 的首期取值(默认 10 分钟)可在联调后按查询耗时调整。
@@ -0,0 +1,44 @@
## Why
`importer` 已将 Lexis 词库完整导入 MySQL `word_market`(36 张表、约 364 万行),但目前没有任何浏览或可视化入口。核对词书内容、排查数据质量问题只能手写 SQL,效率低且容易误操作。需要一套只读管理后台,把词书、词条、词根词族、近反义词四个业务域的数据可视化,并支持从看板钻取到明细,帮助快速理解和核查这批数据。
本期明确只做查询与展示,不提供任何增删改,避免误改源数据。
## What Changes
- 新建 `backend/`:Spring Boot 3(Java 17)+ MyBatis-Plus,只读连接 MySQL `word_market`。
- 新建 `frontend/`:Vue 3 + Vite + TypeScript + Element Plus + ECharts。
- 单管理员登录:账号密码来自环境变量,登录后签发 JWT;前端路由守卫与 401 拦截。
- 概览看板:总量 KPI、考试分布、词书规模排行、词性分布、数据质量红绿灯。
- 词书模块:1,025 本词书的列表、筛选、详情与词条清单分页。
- 词条模块:38,116 个词条的搜索、详情,覆盖义项、短语、例句、易混词、收录词书。
- 词根词族模块:词素(前缀/词根/后缀)、单词卡片、词族及**树形族谱**。
- 近反义词模块:词头列表、义项详情、分考试近义组与反义词。
- 数据质量模块:声明 vs 实际、缺失文件/引用、无结构化义项、跨域覆盖度。
- 全局只读约束:所有接口仅执行 SELECT,应用层开启 read-only 事务,数据库侧建议使用只读账号。
- 聚合查询使用 Caffeine 缓存,列表与子资源统一分页。
## Capabilities
### New Capabilities
- `admin-auth`: 单管理员凭据校验、JWT 签发与校验、未认证访问拦截。
- `admin-overview`: 概览看板的 KPI 与分布图表数据。
- `book-catalog`: 词书列表、筛选、详情与词条清单的只读浏览。
- `word-lexicon`: 词条搜索、详情及义项/短语/例句/易混词/收录词书等子资源浏览。
- `word-morphology`: 词素、单词卡片、词族及树形族谱的只读浏览。
- `synonym-relations`: 近义词头、义项、分考试近义组与反义词的只读浏览。
- `data-quality`: 数据质量指标与异常明细的聚合展示。
### Modified Capabilities
无。当前 `openspec/specs/` 下没有既有能力,本次全部为新增。
## Impact
- 代码:`backend/`、`frontend/` 由占位目录变为实际工程;`importer/` 与数据库 schema 不改动。
- 数据:只读访问 MySQL `s1.void01.com:3306/word_market`,不新增表、不写入。
- 配置:需要数据库连接信息、管理员账号与密码哈希、JWT 密钥等环境变量;不得硬编码凭据。
- 外部依赖:词书封面通过 `https://static.beingfine.cn` + `book.cover_url` 访问。
- 性能:概览聚合依赖 Caffeine 缓存,避免高频全表聚合;详情页子资源必须分页。
- 运维:前后端分离部署,后端产出可执行 jar,前端产出静态资源。
@@ -0,0 +1,62 @@
## Purpose
保护只读管理后台的访问入口,确保只有持有有效凭据的管理员才能查看词库数据。
## ADDED Requirements
### Requirement: 管理员登录
系统 SHALL 提供登录接口,校验单一管理员账号与密码;凭据必须来自外部配置(环境变量),不得硬编码在代码或仓库中。校验成功后签发 JWT,失败时返回统一错误结构。
#### Scenario: 凭据正确
- **WHEN** 管理员提交正确的用户名和密码
- **THEN** 系统返回 JWT 和过期时间,前端进入后台首页
#### Scenario: 凭据错误
- **WHEN** 管理员提交错误的用户名或密码
- **THEN** 系统返回 401,且不返回任何 token 或账号信息
#### Scenario: 请求缺字段
- **WHEN** 登录请求缺少用户名或密码
- **THEN** 系统返回 400,并说明缺少的字段
#### Scenario: 启动时缺少管理员配置
- **WHEN** 应用启动时未提供管理员账号或密码哈希
- **THEN** 应用拒绝启动并输出明确的配置缺失错误
### Requirement: 受保护接口鉴权
除登录接口外,所有业务接口 MUST 要求携带有效 JWT。无效、过期或缺失 token 的请求 SHALL 被拒绝,不得返回业务数据。
#### Scenario: 未携带 token
- **WHEN** 请求受保护接口时未提供 Authorization 头
- **THEN** 系统返回 401
#### Scenario: token 无效或过期
- **WHEN** 请求携带格式错误、签名不匹配或已过期的 token
- **THEN** 系统返回 401,且不返回业务数据
#### Scenario: token 有效
- **WHEN** 请求携带有效 token
- **THEN** 系统正常返回业务数据
### Requirement: 前端会话处理
前端 SHALL 在本地保存登录状态;收到 401 时必须清除登录状态并跳转登录页,不得停留在空白或报错页面。
#### Scenario: token 过期
- **WHEN** 任意页面请求返回 401
- **THEN** 前端清除本地 token 并跳转登录页
#### Scenario: 主动退出
- **WHEN** 管理员点击退出
- **THEN** 前端清除本地 token 并返回登录页
@@ -0,0 +1,69 @@
## Purpose
在一个页面汇总词库的规模、分布与健康度,作为后台入口和问题发现入口。
## ADDED Requirements
### Requirement: 总量指标
系统 SHALL 在概览页展示词书数、词条数、词书词条关联数、例句数、词族数、近义词头数六项核心指标。
#### Scenario: 打开概览页
- **WHEN** 已登录管理员进入概览页
- **THEN** 页面展示六项指标及其当前数值
#### Scenario: 指标查询失败
- **WHEN** 某一指标查询失败
- **THEN** 页面展示该指标的不可用状态,其余指标仍正常展示
### Requirement: 考试维度分布
系统 SHALL 按考试展示词书数与关联词条数,并 MUST 显式包含“未归类”分组,避免未设置考试的词书被忽略。
#### Scenario: 查看考试分布
- **WHEN** 管理员查看考试分布图
- **THEN** 图中包含各考试的词书数、关联词条数以及“未归类”分组
### Requirement: 词书规模排行
系统 SHALL 展示实际词条数最多的前 10 本词书,同时给出各自声明的词条数,便于发现两者差异。
#### Scenario: 查看规模排行
- **WHEN** 管理员查看词书规模排行
- **THEN** 页面按实际词条数降序列出前 10 本,并同时显示声明词条数
### Requirement: 词性分布
系统 SHALL 按 `part_of_speech` 汇总词义数量并展示主要词性占比。
#### Scenario: 查看词性分布
- **WHEN** 管理员查看词性分布
- **THEN** 页面展示各词性的义项数及占比,空词性单独归类
### Requirement: 质量红绿灯
系统 SHALL 在概览页展示关键数据质量指标摘要,并提供进入数据质量模块的入口。
#### Scenario: 查看质量摘要
- **WHEN** 管理员查看质量红绿灯
- **THEN** 页面展示异常项数量与状态,并可跳转到数据质量模块
### Requirement: 聚合结果缓存
概览聚合结果 SHALL 缓存一段时间;缓存有效期内重复请求直接返回缓存,过期后重新查询。系统 SHALL 提供手动刷新方式以强制重新计算。
#### Scenario: 缓存命中
- **WHEN** 缓存在有效期内,管理员重复打开概览页
- **THEN** 系统直接返回缓存结果,不重新执行聚合查询
#### Scenario: 手动刷新
- **WHEN** 管理员触发刷新
- **THEN** 系统忽略现有缓存并重新计算后返回
@@ -0,0 +1,71 @@
## Purpose
以只读方式浏览词书目录及每本词书的词条清单,帮助核对词书规模、考试归属和内容完整性。
## ADDED Requirements
### Requirement: 词书列表与筛选
系统 SHALL 提供分页的词书列表,支持按考试、关键词和是否存在词书文件筛选;列表 MUST 展示名称、业务编码、考试、声明词条数、实际词条数和文件状态。
#### Scenario: 默认分页浏览
- **WHEN** 管理员打开词书列表
- **THEN** 系统按稳定顺序返回第一页词书,并给出总数与总页数
#### Scenario: 按考试筛选
- **WHEN** 管理员选择某个考试
- **THEN** 列表只返回该考试下的词书
#### Scenario: 按关键词搜索
- **WHEN** 管理员输入词书名称或编码的一部分
- **THEN** 列表返回名称或编码匹配的词书
#### Scenario: 按文件状态筛选
- **WHEN** 管理员筛选“无词书文件”
- **THEN** 列表只返回没有对应清单文件的词书
### Requirement: 词书详情
系统 SHALL 展示单本词书的名称、编码、考试、描述、声明词条数、实际词条数、内容版本、封面和文件状态。
#### Scenario: 查看词书详情
- **WHEN** 管理员从列表进入某本词书
- **THEN** 页面展示该词书的完整信息,并标明实际词条数与声明词条数是否一致
#### Scenario: 词书不存在
- **WHEN** 请求的词书 ID 不存在
- **THEN** 系统返回明确的未找到错误,前端展示不存在提示
### Requirement: 词书词条清单
系统 SHALL 以分页方式展示词书内词条,默认按词书内顺序排列,并支持按展示词文本筛选。
#### Scenario: 浏览词条清单
- **WHEN** 管理员打开词书详情的词条清单
- **THEN** 系统按 `seq_book` 返回第一页词条,并给出总数
#### Scenario: 按词筛选
- **WHEN** 管理员在词条清单中输入关键词
- **THEN** 系统只返回展示词包含该关键词的词条
### Requirement: 封面展示
系统 SHALL 将词书封面相对路径拼接到外部 CDN 地址展示;封面为空或加载失败时 MUST 显示占位图,不得展示破图。
#### Scenario: 正常封面
- **WHEN** 词书存在封面路径
- **THEN** 列表与详情展示来自 CDN 的封面图片
#### Scenario: 无封面或加载失败
- **WHEN** 词书没有封面路径或图片加载失败
- **THEN** 页面展示统一的占位图
@@ -0,0 +1,88 @@
## Purpose
汇总词库的数据质量问题,提供可解释的指标口径和到明细的下钻入口,帮助定位需要修复的数据。
## ADDED Requirements
### Requirement: 质量摘要
系统 SHALL 提供数据质量摘要,至少包含:声明与实际词条数不一致的词书数、缺失词书文件数、缺失 zpk 引用数、无结构化义项的词条数、无义项的近义词头数、未设置考试的词书数。
#### Scenario: 查看质量摘要
- **WHEN** 管理员打开数据质量模块
- **THEN** 页面展示上述指标的当前数值和状态
#### Scenario: 指标查询失败
- **WHEN** 某一质量指标查询失败
- **THEN** 页面展示该指标不可用,其余指标正常展示
### Requirement: 指标口径说明
每个质量指标 SHALL 附带口径说明,明确统计范围和判定条件,避免管理员误读。
#### Scenario: 查看口径
- **WHEN** 管理员将鼠标悬停或点击指标说明
- **THEN** 页面展示该指标的统计范围与判定条件
### Requirement: 声明与实际差异明细
系统 SHALL 列出声明词条数与实际词条数不一致的词书,展示两者数值及差值,并支持跳转到词书详情。
#### Scenario: 查看差异明细
- **WHEN** 管理员打开声明与实际差异明细
- **THEN** 页面列出全部不一致词书及其声明数、实际数和差值
#### Scenario: 跳转到词书
- **WHEN** 管理员点击某本差异词书
- **THEN** 前端跳转到该词书详情
### Requirement: 缺失引用与文件明细
系统 SHALL 列出缺失词书文件、缺失 zpk 引用等异常明细,并标明对应标识,便于人工核查。
#### Scenario: 查看缺失明细
- **WHEN** 管理员打开缺失明细
- **THEN** 页面列出每个异常项的标识、来源和缺失类型
### Requirement: 跨域覆盖度
系统 SHALL 展示单词卡片、词族、近义词头与词条索引词之间的文本交集覆盖率,并说明关联是弱关联。
#### Scenario: 查看覆盖度
- **WHEN** 管理员打开跨域覆盖度视图
- **THEN** 页面展示各域与词条索引词的交集数量、占比和未覆盖数量
### Requirement: 异常下钻
系统 SHALL 允许从质量异常项跳转到对应的词书、词条或近义词详情,前提是存在可直接定位的实体标识。
#### Scenario: 下钻到实体
- **WHEN** 管理员点击一个可定位的异常项
- **THEN** 前端跳转到对应实体详情页
#### Scenario: 无法定位
- **WHEN** 异常项没有可定位的实体标识
- **THEN** 页面仅展示明细,不提供跳转
### Requirement: 质量结果缓存
质量摘要与覆盖度等聚合结果 SHALL 缓存一段时间,并支持手动刷新强制重算。
#### Scenario: 缓存命中
- **WHEN** 缓存在有效期内重复访问质量模块
- **THEN** 系统返回缓存结果
#### Scenario: 手动刷新
- **WHEN** 管理员触发刷新
- **THEN** 系统忽略缓存并重新计算
@@ -0,0 +1,75 @@
## Purpose
浏览近义词头、义项,以及按考试划分的近义词组和反义词关系。
## ADDED Requirements
### Requirement: 近义词头列表与搜索
系统 SHALL 提供分页的近义词头列表,支持按单词搜索,并展示义项数量和是否有近义关系。
#### Scenario: 默认浏览
- **WHEN** 管理员打开近义词头列表
- **THEN** 系统返回第一页词头及总数
#### Scenario: 按单词搜索
- **WHEN** 管理员输入单词的一部分
- **THEN** 列表返回单词匹配的词头
### Requirement: 义项详情
系统 SHALL 展示词头下的全部义项,包括词性、中文释义,以及每个义项在各考试下的近义组和反义词。
#### Scenario: 查看义项
- **WHEN** 管理员进入某个词头详情
- **THEN** 页面按义项展示词性和中文释义
#### Scenario: 无义项
- **WHEN** 词头没有任何义项
- **THEN** 页面展示空状态,并保留词头本身的信息
### Requirement: 分考试近义组
系统 SHALL 对每个义项按考试展示近义组,包含规范词、成员单词、成员数量和成员顺序。
#### Scenario: 查看近义组
- **WHEN** 管理员展开某个义项的考试分组
- **THEN** 页面展示该考试下的规范词和全部成员
#### Scenario: 成员较多
- **WHEN** 近义组成员数量超出页面承载
- **THEN** 页面截断或分页展示,并标明完整成员数量
#### Scenario: 某考试无数据
- **WHEN** 义项在某个考试下没有近义组
- **THEN** 该考试不展示为空组
### Requirement: 反义词展示
系统 SHALL 展示每个义项在各考试下的反义词。
#### Scenario: 查看反义词
- **WHEN** 义项存在反义词
- **THEN** 页面在对应考试分组下展示反义词
#### Scenario: 无反义词
- **WHEN** 义项没有反义词
- **THEN** 反义词区域展示空状态
### Requirement: 组规模分布
系统 SHALL 提供近义组规模分布视图,展示不同成员数量的组占比,帮助识别异常过大或过小的组。
#### Scenario: 查看分布
- **WHEN** 管理员打开近义词模块的分布视图
- **THEN** 页面展示按成员数量分桶的组数量与占比
@@ -0,0 +1,108 @@
## Purpose
搜索并查看单个词条的完整词典内容,覆盖释义、短语、例句、易混词及其被词书收录的情况。
## ADDED Requirements
### Requirement: 词条搜索与列表
系统 SHALL 提供分页的词条列表,支持按原形或归一化索引词模糊搜索;列表 MUST 展示原形、音标、释义摘要、义项数量和收录词书数。
#### Scenario: 默认浏览
- **WHEN** 管理员打开词条列表
- **THEN** 系统返回第一页词条及总数
#### Scenario: 按词搜索
- **WHEN** 管理员输入单词的一部分
- **THEN** 系统返回原形或索引词匹配的词条
#### Scenario: 无匹配结果
- **WHEN** 搜索结果为空
- **THEN** 页面展示空状态,而不是错误
### Requirement: 词条基本信息
系统 SHALL 展示词条的原形、索引词、美式与英式音标、释义原文、数据版本、所属考试和来源标识。
#### Scenario: 查看基本信息
- **WHEN** 管理员进入词条详情
- **THEN** 页面展示该词条的基本字段
#### Scenario: 词条不存在
- **WHEN** 请求的词条 ID 不存在
- **THEN** 系统返回未找到错误,前端展示不存在提示
### Requirement: 义项浏览
系统 SHALL 展示词条的结构化义项,包括序号、词性、中文释义、关联考试和义项关系。
#### Scenario: 有结构化义项
- **WHEN** 词条存在结构化义项
- **THEN** 页面按序号展示全部义项及其考试和关系
#### Scenario: 无结构化义项
- **WHEN** 词条没有任何结构化义项
- **THEN** 义项区域展示空状态,并在基本信息中保留原始释义文本
### Requirement: 短语浏览
系统 SHALL 展示词条关联的短语,包括英文、中文、所属义项、分组类型和关联考试。
#### Scenario: 查看短语
- **WHEN** 管理员打开短语区域
- **THEN** 页面展示该词条的短语列表及其考试关联
#### Scenario: 无短语
- **WHEN** 词条没有短语
- **THEN** 短语区域展示空状态
### Requirement: 例句浏览
系统 SHALL 按例句组展示例句,包含例句文本、翻译、使用模式和来源类型;数据量较大时 MUST 分页。
#### Scenario: 查看例句
- **WHEN** 管理员打开例句区域
- **THEN** 页面按例句组展示第一页例句
#### Scenario: 例句较多
- **WHEN** 词条例句数量超过一页
- **THEN** 页面提供分页,不得一次性加载全部例句
#### Scenario: 无例句
- **WHEN** 词条没有例句
- **THEN** 例句区域展示空状态
### Requirement: 易混词浏览
系统 SHALL 展示词条的易混词及其辨析信息。
#### Scenario: 查看易混词
- **WHEN** 管理员打开易混词区域
- **THEN** 页面展示易混词列表及辨析内容
### Requirement: 收录词书浏览
系统 SHALL 分页展示收录该词书的词书,包括词书名称、词书内展示词和顺序。
#### Scenario: 查看收录词书
- **WHEN** 管理员打开收录词书区域
- **THEN** 页面分页展示收录该词条的词书及词书内顺序
#### Scenario: 未被任何词书收录
- **WHEN** 词条没有被任何词书收录
- **THEN** 收录词书区域展示空状态
@@ -0,0 +1,90 @@
## Purpose
浏览词素(前缀、词根、后缀)、单词卡片、词族及其层级关系,支持以树形结构理解词族组成。
## ADDED Requirements
### Requirement: 词素列表与筛选
系统 SHALL 提供分页的词素列表,支持按词素类型(前缀、词根、后缀)和词形关键词筛选,并展示词形、类型、英文释义和中文释义。
#### Scenario: 默认浏览词素
- **WHEN** 管理员打开词素列表
- **THEN** 系统返回第一页词素及总数
#### Scenario: 按类型筛选
- **WHEN** 管理员选择“前缀”
- **THEN** 列表只返回前缀类型词素
#### Scenario: 按词形搜索
- **WHEN** 管理员输入词形的一部分
- **THEN** 列表返回词形匹配的词素
### Requirement: 词素详情
系统 SHALL 展示词素的完整释义、备注以及引用该词素的单词卡片。
#### Scenario: 查看词素详情
- **WHEN** 管理员进入某个词素详情
- **THEN** 页面展示词素信息及关联卡片列表
#### Scenario: 词素不存在
- **WHEN** 请求的词素 ID 不存在
- **THEN** 系统返回未找到错误,前端展示不存在提示
### Requirement: 单词卡片列表与详情
系统 SHALL 提供分页的单词卡片列表,支持按单词搜索;详情展示单词、记忆提示、例句、关联词素、适用考试和关联词族。
#### Scenario: 浏览卡片
- **WHEN** 管理员打开卡片列表
- **THEN** 系统返回第一页卡片及总数
#### Scenario: 查看卡片详情
- **WHEN** 管理员进入某个卡片详情
- **THEN** 页面展示卡片内容、关联词素和适用考试
### Requirement: 词族列表与详情
系统 SHALL 提供分页的词族列表,支持按单词搜索;详情展示词族词条、顶层词族、变体、小组、关联考试和族内顺序。
#### Scenario: 浏览词族
- **WHEN** 管理员打开词族列表
- **THEN** 系统返回第一页词族及总数
#### Scenario: 查看词族详情
- **WHEN** 管理员进入某个词族详情
- **THEN** 页面展示该词族的基础信息、变体和小组
### Requirement: 树形族谱
系统 SHALL 以可展开的树形结构展示词族层级:顶层词族节点可展开其变体与小组,最末级展示成员单词。节点必须标明自身类型和成员数量。
#### Scenario: 展开节点
- **WHEN** 管理员展开一个顶层词族节点
- **THEN** 系统加载并展示其子节点,节点类型和成员数量清晰可见
#### Scenario: 收起节点
- **WHEN** 管理员收起已展开的节点
- **THEN** 其子节点从视图中移除
#### Scenario: 成员过多
- **WHEN** 某个节点的成员数量超过一页
- **THEN** 系统分页或懒加载成员,不得一次性渲染全部成员
#### Scenario: 空族谱
- **WHEN** 顶层词族没有变体、小组或成员
- **THEN** 页面展示空状态,节点仍可正常展开和收起
@@ -0,0 +1,91 @@
## 1. 工程骨架与配置
- [x] 1.1 在 `backend/` 创建 Maven 工程:Spring Boot 3.3.x、Java 17、Web / Security / Validation / MyBatis-Plus / MySQL Driver / Caffeine 依赖
- [x] 1.2 创建 `application.yml` 与 `application-dev.yml`,配置数据源、Hikari `read-only`、连接超时、UTF-8、MyBatis-Plus 分页插件
- [x] 1.3 提供 `application.example.yml` 与后端 `.env.example`,列出 `DB_URL`、`DB_USERNAME`、`DB_PASSWORD`、`ADMIN_USERNAME`、`ADMIN_PASSWORD_HASH`、`JWT_SECRET`、`COVER_BASE_URL`
- [x] 1.4 实现统一响应结构 `{ code, message, data }`、分页结构 `{ items, total, page, size }` 和全局异常处理(400/401/404/500)
- [x] 1.5 配置 CORS 白名单与请求日志,确保中文 UTF-8 正常
- [x] 1.6 在 `frontend/` 创建 Vite + Vue 3 + TypeScript 工程,接入 Element Plus、ECharts、Pinia、Vue Router、Axios
- [x] 1.7 配置前端环境变量 `VITE_API_BASE_URL`、Vite 开发代理 `/api`、路径别名和基础目录结构
## 2. 认证与后台框架
- [x] 2.1 后端实现管理员凭据读取与启动校验:缺少 `ADMIN_USERNAME` / `ADMIN_PASSWORD_HASH` / `JWT_SECRET` 时启动失败并输出缺失项
- [x] 2.2 实现 `POST /api/auth/login`:校验 BCrypt 密码,签发 HS256 JWT,返回 token 与过期时间
- [x] 2.3 实现 JWT 校验过滤器与 Spring Security 配置,除登录接口外全部要求认证,失败统一返回 401
- [x] 2.4 为全部 Service 启用 `@Transactional(readOnly = true)`,确认不存在任何写 Mapper 方法
- [x] 2.5 前端实现登录页、auth store、token 持久化和退出逻辑
- [x] 2.6 前端实现路由守卫与 Axios 拦截器:注入 token、解包响应、401 时清理状态并跳转登录页
- [x] 2.7 前端实现后台布局:侧边栏导航(概览/词书/词条/词根词族/近反义词/数据质量)、顶栏、退出入口
- [x] 2.8 封装通用组件:分页表格、加载态、空状态、错误态、指标卡、图表卡、封面占位图
## 3. 概览模块
- [x] 3.1 实现 `GET /api/dashboard/summary`:词书、词条、关联、例句、词族、近义词头六项总量
- [x] 3.2 实现 `GET /api/dashboard/exam-distribution`:按考试统计词书数与关联词条数,包含“未归类”
- [x] 3.3 实现 `GET /api/dashboard/book-size-top`:实际词条数 Top 10 与声明词条数
- [x] 3.4 实现 `GET /api/dashboard/pos-distribution`:按词性统计义项数
- [x] 3.5 配置 Caffeine 缓存(默认 10 分钟)与 `refresh=true` 强制刷新
- [x] 3.6 前端实现概览页:六项 KPI、考试分布图、规模排行、词性分布、质量红绿灯与跳转
- [x] 3.7 验证缓存命中与手动刷新行为,确认重复进入概览不重复执行重聚合
## 4. 词书模块
- [x] 4.1 实现 `GET /api/books`:分页,支持 `examId`、`keyword`、`hasFile` 筛选,返回声明/实际词条数
- [x] 4.2 实现 `GET /api/books/{id}`:词书详情与声明/实际差异标识,处理不存在返回 404
- [x] 4.3 实现 `GET /api/books/{id}/entries`:按 `seq_book` 分页,支持展示词关键词筛选
- [x] 4.4 前端实现词书列表页:筛选栏、封面对齐 CDN、分页、文件状态标识
- [x] 4.5 前端实现词书详情页:信息卡、封面与占位图、词条清单分页与搜索
- [x] 4.6 验证无封面词书、无文件词书、空词条清单的展示
## 5. 词条模块
- [x] 5.1 实现 `GET /api/entries`:按 `headword` / `index_word` 模糊搜索,分页,返回义项数与收录词书数
- [x] 5.2 实现 `GET /api/entries/{id}`:基本信息与原始释义,处理 404
- [x] 5.3 实现义项接口:义项、考试、义项关系、考试义项顺序
- [x] 5.4 实现短语接口:短语、分组类型、考试关联与顺序
- [x] 5.5 实现例句接口:例句组、使用模式、例句句子,支持分页
- [x] 5.6 实现易混词接口与拼写变体接口
- [x] 5.7 实现 `GET /api/entries/{id}/books`:分页返回收录词书、词书内展示词与顺序
- [x] 5.8 前端实现词条搜索页与详情页,子资源按 Tab 懒加载
- [x] 5.9 验证无结构化义项(约 5,250 条)、无短语、无例句、未被收录等空状态
- [x] 5.10 验证例句较多的词条分页正确,不一次性加载全部数据
## 6. 词根词族模块
- [x] 6.1 实现 `GET /api/morphemes`:按类型与词形筛选,分页
- [x] 6.2 实现 `GET /api/morphemes/{id}`:词素详情与引用它的卡片
- [x] 6.3 实现 `GET /api/cards` 与 `/api/cards/{id}`:卡片列表、详情、关联词素与考试
- [x] 6.4 实现 `GET /api/families` 与 `/api/families/{id}`:词族列表、详情、变体与小组
- [x] 6.5 实现 `GET /api/families/{id}/tree`:按节点类型懒加载子节点,成员分页
- [x] 6.6 前端实现词素列表/详情页,按 prefix/root/suffix 标注类型
- [x] 6.7 前端实现卡片列表/详情页
- [x] 6.8 前端实现词族列表/详情页与 `el-tree` 懒加载树形族谱,支持展开、收起和成员分页
- [x] 6.9 验证空族谱、成员过多节点、深层嵌套节点的展开与收起(当前数据无空族谱实例,界面已覆盖空数组;懒加载展开/收起已验证)
## 7. 近反义词模块
- [x] 7.1 实现 `GET /api/synonyms`:词头分页与搜索,返回义项数
- [x] 7.2 实现 `GET /api/synonyms/{wordId}`:词头、义项、分考试近义组(规范词、成员、顺序)与反义词
- [x] 7.3 实现 `GET /api/synonyms/group-size-distribution`:成员数量分桶统计
- [x] 7.4 前端实现词头列表、详情页与组规模分布图
- [x] 7.5 验证无义项词头(约 19 个)、某考试无数据、成员过多时的截断或分页展示(词头 131 已验证无义项;现有最大成员数 22,截断逻辑已覆盖)
## 8. 数据质量模块
- [x] 8.1 实现 `GET /api/quality/summary`:六项关键指标与口径说明
- [x] 8.2 实现 `GET /api/quality/declared-vs-actual`:声明与实际差异词书明细
- [x] 8.3 实现 `GET /api/quality/missing-references`:缺失文件、缺失 zpk 等明细
- [x] 8.4 实现 `GET /api/quality/cross-domain-coverage`:卡片/词族/近义词与词条索引词的覆盖率
- [x] 8.5 为质量聚合结果接入 Caffeine 缓存与强制刷新
- [x] 8.6 前端实现数据质量页:摘要、口径提示、差异表、缺失明细、覆盖度图与实体跳转
- [x] 8.7 验证可定位异常项跳转正确,不可定位异常项只展示明细
## 9. 联调、验证与交付
- [x] 9.1 用真实数据库完成六个模块的端到端联调,确认登录、分页、筛选、详情与空状态
- [ ] 9.2 验证只读约束:代码中无写 Mapper;Hikari 与应用事务为只读;与用户确认后创建并切换到只读数据库账号(代码、Hikari、事务只读已验证;只读数据库账号待用户确认后创建)
- [x] 9.3 检查关键查询耗时,确认概览与质量页命中缓存,列表与详情响应在可接受范围
- [x] 9.4 为认证、分页边界、404、空状态和缓存刷新补充后端测试
- [x] 9.5 更新 `backend/README.md` 与 `frontend/README.md`:环境变量、启动命令、构建与部署方式
- [x] 9.6 构建后端 jar 与前端 `dist`,按前后端分离方式做一次本地部署演练