docs(README): 更新项目文档并添加部署指南
- 在 README.md 中添加了详细的项目结构、快速开始、使用指南、开发指南等内容 - 新增生产环境部署步骤，包括前端和后端的构建
This commit is contained in:
152
README.md
152
README.md
@@ -1,15 +1,33 @@
|
||||
# 笔记应用 (Biji App)
|
||||
|
||||
这是一个功能完善的全栈笔记应用程序，采用前后端分离架构。前端使用 Vue 3 构建，后端使用 Spring Boot 3 实现。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
一个功能完善的全栈笔记应用程序，采用前后端分离架构设计。前端使用 Vue 3 构建，后端基于 Spring Boot 3 实现，为用户提供简洁高效的笔记管理体验。
|
||||
|
||||
## 📋 目录
|
||||
|
||||
- [✨ 功能特性](#-功能特性)
|
||||
- [🛠️ 技术栈](#️-技术栈)
|
||||
- [📂 项目结构](#-项目结构)
|
||||
- [🚀 快速开始](#-快速开始)
|
||||
- [📖 使用指南](#-使用指南)
|
||||
- [🔧 开发指南](#-开发指南)
|
||||
- [🤝 贡献指南](#-贡献指南)
|
||||
- [📄 许可证](#-许可证)
|
||||
|
||||
## ✨ 功能特性 (Features)
|
||||
|
||||
* **用户认证**: 支持用户注册、登录和 JWT (JSON Web Token) 认证。
|
||||
* **Markdown 笔记**: 提供功能强大的 Markdown 编辑器，支持实时预览和丰富的格式化选项。
|
||||
* **图片管理**: 支持在笔记中上传、插入和管理图片。
|
||||
* **笔记组织**: 用户可以创建分组 (Categories/Groups) 来管理和组织笔记。
|
||||
* **回收站**: 提供回收站功能，可以恢复被误删除的笔记或分组。
|
||||
* **系统设置**: 提供基本的系统配置功能。
|
||||
* **用户认证**: 支持用户注册、登录和 JWT (JSON Web Token) 认证，保障账户安全。
|
||||
* **Markdown 笔记**: 提供功能强大的 Markdown 编辑器，支持实时预览、代码高亮、数学公式和丰富的格式化选项。
|
||||
* **图片管理**: 支持在笔记中上传、插入和管理图片，提供图片预览和删除功能。
|
||||
* **笔记组织**: 用户可以创建分组 (Categories/Groups) 来管理和组织笔记，支持多层级分类。
|
||||
* **回收站**: 提供回收站功能，可以恢复被误删除的笔记或分组，避免数据丢失。
|
||||
* **系统设置**: 提供基本的系统配置功能，包括主题切换、语言选择等个性化设置。
|
||||
* **响应式设计**: 适配桌面和移动设备，提供一致的用户体验。
|
||||
* **数据持久化**: 使用 SQLite 数据库存储用户数据，无需额外配置数据库服务。
|
||||
|
||||
## 🛠️ 技术栈 (Tech Stack)
|
||||
|
||||
@@ -25,13 +43,14 @@
|
||||
|
||||
### 前端 (Frontend - `biji-qianduan`)
|
||||
|
||||
* **框架 (Framework)**: Vue 3
|
||||
* **框架 (Framework)**: Vue 3 (Composition API)
|
||||
* **构建工具 (Build Tool)**: Vite
|
||||
* **UI 库 (UI Library)**: Element Plus
|
||||
* **状态管理 (State Management)**: Pinia
|
||||
* **路由 (Routing)**: Vue Router
|
||||
* **路由 (Routing)**: Vue Router 4
|
||||
* **Markdown 编辑器**: Vditor / @kangc/v-md-editor
|
||||
* **HTTP 客户端 (HTTP Client)**: Axios (封装在 `src/utils/axios.js` 中)
|
||||
* **样式处理**: SCSS
|
||||
|
||||
## 📂 项目结构 (Project Structure)
|
||||
|
||||
@@ -55,6 +74,7 @@
|
||||
│ │ ├── components/ # Vue 组件
|
||||
│ │ ├── router/ # 路由配置
|
||||
│ │ ├── stores/ # Pinia 状态管理
|
||||
│ │ ├── views/ # 页面视图
|
||||
│ │ └── utils/ # 工具函数
|
||||
│ └── package.json # NPM 依赖配置
|
||||
│
|
||||
@@ -68,10 +88,10 @@
|
||||
|
||||
### 环境要求
|
||||
|
||||
* JDK 17
|
||||
* Maven 3.x
|
||||
* Node.js 18+
|
||||
* pnpm (或 npm/yarn)
|
||||
* **Java**: JDK 17 或更高版本
|
||||
* **构建工具**: Maven 3.6+ 或 Gradle 7.0+
|
||||
* **Node.js**: 18.0 或更高版本
|
||||
* **包管理器**: pnpm 8.0+ (推荐) 或 npm/yarn
|
||||
|
||||
### 后端启动
|
||||
|
||||
@@ -82,6 +102,7 @@
|
||||
```bash
|
||||
mvn spring-boot:run
|
||||
```
|
||||
5. **验证**: 访问 `http://localhost:8080/doc.html` 查看 API 文档。
|
||||
|
||||
### 前端启动
|
||||
|
||||
@@ -98,3 +119,108 @@
|
||||
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) 文件。
|
||||
|
||||
Reference in New Issue
Block a user