227 lines
8.2 KiB
Markdown
227 lines
8.2 KiB
Markdown
# 笔记应用 (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:
|
||
```bash
|
||
mvn spring-boot:run
|
||
```
|
||
5. **验证**: 访问 `http://localhost:8080/doc.html` 查看 API 文档。
|
||
|
||
### 前端启动
|
||
|
||
1. **进入目录**: `cd biji-qianduan`
|
||
2. **安装依赖**:
|
||
```bash
|
||
pnpm install
|
||
# 或者使用 npm / yarn
|
||
# npm install
|
||
# yarn install
|
||
```
|
||
3. **运行开发服务器**:
|
||
```bash
|
||
pnpm dev
|
||
```
|
||
4. **访问应用**: 在浏览器中打开 `http://localhost:5173` (或其他 Vite 指定的端口)。
|
||
|
||
### 生产环境部署
|
||
|
||
> 我使用的部署方式：
|
||
> 1、后端部署，使用docker部署后端，并且使用caddy作为反向代理，返代后端
|
||
> 2、在前端，cd biji-qianduan，在.env.production文件添加返代后端的接口地址，之后打包
|
||
> 3、在caddy部署前端打包好的前端文件
|
||
|
||
1. **构建前端**:
|
||
在.env.production文件添加自己后端的接口地址
|
||
```bash
|
||
cd biji-qianduan
|
||
pnpm run build:frontend
|
||
```
|
||
2. **构建后端**:
|
||
```bash
|
||
cd biji-houdaun
|
||
mvn clean package -P prod -D maven.test.skip=true -am docker:build
|
||
```
|
||
3. **运行**: 使用生成的 JAR 文件运行应用:
|
||
```bash
|
||
java -jar target/biji-houdaun-0.0.1-SNAPSHOT.jar
|
||
```
|
||
|
||
## 📖 使用指南
|
||
|
||
### 基本功能
|
||
|
||
1. **注册/登录**: 访问应用首页，点击"注册"创建新账户，或使用已有账户登录。
|
||
2. **创建笔记**: 登录后，点击"新建笔记"按钮，输入标题和内容。
|
||
3. **编辑笔记**: 使用 Markdown 语法编辑笔记，支持实时预览。
|
||
4. **管理分组**: 创建、编辑和删除笔记分组，方便组织笔记。
|
||
5. **上传图片**: 在笔记编辑器中点击图片按钮，上传并插入图片。
|
||
6. **回收站**: 删除的笔记和分组会进入回收站，可在30天内恢复。
|
||
|
||
### 高级功能
|
||
|
||
1. **Markdown 语法**:
|
||
- 标题: `# 一级标题`, `## 二级标题`
|
||
- 列表: `- 无序列表`, `1. 有序列表`
|
||
- 代码: `代码` 或 ```代码块```
|
||
- 链接: `[文本](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. **提交更改**:
|
||
```bash
|
||
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](LICENSE) 文件。
|