# wangsong-react-admin

**Repository Path**: vmaps/wangsong-react-admin

## Basic Information

- **Project Name**: wangsong-react-admin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-26
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WangSong React Admin - 管理系统 ⭐ AI 维护版

**📚 完整项目文档：** [PROJECT_DOCUMENTATION_COMPLETE.md](./PROJECT_DOCUMENTATION_COMPLETE.md) ⭐⭐⭐

基于 **React 18** + **Vite** + **TypeScript** + **Zustand** + **TanStack Query** 的现代化后台管理系统。

---

## 🚀 快速导航

### 👉 唯一官方文档
**[PROJECT_DOCUMENTATION_COMPLETE.md](./PROJECT_DOCUMENTATION_COMPLETE.md)** ⭐⭐⭐

**包含内容：**
- ✅ 完整技术栈说明
- ✅ 所有业务逻辑  
- ✅ 文件结构详解
- ✅ 组件 API 文档
- ✅ 状态管理说明
- ✅ 路由配置
- ✅ 权限系统
- ✅ 错误处理
- ✅ 开发规范
- ✅ 重构总结
- ✅ 代码清理报告
- ✅ AI 快速上手指南

---

## 🎯 技术栈

- **React 18** - 最新版本
- **Vite** - 快速构建工具
- **TypeScript** - 类型安全
- **Zustand** - 轻量级状态管理
- **TanStack Query (v5)** - 服务端状态管理
- **React Router v7** - 路由管理
- **Axios** - HTTP 客户端（带全局错误处理）
- **Tailwind CSS** - 原子化 CSS
- **shadcn/ui** - 高质量 UI 组件库

## 📦 项目结构

