bookMgr-client/README.md

# 图书管理系统（前端）

<p align="center">
  <img src="https://img.shields.io/badge/version-v0.1-blue" alt="version">
  <img src="https://img.shields.io/badge/React-19.2-61DAFB?logo=react" alt="React">
  <img src="https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript" alt="TypeScript">
  <img src="https://img.shields.io/badge/Vite-7.3-646CFF?logo=vite" alt="Vite">
  <img src="https://img.shields.io/badge/Tauri-2.11-FFC131?logo=tauri" alt="Tauri">
  <img src="https://img.shields.io/badge/Tailwind-4.3-38B2AC?logo=tailwindcss" alt="Tailwind CSS">
  <img src="https://img.shields.io/badge/license-MIT-brightgreen" alt="license">
</p>

<img src="app-icon.svg" width="200" height="200" alt="app icon">

图书管理系统的前端，支持 **Web 端** 和 **Tauri 桌面端/移动端**。基于 React + TypeScript + Vite，UI 组件 shadcn/ui + Tailwind CSS。

## 功能

- **图书浏览** — 搜索（书名 / 作者）、查看详情、借阅
- **个人借阅** — 查看借阅记录、归还图书、搜索借阅记录
- **管理后台** — 新增 / 修改 / 删除 / 调整库存、查看全部借阅、手动借还
- **用户认证** — JWT 登录 / 登出、角色权限控制、路由守卫
- **深色模式** — 跟随系统 / 手动切换 / localStorage 持久化
- **多平台** — Web / Linux / Windows / Android 统一代码库
- **响应式** — 桌面侧边栏 / 移动端底部标签栏自适应

## 截图

**Web 登录**

![](screenshots/login-web.png)

**Web 首页（未登录）**

![](screenshots/guest-web.png)

**Web 普通用户**

![](screenshots/user-web.png)

**Web 管理员**

![](screenshots/admin-web.png)

**移动端登录**

![](screenshots/login-mobie.jpg)

**移动端首页（未登录）**

![](screenshots/guest-mobie.jpg)

**移动端普通用户**

![](screenshots/user-mobie.jpg)

**移动端管理员**

![](screenshots/admin-mobie.jpg)

## 技术栈

| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 框架 | React | 19.2 | |
| 语言 | TypeScript | 5.8 | |
| 构建 | Vite | 7.3 | ESM 原生开发服务器，Rollup 生产打包 |
| CSS | Tailwind CSS | 4.3 | 原子化 CSS |
| UI 组件 | shadcn/ui + Radix | — | 无头组件，可控样式 |
| 路由 | React Router | 7.15 | 嵌套布局路由 |
| 数据请求 | TanStack Query | 5.100 | 缓存、自动 refetch |
| HTTP | Axios | 1.16 | 拦截器自动注入 JWT、错误处理 |
| 状态管理 | Zustand | 5.0 | auth / theme 全局状态 |
| 图标 | Lucide React | 1.16 | |
| 桌面端 | Tauri | 2.11 | Rust 后端，WebView 前端 |
| Toast | Sonner | 2.0 | |

## 快速开始

### 环境要求

- Node.js ≥ 22
- pnpm（通过 corepack 管理）

### 1. 安装依赖

```bash
pnpm install
```

### 2. 开发模式

```bash
# Web 版（默认端口 1420）
pnpm dev

# 桌面端
pnpm tauri dev

# 桌面端（跳过前端的 tsc 检查，加快启动）
pnpm tauri dev --no-dev-server-wait
```

开发模式下 `/api/*` 请求自动代理到 `http://localhost:8080`（后端），可通过环境变量覆盖：

```bash
VITE_API_BASE=http://your-backend:8080 pnpm dev
```

### 3. 构建

```bash
# 仅前端（输出到 dist/）
pnpm build

# Tauri 桌面端
pnpm tauri build

# Tauri Android
pnpm tauri android build

# Pacman 包（Arch Linux，需先执行 pnpm tauri build）
./scripts/pacman-pkg.sh
```

### 4. 收集发布产物

将各平台构建产物统一收集到 `releases/<version>/`，并规范命名：

```bash
# Linux / macOS
./scripts/collect-artifacts.sh

# Windows
scripts\collect-artifacts.cmd
```

脚本会**跳过不存在的构建产物**，因此可以放心运行——你当前平台没构建的产物会被忽略。覆盖范围：

