From 46c72e4ceb5f8b0a47b8feb888549e4eb53d0a8e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E5=AE=8F=E5=BB=BA?= <macrocc@outlook.com>
Date: Thu, 30 Apr 2026 00:29:50 +0800
Subject: [PATCH] =?UTF-8?q?docs(readme):=20=E6=B7=BB=E5=8A=A0=E9=A1=B9?=
 =?UTF-8?q?=E7=9B=AE=E6=96=87=E6=A1=A3=E5=92=8C=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 创建了完整的 README.md 文件
- 添加了项目特性介绍和功能说明
- 详细描述了技术栈和架构设计
- 提供了快速开始和安装指南
- 列出了项目结构和 API 接口文档
- 包含了测试和部署说明
- 添加了贡献指南和许可证信息
---
 README.md | 302 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 302 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b3d5939
--- /dev/null
+++ b/README.md
@@ -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**