**详细结构见：** [PROJECT_DOCUMENTATION_COMPLETE.md](./PROJECT_DOCUMENTATION_COMPLETE.md#项目结构)

```
wangsong-react-admin/
├── src/
│   ├── api/              # API 接口定义
│   │   ├── auth.ts      # 认证相关 API
│   │   ├── user.ts      # 用户相关 API
│   │   ├── role.ts      # 角色相关 API
│   │   └── resources.ts # 权限相关 API
│   ├── components/       # 组件（含 5 个通用组件 ⭐）
│   │   ├── ui/          # UI 组件 + 通用组件
│   │   ├── auth/        # 认证组件
│   │   └── Layout.tsx   # 布局组件
│   ├── config/          # 配置文件
│   │   └── index.ts     # 全局配置
│   ├── hooks/           # 自定义 Hooks
│   │   └── useAuth.ts   # 认证 Hook
│   ├── lib/             # 工具库
│   │   └── utils.ts     # 工具函数
│   ├── pages/           # 页面组件
│   │   ├── HomePage.tsx
│   │   ├── user/        # 用户管理
│   │   ├── role/        # 角色管理
│   │   └── resources/   # 权限管理
│   ├── providers/       # Provider 组件
│   │   └── AppProvider.tsx
│   ├── router/          # 路由配置
│   │   └── index.tsx    # 路由定义
│   ├── services/        # API 服务
│   │   └── api.ts       # Axios 实例
│   ├── store/           # 状态管理
│   │   └── authStore.ts # 认证 Store
│   ├── types/           # 类型定义
│   │   └── index.ts     # 全局类型
│   ├── utils/           # 工具函数（含导航工具 ⭐）
│   │   └── navigation.ts    # 导航工具 ⭐
│   ├── App.tsx          # 主应用组件
│   ├── main.tsx         # 入口文件
│   └── index.css        # 全局样式
├── .eslintrc.cjs        # ESLint 配置
├── .prettierrc          # Prettier 配置
├── package.json
├── vite.config.js
├── tailwind.config.js
├── postcss.config.js
└── tsconfig.json
```

## 🚀 快速开始

### 安装依赖

```bash
npm install
```

### 启动开发服务器

```bash
npm run dev
```

访问 http://localhost:5173

### 构建生产版本

```bash
npm run build
```

### 预览生产构建

```bash
npm run preview
```

## ✅ 完成情况

### 第 1 步：项目初始化与环境搭建 ✅

已完成项目初始化：

- ✅ Vite + React 18 + TypeScript 项目创建
- ✅ Zustand + TanStack Query + React Router 安装
- ✅ Tailwind CSS + shadcn/ui 配置
- ✅ 基础路由结构配置
- ✅ Axios + API 服务 + 环境变量配置
- ✅ API 接口定义（auth, user, role, resources）

### 第 2 步：状态管理与认证体系 ✅

已完成认证体系构建：

- ✅ Zustand Store 创建 (token, permissions)
- ✅ 本地存储持久化实现
- ✅ TanStack Query 全局错误处理配置
- ✅ Axios 拦截器实现（Token 注入、登录异常处理）
- ✅ 认证 Hook (useAuth) 创建
- ✅ 认证守卫组件 (AuthGuard) 实现

### 第 3 步：登录页面 ✅

已完成登录功能：

- ✅ shadcn/ui Button、Input、Card 组件创建
- ✅ Login 登录表单组件实现
- ✅ 表单验证逻辑实现
- ✅ 集成 useAuth Hook 进行登录
- ✅ 登录成功跳转和错误提示
- ✅ ProtectedRoute 路由守卫实现

### 第 4 步：布局组件 ✅

已完成主框架布局：

- ✅ Layout 主框架组件创建
- ✅ 侧边栏菜单实现（基于权限显示）
- ✅ 顶栏和面包屑导航实现
- ✅ 用户下拉菜单（修改密码、退出）
- ✅ DropdownMenu 组件实现
- ✅ 路由配置更新集成 Layout

### 第 5 步：用户管理模块 ✅

已完成用户列表功能：

- ✅ Table、Dialog UI 组件创建
- ✅ UserList 用户列表组件实现
- ✅ 集成 TanStack Query 获取用户数据
- ✅ 搜索和分页功能实现
- ✅ 删除用户功能实现
- ✅ UserAdd 新增用户表单实现
- ✅ UserEdit 编辑用户表单实现
- ✅ 权限控制集成

## 📋 下一步计划

### 第 2 步：状态管理与认证体系

- [ ] 创建 Zustand Store (token, permissions)
- [ ] 实现本地存储持久化
- [ ] 配置 TanStack Query 全局错误处理
- [ ] 实现 Axios 拦截器
- [ ] 创建认证 Hook

### 第 3 步：登录页面

- [ ] Login 组件实现
- [ ] 表单验证
- [ ] 登录功能集成

## 🔧 开发说明

### 通用组件库 ⭐ 重要

**已创建 5 个通用组件，减少 455+ 行代码：**

1. **Pagination** - 分页组件
2. **ActionButtonGroup** - 操作按钮组  
3. **TreeSelector** - 树形选择器
4. **FormPage** - 表单页面布局
5. **Navigation Utils** - 导航工具函数

**使用示例：**
```tsx
import { Pagination, ActionButtonGroup, FormPage } from '@/components/ui'
import { navigateToAdd } from '@/utils/navigation'

// 列表页
<Pagination currentPage={page} total={total} onPageChange={setPage} />
<ActionButtonGroup actions={actions} />

// 表单页
<FormPage title="标题" onSubmit={...} onBack={...}>
  {/* 表单内容 */}
</FormPage>
```

**详细文档：** [PROJECT_DOCUMENTATION_COMPLETE.md](./PROJECT_DOCUMENTATION_COMPLETE.md#通用组件库)

---

### API 调用

所有 API 接口已定义在 `src/api` 目录下，使用 Axios 进行 HTTP 请求。

**全局错误处理**：
- ✅ 401/403 错误自动跳转到登录页
- ✅ 友好的错误提示
- ✅ 统一的错误处理工具函数

详见：[PROJECT_DOCUMENTATION_COMPLETE.md](./PROJECT_DOCUMENTATION_COMPLETE.md#错误处理)

### 环境变量

修改 `src/config/index.ts` 中的 `API_BASE_URL` 来配置后端 API 地址。

当前配置：`http://127.0.0.1:8081`

## 📝 脚本命令

| 命令 | 说明 |
|------|------|
| `npm run dev` | 启动开发服务器 |
| `npm run build` | 构建生产版本 |
| `npm run preview` | 预览生产构建 |

## 🎨 UI 组件

项目使用 shadcn/ui 组件库，提供以下基础组件：

- Button
- Input
- Form
- Table
- Dialog
- Card
- ...更多组件将在后续步骤中添加

## 📄 License

ISC