From 466d816aa217e0a45caf1ba664c91c27692b2f18 Mon Sep 17 00:00:00 2001
From: hyx <1515023255@qq.com>
Date: Thu, 7 Aug 2025 21:28:10 +0800
Subject: [PATCH] =?UTF-8?q?=E5=89=8D=E5=90=8E=E7=AB=AF=E4=BA=A4=E4=BA=92?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 前端文档.md | 167 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 167 insertions(+)
 create mode 100644 前端文档.md

diff --git a/前端文档.md b/前端文档.md
new file mode 100644
index 0000000..18d26e5
--- /dev/null
+++ b/前端文档.md
@@ -0,0 +1,167 @@
+# 图书馆管理系统 - 前端与后端交互文档
+
+## 1.技术栈说明
+
+- **核心框架**：Vue 3（使用`<script setup>`语法糖）
+- **构建工具**：Vite
+- **UI 组件库**：Element Plus
+- **网络请求**：Axios
+- **状态管理**：Vuex
+- **路由管理**：Vue Router
+- **日期处理**：自定义`formatDate`工具函数
+
+## 2.项目文件结构说明
+
+```plaintext
+src/
+├── views/                 # 页面视图组件
+│   ├── Books/             # 图书相关页面
+│   │   ├── BookDetail.vue # 图书详情页
+│   │   ├── BookList.vue   # 图书列表页
+│   │   ├── AddBook.vue    # 添加图书页
+│   │   └── EditBook.vue   # 编辑图书页
+│   ├── Admin/             # 管理员页面
+│   │   ├── BookManagement.vue # 图书管理页
+│   │   └── AllBorrowRecords.vue # 所有借阅记录页
+│   ├── Borrow/            # 借阅相关页面
+│   │   ├── BorrowBook.vue # 借阅图书页
+│   │   └── ReturnBook.vue # 归还图书页
+│   ├── User/              # 用户相关页面
+│   │   ├── Profile.vue    # 个人中心页
+│   │   ├── BorrowRecords.vue # 借阅记录页
+│   │   └── Recharge.vue   # 账户充值页
+│   ├── Auth/              # 认证相关页面
+│   │   ├── Login.vue      # 登录页
+│   │   └── Register.vue   # 注册页
+│   ├── Ranking/           # 排行榜页面
+│   │   ├── WeeklyRank.vue # 本周热租榜
+│   │   └── MonthlyRank.vue # 本月热租榜
+│   └── Home.vue           # 首页
+├── components/            # 通用组件
+│   ├── HeaderBar.vue      # 顶部导航栏
+│   └── BookCard.vue       # 图书卡片组件
+├── router/                # 路由配置
+│   └── index.js           # 路由规则及守卫配置
+├── store/                 # Vuex状态管理
+│   ├── index.js           # store入口
+│   ├── modules/
+│   │   ├── book.js        # 图书相关状态
+│   │   ├── borrow.js      # 借阅相关状态
+│   │   └── user.js        # 用户相关状态
+└── App.vue                # 根组件
+```
+
+## 3.预设数据标注
+
+1. **BookDetail.vue** - fetchBook 失败时：
+
+   ```javascript
+   book.value = {
+     id: bookId,
+     title: '示例书籍',
+     url: 'https://picsum.photos/id/24/300/400',
+     money: 5.00,
+     number: 8,
+     content: '这是一本示例书籍，用于展示书籍详情页面的效果。',
+     state: '维护中'
+   }
+   ```
+
+2. **BookList.vue** - fetchBooks 失败时：
+
+   ```javascript
+   books.value = [
+     { id: 1, title: '三体', url: 'https://picsum.photos/id/24/200/300', money: 5, number: 12, state: '可借', content: '科幻' },
+     // ...共12条示例数据
+   ]
+   total.value = books.value.length
+   ```
+
+3. **BorrowBook.vue** - fetchBooks 失败时：
+
+   ```javascript
+   books.value = [
+     { id: 1, title: '三体', url: 'https://picsum.photos/id/24/200/300', money: 5, number: 12, state: '可借', content: '科幻' },
+     // ...共12条示例数据（同BookList）
+   ]
+   total.value = books.value.length
+   ```
+
+4. **ReturnBook.vue** - fetchBorrowedBooks 失败时：
+
+   ```javascript
+   store.commit('setBorrowedBooks', [
+     { 
+       id: 1, 
+       title: '三体', 
+       url: 'https://picsum.photos/id/24/200/300', 
+       borrow_time: '2023-10-01T10:30:00' 
+     },
+     { 
+       id: 4, 
+       title: '活着', 
+       url: 'https://picsum.photos/id/27/200/300', 
+       borrow_time: '2023-10-05T14:20:00' 
+     }
+   ])
+   ```
+
+5. **Home.vue** - 获取排行榜失败时：
+
+   ```javascript
+   // 本周热门预设
+   weeklyRank.value = [
+     { id: 1, title: '三体', url: 'https://picsum.photos/id/24/200/300', money: 5, number: 12 },
+     // ...共6条示例数据
+   ]
+   // 本月热门预设
+   monthlyRank.value = [
+     { id: 7, title: '小王子', url: 'https://picsum.photos/id/30/200/300', money: 2, number: 20 },
+     // ...共6条示例数据
+   ]
+   ```
+
+## 4.额外说明
+
+1. **权限控制**：
+   - 管理员权限：通过`store.getters.isAdmin`判断，对应路由 meta.requiresAdmin
+   - 用户登录态：通过`store.getters.isAuthenticated`判断，对应路由 meta.requiresAuth
+2. **状态管理**：
+   - 图书相关状态：`store/modules/book.js`
+   - 借阅相关状态：`store/modules/borrow.js`
+   - 用户相关状态：`store/modules/user.js`（包含用户信息、权限标识等）
+3. **错误处理**：
+   - 所有接口调用均包含 try/catch 处理
+   - 失败时通过`ElMessage.error`提示用户
+   - 关键接口失败时使用预设数据降级展示
+4. **路由配置**：
+   - 已在`router/index.js`中配置所有页面路由
+   - 包含路由守卫，控制权限访问
+5. **UI 组件**：
+   - 使用 Element Plus 组件库
+   - 主要组件：el-card、el-table、el-form、el-button、el-pagination 等
+
+------
+
+测试用例（网页控制台复制代码回车即可）
+
+```
+//用户
+store.commit('setUser',{ 
+ username: 'testuser', 
+ pic: 'https://picsum.photos/id/64/100/100', // 头像地址 
+ admin: false, // 普通用户 
+ create_time: '2023-01-01T00:00:00', 
+ update_time: '2023-10-01T00:00:00' }) // 同时设置余额和VIP信息 
+ store.commit('setBalanceAndVip', 
+{ balance: 100.50, vip: 2 }) 
+
+// 管理员 
+store.commit('setUser',{
+ username: 'admin',
+ pic: 'https://picsum.photos/id/91/100/100', 
+ admin: true, // 管理员 
+ create_time: '2023-01-01T00:00:00',
+ update_time: '2023-10-01T00:00:00' })
+```
+