笔记应用 (Biji App)

一个功能完善的全栈笔记应用程序，采用前后端分离架构设计。前端使用 Vue 3 构建，后端基于 Spring Boot 3 实现，为用户提供简洁高效的笔记管理体验。

📋 目录

• ✨ 功能特性
• 🛠️ 技术栈
• 📂 项目结构
• 🚀 快速开始
• 📖 使用指南
• 🔧 开发指南
• 🤝 贡献指南
• 📄 许可证

✨ 功能特性 (Features)

• 用户认证: 支持用户注册、登录和 JWT (JSON Web Token) 认证，保障账户安全。
• Markdown 笔记: 提供功能强大的 Markdown 编辑器，支持实时预览、代码高亮、数学公式和丰富的格式化选项。
• 图片管理: 支持在笔记中上传、插入和管理图片，提供图片预览和删除功能。
• 笔记组织: 用户可以创建分组 (Categories/Groups) 来管理和组织笔记，支持多层级分类。
• 回收站: 提供回收站功能，可以恢复被误删除的笔记或分组，避免数据丢失。
• 系统设置: 提供基本的系统配置功能，包括主题切换、语言选择等个性化设置。
• 响应式设计: 适配桌面和移动设备，提供一致的用户体验。
• 数据持久化: 使用 SQLite 数据库存储用户数据，无需额外配置数据库服务。

🛠️ 技术栈 (Tech Stack)

后端 (Backend - biji-houdaun)

• 框架 (Framework): Spring Boot 3.5.0
• 语言 (Language): Java 17
• 数据访问 (Data Access): MyBatis-Plus 3.5.7
• 数据库 (Database): SQLite
• API 文档 (API Docs): Knife4j / SpringDoc
• 安全 (Security): Spring Security, JJWT
• 工具库 (Utilities): Lombok, Hutool, Commons Codec

前端 (Frontend - biji-qianduan)

• 框架 (Framework): Vue 3 (Composition API)
• 构建工具 (Build Tool): Vite
• UI 库 (UI Library): Element Plus
• 状态管理 (State Management): Pinia
• 路由 (Routing): Vue Router 4
• Markdown 编辑器: Vditor / @kangc/v-md-editor
• HTTP 客户端 (HTTP Client): Axios (封装在 src/utils/axios.js 中)
• 样式处理: SCSS

📂 项目结构 (Project Structure)

.
├── biji-houdaun/         # 后端 Spring Boot 项目
│   ├── src/main/java/    # Java 源码
│   │   └── com/test/bijihoudaun/
│   │       ├── controller/ # API 控制器
│   │       ├── service/    # 业务逻辑服务
│   │       ├── mapper/     # MyBatis 数据映射
│   │       ├── entity/     # 数据库实体
│   │       ├── config/     # 应用配置
│   │       └── common/     # 通用工具 (异常处理、响应)
│   └── pom.xml           # Maven 依赖配置
│
├── biji-qianduan/        # 前端 Vue 项目
│   ├── src/              # 前端源码
│   │   ├── api/          # API 请求模块
│   │   ├── assets/       # 静态资源 (CSS, images)
│   │   ├── components/   # Vue 组件
│   │   ├── router/       # 路由配置
│   │   ├── stores/       # Pinia 状态管理
│   │   ├── views/        # 页面视图
│   │   └── utils/        # 工具函数
│   └── package.json      # NPM 依赖配置
│
├── sql/                  # 数据库初始化脚本
├── uploads/              # 用户上传文件目录
├── doc/                  # 项目相关文档
└── README.md             # 本文档

🚀 快速开始 (Getting Started)

环境要求

• Java: JDK 17 或更高版本
• 构建工具: Maven 3.6+ 或 Gradle 7.0+
• Node.js: 18.0 或更高版本
• 包管理器: pnpm 8.0+ (推荐) 或 npm/yarn

后端启动

