locobook/README.md

# 📚 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**