# 用户管理系统

## 项目概述

本项目是一个基于现代 Web 技术栈开发的用户管理系统，支持三种用户角色：**系统管理员**、**管理员** 和 **普通用户**。系统通过角色权限控制，实现对用户数据的安全管理和操作。

### 核心功能
1. **用户管理**：
   - 系统管理员在项目启动时自动生成，且唯一。
   - 所有账户必须由管理员手动创建。
   - 用户表包含密码、ID、角色、描述等信息。
   - 管理员可以对用户表进行增删改查操作。
   - 普通用户仅能读取用户列表。

2. **权限控制**：
   - 基于角色的权限管理（RBAC），确保不同角色只能访问其权限范围内的功能。
   - 系统管理员和管理员可操作修改和删除按钮，普通用户仅能查看用户列表。

3. **安全认证**：
   - 使用 JWT（JSON Web Token）实现身份验证和权限控制。
   - Access Token 和 Refresh Token 的自动刷新机制，保障用户会话的安全性和连续性。
   - 密码使用 bcrypt 加密存储，确保数据安全。

4. **前后端分离架构**：
   - 前端采用 Vue.js 框架，结合 Vue Router、Pinia 和 Element Plus，提供响应式和交互性强的用户界面。
   - 后端基于 FastAPI 框架，提供 RESTful API 接口，与 MySQL 数据库交互，完成用户认证、权限管理和数据操作。

5. **容器化部署**：
   - 支持 Docker 容器化部署，简化开发和生产环境配置。
   - 包括前端、后端、数据库和 Nginx 反向代理服务，便于快速搭建和扩展。

### 技术亮点
- **现代化技术栈**：涵盖前端、后端、数据库和安全认证等多个领域。
- **完整的开发流程**：从数据库设计到 API 开发，从前端页面到生产部署，覆盖全生命周期。
- **高可扩展性**：模块化设计，易于扩展新功能或集成第三方服务。


## 技术栈

### 后端技术栈
- FastAPI
- SQLAlchemy
- MySQL
- bcrypt
- PyJWT
- logging

### 前端技术栈
- Typescript
- Vue.js
- Vue Router
- Pinia
- Element Plus
- Axios
- Vite
- npm
- pinia-plugin-persistedstate
- jwt-decode

## 数据库设计

### 用户表结构

| 字段名 | 数据类型 | 约束条件 | 默认值 | 说明 |
| -------- | ---------- | ---------- | -------- | ---------------------------------------------------- |
| `id` | `INT` | `PRIMARY KEY`, `AUTO_INCREMENT` | - | 用户ID，主键，自增 |
| `username` | `VARCHAR(50)` | `NOT NULL`, `UNIQUE` | - | 用户名，唯一 |
| `password` | `VARCHAR(255)` | `NOT NULL` | - | 用户密码，使用哈希加密存储 |
| `role` | `ENUM` | `NOT NULL` | `UserRole.USER` | 用户角色，枚举类型，可选值为 `UserRole.SYSTEM_ADMIN`, `UserRole.ADMIN`, `UserRole.USER` |
| `description` | `TEXT` | - | - | 用户描述，可选 |
| `created_at` | `DATETIME` | - | `当前UTC时间` | 用户创建时间，默认值为当前UTC时间 |
| `updated_at` | `DATETIME` | - | `当前UTC时间，更新时自动更新` | 用户信息更新时间，默认值为当前UTC时间，更新时自动更新 |

### 数据库初始化
- 系统初始化时，后端控制层会检查表是否存在，若不存在则自动创建表。
- 检查表中是否存在系统管理员，若不存在则创建一个名为`admin`、密码为`password`、描述为`default system admin`的系统管理员。

## 鉴权设计

### 角色权限
- **系统管理员、管理员**：可以访问所有 API，包括用户增删改查。
- **普通用户**：只能访问用户列表（只读）。

