# xuliehao

**Repository Path**: luojietring/xuliehao

## Basic Information

- **Project Name**: xuliehao
- **Description**: 序列号查询系统是一个基于 Web 的全栈应用程序，旨在提供序列号的查询和管理功能。系统分为用户端和管理端两个部分：

- **用户端**：普通用户可以通过输入序列号查询相关信息，包括序列号的真实性、激活时间、状态和持有者信息。
- **管理端**：管理员可以登录后台管理系统，对序列号进行增删改查操作，包括添加新序列号、编辑序列号信息、修改状态和删除序列号。

系统采用现代化的技术栈，提供流畅的用户
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-11-07
- **Last Updated**: 2025-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 序列号查询系统

[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
[![Vue](https://img.shields.io/badge/Vue-3.3+-4FC08D.svg)](https://vuejs.org/)
[![MySQL](https://img.shields.io/badge/MySQL-8.0+-4479A1.svg)](https://www.mysql.com/)
[![License](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)

一个功能完整的序列号查询与管理系统，支持用户查询序列号信息和管理员后台管理。系统采用前后端分离架构，提供现代化的用户界面和完善的 API 接口。

## 📋 目录

- [项目简介](#项目简介)
- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [详细安装步骤](#详细安装步骤)
- [配置说明](#配置说明)
- [运行项目](#运行项目)
- [API 文档](#api-文档)
- [前端页面说明](#前端页面说明)
- [数据库设计](#数据库设计)
- [开发指南](#开发指南)
- [测试说明](#测试说明)
- [部署指南](#部署指南)
- [常见问题](#常见问题)
- [更新日志](#更新日志)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

## 🎯 项目简介

序列号查询系统是一个基于 Web 的全栈应用程序，旨在提供序列号的查询和管理功能。系统分为用户端和管理端两个部分：

- **用户端**：普通用户可以通过输入序列号查询相关信息，包括序列号的真实性、激活时间、状态和持有者信息。
- **管理端**：管理员可以登录后台管理系统，对序列号进行增删改查操作，包括添加新序列号、编辑序列号信息、修改状态和删除序列号。

系统采用现代化的技术栈，提供流畅的用户体验和稳定可靠的后端服务。

## ✨ 功能特性

### 用户端功能

- 🔍 **序列号查询**
  - 输入序列号进行查询
  - 显示序列号的真实性（存在/不存在）
  - 显示序列号的激活时间
  - 显示序列号的状态（生效/失效）
  - 显示序列号对应的持有者姓名
  - 支持回车键快捷查询

- 🎨 **用户界面**
  - 现代化的 UI 设计
  - 响应式布局，支持各种屏幕尺寸
  - 友好的错误提示和加载状态
  - 清晰的查询结果展示

### 管理员端功能

- 🔐 **身份认证**
  - 安全的登录系统
  - JWT Token 认证机制
  - Token 自动过期管理
  - 密码加密存储

- 📊 **序列号管理**
  - 查看所有序列号列表
  - 添加新序列号
  - 编辑序列号信息（序列号、持有者、状态）
  - 删除序列号
  - 修改序列号状态（生效/失效）

- 🔎 **搜索与筛选**
  - 按序列号搜索
  - 按持有者姓名搜索
  - 按状态筛选（生效/失效）
  - 支持组合搜索

- 📄 **分页功能**
  - 支持分页显示
  - 可自定义每页显示数量
  - 显示总记录数和当前页码

- 🎨 **管理界面**
  - 直观的数据表格展示
  - 模态框形式的添加/编辑表单
  - 操作确认提示
  - 实时的状态反馈

## 🛠 技术栈

### 后端技术

- **Node.js** (v18+) - JavaScript 运行时环境
- **Express** (v4.18.2) - Web 应用框架
- **MySQL2** (v3.6.5) - MySQL 数据库驱动
- **JWT** (v9.0.2) - JSON Web Token 身份认证
- **bcryptjs** (v2.4.3) - 密码加密库
- **CORS** (v2.8.5) - 跨域资源共享
- **dotenv** (v16.3.1) - 环境变量管理

### 前端技术

- **Vue 3** (v3.3.4) - 渐进式 JavaScript 框架
- **Vue Router** (v4.2.5) - 官方路由管理器
- **Axios** (v1.6.2) - HTTP 客户端
- **Vite** (v7.2.2) - 下一代前端构建工具

### 数据库

- **MySQL** (v8.0+) - 关系型数据库管理系统

### 开发工具

- **nodemon** (v3.0.2) - 开发时自动重启服务器
- **@vitejs/plugin-vue** (v6.0.1) - Vite 的 Vue 插件

## 📁 项目结构

```
Demo/
├── backend/                    # 后端项目目录
│   ├── config/                 # 配置文件
│   │   └── database.js        # 数据库配置
│   ├── middleware/             # 中间件
│   │   └── auth.js            # JWT 认证中间件
│   ├── routes/                 # 路由文件
│   │   ├── admin.js           # 管理员路由
│   │   └── serial.js          # 序列号路由
│   ├── scripts/                # 脚本文件
│   │   └── initAdmin.js       # 初始化管理员脚本
│   ├── node_modules/           # 依赖包
│   ├── package.json           # 后端项目配置
│   ├── package-lock.json      # 依赖锁定文件
│   ├── server.js              # 服务器入口文件
│   └── README.md              # 后端说明文档
│
├── frontend/                   # 前端项目目录
│   ├── src/                    # 源代码目录
│   │   ├── api/               # API 请求封装
│   │   │   ├── admin.js       # 管理员 API
│   │   │   ├── request.js     # Axios 配置
│   │   │   └── serial.js      # 序列号 API
│   │   ├── router/            # 路由配置
│   │   │   └── index.js       # 路由定义
│   │   ├── views/             # 页面组件
│   │   │   ├── AdminDashboard.vue  # 管理后台
│   │   │   ├── AdminLogin.vue      # 管理员登录
│   │   │   └── UserQuery.vue       # 用户查询
│   │   ├── App.vue            # 根组件
│   │   ├── main.js            # 入口文件
│   │   └── style.css          # 全局样式
│   ├── node_modules/           # 依赖包
│   ├── index.html             # HTML 模板
│   ├── package.json           # 前端项目配置
│   ├── package-lock.json      # 依赖锁定文件
│   ├── vite.config.js         # Vite 配置文件
│   └── README.md              # 前端说明文档
│
└── README.md                   # 项目主文档（本文件）
```

## 🔧 环境要求

在开始之前，请确保你的开发环境满足以下要求：

### 必需软件

1. **Node.js** (v18.0.0 或更高版本)
   - 下载地址：https://nodejs.org/
   - 验证安装：`node --version`

2. **MySQL** (v8.0 或更高版本)
   - 下载地址：https://www.mysql.com/downloads/
   - 验证安装：`mysql --version`

3. **npm** (v7.0.0 或更高版本，通常随 Node.js 一起安装)
   - 验证安装：`npm --version`

### 推荐软件

1. **Git** - 版本控制工具
2. **VS Code** - 代码编辑器（推荐）
3. **Postman** - API 测试工具（可选）

### 系统要求

- **操作系统**：Windows 10/11, macOS, Linux
- **内存**：至少 4GB RAM
- **磁盘空间**：至少 500MB 可用空间
- **网络**：用于下载依赖包

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd Demo
```

### 2. 安装依赖

```bash
# 安装后端依赖
cd backend
npm install

# 安装前端依赖
cd ../frontend
npm install
```

### 3. 配置数据库

创建 MySQL 数据库并导入表结构（见[数据库设计](#数据库设计)部分）。

### 4. 启动项目

```bash
# 启动后端服务器（在 backend 目录）
cd backend
npm start

# 启动前端开发服务器（在新终端，frontend 目录）
cd frontend
npm run dev
```

### 5. 访问应用

- 前端应用：http://localhost:5173
- 后端 API：http://localhost:3000
- 健康检查：http://localhost:3000/health

## 📖 详细安装步骤

### 步骤 1：安装 Node.js

1. 访问 [Node.js 官网](https://nodejs.org/)
2. 下载 LTS 版本（推荐 v18 或更高版本）
3. 运行安装程序，按照提示完成安装
4. 验证安装：
   ```bash
   node --version
   npm --version
   ```

### 步骤 2：安装 MySQL

1. 访问 [MySQL 官网](https://www.mysql.com/downloads/)
2. 下载 MySQL Community Server
3. 运行安装程序，按照提示完成安装
4. 记住设置的 root 密码（默认使用 `123456`）
5. 验证安装：
   ```bash
   mysql --version
   ```

### 步骤 3：创建数据库

1. 启动 MySQL 服务
2. 使用 MySQL 客户端连接数据库：
   ```bash
   mysql -u root -p
   ```
3. 输入 root 密码
4. 创建数据库：
   ```sql
   CREATE DATABASE xfsz CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   USE xfsz;
   ```
5. 创建数据表（见[数据库设计](#数据库设计)部分）

### 步骤 4：配置项目

1. **后端配置**

   编辑 `backend/config/database.js`，确保数据库配置正确：
   ```javascript
   const dbConfig = {
     host: 'localhost',
     port: 3306,
     user: 'root',
     password: '123456',  // 修改为你的 MySQL 密码
     database: 'xfsz',
     // ...
   };
   ```

2. **前端配置**

   前端配置在 `frontend/vite.config.js` 中，默认配置已设置代理：
   ```javascript
   server: {
     port: 5173,
     proxy: {
       '/api': {
         target: 'http://localhost:3000',
         changeOrigin: true
       }
     }
   }
   ```

### 步骤 5：初始化管理员账号

运行初始化脚本（可选，首次登录会自动创建）：

```bash
cd backend
node scripts/initAdmin.js
```

默认管理员账号：
- 用户名：`admin`
- 密码：`123456`

## ⚙️ 配置说明

### 环境变量配置

在后端项目根目录创建 `.env` 文件（可选）：

```env
# 服务器端口
PORT=3000

# JWT 密钥（生产环境请修改）
JWT_SECRET=your-secret-key-change-in-production

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=123456
DB_NAME=xfsz
```

### 数据库配置

数据库配置文件：`backend/config/database.js`

```javascript
const dbConfig = {
  host: 'localhost',        // 数据库主机
  port: 3306,               // 数据库端口
  user: 'root',             // 数据库用户名
  password: '123456',       // 数据库密码
  database: 'xfsz',         // 数据库名称
  waitForConnections: true, // 等待连接
  connectionLimit: 10,      // 连接池大小
  queueLimit: 0             // 队列限制
};
```

### 前端代理配置

前端代理配置文件：`frontend/vite.config.js`

```javascript
export default defineConfig({
  plugins: [vue()],
  server: {
    port: 5173,             // 前端开发服务器端口
    proxy: {
      '/api': {
        target: 'http://localhost:3000',  // 后端服务器地址
        changeOrigin: true
      }
    }
  }
})
```

## 🏃 运行项目

### 开发模式

#### 启动后端服务器

```bash
cd backend

# 使用 npm start（生产模式）
npm start

# 或使用 npm run dev（开发模式，自动重启）
npm run dev
```

后端服务器将在 `http://localhost:3000` 启动。

#### 启动前端开发服务器

```bash
cd frontend
npm run dev
```

前端开发服务器将在 `http://localhost:5173` 启动。

### 生产模式

#### 构建前端项目

```bash
cd frontend
npm run build
```

构建产物将输出到 `frontend/dist` 目录。

#### 预览生产构建

```bash
cd frontend
npm run preview
```

#### 启动后端生产服务器

```bash
cd backend
npm start
```

## 📚 API 文档

### 基础信息

- **Base URL**: `http://localhost:3000`
- **Content-Type**: `application/json`
- **认证方式**: JWT Token（Bearer Token）

### 用户端接口

#### 1. 查询序列号

**接口地址**: `GET /api/serial/:serialNumber`

**描述**: 根据序列号查询序列号信息

**请求参数**:
- `serialNumber` (路径参数): 序列号

**请求示例**:
```bash
GET http://localhost:3000/api/serial/SN123456
```

**响应示例**（序列号存在）:
```json
{
  "success": true,
  "data": {
    "isReal": true,
    "serialNumber": "SN123456",
    "holderName": "张三",
    "status": "生效",
    "activateTime": "2024-01-15T10:30:00.000Z"
  }
}
```

**响应示例**（序列号不存在）:
```json
{
  "success": true,
  "data": {
    "isReal": false,
    "message": "序列号不存在"
  }
}
```

**状态码**:
- `200 OK`: 查询成功

---

### 管理员端接口

#### 1. 管理员登录

**接口地址**: `POST /api/admin/login`

**描述**: 管理员登录，获取认证 Token

**请求头**:
```
Content-Type: application/json
```

**请求体**:
```json
{
  "username": "admin",
  "password": "123456"
}
```

**请求示例**:
```bash
curl -X POST http://localhost:3000/api/admin/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'
```

**响应示例**:
```json
{
  "success": true,
  "message": "登录成功",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "admin"
}
```

**状态码**:
- `200 OK`: 登录成功
- `401 Unauthorized`: 用户名或密码错误
- `400 Bad Request`: 请求参数错误

---

#### 2. 添加序列号

**接口地址**: `POST /api/admin/serial`

**描述**: 添加新的序列号

**请求头**:
```
Authorization: Bearer <token>
Content-Type: application/json
```

**请求体**:
```json
{
  "serialNumber": "SN123456",
  "holderName": "张三",
  "status": "active"
}
```

**参数说明**:
- `serialNumber` (必填): 序列号，必须唯一
- `holderName` (必填): 持有者姓名
- `status` (可选): 状态，`active`（生效）或 `inactive`（失效），默认为 `active`

**请求示例**:
```bash
curl -X POST http://localhost:3000/api/admin/serial \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"serialNumber":"SN123456","holderName":"张三","status":"active"}'
```

**响应示例**:
```json
{
  "success": true,
  "message": "序列号添加成功",
  "data": {
    "id": 1,
    "serialNumber": "SN123456",
    "holderName": "张三",
    "status": "active",
    "activateTime": "2024-01-15T10:30:00.000Z"
  }
}
```

**状态码**:
- `200 OK`: 添加成功
- `400 Bad Request`: 序列号已存在或参数错误
- `401 Unauthorized`: 未认证或 Token 无效

---

#### 3. 获取序列号列表

**接口地址**: `GET /api/admin/serials`

**描述**: 获取序列号列表，支持分页、搜索和筛选

**请求头**:
```
Authorization: Bearer <token>
```

**查询参数**:
- `page` (可选): 页码，默认为 1
- `pageSize` (可选): 每页数量，默认为 20
- `status` (可选): 筛选状态，`active` 或 `inactive`
- `search` (可选): 搜索关键字（序列号或持有者姓名）

**请求示例**:
```bash
# 获取第一页数据
GET http://localhost:3000/api/admin/serials?page=1&pageSize=20

# 搜索序列号
GET http://localhost:3000/api/admin/serials?search=SN123

# 筛选状态
GET http://localhost:3000/api/admin/serials?status=active

# 组合查询
GET http://localhost:3000/api/admin/serials?page=1&pageSize=10&status=active&search=张三
```

**响应示例**:
```json
{
  "success": true,
  "data": {
    "list": [
      {
        "id": 1,
        "serial_number": "SN123456",
        "holder_name": "张三",
        "status": "active",
        "activate_time": "2024-01-15T10:30:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}
```

**状态码**:
- `200 OK`: 查询成功
- `401 Unauthorized`: 未认证或 Token 无效

---

#### 4. 修改序列号信息

**接口地址**: `PUT /api/admin/serial/:id`

**描述**: 修改序列号信息（序列号、持有者、状态）

**请求头**:
```
Authorization: Bearer <token>
Content-Type: application/json
```

**路径参数**:
- `id`: 序列号 ID

**请求体**:
```json
{
  "serialNumber": "SN123456-UPDATED",
  "holderName": "李四",
  "status": "inactive"
}
```

**参数说明**:
- `serialNumber` (可选): 新序列号
- `holderName` (可选): 新持有者姓名
- `status` (可选): 新状态，`active` 或 `inactive`

**请求示例**:
```bash
curl -X PUT http://localhost:3000/api/admin/serial/1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"holderName":"李四","status":"inactive"}'
```

**响应示例**:
```json
{
  "success": true,
  "message": "序列号更新成功"
}
```

**状态码**:
- `200 OK`: 更新成功
- `400 Bad Request`: 序列号已被使用或参数错误
- `404 Not Found`: 序列号不存在
- `401 Unauthorized`: 未认证或 Token 无效

---

#### 5. 删除序列号

**接口地址**: `DELETE /api/admin/serial/:id`

**描述**: 删除序列号

**请求头**:
```
Authorization: Bearer <token>
```

**路径参数**:
- `id`: 序列号 ID

**请求示例**:
```bash
curl -X DELETE http://localhost:3000/api/admin/serial/1 \
  -H "Authorization: Bearer <token>"
```

**响应示例**:
```json
{
  "success": true,
  "message": "序列号删除成功"
}
```

**状态码**:
- `200 OK`: 删除成功
- `404 Not Found`: 序列号不存在
- `401 Unauthorized`: 未认证或 Token 无效

---

#### 6. 健康检查

**接口地址**: `GET /health`

**描述**: 检查服务器运行状态

**请求示例**:
```bash
GET http://localhost:3000/health
```

**响应示例**:
```json
{
  "status": "ok",
  "message": "服务器运行正常"
}
```

**状态码**:
- `200 OK`: 服务器正常运行

---

## 🖥 前端页面说明

### 1. 用户查询页面

**路径**: `/`

**功能**:
- 输入序列号进行查询
- 显示查询结果（真实性、激活时间、状态、持有者）
- 跳转到管理员登录页面

**使用步骤**:
1. 在输入框中输入序列号
2. 点击"查询"按钮或按回车键
3. 查看查询结果

**页面元素**:
- 序列号输入框
- 查询按钮
- 查询结果展示区域
- 管理员登录链接

---

### 2. 管理员登录页面

**路径**: `/admin/login`

**功能**:
- 管理员身份认证
- 登录后跳转到管理后台

**使用步骤**:
1. 输入用户名和密码
2. 点击"登录"按钮
3. 登录成功后自动跳转到管理后台

**默认账号**:
- 用户名: `admin`
- 密码: `123456`

**页面元素**:
- 用户名输入框
- 密码输入框
- 登录按钮
- 错误提示区域
- 返回用户查询链接

---

### 3. 管理后台页面

**路径**: `/admin/dashboard`

**功能**:
- 查看序列号列表
- 添加序列号
- 编辑序列号
- 删除序列号
- 搜索和筛选
- 分页浏览

**使用步骤**:

1. **查看列表**
   - 页面加载时自动显示序列号列表
   - 使用分页控件浏览不同页面

2. **搜索序列号**
   - 在搜索框输入关键字
   - 支持搜索序列号或持有者姓名
   - 点击"搜索"按钮或自动搜索

3. **筛选状态**
   - 在下拉菜单中选择状态（全部/生效/失效）
   - 自动刷新列表

4. **添加序列号**
   - 点击"添加序列号"按钮
   - 在弹窗中填写序列号、持有者姓名和状态
   - 点击"确定"保存

5. **编辑序列号**
   - 点击表格中的"编辑"按钮
   - 在弹窗中修改序列号、持有者姓名或状态
   - 点击"确定"保存

6. **删除序列号**
   - 点击表格中的"删除"按钮
   - 确认删除操作
   - 删除后自动刷新列表

7. **退出登录**
   - 点击"退出登录"按钮
   - 确认后返回登录页面

**页面元素**:
- 标题和操作按钮区域
- 搜索和筛选区域
- 序列号列表表格
- 分页控件
- 添加/编辑模态框
- 提示信息区域

---

## 🗄 数据库设计

### 数据库信息

- **数据库名**: `xfsz`
- **字符集**: `utf8mb4`
- **排序规则**: `utf8mb4_unicode_ci`

### 数据表结构

#### 1. 序列号表 (serial_numbers)

**表名**: `serial_numbers`

**字段说明**:

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 主键，自增 |
| serial_number | VARCHAR(100) | NOT NULL, UNIQUE | 序列号，唯一 |
| holder_name | VARCHAR(50) | NOT NULL | 持有者姓名 |
| status | ENUM('active', 'inactive') | DEFAULT 'active' | 状态（生效/失效） |
| activate_time | DATETIME | NULL | 激活时间 |

**索引**:
- `PRIMARY KEY (id)`
- `UNIQUE KEY (serial_number)`
- `INDEX idx_serial (serial_number)`
- `INDEX idx_status (status)`

**建表语句**:
```sql
CREATE TABLE serial_numbers (
    id INT AUTO_INCREMENT PRIMARY KEY,
    serial_number VARCHAR(100) NOT NULL UNIQUE,
    holder_name VARCHAR(50) NOT NULL,
    status ENUM('active', 'inactive') DEFAULT 'active',
    activate_time DATETIME,
    INDEX idx_serial (serial_number),
    INDEX idx_status (status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

#### 2. 管理员表 (admins)

**表名**: `admins`

**字段说明**:

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | INT | PRIMARY KEY, AUTO_INCREMENT | 主键，自增 |
| username | VARCHAR(50) | NOT NULL, UNIQUE | 用户名，唯一 |
| password | VARCHAR(255) | NOT NULL | 密码（加密存储） |

**索引**:
- `PRIMARY KEY (id)`
- `UNIQUE KEY (username)`

**建表语句**:
```sql
CREATE TABLE admins (
    id INT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    password VARCHAR(255) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

### 初始化数据

#### 创建默认管理员

运行初始化脚本：
```bash
cd backend
node scripts/initAdmin.js
```

或手动插入：
```sql
INSERT INTO admins (username, password) 
VALUES ('admin', '$2a$10$...');  -- 密码需要加密
```

默认管理员账号：
- 用户名: `admin`
- 密码: `123456`

## 💻 开发指南

### 代码规范

1. **JavaScript 代码风格**
   - 使用 ES6+ 语法
   - 使用 `const` 和 `let`，避免使用 `var`
   - 使用箭头函数
   - 使用 async/await 处理异步操作

2. **Vue 组件规范**
   - 使用 Composition API
   - 组件名使用 PascalCase
   - Props 定义类型和默认值
   - 使用 scoped 样式

3. **文件命名规范**
   - 组件文件使用 PascalCase: `UserQuery.vue`
   - 工具文件使用 camelCase: `request.js`
   - 常量文件使用 UPPER_SNAKE_CASE: `CONSTANTS.js`

### 目录结构说明

#### 后端目录结构

```
backend/
├── config/          # 配置文件
│   └── database.js # 数据库配置
├── middleware/      # 中间件
│   └── auth.js     # 认证中间件
├── routes/          # 路由文件
│   ├── admin.js    # 管理员路由
│   └── serial.js   # 序列号路由
├── scripts/         # 脚本文件
│   └── initAdmin.js # 初始化脚本
└── server.js        # 服务器入口
```

#### 前端目录结构

```
frontend/
├── src/
│   ├── api/         # API 请求封装
│   │   ├── admin.js # 管理员 API
│   │   ├── request.js # Axios 配置
│   │   └── serial.js # 序列号 API
│   ├── router/      # 路由配置
│   │   └── index.js # 路由定义
│   ├── views/       # 页面组件
│   │   ├── AdminDashboard.vue # 管理后台
│   │   ├── AdminLogin.vue # 管理员登录
│   │   └── UserQuery.vue # 用户查询
│   ├── App.vue      # 根组件
│   ├── main.js      # 入口文件
│   └── style.css    # 全局样式
├── index.html       # HTML 模板
└── vite.config.js   # Vite 配置
```

### 添加新功能

#### 后端添加新接口

1. 在 `routes/` 目录下创建或修改路由文件
2. 在 `server.js` 中注册路由
3. 测试接口功能

示例：
```javascript
// routes/example.js
const express = require('express');
const router = express.Router();

router.get('/example', (req, res) => {
  res.json({ message: 'Hello World' });
});

module.exports = router;
```

#### 前端添加新页面

1. 在 `src/views/` 目录下创建 Vue 组件
2. 在 `src/router/index.js` 中添加路由
3. 在 `src/api/` 中添加对应的 API 方法
4. 测试页面功能

示例：
```javascript
// src/router/index.js
{
  path: '/example',
  name: 'Example',
  component: () => import('../views/Example.vue')
}
```

### 调试技巧

1. **后端调试**
   - 使用 `console.log()` 输出调试信息
   - 使用 Node.js 调试器
   - 查看服务器日志

2. **前端调试**
   - 使用 Vue DevTools
   - 使用浏览器开发者工具
   - 查看网络请求

3. **数据库调试**
   - 使用 MySQL 客户端查看数据
   - 查看 SQL 查询日志
   - 使用数据库管理工具

## 🧪 测试说明

### 使用 Postman 测试 API

#### 1. 导入 Postman Collection

创建 Postman Collection，包含所有 API 接口。

#### 2. 设置环境变量

在 Postman 中创建环境，设置以下变量：
- `base_url`: `http://localhost:3000`
- `token`: （登录后自动设置）

#### 3. 测试流程

1. **健康检查**
   - 测试服务器是否正常运行

2. **管理员登录**
   - 获取 Token
   - 保存到环境变量

3. **添加序列号**
   - 使用 Token 认证
   - 添加测试数据

4. **查询序列号**
   - 测试用户端查询功能

5. **获取序列号列表**
   - 测试分页、搜索、筛选

6. **编辑序列号**
   - 测试更新功能

7. **删除序列号**
   - 测试删除功能

### 单元测试

（可选）添加单元测试：

```bash
# 安装测试框架
npm install --save-dev jest

# 运行测试
npm test
```

### 集成测试

（可选）添加集成测试：

```bash
# 安装测试框架
npm install --save-dev supertest

# 运行测试
npm run test:integration
```

## 🚀 部署指南

### 生产环境部署

#### 1. 后端部署

1. **构建项目**
   ```bash
   cd backend
   npm install --production
   ```

2. **配置环境变量**
   ```bash
   # 创建 .env 文件
   PORT=3000
   JWT_SECRET=your-production-secret-key
   DB_HOST=your-db-host
   DB_PORT=3306
   DB_USER=your-db-user
   DB_PASSWORD=your-db-password
   DB_NAME=xfsz
   ```

3. **使用 PM2 管理进程**
   ```bash
   # 安装 PM2
   npm install -g pm2

   # 启动应用
   pm2 start server.js --name xfsz-backend

   # 查看状态
   pm2 status

   # 查看日志
   pm2 logs xfsz-backend
   ```

#### 2. 前端部署

1. **构建生产版本**
   ```bash
   cd frontend
   npm run build
   ```

2. **部署到 Web 服务器**
   - 将 `dist` 目录部署到 Nginx 或 Apache
   - 配置反向代理到后端 API

3. **Nginx 配置示例**
   ```nginx
   server {
       listen 80;
       server_name your-domain.com;

       # 前端静态文件
       location / {
           root /path/to/frontend/dist;
           try_files $uri $uri/ /index.html;
       }

       # 后端 API 代理
       location /api {
           proxy_pass http://localhost:3000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }
   ```

### Docker 部署（可选）

#### 1. 创建 Dockerfile

**后端 Dockerfile**:
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]
```

**前端 Dockerfile**:
```dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

#### 2. 使用 Docker Compose

创建 `docker-compose.yml`:
```yaml
version: '3.8'
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: 123456
      MYSQL_DATABASE: xfsz
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql

  backend:
    build: ./backend
    ports:
      - "3000:3000"
    depends_on:
      - mysql
    environment:
      DB_HOST: mysql
      DB_PORT: 3306
      DB_USER: root
      DB_PASSWORD: 123456
      DB_NAME: xfsz

  frontend:
    build: ./frontend
    ports:
      - "80:80"
    depends_on:
      - backend

volumes:
  mysql_data:
```

运行：
```bash
docker-compose up -d
```

## ❓ 常见问题

### 1. 数据库连接失败

**问题**: 启动服务器时提示数据库连接失败

**解决方案**:
- 检查 MySQL 服务是否启动
- 检查数据库连接信息是否正确
- 检查数据库 `xfsz` 是否已创建
- 检查数据库用户权限

### 2. Token 无效或过期

**问题**: 调用管理员接口时返回 401 错误

**解决方案**:
- 检查 Token 是否正确添加到请求头
- 检查 Token 格式：`Bearer <token>`
- Token 可能已过期，重新登录获取新 Token
- Token 有效期为 24 小时

### 3. 序列号已存在

**问题**: 添加序列号时提示"序列号已存在"

**解决方案**:
- 序列号在数据库中必须唯一
- 使用不同的序列号
- 或先删除已存在的序列号

### 4. 端口被占用

**问题**: 启动服务器时提示端口被占用

**解决方案**:
- 修改 `server.js` 中的端口号
- 或关闭占用端口的其他程序
- 使用 `netstat -ano | findstr :3000` 查找占用端口的进程

### 5. 前端无法连接后端

**问题**: 前端请求后端 API 时出现跨域错误

**解决方案**:
- 检查后端 CORS 配置
- 检查前端代理配置
- 确保后端服务器正在运行
- 检查端口号是否正确

### 6. 页面刷新后路由丢失

**问题**: 刷新页面后出现 404 错误

**解决方案**:
- 配置 Web 服务器支持 SPA 路由
- Nginx 配置 `try_files $uri $uri/ /index.html;`
- Apache 配置 `.htaccess` 文件

### 7. 构建失败

**问题**: 运行 `npm run build` 时出现错误

**解决方案**:
- 检查 Node.js 版本是否满足要求
- 删除 `node_modules` 和 `package-lock.json`，重新安装
- 检查依赖版本是否兼容
- 查看错误日志，根据提示解决问题

## 📝 更新日志

### v1.0.0 (2024-01-15)

#### 新增功能
- ✅ 用户端序列号查询功能
- ✅ 管理员登录认证系统
- ✅ 序列号 CRUD 操作
- ✅ 搜索和筛选功能
- ✅ 分页功能
- ✅ JWT 认证机制
- ✅ 响应式 UI 设计

#### 修复问题
- 🔧 修复 MySQL 参数类型错误
- 🔧 修复分页查询问题
- 🔧 优化错误处理

#### 改进
- 🎨 更新主题色为橙色 (#ff7000)
- 🎨 优化用户界面
- 🚀 提升性能
- 📝 完善文档

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. **Fork 项目**
2. **创建特性分支**
   ```bash
   git checkout -b feature/AmazingFeature
   ```
3. **提交更改**
   ```bash
   git commit -m 'Add some AmazingFeature'
   ```
4. **推送到分支**
   ```bash
   git push origin feature/AmazingFeature
   ```
5. **开启 Pull Request**

### 贡献规范

- 遵循代码规范
- 添加必要的注释
- 更新相关文档
- 添加测试用例（如果适用）

## 📄 许可证

本项目采用 ISC 许可证。详情请参阅 [LICENSE](LICENSE) 文件。

## 👥 作者

- **开发者** - [Your Name](https://github.com/yourusername)

## 🙏 致谢

- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [Express](https://expressjs.com/) - Web 应用框架
- [MySQL](https://www.mysql.com/) - 数据库管理系统
- [Vite](https://vitejs.dev/) - 前端构建工具

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- **Issues**: [GitHub Issues](https://github.com/yourusername/repo/issues)
- **Email**: your.email@example.com

---

**祝使用愉快！** 🎉