- 新增 Spring Boot 3 后端:JWT 认证、六个业务模块查询接口、Caffeine 聚合缓存与只读事务约束 - 新增 Vue 3 管理前端:登录、概览、词书、词条、词根词族、近反义词与数据质量 - 补充前后端 README、环境变量示例与本地构建部署说明 - 同步 OpenSpec 变更文档与任务进度(64/65,只读数据库账号待确认) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
7.1 KiB
7.1 KiB
1. 工程骨架与配置
- 1.1 在
backend/创建 Maven 工程:Spring Boot 3.3.x、Java 17、Web / Security / Validation / MyBatis-Plus / MySQL Driver / Caffeine 依赖 - 1.2 创建
application.yml与application-dev.yml,配置数据源、Hikariread-only、连接超时、UTF-8、MyBatis-Plus 分页插件 - 1.3 提供
application.example.yml与后端.env.example,列出DB_URL、DB_USERNAME、DB_PASSWORD、ADMIN_USERNAME、ADMIN_PASSWORD_HASH、JWT_SECRET、COVER_BASE_URL - 1.4 实现统一响应结构
{ code, message, data }、分页结构{ items, total, page, size }和全局异常处理(400/401/404/500) - 1.5 配置 CORS 白名单与请求日志,确保中文 UTF-8 正常
- 1.6 在
frontend/创建 Vite + Vue 3 + TypeScript 工程,接入 Element Plus、ECharts、Pinia、Vue Router、Axios - 1.7 配置前端环境变量
VITE_API_BASE_URL、Vite 开发代理/api、路径别名和基础目录结构
2. 认证与后台框架
- 2.1 后端实现管理员凭据读取与启动校验:缺少
ADMIN_USERNAME/ADMIN_PASSWORD_HASH/JWT_SECRET时启动失败并输出缺失项 - 2.2 实现
POST /api/auth/login:校验 BCrypt 密码,签发 HS256 JWT,返回 token 与过期时间 - 2.3 实现 JWT 校验过滤器与 Spring Security 配置,除登录接口外全部要求认证,失败统一返回 401
- 2.4 为全部 Service 启用
@Transactional(readOnly = true),确认不存在任何写 Mapper 方法 - 2.5 前端实现登录页、auth store、token 持久化和退出逻辑
- 2.6 前端实现路由守卫与 Axios 拦截器:注入 token、解包响应、401 时清理状态并跳转登录页
- 2.7 前端实现后台布局:侧边栏导航(概览/词书/词条/词根词族/近反义词/数据质量)、顶栏、退出入口
- 2.8 封装通用组件:分页表格、加载态、空状态、错误态、指标卡、图表卡、封面占位图
3. 概览模块
- 3.1 实现
GET /api/dashboard/summary:词书、词条、关联、例句、词族、近义词头六项总量 - 3.2 实现
GET /api/dashboard/exam-distribution:按考试统计词书数与关联词条数,包含“未归类” - 3.3 实现
GET /api/dashboard/book-size-top:实际词条数 Top 10 与声明词条数 - 3.4 实现
GET /api/dashboard/pos-distribution:按词性统计义项数 - 3.5 配置 Caffeine 缓存(默认 10 分钟)与
refresh=true强制刷新 - 3.6 前端实现概览页:六项 KPI、考试分布图、规模排行、词性分布、质量红绿灯与跳转
- 3.7 验证缓存命中与手动刷新行为,确认重复进入概览不重复执行重聚合
4. 词书模块
- 4.1 实现
GET /api/books:分页,支持examId、keyword、hasFile筛选,返回声明/实际词条数 - 4.2 实现
GET /api/books/{id}:词书详情与声明/实际差异标识,处理不存在返回 404 - 4.3 实现
GET /api/books/{id}/entries:按seq_book分页,支持展示词关键词筛选 - 4.4 前端实现词书列表页:筛选栏、封面对齐 CDN、分页、文件状态标识
- 4.5 前端实现词书详情页:信息卡、封面与占位图、词条清单分页与搜索
- 4.6 验证无封面词书、无文件词书、空词条清单的展示
5. 词条模块
- 5.1 实现
GET /api/entries:按headword/index_word模糊搜索,分页,返回义项数与收录词书数 - 5.2 实现
GET /api/entries/{id}:基本信息与原始释义,处理 404 - 5.3 实现义项接口:义项、考试、义项关系、考试义项顺序
- 5.4 实现短语接口:短语、分组类型、考试关联与顺序
- 5.5 实现例句接口:例句组、使用模式、例句句子,支持分页
- 5.6 实现易混词接口与拼写变体接口
- 5.7 实现
GET /api/entries/{id}/books:分页返回收录词书、词书内展示词与顺序 - 5.8 前端实现词条搜索页与详情页,子资源按 Tab 懒加载
- 5.9 验证无结构化义项(约 5,250 条)、无短语、无例句、未被收录等空状态
- 5.10 验证例句较多的词条分页正确,不一次性加载全部数据
6. 词根词族模块
- 6.1 实现
GET /api/morphemes:按类型与词形筛选,分页 - 6.2 实现
GET /api/morphemes/{id}:词素详情与引用它的卡片 - 6.3 实现
GET /api/cards与/api/cards/{id}:卡片列表、详情、关联词素与考试 - 6.4 实现
GET /api/families与/api/families/{id}:词族列表、详情、变体与小组 - 6.5 实现
GET /api/families/{id}/tree:按节点类型懒加载子节点,成员分页 - 6.6 前端实现词素列表/详情页,按 prefix/root/suffix 标注类型
- 6.7 前端实现卡片列表/详情页
- 6.8 前端实现词族列表/详情页与
el-tree懒加载树形族谱,支持展开、收起和成员分页 - 6.9 验证空族谱、成员过多节点、深层嵌套节点的展开与收起(当前数据无空族谱实例,界面已覆盖空数组;懒加载展开/收起已验证)
7. 近反义词模块
- 7.1 实现
GET /api/synonyms:词头分页与搜索,返回义项数 - 7.2 实现
GET /api/synonyms/{wordId}:词头、义项、分考试近义组(规范词、成员、顺序)与反义词 - 7.3 实现
GET /api/synonyms/group-size-distribution:成员数量分桶统计 - 7.4 前端实现词头列表、详情页与组规模分布图
- 7.5 验证无义项词头(约 19 个)、某考试无数据、成员过多时的截断或分页展示(词头 131 已验证无义项;现有最大成员数 22,截断逻辑已覆盖)
8. 数据质量模块
- 8.1 实现
GET /api/quality/summary:六项关键指标与口径说明 - 8.2 实现
GET /api/quality/declared-vs-actual:声明与实际差异词书明细 - 8.3 实现
GET /api/quality/missing-references:缺失文件、缺失 zpk 等明细 - 8.4 实现
GET /api/quality/cross-domain-coverage:卡片/词族/近义词与词条索引词的覆盖率 - 8.5 为质量聚合结果接入 Caffeine 缓存与强制刷新
- 8.6 前端实现数据质量页:摘要、口径提示、差异表、缺失明细、覆盖度图与实体跳转
- 8.7 验证可定位异常项跳转正确,不可定位异常项只展示明细
9. 联调、验证与交付
- 9.1 用真实数据库完成六个模块的端到端联调,确认登录、分页、筛选、详情与空状态
- 9.2 验证只读约束:代码中无写 Mapper;Hikari 与应用事务为只读;与用户确认后创建并切换到只读数据库账号(代码、Hikari、事务只读已验证;只读数据库账号待用户确认后创建)
- 9.3 检查关键查询耗时,确认概览与质量页命中缓存,列表与详情响应在可接受范围
- 9.4 为认证、分页边界、404、空状态和缓存刷新补充后端测试
- 9.5 更新
backend/README.md与frontend/README.md:环境变量、启动命令、构建与部署方式 - 9.6 构建后端 jar 与前端
dist,按前后端分离方式做一次本地部署演练