rosercode
5eb1d331f9
同步 ledgerly 近期开发改动（接口请求/响应体加解密、代码检查工具、安全与稳定性修复、AI 提示词模板抽取），补齐对应开发文档并修正过时表述，同时在快速开始补充小屏适配说明。 变更内容： - dev/api.md：新增「接口数据加密」小节，说明 RSA + AES-GCM 握手流程、信封格式、会话有效期与失效码、豁免范围及编译期开关。 - dev/architecture.md：请求处理流程补入加密会话拦截器与请求/响应体 Advice，关键设计亮点新增接口数据加密一条。 - dev/development.md：新增「代码检查」小节，登记 Spotless / Checkstyle / SpotBugs 与前端 ESLint / Prettier 配置及运行命令。 - dev/build-deploy.md：新增「安全配置」（JWT_SECRET 覆盖、CORS 放行来源），构建任务链补入前端 lint 校验说明。 - dev/ai.md：修正已重命名的提示词模板名，补充「提示词模板」片段机制与图片记账 SSE 超时、心跳说明。 - dev/project-structure.md：补充 config.crypto / util.crypto 包、prompts 资源目录、crypto-keys.json 运行时文件与交易服务拆分说明。 - guide/getting-started.md：新增「小屏与移动端适配」说明。 - guide/transactions.md：导出说明补充单次 10000 条上限。
111 lines
5.1 KiB
Markdown
111 lines
5.1 KiB
Markdown
# 整体架构
|
||
|
||
本章介绍系统的分层结构与关键技术设计。
|
||
|
||
## 技术栈
|
||
|
||
| 层级 | 技术 |
|
||
|---|---|
|
||
| 后端 | 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 |
|
||
| AI | DeepSeek（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` | 入参请求对象 / 出参视图对象 |
|
||
| `converter` | MapStruct 实体↔VO 转换（`VoConverter`） |
|
||
| `importer` | 账单解析器（`BillParser` 及实现、`BillArchiveExtractor`） |
|
||
| `exporter` | Excel 导出样式处理 |
|
||
| `notification` | 通知渠道发送器（工厂 + 各渠道实现） |
|
||
| `scheduler` | 定时任务（通知、日志清理、邮箱账单） |
|
||
| `interceptor` | JWT 鉴权、访问日志 |
|
||
| `config` | Web、JWT、Knife4j、MyBatis-Plus、动态数据源、SPA 路由回退 |
|
||
| `client` | DeepSeek 客户端 |
|
||
| `email` | IMAP 邮箱账单抓取（监听、拉取、解析、存储） |
|
||
| `common` | `Result`、`PageResult`、业务异常、全局异常处理 |
|
||
| `util` | `JwtUtil`、`UserContext`、`AppLogUtils` 等 |
|
||
| `enums` | `BillType`、`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 文档 · 接口数据加密](/dev/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. **运行时动态数据源**：启动无需数据库，配置后热切换，见[动态数据源](/dev/database)。
|
||
2. **账单两阶段导入**：解析预览 → 确认导入，按交易号去重，见[账单解析](/dev/bill-parsing)。
|
||
3. **规则引擎**：分类取最高优先级、标签取并集，见[规则引擎](/dev/rule-engine)。
|
||
4. **体系化 AI 调用**：13 类调用类型并记录 token 用量，见 [AI 集成](/dev/ai)。
|
||
5. **SSE 实时能力**：运行日志、邮箱检查进度、图片记账识别进度与数据库配置执行进度实时推送。
|
||
6. **用户偏好缓存**：`t_user_preference` 的读取走 Spring Cache 进程内缓存（`ConcurrentMapCacheManager`），写入时按用户失效，切换数据源时整体清空。
|
||
7. **接口数据加密**：`/api/**` 请求/响应体支持 RSA + AES-GCM 端到端加密，握手自动完成、对未加密客户端透明，见 [API 文档](/dev/api#接口数据加密)。
|
||
|
||
## 相关文档
|
||
|
||
- [数据模型](/dev/data-model)
|
||
- [账单解析](/dev/bill-parsing)
|
||
- [规则引擎](/dev/rule-engine)
|
||
- [AI 集成](/dev/ai)
|
||
- [定时通知](/dev/notifications)
|
||
- [动态数据源](/dev/database)
|