# react_yq

**Repository Path**: hlw422/react_yq

## Basic Information

- **Project Name**: react_yq
- **Description**: 一款基于 React 18 + Vite + Tailwind CSS + Express + TiDB Cloud 开发的类语雀文档知识库管理系统，支持 Markdown 编辑、文件夹管理、实时搜索、深色模式等完整功能，采用前后端分离架构。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# React Yuque Docs

> 一款基于 **React 18 + Vite + Tailwind CSS + Express + TiDB Cloud** 开发的类语雀文档知识库管理系统，支持 Markdown 编辑、文件夹管理、实时搜索、深色模式等完整功能，采用前后端分离架构。

![Vite](https://img.shields.io/badge/Vite-5.4-purple) ![React](https://img.shields.io/badge/React-18-blue) ![Tailwind](https://img.shields.io/badge/Tailwind_CSS-3.4-cyan) ![Express](https://img.shields.io/badge/Express-4.19-black) ![TiDB](https://img.shields.io/badge/TiDB_Cloud-MySQL-green)

## ✨ 功能特性

### 📝 文档管理
- **Markdown 编辑器**：支持编辑 / 预览 / 分屏三种模式自由切换
- **实时预览**：集成 `react-markdown` + `remark-gfm`，支持 GFM 语法（表格、任务列表、删除线等）
- **代码高亮**：`rehype-highlight` 提供语法高亮
- **行内标题编辑**：双击标题即可重命名
- **自动保存**：内容变更 800ms 防抖后自动保存到后端数据库

### 📁 文件夹体系
- **嵌套式文档列表**：点击展开文件夹，下属文档直接显示在文件夹下方（语雀风格）
- **文件夹 CRUD**：新建 / 重命名（双击） / 删除（级联删除文件夹下所有文档），带操作菜单和确认弹窗
- **选中关联创建**：选中文件夹后新建的文档自动归入该文件夹
- **未分类文档区**：底部独立展示所有未分配文件夹的文档

### 🔍 搜索功能
- **全局模糊搜索**：实时防抖过滤，支持中英文关键词匹配
- **全区域检索**：同时搜索文件夹内文档和未分类文档
- **智能展开**：搜索到匹配项时自动展开对应文件夹

### 🎨 界面体验
- **深色 / 浅色主题切换**：CSS 变量驱动的平滑过渡动画
- **语雀 UI 风格**：主色调 `#1677ff`，完整复刻语雀视觉语言
- **响应式交互**：悬浮高亮、选中态蓝色左边框、删除按钮渐显等细节打磨
- **时间戳显示**：每篇文档显示最近修改日期

### 📤 导出功能
- **导出 Markdown (.md)**：一键下载为标准 MD 文件，含文件名清理

### 💾 数据持久化（前后端分离架构）

| 层级 | 技术 | 说明 |
|------|------|------|
| 前端框架 | React 18 + Context + useReducer | 集中式状态管理 |
| 后端服务 | Express.js (RESTful API) | 端口 4000，提供文档/文件夹 CRUD 接口 |
| 数据库 | **TiDB Cloud MySQL** | 云端持久化存储，支持 SSL 连接 |
| 开发代理 | Vite Proxy (`/api`) | 前端开发时 `/api` 自动转发至后端 |

**API 端点概览：**

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/docs` | 获取全部文档列表 |
| GET | `/api/docs/:id` | 获取单个文档详情 |
| GET | `/api/docs/search?q=` | 搜索文档（标题/内容） |
| POST | `/api/docs` | 创建新文档 |
| PUT | `/api/docs/:id` | 更新文档 |
| DELETE | `/api/docs/:id` | 删除文档 |
| GET | `/api/folders` | 获取全部文件夹列表 |
| POST | `/api/folders` | 创建新文件夹 |
| PUT | `/api/folders/:id` | 更新文件夹名称 |
| DELETE | `/api/folders/:id` | 删除文件夹（含级联删除） |
| GET | `/api/health` | 健康检查 |

## 🛠️ 技术栈

| 类别 | 技术 |
|------|------|
| 前端框架 | [React 18](https://react.dev/) (纯函数组件 + Hooks) |
| 构建工具 | [Vite 5.4](https://vitejs.dev/) |
| 样式系统 | [Tailwind CSS 3.4](https://tailwindcss.com/) + 语雀色彩变量 |
| 路由 | [React Router DOM v6](https://reactrouter.com/) |
| Markdown 渲染 | [react-markdown](https://github.com/remarkjs/react-markdown) + remark-gfm + rehype-highlight |
| 图标库 | [lucide-react](https://lucide.dev/) |
| 代码高亮 | [highlight.js](https://highlightjs.org/) |
| 后端服务 | [Express.js](https://expressjs.com/) |
| 数据库驱动 | [mysql2](https://github.com/sidorares/node-mysql2) (连接池) |
| 云数据库 | [TiDB Cloud](https://tidbcloud.com/) (Serverless MySQL) |

## 📦 项目结构

```
├── src/                              # 前端源码
│   ├── main.jsx                      # 应用入口
│   ├── App.jsx                       # 根组件 (AppProvider + Router)
│   ├── index.css                     # 全局样式 (Tailwind + 暗色主题 + Markdown)
│   │
│   ├── components/
│   │   ├── Layout/Layout.jsx         # 主布局 (顶栏 + 双栏内容)
│   │   ├── Sidebar/                  # 左侧边栏组件组
│   │   │   ├── Sidebar.jsx           # 边栏容器 (含未分类文档区)
│   │   │   ├── FolderTree.jsx        # 文件夹树 (嵌套文档列表)
│   │   │   ├── NewDocButton.jsx      # 新建文档按钮
│   │   │   └── SearchBar.jsx         # 实时搜索框
│   │   ├── Editor/                   # 编辑区组件组
│   │   │   ├── EditorArea.jsx        # 编辑区容器
│   │   │   ├── DocTitle.jsx          # 行内标题编辑 (含时间戳)
│   │   │   ├── Toolbar.jsx           # 工具栏 (模式切换 + 导出)
│   │   │   ├── MarkdownEditor.jsx    # 文本编辑器 (textarea)
│   │   │   └── PreviewPane.jsx       # Markdown 预览渲染
│   │   └── Common/                   # 公共组件
│   │       ├── EmptyState.jsx        # 空状态引导页
│   │       ├── ThemeToggle.jsx       # 深浅主题切换按钮
│   │       └── ConfirmDialog.jsx     # 删除确认弹窗
│   │
│   ├── contexts/
│   │   └── AppContext.jsx             # 全局状态管理 (异步数据流 + 防抖自动保存)
│   │
│   ├── services/
│   │   ├── docService.js             # 文档 CRUD 服务层 (async fetch → /api/docs)
│   │   └── folderService.js          # 文件夹 CRUD 服务层 (async fetch → /api/folders)
│   │
│   ├── hooks/
│   │   └── useDebounce.js            # 防抖 Hook
│   │
│   └── utils/
│       ├── idGenerator.js            # 唯一 ID 生成器
│       ├── dateUtils.js              # 时间格式化工具
│       └── exportUtils.js            # 导出 MD 工具
│
├── server/                           # 后端源码
│   ├── server.js                     # Express 入口 (路由挂载 / CORS / 错误处理)
│   ├── config/
│   │   └── db.js                     # mysql2 连接池配置 (SSL/TLS)
│   ├── routes/
│   │   ├── documents.js              # 文档 RESTful API 路由
│   │   └── folders.js                # 文件夹 RESTful API 路由 (含级联删除)
│   ├── middleware/
│   │   └── errorHandler.js           # 统一错误处理中间件
│   ├── sql/
│   │   └── init.sql                  # 建表 SQL 参考
│   ├── init-db.js                    # 数据库初始化脚本
│   ├── package.json                  # 后端依赖 (express, mysql2, dotenv, cors)
│   ├── .env                          # 🔒 数据库连接凭据 (已 gitignore)
│   └── .env.example                 # 环境变量模板
│
├── vite.config.js                    # Vite 配置 (含 /api 代理转发)
├── tailwind.config.js               # Tailwind 配置 (语雀色彩变量)
├── index.html                        # HTML 入口
├── package.json                      # 前端依赖
└── README.md                         # 项目文档
```

## 🚀 快速开始

### 环境要求

- Node.js >= 16
- npm >= 8
- TiDB Cloud 账号（或本地 MySQL 实例）

### 安装运行

```bash
# 克隆项目
git clone https://github.com/hlw422/react_yq.git
cd react_yq

# ====== 前端 ======
npm install

# ====== 后端 ======
cd server
npm install
cp .env.example .env      # 复制环境变量模板

# 编辑 .env，填入你的数据库连接信息：
#   TIDB_HOST - 数据库主机地址
#   TIDB_PORT - 端口 (默认 4000)
#   TIDB_USER - 用户名
#   TIDB_PASSWORD - 密码
#   TIDB_DATABASE - 数据库名称
#   PORT - 后端服务端口 (默认 4000)

# 初始化数据库表
node init-db.js

# 启动后端服务 (默认 http://localhost:4000)
npm run dev
```

```bash
# 回到项目根目录启动前端
cd ..

# 启动前端开发服务器 (默认 http://localhost:3000)
# 前端会通过 Vite 代理将 /api 请求转发至 localhost:4000
npm run dev
```

### 生产部署

```bash
# 前端构建
npm run build

# 后端生产环境启动
cd server
npm start
```

## 🎯 使用指南

### 基本操作

1. **新建文档**：点击顶部「新建文档」按钮 → 自动在当前选中的文件夹下创建
2. **新建文件夹**：点击「文件夹」旁的 `+` 按钮 → 输入名称回车确认
3. **编辑文档**：左侧点击文档打开 → 右侧编辑区输入 Markdown 内容（800ms 防抖自动保存）
4. **切换模式**：使用工具栏「编辑」「分屏」「预览」按钮切换视图
5. **搜索文档**：在搜索框输入关键词 → 实时过滤所有区域的文档
6. **重命名**：双击文件夹名称或文档标题 → 输入新名称回车确认
7. **删除**：悬浮文档或点击文件夹 `···` 菜单 → 点击垃圾桶图标确认删除（文件夹删除会级联删除其下所有文档）
8. **导出**：点击工具栏「导出MD」按钮 → 自动下载 .md 文件

### 快捷键说明

| 操作 | 快捷键 |
|------|--------|
| 新建文件夹确认 | `Enter` |
| 取消输入/关闭弹窗 | `Escape` |
| 重命名确认 | `Enter` |

## ⚙️ 配置说明

### 数据库配置

项目默认使用 **TiDB Cloud Serverless**（免费层），也可替换为本地 MySQL：

**server/.env 配置项：**

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `TIDB_HOST` | 数据库主机地址 | `localhost` |
| `TIDB_PORT` | 数据库端口 | `4000` |
| `TIDB_USER` | 数据库用户名 | `root` |
| `TIDB_PASSWORD` | 数据库密码 | （空） |
| `TIDB_DATABASE` | 数据库名称 | `test` |
| `PORT` | 后端服务监听端口 | `4000` |

> **注意**: TiDB Cloud Serverless 强制要求 SSL/TLS 连接，项目已在连接池中配置了 `ssl: { minVersion: 'TLSv1.2' }`。如果使用本地 MySQL 可移除此选项。

### Vite 代理配置

前端开发环境通过 Vite proxy 将 `/api` 请求转发至后端：

```js
// vite.config.js
proxy: {
  '/api': {
    target: 'http://localhost:4000',
    changeOrigin: true,
  },
},
```

## 🌈 主题定制

项目使用 Tailwind CSS 变量实现主题系统。自定义颜色可在 `tailwind.config.js` 中修改：

```js
// tailwind.config.js - 语雀色彩配置示例
colors: {
  primary: '#1677ff',      // 主色调
  'primary-dark': '#0958d9',
  // ... 更多颜色变量
}
```

## 🔄 迁移说明

本项目从 **纯 localStorage 前端存储** 升级为 **前后端分离 + 云数据库** 架构：

- ✅ 所有 localStorage 操作已迁移为异步 API 调用
- ✅ 状态管理从同步 Reducer 改造为 async data flow
- ✅ 新增防抖自动保存机制（800ms debounce）
- ✅ 文档切换时立即保存当前文档
- ✅ 删除文件夹时级联删除其下所有文档

## 📄 License

MIT License — 自由使用、修改和分发。

---

<p align="center">
  Built with ❤️ using React + Vite + Tailwind CSS + Express + TiDB Cloud
</p>