docs: 添加项目文档 README.md（需求、设计、配置说明）
This commit is contained in:
小龙
parent
edfdbc30cc
commit
77bdfbc5da
276
README.md
Normal file
276
README.md
Normal file
@ -0,0 +1,276 @@
|
|||||||
|
# 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
|
||||||
Loading…
Reference in New Issue
Block a user