### JWT 鉴权
JWT（JSON Web Token）用于用户身份验证和权限控制。JWT 包含以下信息：
- **Payload**：用户 ID、用户名、角色、Token 过期时间、token_type等。
- **签名**：使用后端密钥对 Payload 进行签名，确保 Token 的完整性和安全性。

### JWT Token 数据结构
```python
class TokenPayload:
    id: int  # 用户ID
    username: str  # 用户名
    role: str  # 用户角色
    exp: int  # Token过期时间
    token_type: str  # Token类型（access或refresh）
```

### JWT 自动过期机制
- **Access Token**：用于常规 API 请求，有效期较短（如 30 分钟）。
- **Refresh Token**：用于刷新 Access Token，有效期较长（如 7 天）。

#### Token 刷新流程
1. 客户端使用 Refresh Token 请求 `/api/auth/refresh` 接口。
2. 服务端验证 Refresh Token 的有效性。
3. 服务端生成新的 Access Token 和 Refresh Token，并返回给客户端。
4. 客户端更新本地存储的 Token。

### Token 验证
- **verify_access_token**：验证access token有效性并返回payload，如果token无效或类型不匹配则返回None
- **verify_refresh_token**：验证refresh token有效性并返回payload，如果token无效或类型不匹配则返回None

## 前端页面设计

### 1. 登录页面 (`loginPage`)
#### UI 组件安排
- 用户名输入框：使用 Element Plus 的 `el-input` 组件，用于输入用户名。
- 密码输入框：使用 Element Plus 的 `el-input` 组件，类型为 `password`，用于输入密码。
- 登录按钮：使用 Element Plus 的 `el-button` 组件，点击后触发登录逻辑。

#### 功能描述
- 用户输入用户名和密码后，点击登录按钮，前端通过 Axios 发送登录请求到后端 `/api/auth/login` 接口。
- 登录成功后，前端将获取到的 `access_token` 和 `refresh_token` 存储在 Pinia 状态管理中，并跳转到用户管理页面。
- 登录失败时，前端显示错误提示。

### 2. 用户管理页面 (`managePage`)
#### UI 组件安排
- 导航栏：使用 Element Plus 的 `el-menu` 组件，显示欢迎信息和当前用户信息
- 登出按钮：使用 Element Plus 的 `el-button` 组件，位于页面右上角，点击后触发登出逻辑。
- 用户列表：使用 Element Plus 的 `el-table` 组件，展示用户信息，包括 `ID`、`用户名`、`角色`、`描述` 等字段。
- 创建用户按钮：使用 Element Plus 的 `el-button` 组件，仅管理员可见，点击后弹出创建用户对话框。
- 修改按钮：使用 Element Plus 的 `el-button` 组件，位于每一行的操作列中，点击后弹出修改对话框。
- 删除按钮：使用 Element Plus 的 `el-button` 组件，位于每一行的操作列中，点击后触发删除逻辑。
- 修改对话框：使用 Element Plus 的 `el-dialog` 组件，用于修改用户信息。

#### 功能描述
- 用户列表展示：前端通过 Axios 发送请求到 `/api/users` 接口，获取用户列表数据，并在表格中展示。
- 创建用户：管理员点击创建用户按钮后，弹出创建用户对话框，填写信息后提交。
- 修改按钮的显示与隐藏：根据当前登录用户的角色，动态控制修改按钮的显示与隐藏。只有 `系统管理员` 和 `管理员` 可以看到并操作修改按钮。
- 删除按钮的显示与隐藏：根据当前登录用户的角色，动态控制删除按钮的显示与隐藏。只有 `系统管理员` 和 `管理员` 可以看到并操作删除按钮。
- 修改用户信息：点击修改按钮后，弹出修改对话框，用户可以在对话框中修改用户名、角色和描述信息。修改完成后，前端通过 Axios 发送请求到 `/api/users/{user_id}` 接口，更新用户信息。
- 删除用户：点击删除按钮后，前端通过 Axios 发送请求到 `/api/users/{user_id}` 接口，删除对应用户。