| 平台 | 产物 |
|------|------|
| Web | `.tar.gz` `.zip` |
| Linux | `.AppImage` `.deb` `.rpm` `.pkg.tar.zst` |
| Windows | `.msi` `.exe` |
| macOS | `.dmg` |
| Android | `.apk`（arm64 / x86_64 / universal） |

输出示例：

```
releases/0.1.0/
├── bookmgr-client-0.1.0-android-arm64.apk
├── bookmgr-client-0.1.0-android-universal.apk
├── bookmgr-client-0.1.0-android-x86_64.apk
├── bookmgr-client-0.1.0-linux-amd64.AppImage
├── bookmgr-client-0.1.0-linux-amd64.deb
├── bookmgr-client-0.1.0-linux-x86_64.pkg.tar.zst
├── bookmgr-client-0.1.0-linux-x86_64.rpm
├── bookmgr-client-0.1.0-web.tar.gz
└── bookmgr-client-0.1.0-web.zip
```

## 项目结构

```
src/
├── api/                  # API 层 — axios 请求函数
│   ├── client.ts         # axios 实例、拦截器、snake→camel 转换
│   ├── auth.ts           # 认证接口
│   ├── books.ts          # 图书接口
│   ├── borrows.ts        # 借阅接口
│   └── admin/
│       ├── books.ts      # 管理员图书接口
│       └── borrows.ts    # 管理员借阅接口
├── components/
│   ├── ui/               # shadcn/ui 组件（Button、Table、Dialog 等）
│   ├── layout/           # 布局组件
│   │   ├── AppLayout.tsx     # Web 版布局（顶栏）
│   │   ├── UserLayout.tsx    # 用户端布局（侧边栏 + 底部标签）
│   │   └── AdminLayout.tsx   # 管理端布局
│   ├── common/           # 通用组件
│   └── ThemeToggle.tsx   # 深色模式切换
├── features/             # 页面功能模块
│   ├── auth/             # 登录页
│   ├── books/            # 书目浏览
│   ├── borrows/          # 我的借阅
│   └── admin/            # 管理后台（图书管理 + 借阅管理）
├── router/               # React Router 路由配置
├── store/                # Zustand 全局状态
│   ├── authStore.ts      # JWT 认证状态
│   └── themeStore.ts     # 深色模式状态
├── hooks/                # 通用 Hooks
├── lib/                  # 工具函数（格式化、错误处理）
└── types/                # TypeScript 类型定义
```

## 部署

### 静态文件（tar.gz）

```bash
pnpm build
cd dist && tar -czf bookmgr-client-web-v0.1.tar.gz *
```

解压到任意 Web 服务器即可。Nginx 需配置 SPA 路由 fallback：

```nginx
location / {
    try_files $uri /index.html;
}
```

### Docker

镜像基于 `nginx:alpine`，多阶段构建（Node 编译 + Nginx 服务），暴露 80 端口。

```bash
# 构建
./scripts/docker-build.sh

# 拉取镜像
docker pull git.msksbr.com/msksbr/bookmgr-client:v0.1

# 运行
docker run -d -p 80:80 git.msksbr.com/msksbr/bookmgr-client:v0.1
```

### Docker Compose

```yaml
services:
  bookmgr-web:
    image: git.msksbr.com/msksbr/bookmgr-client:latest
    container_name: bookmgr-web
    ports:
      - "80:80"
```

## 开发指南

### 新增页面

1. 在 `src/features/` 下新建模块目录
2. 创建页面组件和 `hooks.ts`
3. 在 `src/router/index.tsx` 注册路由
4. 在对应布局组件中添加导航入口

### 新增 API 接口

1. 在 `src/api/` 对应模块中添加请求函数
2. 在 `src/types/api.ts` 中添加类型
3. 前端类型命名遵循后端 `vo` / `dto` 约定，字段自动 snake→camel 转换

### 图标生成

改图标后运行：

```bash
pnpm icon
```

自动同步 `app-icon.svg` 和 `32x32.png` 到 `public/`（Web favicon）。

Tauri 图标用 `tauri icon` 从 `app-icon.png` 重新生成。

## 声明

本项目基于 **MIT** 协议开源。本软件无任何销售渠道，不收取费用。请遵守开源协议合法使用。

## 作者

- 个人主页：[msksbr.com](https://msksbr.com/)
- 项目仓库：[git.msksbr.com/msksbr/bookMgr-client](https://git.msksbr.com/msksbr/bookMgr-client)