1. 克隆项目: git clone <repository-url>
2. 数据库初始化: 使用 sql/ 目录下的脚本初始化 SQLite 数据库 (mydatabase.db)。
3. 配置: 检查 biji-houdaun/src/main/resources/application-dev.yml 中的配置是否正确。
4. 运行: 在 biji-houdaun 目录下，通过 IDE 直接运行 BijiHoudaunApplication.java 或使用 Maven:

   mvn spring-boot:run
   

5. 验证: 访问 http://localhost:8080/doc.html 查看 API 文档。

前端启动

1. 进入目录: cd biji-qianduan
2. 安装依赖:

   pnpm install
   # 或者使用 npm / yarn
   # npm install
   # yarn install
   

3. 运行开发服务器:

   pnpm dev
   

4. 访问应用: 在浏览器中打开 http://localhost:5173 (或其他 Vite 指定的端口)。

生产环境部署

我使用的部署方式： 1、后端部署，使用docker部署后端，并且使用caddy作为反向代理，返代后端 2、在前端，cd biji-qianduan，在.env.production文件添加返代后端的接口地址，之后打包 3、在caddy部署前端打包好的前端文件

1. 构建前端: 在.env.production文件添加自己后端的接口地址

   cd biji-qianduan
   pnpm run build:frontend
   

2. 构建后端:

   cd biji-houdaun
   mvn clean package -P prod -D maven.test.skip=true -am docker:build
   

3. 运行: 使用生成的 JAR 文件运行应用:

   java -jar target/biji-houdaun-0.0.1-SNAPSHOT.jar
   

📖 使用指南

基本功能

1. 注册/登录: 访问应用首页，点击"注册"创建新账户，或使用已有账户登录。
2. 创建笔记: 登录后，点击"新建笔记"按钮，输入标题和内容。
3. 编辑笔记: 使用 Markdown 语法编辑笔记，支持实时预览。
4. 管理分组: 创建、编辑和删除笔记分组，方便组织笔记。
5. 上传图片: 在笔记编辑器中点击图片按钮，上传并插入图片。
6. 回收站: 删除的笔记和分组会进入回收站，可在30天内恢复。

高级功能

1. Markdown 语法:

   • 标题: # 一级标题, ## 二级标题
   • 列表: - 无序列表, 1. 有序列表
   • 代码: 代码 或 代码块
   • 链接: [文本](URL)
   • 图片: ![描述](图片URL)

2. 快捷键:

   • 保存笔记: Ctrl + S
   • 加粗: Ctrl + B
   • 斜体: Ctrl + I
   • 撤销: Ctrl + Z
   • 重做: Ctrl + Y

🔧 开发指南

后端开发

1. 添加新 API:

   • 在 controller 包中创建新的控制器类
   • 在 service 包中实现业务逻辑
   • 在 mapper 包中定义数据访问接口
   • 在 entity 包中创建数据实体类

2. 数据库变更:

   • 修改 sql 目录下的数据库脚本
   • 更新对应的实体类和映射文件

前端开发

1. 添加新页面:

   • 在 src/views 目录下创建新组件
   • 在 src/router 中添加路由配置
   • 在 src/api 中添加相关的 API 请求方法

2. 添加新组件:

   • 在 src/components 目录下创建新组件
   • 在需要的地方导入并使用组件

3. 状态管理:

   • 在 src/stores 目录下创建新的 store
   • 在组件中使用 useStore 访问状态

🤝 贡献指南

我们欢迎所有形式的贡献！如果您想为 Biji App 做出贡献，请遵循以下步骤：

1. Fork 项目: 点击页面右上角的 Fork 按钮。
2. 克隆仓库: git clone https://github.com/yourusername/biji-app.git
3. 创建分支: git checkout -b feature/your-feature-name
4. 提交更改:

   git add .
   git commit -m "Add your feature"
   

5. 推送分支: git push origin feature/your-feature-name
6. 提交 Pull Request: 在 GitHub 上创建 Pull Request。

开发规范

• 遵循项目中现有的代码风格
• 提交信息应清晰明了，使用英文
• 每个功能或修复应提交单独的 Pull Request
• 确保所有测试通过后再提交

📄 许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。