## 权限控制

### 1. 修改和删除按钮的权限控制
- 系统管理员、管理员：可以看到并操作所有用户的修改和删除按钮。
- 普通用户：无法看到修改和删除按钮，只能查看用户列表。

#### 实现逻辑
- 前端在用户登录成功后，从后端获取用户角色信息，并存储在 Pinia 状态管理中。
- 在用户管理页面中，前端根据当前用户的角色动态渲染表格中的操作列。如果当前用户是 `普通用户`，则不渲染修改和删除按钮；如果是 `系统管理员` 或 `管理员`，则渲染这些按钮。

### 2. 路由权限控制
- 登录页面：所有用户都可以访问。
- 用户管理页面：只有登录成功的用户才能访问。如果用户未登录，尝试访问用户管理页面时，前端应自动跳转到登录页面。

#### 实现逻辑
- 使用 Vue Router 的导航守卫（`beforeEach`）进行路由权限控制。在每次路由跳转前，检查 Pinia 中是否存储了有效的 `access_token`。如果没有，则跳转到登录页面。

## Token 管理

### 1. Access Token 和 Refresh Token 的存储
- 登录成功后，前端将 `access_token` 和 `refresh_token` 存储在 Pinia 状态管理中，并设置 `access_token` 的过期时间。
- 每次发送 API 请求时，前端从 Pinia 中获取 `access_token` 并添加到请求头中。
- 使用 pinia-plugin-persistedstate 插件将 token 存储在 localStorage 中，实现状态持久化

### 2. Token 自动刷新
- 前端在每次发送 API 请求前，检查 `access_token` 是否即将过期（例如，剩余有效期小于 5 分钟）。如果即将过期，前端使用 `refresh_token` 调用 `/api/auth/refresh` 接口，获取新的 `access_token` 和 `refresh_token`，并更新 Pinia 中的存储。
- 使用 Axios 的拦截器统一处理 token 刷新逻辑，避免在每个请求中重复编写代码。

## 状态管理

### 用户登录状态
- 使用 Pinia 存储用户登录状态，包括 `access_token`、`refresh_token`、用户角色、用户名、用户ID等信息。
- 在用户登出时，清除 Pinia 中的登录状态。
- 使用 pinia-plugin-persistedstate 插件进行状态持久化，在应用启动时自动从 localStorage 恢复状态

## 开发环境配置

### 后端
1. 安装依赖：
   ```bash
   pip install -r requirements.txt
   ```

2. 启动开发服务器：
   ```bash
   uvicorn main:app --reload
   ```

### 前端
1. 安装依赖：
   ```bash
   npm install
   ```

2. 启动开发服务器：
   ```bash
   npm run dev
   ```

3. 构建生产环境：
   ```bash
   npm run build
   ```

## Docker 部署

### 1. 环境要求
- Docker 20.10.0 或更高版本
- Docker Compose 2.0.0 或更高版本

### 2. 部署步骤
1. 确保已安装 Docker 和 Docker Compose
2. 在项目根目录下运行以下命令：
   ```bash
   docker-compose up --build
   ```
3. 应用启动后，可以通过以下地址访问：
   - 前端：http://localhost
   - 后端API：http://localhost/api
4. 停止并移除容器：
   ```bash
   docker-compose down
   ```

### 3. 服务说明
- **frontend**: 前端服务，基于Vue.js构建
- **backend**: 后端服务，基于FastAPI构建
- **mysql**: MySQL数据库服务
- **nginx**: Nginx反向代理服务

### 4. 环境变量配置
所有环境变量配置在 `docker-compose.yml` 文件中，包括：
- 数据库连接信息
- JWT配置
- 日志配置
- 系统管理员初始配置

## 后续开发
- **CI/CD 流程**：自动化构建和部署流程