Files
word-market/openspec/changes/add-admin-console/design.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

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