chore: 初始化文档站仓库

2026-09-21 13:38:20 +08:00
commit a4ae7ac979
58 changed files with 4622 additions and 0 deletions
@@ -0,0 +1,93 @@
+# 项目结构
+
+## 仓库根目录
+
+```text
+finance-app/
+├── 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/finance/`
+
+| 包 | 职责 |
+|---|---|
+| `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` 等） |
+| `vo` | 响应对象 |
+| `launcher` | 桌面 GUI 启动器（仅打入带 GUI 的 jar） |
+
+## 资源目录
+
+`src/main/resources/`
+
+```text
+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/`
+
+```text
+App.vue        # 应用根组件
+main.ts        # 入口（挂载应用与插件）
+style.css      # 全局样式
+api/           # 各模块 REST 接口封装（axios）
+components/    # 复用组件（账单预览、导入结果、AI/通知/数据库配置面板等）
+locales/       # 中/英/日三语文案（messages.ts）
+router/        # 路由与导航守卫
+store/         # Pinia 状态（user / database / registration）
+utils/         # 工具（交易渠道标签、SSE 封装、渲染辅助）
+views/         # 页面组件
+```
+
+## 运行时目录
+
+应用运行目录下会自动创建：
+
+| 目录/文件 | 说明 |
+|---|---|
+| `config/database.json` | 数据库配置（SQLite / MySQL） |
+| `config/app.json` | 应用配置（注册开关、通知链接、日志保留天数、按账单来源的计入统计默认值） |
+| `data/` | SQLite 数据文件与邮箱账单附件 |
+| `logs/` | 运行日志文件 |
+
+## 相关文档
+
+- [整体架构](/dev/architecture)
+- [构建与部署](/dev/build-deploy)
+- [开发环境与规范](/dev/development)