Files
word-market/openspec/changes/archive/2026-11-08-add-admin-console/design.md
T
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

9.3 KiB
Raw Blame History

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 分钟)可在联调后按查询耗时调整。