# why-blog

**Repository Path**: dev_why/why-blog

## Basic Information

- **Project Name**: why-blog
- **Description**: 我的 blog website。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-18
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WHY BLOG

一个基于 Vue 3 + TypeScript 构建的现代化、可配置的个人博客系统。拥有功能强大的后台管理面板和简洁响应式的前台界面。

## ✨ 特性

### 前台

- 🎨 **现代化 UI**：简洁响应式设计，支持亮色/暗色主题
- 📱 **移动端友好**：全设备响应式布局
- 🌍 **国际化**：内置 i18n 支持（中文/英文）
- ⚡ **快速性能**：使用 Vite 优化，实现极速开发和构建
- 🎯 **SEO 友好**：可配置的 meta 标签和 Open Graph 支持
- 👀 **浏览统计**：文章浏览数统计和热门文章展示
- 💬 **评论系统**：极简设计，支持引用评论、自动审核、本地存储用户信息

### 后台管理

- 🔐 **安全认证**：基于 JWT 的认证系统
- 📝 **内容管理**：文章、分类、标签的完整 CRUD 操作
- ✏️ **Markdown 编辑器**：功能强大的 Markdown 编辑器，支持图片上传
- 🖼️ **图片上传**：支持封面图片和文章内图片上传
- 🔍 **搜索过滤**：支持关键词搜索、状态筛选、分类筛选
- 📊 **数据统计**：Dashboard 展示文章统计、浏览量统计、热门文章等
- ⚙️ **网站配置**：全面的网站设置管理
  - 首页 Hero 区域自定义
  - 关于页面配置
  - 页脚内容管理
  - SEO 元数据
  - 社交链接编辑器
- 🎨 **现代化后台 UI**：增强的设计，流畅的动画和过渡效果
- 🌓 **暗色模式**：后台管理面板完整暗色主题支持
- 💬 **评论管理**：评论审核（通过/拒绝/删除）、状态筛选、关键词搜索、Dashboard 统计展示

### 开发体验

- 📦 **TypeScript**：完整的类型安全
- 🔄 **Mock 数据**：内置 Mock 服务器用于前端开发
- 📚 **完整文档**：API 文档和集成指南
- 🛠️ **简单配置**：简单的配置和部署

## 🚀 快速开始

### 前置要求

- Node.js >= 16
- npm 或 yarn

### 安装

```bash
# 克隆仓库
git clone https://github.com/yourusername/why-blog.git
cd why-blog

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

应用将在 `http://localhost:5173` 可用

### 默认登录凭据

- **用户名**: admin
- **密码**: admin123

## 📖 文档

完整的项目文档帮助您快速上手和深入了解系统：

### 核心文档
- **[API 文档](./API_DOCUMENTATION.md)** - 完整的API接口规范（后端必读⭐）
- **[后端接入指南](./docs/BACKEND_INTEGRATION.md)** - 后端开发者集成指南
- **[评论模块文档](./docs/COMMENT_MODULE.md)** - 评论系统详细设计与实现指南
- **[前端配置指南](./docs/FRONTEND_CONFIGURATION.md)** - 环境配置和部署说明
- **[更新日志](./CHANGELOG.md)** - 版本变更历史

### 进阶文档
- **[系统架构](./docs/ARCHITECTURE.md)** - 技术架构和设计决策
- **[功能模块](./docs/FEATURE_MODULES.md)** - 各模块详细说明
- **[开发指南](./docs/DEVELOPMENT_GUIDE.md)** - 开发规范和最佳实践
- **[产品规格](./docs/PRODUCT_SPECIFICATION.md)** - 产品功能规格说明

