docs(readme): 添加项目文档和说明
- 创建了完整的 README.md 文件 - 添加了项目特性介绍和功能说明 - 详细描述了技术栈和架构设计 - 提供了快速开始和安装指南 - 列出了项目结构和 API 接口文档 - 包含了测试和部署说明 - 添加了贡献指南和许可证信息
This commit is contained in:
@@ -0,0 +1,302 @@
|
||||
# 📚 LocoBook - 图书管理系统
|
||||
|
||||
一个基于 **Rust Loco** 后端和 **Vue 3** 前端的现代化图书管理系统。
|
||||
|
||||
## ✨ 特性
|
||||
|
||||
- 🔐 **用户认证**: JWT 基于 token 的登录/注册系统
|
||||
- 📖 **图书管理**: 浏览、阅读图书,支持分页加载
|
||||
- 📝 **阅读记录**: 自动保存阅读进度和历史记录
|
||||
- 🎨 **现代 UI**: 使用 Tailwind CSS 4 构建的响应式界面
|
||||
- ⚡ **高性能**: Rust 后端提供快速稳定的 API 服务
|
||||
- 🔧 **开发友好**: Vite 统一管理前后端,一键启动
|
||||
|
||||
## 🛠️ 技术栈
|
||||
|
||||
### 后端
|
||||
- **框架**: [Loco.rs](https://loco.rs/) 0.16 (基于 Axum + SeaORM)
|
||||
- **语言**: Rust
|
||||
- **数据库**: SQLite
|
||||
- **认证**: JWT
|
||||
- **ORM**: SeaORM
|
||||
|
||||
### 前端
|
||||
- **框架**: Vue 3.5 (Composition API)
|
||||
- **构建工具**: Vite 8.0
|
||||
- **路由**: Vue Router 4.5
|
||||
- **状态管理**: Pinia 2.3
|
||||
- **HTTP 客户端**: Axios 1.7
|
||||
- **样式**: Tailwind CSS 4.2
|
||||
|
||||
## 📦 快速开始
|
||||
|
||||
### 前置要求
|
||||
|
||||
- [Rust](https://www.rust-lang.org/tools/install) (最新稳定版)
|
||||
- [Node.js](https://nodejs.org/) (v18+)
|
||||
- [Cargo Loco CLI](https://loco.rs/docs/getting-started/installation/)
|
||||
|
||||
### 安装
|
||||
|
||||
1. **克隆仓库**
|
||||
```bash
|
||||
git clone http://macrocc.com:3000/macrocc/locobook.git
|
||||
cd locobook
|
||||
```
|
||||
|
||||
2. **安装前端依赖**
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. **初始化数据库**
|
||||
```bash
|
||||
cd src-loco
|
||||
cargo loco db migrate
|
||||
cd ..
|
||||
```
|
||||
|
||||
### 运行开发服务器
|
||||
|
||||
**一键启动前后端:**
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
这将:
|
||||
- 启动后端服务器 (http://localhost:5150)
|
||||
- 启动前端开发服务器 (http://localhost:5173)
|
||||
- 自动打开浏览器
|
||||
|
||||
**单独启动:**
|
||||
```bash
|
||||
# 仅启动后端
|
||||
cd src-loco && cargo loco start
|
||||
|
||||
# 仅启动前端
|
||||
npm run dev:frontend
|
||||
```
|
||||
|
||||
### 重启服务
|
||||
|
||||
修改 Rust 代码后需要重启:
|
||||
```bash
|
||||
npm run restart
|
||||
```
|
||||
|
||||
## 📁 项目结构
|
||||
|
||||
```
|
||||
locobook/
|
||||
├── src-loco/ # Rust Loco 后端
|
||||
│ ├── src/
|
||||
│ │ ├── controllers/ # API 控制器
|
||||
│ │ │ ├── auth.rs # 认证相关接口
|
||||
│ │ │ ├── books.rs # 图书管理接口
|
||||
│ │ │ └── reading.rs # 阅读记录接口
|
||||
│ │ ├── models/ # 数据模型
|
||||
│ │ │ ├── users.rs
|
||||
│ │ │ ├── books.rs
|
||||
│ │ │ └── reading_records.rs
|
||||
│ │ ├── views/ # 响应视图
|
||||
│ │ └── app.rs # 应用配置
|
||||
│ ├── migration/ # 数据库迁移
|
||||
│ ├── tests/ # 后端测试
|
||||
│ └── config/ # 配置文件
|
||||
├── src/ # Vue 3 前端
|
||||
│ ├── views/ # 页面组件
|
||||
│ │ ├── Login.vue
|
||||
│ │ ├── Register.vue
|
||||
│ │ ├── BookList.vue
|
||||
│ │ ├── BookReader.vue
|
||||
│ │ └── ReadingHistory.vue
|
||||
│ ├── components/ # 通用组件
|
||||
│ │ └── Navbar.vue
|
||||
│ ├── api/ # API 封装
|
||||
│ ├── router/ # 路由配置
|
||||
│ └── main.js # 入口文件
|
||||
├── package.json # 前端依赖和脚本
|
||||
├── vite.config.js # Vite 配置
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## 🔌 API 接口
|
||||
|
||||
### 认证接口
|
||||
|
||||
| 方法 | 路径 | 描述 | 认证 |
|
||||
|------|------|------|------|
|
||||
| POST | `/api/auth/register` | 用户注册 | ❌ |
|
||||
| POST | `/api/auth/login` | 用户登录 | ❌ |
|
||||
| POST | `/api/auth/verify` | 验证邮箱 | ❌ |
|
||||
| GET | `/api/auth/current` | 获取当前用户 | ✅ |
|
||||
|
||||
### 图书接口
|
||||
|
||||
| 方法 | 路径 | 描述 | 认证 |
|
||||
|------|------|------|------|
|
||||
| GET | `/api/books` | 获取图书列表(分页) | ❌ |
|
||||
| GET | `/api/books/:id` | 获取单本图书 | ❌ |
|
||||
| POST | `/api/books` | 创建图书 | ✅ |
|
||||
| PUT | `/api/books/:id` | 更新图书 | ✅ |
|
||||
| DELETE | `/api/books/:id` | 删除图书 | ✅ |
|
||||
|
||||
**分页参数:**
|
||||
```
|
||||
GET /api/books?page=1&per_page=12
|
||||
```
|
||||
|
||||
**响应格式:**
|
||||
```json
|
||||
{
|
||||
"books": [...],
|
||||
"total": 100,
|
||||
"page": 1,
|
||||
"per_page": 12,
|
||||
"total_pages": 9
|
||||
}
|
||||
```
|
||||
|
||||
### 阅读记录接口
|
||||
|
||||
| 方法 | 路径 | 描述 | 认证 |
|
||||
|------|------|------|------|
|
||||
| POST | `/api/reading/record` | 保存阅读进度 | ✅ |
|
||||
| GET | `/api/reading/history` | 获取阅读历史 | ✅ |
|
||||
|
||||
## 🧪 测试
|
||||
|
||||
### 运行后端测试
|
||||
|
||||
```bash
|
||||
cd src-loco
|
||||
|
||||
# 运行所有测试
|
||||
cargo test
|
||||
|
||||
# 运行特定模块测试
|
||||
cargo test books
|
||||
cargo test auth
|
||||
|
||||
# 运行单个测试
|
||||
cargo test can_list_books_with_pagination
|
||||
|
||||
# 显示测试输出
|
||||
cargo test -- --nocapture
|
||||
```
|
||||
|
||||
测试文件位于 `src-loco/tests/requests/`:
|
||||
- `auth.rs` - 认证接口测试
|
||||
- `books.rs` - 图书接口测试
|
||||
- `prepare_data.rs` - 测试数据准备
|
||||
|
||||
## 🎨 前端路由
|
||||
|
||||
| 路径 | 组件 | 描述 | 认证 |
|
||||
|------|------|------|------|
|
||||
| `/login` | Login | 登录页面 | ❌ |
|
||||
| `/register` | Register | 注册页面 | ❌ |
|
||||
| `/` | BookList | 图书列表 | ✅ |
|
||||
| `/book/:id` | BookReader | 图书阅读器 | ✅ |
|
||||
| `/history` | ReadingHistory | 阅读历史 | ✅ |
|
||||
|
||||
## ⚙️ 配置
|
||||
|
||||
### 后端配置
|
||||
|
||||
配置文件位于 `src-loco/config/`:
|
||||
- `development.yaml` - 开发环境
|
||||
- `test.yaml` - 测试环境
|
||||
- `production.yaml` - 生产环境
|
||||
|
||||
主要配置项:
|
||||
```yaml
|
||||
server:
|
||||
port: 5150
|
||||
|
||||
database:
|
||||
uri: sqlite://book-manager_development.sqlite?mode=rwc
|
||||
auto_migrate: true
|
||||
|
||||
auth:
|
||||
jwt:
|
||||
secret: your-secret-key
|
||||
expiration: 604800 # 7 days
|
||||
```
|
||||
|
||||
### 前端配置
|
||||
|
||||
Vite 配置在 `vite.config.js`:
|
||||
```javascript
|
||||
{
|
||||
server: {
|
||||
port: 5173,
|
||||
proxy: {
|
||||
'/api': {
|
||||
target: 'http://localhost:5150',
|
||||
changeOrigin: true
|
||||
}
|
||||
}
|
||||
},
|
||||
resolve: {
|
||||
alias: {
|
||||
'@': path.resolve(__dirname, './src')
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🚀 部署
|
||||
|
||||
### 构建前端
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
构建产物将输出到 `dist/` 目录。
|
||||
|
||||
### 构建后端
|
||||
|
||||
```bash
|
||||
cd src-loco
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
二进制文件位于 `target/release/book_manager-cli`。
|
||||
|
||||
### 生产环境运行
|
||||
|
||||
```bash
|
||||
# 后端
|
||||
cd src-loco
|
||||
cargo loco start --env production
|
||||
|
||||
# 前端 (使用静态文件服务器)
|
||||
npm run preview
|
||||
```
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
欢迎提交 Issue 和 Pull Request!
|
||||
|
||||
1. Fork 本仓库
|
||||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||||
5. 开启 Pull Request
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
|
||||
|
||||
## 🙏 致谢
|
||||
|
||||
- [Loco.rs](https://loco.rs/) - 优秀的 Rust Web 框架
|
||||
- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
|
||||
- [Tailwind CSS](https://tailwindcss.com/) - 实用优先的 CSS 框架
|
||||
- [SeaORM](https://www.sea-ql.org/SeaORM/) - Rust ORM 框架
|
||||
|
||||
---
|
||||
|
||||
**Made with ❤️ using Rust & Vue**
|
||||
Reference in New Issue
Block a user