ledgerly-docs/dev/project-structure.md

项目结构

仓库根目录

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 路由回退
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	业务层
util	工具类（JwtUtil、UserContext、AppLogUtils、ImageUtils、AppHome、TransactionDedupUtils 等）；util.sql 为智能查数的安全网关（TextToSqlGuard / TextToSqlTables / TextToSqlSchemaProvider）
prompt	AI 提示词模板加载（PromptTemplateService，模板位于 resources/prompts/）
vo	响应对象
launcher	桌面 GUI 启动器（仅打入带 GUI 的 jar）

资源目录

src/main/resources/

application.yml         # 应用配置（JWT、MyBatis-Plus、springdoc、端口等）
logback-spring.xml      # 日志配置（控制台 + 按天滚动文件）
mapper/                 # MyBatis XML
sql/
├── init.sql            # MySQL 建表脚本
├── schema-sqlite.sql   # SQLite 建表脚本（以 ;; 分隔语句）
├── init_categories.sql # 默认分类种子（MySQL）
└── init_tags.sql       # 默认标签种子（MySQL）

前端结构

frontend/src/

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	应用配置（注册开关、通知链接、日志保留天数、按账单来源的计入统计默认值）
data/	SQLite 数据文件、邮箱账单附件与图片记账截图（data/ai-images/）
logs/	运行日志文件

相关文档

• 整体架构
• 构建与部署
• 开发环境与规范