Skip to content

整体架构 ​

本章介绍系统的分层结构与关键技术设计。

技术栈 ​

层级技术
后端Spring Boot 3.3.6 + Java 21 + MyBatis-Plus 3.5.12
数据库SQLite(本地单文件)/ MySQL
前端Vue 3 + TypeScript + Vite + Naive UI + ECharts + Pinia + vue-i18n
认证JWT(HMAC)
对象映射MapStruct 1.6.3
账单解析EasyExcel(xlsx)/ Apache POI(xls)+ commons-csv + PDFBox + Zip4j
AIDeepSeek(OpenAI 兼容接口,Spring RestClient)
通知Jakarta Mail(SMTP / IMAP)+ Server 酱 + 飞书自定义机器人
API 文档Knife4j(OpenAPI 3)

后端分层 ​

text
controller   接口层,统一返回 Result<T>,经 UserContext 取当前用户
   │
service      业务层(接口 + impl),事务、跨表校验、聚合
   │
mapper       MyBatis-Plus BaseMapper,少量自定义 SQL
   │
entity       数据库表映射实体

辅助包:

包职责
dto / vo入参请求对象 / 出参视图对象
converterMapStruct 实体↔VO 转换(VoConverter)
importer账单解析器(BillParser 及实现、BillArchiveExtractor)
exporterExcel 导出样式处理
notification通知渠道发送器(工厂 + 各渠道实现)
scheduler定时任务(通知、日志清理、邮箱账单)
interceptorJWT 鉴权、访问日志
configWeb、JWT、Knife4j、MyBatis-Plus、动态数据源、SPA 路由回退
clientDeepSeek 客户端
emailIMAP 邮箱账单抓取(监听、拉取、解析、存储)
commonResult、PageResult、业务异常、全局异常处理
utilJwtUtil、UserContext、AppLogUtils 等
enumsBillType、AiCallType、StatisticsDimension 等

请求处理流程 ​

text
浏览器
  │  /api/**(可携带加密会话头 X-Crypto-Session)
  ▼
AccessLogInterceptor   记录访问日志(方法/路径/耗时/状态/IP/用户)
  │
CryptoSessionInterceptor  解析加密会话(无会话头则按明文处理)
  │
JwtInterceptor         校验 Bearer Token(兼容 ?token= 供 SSE),写入 userId
  │
Controller             UserContext.getUserId()
  │
Service → Mapper → 数据库(动态数据源)
  │
GlobalExceptionHandler 统一异常 → Result{code,message,data}
  • 请求/响应体加解密:ApiCryptoRequestBodyAdvice 在参数绑定前解密请求体,ApiCryptoResponseBodyAdvice 在写出前加密 Result 响应体,二者均依赖 CryptoSessionInterceptor 写入的会话。详见 API 文档 · 接口数据加密。

  • 登录、注册、注册状态、数据库状态等接口无需鉴权。

  • 数据库未配置时,UnconfiguredDataSource 抛出的异常会转为业务码 5031,前端据此跳转初始化引导页。

认证与鉴权 ​

  • JwtUtil 使用 HMAC 密钥签发 JWT,subject 为用户 ID,附带用户名 claim,默认有效期 24 小时。
  • JwtInterceptor 从 Authorization: Bearer <token> 解析;由于 EventSource 无法自定义请求头,同时兼容 ?token= 查询参数(用于日志实时推送等 SSE 场景)。
  • UserContext 基于 RequestContextHolder 读取拦截器写入的 userId,使控制器无需声明 HttpServletRequest。

前端结构 ​

text
src/
├── api/          各模块 REST 接口封装(axios,统一携带 Token、处理 401/业务码)
├── views/        页面组件(Dashboard、TransactionList、BillImport 等)
├── components/   复用组件(账单预览、导入结果、AI 配置、通知配置等)
├── router/       路由与导航守卫(数据库配置校验、登录校验)
├── store/        Pinia 状态(user / database / registration)
├── locales/      中/英/日三语文案
├── composables/  组合式函数(关键词历史)
└── utils/        工具(交易渠道标签、SSE 封装等)

关键设计亮点 ​

  1. 运行时动态数据源:启动无需数据库,配置后热切换,见动态数据源。
  2. 账单两阶段导入:解析预览 → 确认导入,按交易号去重,见账单解析。
  3. 规则引擎:分类取最高优先级、标签取并集,见规则引擎。
  4. 体系化 AI 调用:13 类调用类型并记录 token 用量,见 AI 集成。
  5. SSE 实时能力:运行日志、邮箱检查进度、图片记账识别进度与数据库配置执行进度实时推送。
  6. 用户偏好缓存:t_user_preference 的读取走 Spring Cache 进程内缓存(ConcurrentMapCacheManager),写入时按用户失效,切换数据源时整体清空。
  7. 接口数据加密:/api/** 请求/响应体支持 RSA + AES-GCM 端到端加密,握手自动完成、对未加密客户端透明,见 API 文档。

相关文档 ​

基于 Spring Boot 3 + Vue 3 的个人汇账