- 将变更移动到 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>
9.3 KiB
9.3 KiB
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/deleteMapper 方法;代码评审时以此为准。
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_entry123 万行的全表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
- 在数据库侧创建只读账号(需单独确认并执行授权语句)。
- 配置后端环境变量,启动 jar 并验证登录与只读接口。
- 构建前端静态资源,部署到 Nginx,配置
/api反向代理。 - 回滚:停止新服务并恢复上一版本 jar/dist;数据库无 schema 变更,无需回滚脚本。
Open Questions
- 概览各图表的最终视觉形式(柱状/环形/横向条)在实现时按数据分布微调,不影响接口契约。
- 缓存 TTL 的首期取值(默认 10 分钟)可在联调后按查询耗时调整。