Navi/README.md

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	删除分类

创建/更新分类参数:

{
  "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	记录点击

创建/更新网站参数:

{
  "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	数据库名称

快速启动

方式一：使用启动脚本

cd favorites-nav
./start.sh

方式二：手动启动

1. 启动后端

cd backend
pip install -r requirements.txt  # 安装依赖
python main.py                    # 启动后端 (端口 5003)

2. 启动前端

cd frontend
npm install                       # 安装依赖
npm run dev                       # 启动开发服务器 (端口 5173)

方式三：生产环境构建

cd frontend
npm run build                     # 构建前端

# 后端使用 Gunicorn
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5003 main:app

部署说明

数据库初始化

需要手动创建数据库和表：

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