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