myblog/.codebuddy/.rules/项目介绍.mdc

---
description: 
globs:
alwaysApply: true
---
# 项目介绍

## 项目概述
这是一个基于TypeScript + React Router v7 + shadcn/ui + Tailwind CSS+Zustand的React前端项目
## 技术栈
TypeScript + React Router v7 + shadcn/ui + Tailwind CSS+Zustand的React
### 核心框架和库

- **React 19**: 用于构建用户界面的JavaScript库
- **TypeScript**: 添加静态类型检查的JavaScript超集
- **Vite**: 现代化的前端构建工具，提供快速的开发体验
- **React Router**: 用于处理应用程序的路由
- **Zustand**: 轻量级状态管理库，用于管理应用状态

### UI组件和样式

- **Shadcn UI**: 基于Radix UI的组件集合，提供了可定制的UI组件
- **Tailwind CSS**: 实用优先的CSS框架，用于快速构建自定义设计
- **Radix UI**: 提供无样式、可访问的UI组件
- **Lucide React**: 提供简洁的图标集

### 表单和验证

- **React Hook Form**: 用于表单处理和验证
- **Zod**: TypeScript优先的模式验证库

### 开发工具

- **ESLint**: 代码质量检查工具
- **TypeScript ESLint**: TypeScript的ESLint插件

## 项目结构

