Files
voidandClaude Sonnet 4.6 dd928a9513 chore(openspec): 归档 add-admin-console
- 将变更移动到 changes/archive/2026-11-08-add-admin-console
- 同步 7 个能力、37 条需求到 openspec/specs/
- openspec validate --all 全部通过

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

7.1 KiB
Raw Permalink Blame History

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,配置数据源、Hikari read-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,按前后端分离方式做一次本地部署演练