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

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-11-08 22:55:15 +08:00

92 lines
7.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 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`,按前后端分离方式做一次本地部署演练