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 条上限。
98 lines
4.5 KiB
Markdown
98 lines
4.5 KiB
Markdown
# 项目结构
|
||
|
||
## 仓库根目录
|
||
|
||
```text
|
||
ledgerly/
|
||
├── build.gradle # Gradle 构建脚本（依赖、打包、前端集成、Spotless）
|
||
├── settings.gradle # Gradle 项目设置
|
||
├── gradlew / gradlew.bat # Gradle Wrapper
|
||
├── gradle/wrapper/ # Wrapper 配置与 jar
|
||
├── .gitignore
|
||
├── README.md # 功能特性与技术栈概览
|
||
├── src/main/java/ # 后端源码
|
||
├── src/main/resources/ # 配置、MyBatis XML、建表脚本
|
||
└── frontend/ # Vue 3 前端
|
||
```
|
||
|
||
> 以上为纳入版本管理的目录与文件；本地开发用的运行编排、脚本与文档（如 `run/`、`reload.sh`、`docs/` 等）不在版本管理中，故不在此列出。
|
||
|
||
## 后端包结构
|
||
|
||
`src/main/java/cn/rosercode/ledgerly/`
|
||
|
||
| 包 | 职责 |
|
||
|---|---|
|
||
| `client` | 外部服务客户端（DeepSeek） |
|
||
| `common` | 通用响应（`Result`、`PageResult`）、业务异常与全局异常处理 |
|
||
| `config` | 应用配置、动态数据源、Knife4j、MyBatis-Plus、SPA 路由回退；`config.crypto` 为接口加解密拦截器与请求/响应体 Advice |
|
||
| `controller` | REST 接口层 |
|
||
| `converter` | MapStruct 对象转换器（`VoConverter`） |
|
||
| `dto` | 请求对象 |
|
||
| `email` | IMAP 邮箱账单抓取（监听、拉取、解析、存储） |
|
||
| `entity` | 数据库表映射实体 |
|
||
| `enums` | 枚举（`BillType`、`AiCallType`、`StatisticsDimension` 等） |
|
||
| `exporter` | Excel 导出处理 |
|
||
| `importer` | 账单解析器（支付宝/微信/美团/淘宝/京东/银行）与压缩包解密 |
|
||
| `interceptor` | JWT 鉴权、访问日志 |
|
||
| `mapper` | 数据访问层（MyBatis-Plus） |
|
||
| `notification` | 通知渠道发送器 |
|
||
| `scheduler` | 定时任务（通知、日志清理、邮箱账单） |
|
||
| `service` / `service.impl` | 业务层（交易记录服务已按职责拆分：查询条件构建、VO 富化、标签写入、批量操作、导出组装） |
|
||
| `util` | 工具类（`JwtUtil`、`UserContext`、`AppLogUtils`、`ImageUtils`、`AppHome`、`TransactionDedupUtils` 等）；`util.sql` 为智能查数的安全网关（`TextToSqlGuard` / `TextToSqlTables` / `TextToSqlSchemaProvider`）；`util.crypto` 为接口加解密服务（`ApiCryptoService` / `CryptoSessionStore` / `RsaKeyManager`） |
|
||
| `prompt` | AI 提示词模板加载（`PromptTemplateService`，模板位于 `resources/prompts/`） |
|
||
| `vo` | 响应对象 |
|
||
| `launcher` | 桌面 GUI 启动器（仅打入带 GUI 的 jar） |
|
||
|
||
## 资源目录
|
||
|
||
`src/main/resources/`
|
||
|
||
```text
|
||
application.yml # 应用配置（JWT、MyBatis-Plus、springdoc、端口等）
|
||
logback-spring.xml # 日志配置（控制台 + 按天滚动文件）
|
||
mapper/ # MyBatis XML
|
||
prompts/ # AI 提示词模板（Thymeleaf TEXT 模式，*.tpl；系统/用户提示词为同文件不同片段）
|
||
sql/
|
||
├── init.sql # MySQL 建表脚本
|
||
├── schema-sqlite.sql # SQLite 建表脚本（以 ;; 分隔语句）
|
||
├── init_categories.sql # 默认分类种子（MySQL）
|
||
└── init_tags.sql # 默认标签种子（MySQL）
|
||
```
|
||
|
||
## 前端结构
|
||
|
||
`frontend/src/`
|
||
|
||
```text
|
||
App.vue # 应用根组件
|
||
main.ts # 入口（挂载应用与插件）
|
||
style.css # 全局样式
|
||
api/ # 各模块 REST 接口封装（axios）
|
||
components/ # 复用组件（账单预览、导入结果、AI/通知/数据库配置面板、账单关系、AI 查询浮窗等）
|
||
composables/ # 组合式函数（AI 启用状态、导航配置、分页选项、关键词历史等）
|
||
locales/ # 中/英/日三语文案（messages.ts）
|
||
router/ # 路由与导航守卫
|
||
store/ # Pinia 状态（user / database / registration）
|
||
utils/ # 工具（交易渠道标签、SSE 封装、本地偏好存储、渲染辅助）
|
||
views/ # 页面组件
|
||
```
|
||
|
||
## 运行时目录
|
||
|
||
应用运行目录下会自动创建：
|
||
|
||
| 目录/文件 | 说明 |
|
||
|---|---|
|
||
| `config/database.json` | 数据库配置（SQLite / MySQL） |
|
||
| `config/app.json` | 应用配置（注册开关、通知链接、日志保留天数、按账单来源的计入统计默认值） |
|
||
| `config/crypto-keys.json` | 接口加解密用的 RSA 密钥对（首次启动自动生成） |
|
||
| `data/` | SQLite 数据文件、邮箱账单附件与图片记账截图（`data/ai-images/`） |
|
||
| `logs/` | 运行日志文件 |
|
||
|
||
## 相关文档
|
||
|
||
- [整体架构](/dev/architecture)
|
||
- [构建与部署](/dev/build-deploy)
|
||
- [开发环境与规范](/dev/development)
|