277 lines
6.9 KiB
Markdown
277 lines
6.9 KiB
Markdown
# EasyNavi - 导航网站
|
||
|
||
简洁美观的个人网址导航网站，支持分类管理、网站收藏和搜索功能。
|
||
|
||
## 功能特性
|
||
|
||
### 网站管理
|
||
- ✅ 添加/编辑/删除网站
|
||
- ✅ 网站图标、名称、描述管理
|
||
- ✅ 点击计数统计
|
||
- ✅ 一键打开网站（在新窗口中打开）
|
||
|
||
### 分类管理
|
||
- ✅ 创建/编辑/删除分类
|
||
- ✅ 自定义分类图标（预设图标库）
|
||
- ✅ 自定义分类颜色（预设色板）
|
||
- ✅ 分类排序（数字越小越靠前）
|
||
- ✅ 删除分类时网站自动变为"未分类"状态
|
||
|
||
### 收藏功能
|
||
- ⭐ 标记网站为收藏
|
||
- 📌 收藏网站单独展示在页面顶部
|
||
- 🔄 支持快速切换收藏状态
|
||
|
||
### 搜索功能
|
||
- 🔍 按网站名称搜索
|
||
- 🔍 按网站描述搜索
|
||
- ⚡ 实时过滤，无需提交
|
||
|
||
### 用户体验
|
||
- 🎨 响应式设计，支持暗色主题
|
||
- ⚡ 乐观更新，界面反应迅速
|
||
- 🎯 分类颜色应用到卡片悬停效果
|
||
- 📱 适配桌面和移动设备
|
||
|
||
## 技术栈
|
||
|
||
### 前端
|
||
- **框架**: React 18
|
||
- **构建工具**: Vite 5
|
||
- **样式**: Tailwind CSS 3
|
||
- **图标**: Lucide React（也包含内联 SVG 图标）
|
||
- **HTTP 客户端**: Axios
|
||
|
||
### 后端
|
||
- **框架**: Flask
|
||
- **数据库**: MySQL 8.0
|
||
- **连接池**: PyMySQL
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
favorites-nav/
|
||
├── backend/
|
||
│ ├── main.py # Flask API 服务
|
||
│ ├── requirements.txt # Python 依赖
|
||
│ └── venv/ # Python 虚拟环境
|
||
├── frontend/
|
||
│ ├── src/
|
||
│ │ ├── api/ # API 调用封装
|
||
│ │ ├── components/ # React 组件
|
||
│ │ ├── pages/ # 页面组件
|
||
│ │ ├── App.jsx # 主应用组件
|
||
│ │ ├── index.css # 全局样式
|
||
│ │ └── main.jsx # 入口文件
|
||
│ ├── public/ # 静态资源
|
||
│ ├── index.html # HTML 模板
|
||
│ ├── package.json # Node 依赖
|
||
│ ├── vite.config.js # Vite 配置
|
||
│ └── tailwind.config.js # Tailwind 配置
|
||
├── start.sh # 启动脚本
|
||
└── README.md
|
||
```
|
||
|
||
## API 接口
|
||
|
||
### 分类接口
|
||
|
||
| 方法 | 路径 | 描述 |
|
||
|------|------|------|
|
||
| GET | `/api/categories` | 获取所有分类 |
|
||
| POST | `/api/categories` | 创建分类 |
|
||
| PUT | `/api/categories/:id` | 更新分类 |
|
||
| DELETE | `/api/categories/:id` | 删除分类 |
|
||
|
||
**创建/更新分类参数**:
|
||
```json
|
||
{
|
||
"name": "分类名称",
|
||
"icon": "图标名称",
|
||
"color": "#667eea",
|
||
"sort_order": 0
|
||
}
|
||
```
|
||
|
||
### 网站接口
|
||
|
||
| 方法 | 路径 | 描述 |
|
||
|------|------|------|
|
||
| GET | `/api/websites` | 获取所有网站 |
|
||
| GET | `/api/websites?category_id=:id` | 按分类获取网站 |
|
||
| POST | `/api/websites` | 创建网站 |
|
||
| PUT | `/api/websites/:id` | 更新网站 |
|
||
| DELETE | `/api/websites/:id` | 删除网站 |
|
||
| POST | `/api/websites/:id/click` | 记录点击 |
|
||
|
||
**创建/更新网站参数**:
|
||
```json
|
||
{
|
||
"name": "网站名称",
|
||
"url": "https://example.com",
|
||
"icon": "图标名称或URL",
|
||
"description": "网站描述",
|
||
"category_id": 1,
|
||
"is_favorite": false
|
||
}
|
||
```
|
||
|
||
### 系统接口
|
||
|
||
| 方法 | 路径 | 描述 |
|
||
|------|------|------|
|
||
| GET | `/api/health` | 健康检查 |
|
||
|
||
## 数据库表结构
|
||
|
||
### categories 表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | INT | 主键，自增 |
|
||
| name | VARCHAR(100) | 分类名称 |
|
||
| icon | VARCHAR(50) | 图标名称 |
|
||
| color | VARCHAR(20) | 颜色代码 |
|
||
| sort_order | INT | 排序序号 |
|
||
| created_at | DATETIME | 创建时间 |
|
||
|
||
### websites 表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | INT | 主键，自增 |
|
||
| name | VARCHAR(100) | 网站名称 |
|
||
| url | VARCHAR(500) | 网站 URL |
|
||
| icon | VARCHAR(500) | 图标（内联名称或 URL） |
|
||
| description | VARCHAR(500) | 网站描述 |
|
||
| category_id | INT | 关联分类 ID |
|
||
| is_favorite | TINYINT(1) | 是否收藏 |
|
||
| click_count | INT | 点击次数 |
|
||
| created_at | DATETIME | 创建时间 |
|
||
| updated_at | DATETIME | 更新时间 |
|
||
|
||
## 环境变量
|
||
|
||
后端通过环境变量配置数据库连接：
|
||
|
||
| 变量名 | 默认值 | 说明 |
|
||
|--------|--------|------|
|
||
| DB_HOST | 192.168.8.160 | 数据库地址 |
|
||
| DB_PORT | 3306 | 数据库端口 |
|
||
| DB_USER | dbuser | 数据库用户名 |
|
||
| DB_PASS | Tata@1234 | 数据库密码 |
|
||
| DB_NAME | favorites_nav | 数据库名称 |
|
||
|
||
## 快速启动
|
||
|
||
### 方式一：使用启动脚本
|
||
|
||
```bash
|
||
cd favorites-nav
|
||
./start.sh
|
||
```
|
||
|
||
### 方式二：手动启动
|
||
|
||
**1. 启动后端**
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt # 安装依赖
|
||
python main.py # 启动后端 (端口 5003)
|
||
```
|
||
|
||
**2. 启动前端**
|
||
```bash
|
||
cd frontend
|
||
npm install # 安装依赖
|
||
npm run dev # 启动开发服务器 (端口 5173)
|
||
```
|
||
|
||
### 方式三：生产环境构建
|
||
|
||
```bash
|
||
cd frontend
|
||
npm run build # 构建前端
|
||
|
||
# 后端使用 Gunicorn
|
||
pip install gunicorn
|
||
gunicorn -w 4 -b 0.0.0.0:5003 main:app
|
||
```
|
||
|
||
## 部署说明
|
||
|
||
### 数据库初始化
|
||
|
||
需要手动创建数据库和表：
|
||
|
||
```sql
|
||
CREATE DATABASE favorites_nav CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||
|
||
USE favorites_nav;
|
||
|
||
CREATE TABLE categories (
|
||
id INT AUTO_INCREMENT PRIMARY KEY,
|
||
name VARCHAR(100) NOT NULL,
|
||
icon VARCHAR(50) DEFAULT 'folder',
|
||
color VARCHAR(20) DEFAULT '#667eea',
|
||
sort_order INT DEFAULT 0,
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
|
||
CREATE TABLE websites (
|
||
id INT AUTO_INCREMENT PRIMARY KEY,
|
||
name VARCHAR(100) NOT NULL,
|
||
url VARCHAR(500) NOT NULL,
|
||
icon VARCHAR(500) DEFAULT '',
|
||
description VARCHAR(500) DEFAULT '',
|
||
category_id INT NULL,
|
||
is_favorite TINYINT(1) DEFAULT 0,
|
||
click_count INT DEFAULT 0,
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
FOREIGN KEY (category_id) REFERENCES categories(id) ON DELETE SET NULL
|
||
);
|
||
```
|
||
|
||
### 静态文件部署
|
||
|
||
前端构建后生成 `dist/` 目录，可以配置 Nginx 指向静态文件目录，或将 `dist/` 内容复制到后端的静态文件夹中。
|
||
|
||
## 预设图标
|
||
|
||
系统内置以下图标可用作分类或网站的图标：
|
||
|
||
```
|
||
book, briefcase, code, dollar-sign, edit, folder, globe, heart,
|
||
home, layers, link, map-pin, message-circle, monitor, music,
|
||
package, settings, shopping-cart, star, tool, truck, video, zap
|
||
```
|
||
|
||
## 预设颜色
|
||
|
||
```
|
||
#667eea, #764ba2, #f56565, #ed8936, #ecc94b,
|
||
#48bb78, #38b2ac, #4299e1, #9f7aea, #ed64a6
|
||
```
|
||
|
||
## 开发笔记
|
||
|
||
### 乐观更新模式
|
||
|
||
为了提升用户体验，分类和网站的增删改操作采用乐观更新策略：
|
||
1. 先立即更新本地 UI 状态
|
||
2. 后台发送 API 请求
|
||
3. 如果请求失败，则回滚 UI 并重新加载数据
|
||
|
||
### 点击统计
|
||
|
||
网站点击后会异步调用点击接口，不会阻塞页面跳转。
|
||
|
||
### CORS 配置
|
||
|
||
后端 API 配置了允许所有来源的 CORS，方便前后端分离开发和调试。生产环境建议限制为具体域名。
|
||
|
||
## License
|
||
|
||
MIT License
|