### 快速链接
- 🚀 [快速开始](#-快速开始) - 5分钟运行项目
- 🔐 [默认登录凭据](#默认登录凭据) - admin/admin123
- 📊 [About页面定制](./docs/FEATURE_MODULES.md#about-页面深度定制系统) - 7种区块类型详解

## 🛠️ 技术栈

### 核心

- **框架**: Vue 3 (Composition API)
- **语言**: TypeScript
- **构建工具**: Vite
- **路由**: Vue Router 4
- **状态管理**: Pinia
- **UI 库**: Naive UI
- **HTTP 客户端**: Axios
- **国际化**: Vue I18n
- **Markdown 编辑器**: md-editor-v3

### 开发

- **代码质量**: ESLint + Prettier
- **版本控制**: Git

## 📁 项目结构

```
why-blog/
├── src/
│   ├── api/              # API 接口定义
│   ├── assets/           # 静态资源
│   ├── components/       # 可复用组件
│   ├── layouts/          # 布局组件
│   ├── locales/          # i18n 翻译文件
│   ├── mock/             # 开发用 Mock 数据
│   ├── router/           # 路由配置
│   ├── stores/           # Pinia 状态管理
│   ├── styles/           # 全局样式
│   ├── types/            # TypeScript 类型定义
│   ├── utils/            # 工具函数
│   ├── views/            # 页面组件
│   │   ├── admin/        # 后台管理页面
│   │   └── front/        # 前台页面
│   ├── App.vue           # 根组件
│   └── main.ts           # 应用入口
├── docs/                 # 文档
├── public/               # 公共静态文件
├── .env.development      # 开发环境变量
├── .env.production       # 生产环境变量
└── package.json
```

## ⚙️ 配置

### 环境变量

创建 `.env.development` 和 `.env.production` 文件：

```bash
# 开发环境
VITE_API_BASE_URL=http://localhost:3000/api
VITE_USE_MOCK=true

# 生产环境
VITE_API_BASE_URL=https://api.yourdomain.com/api
VITE_USE_MOCK=false
```

### Mock 模式 vs 真实后端

**Mock 模式** (无需后端的前端开发):
```bash
VITE_USE_MOCK=true
```
- 使用 `src/mock/data/` 中的本地 Mock 数据
- 适合前端开发和原型设计

**真实后端模式**:
```bash
VITE_USE_MOCK=false
VITE_API_BASE_URL=your_backend_url
```
- 连接到实际的后端 API
- 需要后端服务器运行

## 🎨 核心功能实现

### 1. 可配置的网站内容

所有前台内容都可以通过后台管理面板管理：

- **Hero 区域**: 标题、描述、按钮标签
- **关于页面**: 页面标题、副标题、理念卡片
- **页脚**: 快速链接、版权信息、座右铭
- **社交链接**: 添加/编辑/删除社交媒体链接
- **SEO**: 关键词、meta 描述、OG 图片

### 2. 暗色主题支持

- 基于系统偏好的自动主题检测
- 前台和后台的手动主题切换
- 主题偏好持久化存储在 localStorage
- 流畅的主题过渡效果

### 3. 响应式设计

- 移动优先的设计方法
- 针对所有屏幕尺寸优化的布局
- 触摸友好的界面

### 4. 文章浏览统计

- 自动记录文章浏览数
- Dashboard 显示总浏览量
- 热门文章排行榜（按浏览量排序）
- 前台文章列表和详情页展示浏览数

### 5. 评论系统

- **极简设计**：纯文本评论，专注核心功能
- **引用功能**：扁平化引用替代复杂嵌套回复
- **自动审核**：本地敏感词过滤（<10ms）+ 白名单机制
- **用户体验**：localStorage 自动保存用户信息
- **后台管理**：评论审核、状态筛选、关键词搜索
- **Dashboard 集成**：评论统计和最近评论展示
- **安全防护**：XSS 防护、频率限制、HTML 转义

## 📝 可用脚本

```bash
# 开发
npm run dev          # 启动开发服务器

# 构建
npm run build        # 生产环境构建
npm run build:dev    # 开发环境构建

# 预览
npm run preview      # 预览生产构建

# 代码检查
npm run lint         # 检查并修复文件
```

## 🚀 部署

### 生产环境构建

```bash
npm run build
```

构建文件将在 `dist/` 目录中。

### 部署到静态托管服务

应用可以部署到任何静态托管服务：

- **Vercel**: 连接你的 GitHub 仓库
- **Netlify**: 拖放 `dist` 文件夹
- **GitHub Pages**: 使用 GitHub Actions
- **Nginx**: 提供 `dist` 文件夹服务

### Nginx 配置示例

```nginx
server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/blog/dist;
    index index.html;

    # SPA 路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

## 🔧 后端集成

### API 要求

前端需要一个遵循 [`API_DOCUMENTATION.md`](./API_DOCUMENTATION.md) 规范的 RESTful API。

### 主要端点

- `POST /api/auth/login` - 认证登录
- `POST /api/auth/logout` - 退出登录
- `POST /api/auth/refresh` - 刷新 Token
- `GET /api/site` - 获取网站配置
- `PUT /api/site` - 更新网站配置
- `GET /api/posts` - 获取文章列表（支持关键词搜索、状态筛选、分类筛选）
- `POST /api/posts` - 创建文章
- `PUT /api/posts/:id` - 更新文章
- `DELETE /api/posts/:id` - 删除文章
- `POST /api/posts/:id/view` - 增加文章浏览数
- `GET /api/categories` - 获取分类列表
- `POST /api/categories` - 创建分类
- `PUT /api/categories/:id` - 更新分类
- `DELETE /api/categories/:id` - 删除分类
- `GET /api/tags` - 获取标签列表
- `POST /api/tags` - 创建标签
- `PUT /api/tags/:id` - 更新标签
- `DELETE /api/tags/:id` - 删除标签
- `GET /api/comments` - 获取评论列表（支持文章ID筛选、状态筛选、排序）
- `POST /api/comments` - 发表评论（自动审核、敏感词过滤）
- `DELETE /api/comments/:id` - 删除评论
- `PUT /api/comments/:id/approve` - 通过审核
- `PUT /api/comments/:id/reject` - 拒绝审核
- `POST /api/upload/image` - 上传图片
- `GET /api/dashboard/stats` - 获取 Dashboard 统计数据

详细的 API 规范请查看 [API 文档](./API_DOCUMENTATION.md)。

## 🤝 贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 本仓库
2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [Naive UI](https://www.naiveui.com/) - Vue 3 组件库
- [Vite](https://vitejs.dev/) - 下一代前端构建工具
- [Pinia](https://pinia.vuejs.org/) - Vue.js 的直观状态管理库
- [md-editor-v3](https://github.com/imzbf/md-editor-v3) - Vue3 Markdown 编辑器

## 📧 联系方式

- **GitHub**: [Your GitHub Profile](https://github.com/yourusername)
- **Email**: your.email@example.com
- **Website**: https://yourdomain.com

---

**使用 Vue 3 + TypeScript 用 ❤️ 构建**