From 77bdfbc5da32022cb3f1e50afb6c92e1d100304e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E9=BE=99?= Date: Tue, 7 Apr 2026 10:19:31 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E6=96=87=E6=A1=A3=20README.md=EF=BC=88=E9=9C=80=E6=B1=82?= =?UTF-8?q?=E3=80=81=E8=AE=BE=E8=AE=A1=E3=80=81=E9=85=8D=E7=BD=AE=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 276 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8a160ef --- /dev/null +++ b/README.md @@ -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