```
├── src/                              # 源代码目录
│   ├── App.tsx                       # 应用主组件（ThemeProvider + Outlet）
│   ├── main.tsx                      # 应用入口，挂载 RouterProvider 与全局样式
│   ├── vite-env.d.ts                 # Vite 环境类型声明
│   ├── assets/                       # 静态资源
│   │   └── react.svg                 # React 图标
│   ├── components/                   # 组件目录
│   │   ├── theme-provider.tsx        # 主题提供者
│   │   ├── theme-toggle.tsx          # 主题切换（圆形扩散动画）
│   │   ├── blog/                     # 博客相关组件
│   │   │   ├── article-card.tsx
│   │   │   ├── article-toc.tsx
│   │   │   ├── blog-footer.tsx
│   │   │   ├── blog-header.tsx
│   │   │   ├── blog-sidebar.tsx
│   │   │   ├── code-block.tsx
│   │   │   ├── markdown-renderer.tsx
│   │   │   ├── search-suggestions.tsx
│   │   │   ├── simple-markdown.tsx
│   │   │   ├── timeline-archive.tsx
│   │   │   ├── user-profile.tsx
│   │   │   └── UserIpInfo.tsx
│   │   ├── layout/                   # 布局组件
│   │   │   ├── blog-layout.tsx
│   │   │   ├── mode-toggle.tsx
│   │   │   └── page-transition.tsx
│   │   └── ui/                       # 基础 UI 组件（shadcn/ui 集合）
│   │       ├── accordion.tsx
│   │       ├── alert-dialog.tsx
│   │       ├── alert.tsx
│   │       ├── aspect-ratio.tsx
│   │       ├── avatar.tsx
│   │       ├── badge.tsx
│   │       ├── breadcrumb.tsx
│   │       ├── button.tsx
│   │       ├── calendar.tsx
│   │       ├── card.tsx
│   │       ├── carousel.tsx
│   │       ├── chart.tsx
│   │       ├── checkbox.tsx
│   │       ├── collapsible.tsx
│   │       ├── command.tsx
│   │       ├── context-menu.tsx
│   │       ├── dialog.tsx
│   │       ├── drawer.tsx
│   │       ├── dropdown-menu.tsx
│   │       ├── form.tsx
│   │       ├── hover-card.tsx
│   │       ├── input-otp.tsx
│   │       ├── input.tsx
│   │       ├── label.tsx
│   │       ├── menubar.tsx
│   │       ├── navigation-menu.tsx
│   │       ├── pagination.tsx
│   │       ├── popover.tsx
│   │       ├── progress.tsx
│   │       ├── radio-group.tsx
│   │       ├── resizable.tsx
│   │       ├── scroll-area.tsx
│   │       ├── select.tsx
│   │       ├── separator.tsx
│   │       ├── sheet.tsx
│   │       ├── sidebar.tsx
│   │       ├── skeleton.tsx
│   │       ├── slider.tsx
│   │       ├── sonner.tsx
│   │       ├── switch.tsx
│   │       ├── table.tsx
│   │       ├── tabs.tsx
│   │       ├── textarea.tsx
│   │       ├── toggle-group.tsx
│   │       ├── toggle.tsx
│   │       └── tooltip.tsx
│   ├── hooks/                        # 自定义 Hook
│   │   ├── api/                      # API 请求钩子目录
│   │   ├── use-mobile.ts             # 移动设备检测
│   │   ├── use-mouse-transform.ts    # 鼠标位移变换
│   │   └── use-simple-mouse-scale.ts # 简易鼠标缩放
│   ├── lib/                          # 工具与服务
│   │   ├── highlight-utils.ts        # 代码高亮工具
│   │   ├── search-service.ts         # 搜索服务
│   │   ├── simple-post-loader.ts     # Markdown 文章加载器
│   │   └── utils.ts                  # 通用工具函数
│   ├── pages/                        # 页面
│   │   ├── About.tsx
│   │   ├── Archive.tsx
│   │   ├── ArticleDetail.tsx
│   │   ├── ArticleList.tsx
│   │   ├── BlogHome.tsx
│   │   ├── Categories.tsx
│   │   ├── HelloWorld.tsx
│   │   ├── Search.tsx
│   │   ├── Tags.tsx
│   │   └── TestPost.tsx
│   ├── posts/                        # Markdown 文章目录（节选，禁止在当前文件更新该目录下的文章）
│   │   ├── 4月测试文章.md
│   │   ├── 2002-最佳实践 copy.md
│   │   └── ......
│   ├── routes/                       # 路由配置
│   │   ├── blog-routes.tsx
│   │   └── routes.tsx
│   ├── store/                        # 状态管理（Zustand）
│   │   ├── blog-store.ts
│   │   ├── counter-store.ts
│   │   └── theme-store.ts
│   ├── styles/                       # 样式
│   │   ├── App.css
│   │   └── index.css                 # 包含 Tailwind CSS 引入
│   └── types/                        # TypeScript 类型定义
│       ├── blog.ts
│       ├── components.ts
│       └── index.ts
├── public/                           # 公共静态资源
│   ├── avatar.jpg
│   ├── blog-background.jpg
│   └── vite.svg
├── rule/                             # 项目规则与文档
│   ├── rule.md
│   ├── 前端代码注释规则.md
│   ├── 前端页面设计规则.md
│   ├── 文件命名规则.md
│   └── 后端api接口文档/
│       └── 接口统一响应文档.md
├── .gitignore
├── components.json                   # shadcn/ui 组件配置
├── eslint.config.js
├── index.html
├── package.json
├── pnpm-lock.yaml
├── tsconfig.json
├── tsconfig.app.json
├── tsconfig.node.json
└── vite.config.ts
```

## 主要功能

### 状态管理

项目使用Zustand进行状态管理，包括：

- **主题状态管理**: 支持亮色、暗色和系统主题
- **计数器状态管理**: 简单的计数器示例，展示Zustand的基本用法

### 路由管理

使用React Router进行路由管理，支持嵌套路由和动态路由。

### 组件系统

项目采用组件化开发方式，组件分为以下几类：

- **功能组件**: 实现特定业务功能的组件
- **布局组件**: 处理页面布局的组件
- **UI组件**: 基础UI组件，如按钮、卡片等

## 开发指南

### 安装依赖

```bash
pnpm install
```

### 启动开发服务器

```bash
pnpm dev
```

### 构建项目

```bash
pnpm build
```

### 代码检查

```bash
pnpm lint
```

## 最佳实践

1. 使用TypeScript类型定义确保代码类型安全
2. 遵循组件化开发原则，保持组件的单一职责
3. 使用Zustand进行状态管理，避免过度使用全局状态
4. 使用Tailwind CSS进行样式开发，保持样式的一致性
5. 遵循ESLint规则，保持代码质量