# wangsong-typescript-admin

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

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WangSong Admin

现代化的后台管理系统，基于 Next.js 16 + TypeScript + tRPC + Prisma 构建。

![Next.js](https://img.shields.io/badge/Next.js-16-black)
![TypeScript](https://img.shields.io/badge/TypeScript-5-blue)
![tRPC](https://img.shields.io/badge/tRPC-10-orange)
![Prisma](https://img.shields.io/badge/Prisma-5-purple)

## ✨ 特性

- 🚀 **端到端类型安全** - tRPC 提供完整的 TypeScript 类型推断
- 🎨 **现代化 UI** - Tailwind CSS + Radix UI + Lucide Icons
- 🔐 **认证与授权** - JWT + Middleware 路由守卫
- 📊 **完整的 CRUD** - 用户、角色、资源管理
- 🎯 **高性能表单** - React Hook Form + Zod 验证
- 🌳 **树形结构** - 资源/菜单的递归展示
- 📱 **响应式设计** - 适配桌面和移动端

## 🛠️ 技术栈

**前端**:
- Next.js 16 (App Router)
- TypeScript 5
- Tailwind CSS 4
- Radix UI (无障碍组件)
- React Hook Form + Zod
- Lucide Icons

**后端**:
- tRPC 10 (API 层)
- Prisma 5 (ORM)
- MySQL (数据库)
- JWT (认证)

## 🚀 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env` 并修改配置：

```env
DATABASE_URL="mysql://root:password@localhost:3306/wangsong_admin"
JWT_SECRET="your-super-secret-jwt-key-change-this"
```

### 3. 初始化数据库

```bash
# 生成 Prisma Client
npx prisma generate

# 同步数据库结构（首次运行）
npx prisma db push

# 或者使用迁移（生产环境推荐）
npx prisma migrate dev
```

### 4. 启动开发服务器

```bash
npm run dev
```

访问 http://localhost:3000

### 5. 测试账号

- 用户名: `wangsong`
- 密码: `123456`

## 📁 项目结构

```
wangsong-admin/
├── app/                    # Next.js App Router
│   ├── api/trpc/[trpc]/   # tRPC API 入口
│   ├── login/             # 登录页
│   ├── system/            # 系统管理
│   │   ├── user/          # 用户管理
│   │   ├── role/          # 角色管理
│   │   └── resources/     # 资源管理
│   ├── layout.tsx         # 根布局
│   └── page.tsx           # 首页
├── components/            # React 组件
│   ├── ui/                # UI 组件库
│   │   ├── Button.tsx
│   │   ├── Form.tsx
│   │   ├── Pagination.tsx
│   │   └── ...
│   ├── DashboardLayout.tsx
│   ├── Toast.tsx
│   └── ConfirmDialog.tsx
├── server/                # 服务端代码
│   ├── routers/           # tRPC 路由
│   │   ├── auth.ts
│   │   ├── user.ts
│   │   ├── role.ts
│   │   └── resources.ts
│   └── trpc/              # tRPC 配置
├── lib/                   # 工具库
│   ├── prisma.ts
│   └── trpc.ts
├── utils/                 # 通用工具函数
├── hooks/                 # 自定义 Hooks
├── prisma/
│   └── schema.prisma      # 数据库 Schema
└── middleware.ts          # Next.js 中间件
```

## 🎯 核心功能

### 认证系统

- JWT Token 认证
- Middleware 路由守卫
- 自动重定向未登录用户
- 登录后返回原路径

### 用户管理

- ✅ 用户列表（分页 + 搜索）
- ✅ 新增/编辑/删除用户
- ✅ 分配角色
- ✅ 密码修改

### 角色管理

- ✅ 角色列表（分页 + 搜索）
- ✅ 新增/编辑/删除角色
- ✅ 分配权限（树形选择）

### 资源管理

- ✅ 树形结构展示
- ✅ 新增/编辑/删除资源
- ✅ 支持菜单和按钮类型
- ✅ 父子关系自动维护

## 💻 开发指南

### 添加新的 tRPC 路由

1. 创建路由文件 `server/routers/xxx.ts`:

```typescript
import { z } from 'zod'
import { router, protectedProcedure } from '../trpc'

export const xxxRouter = router({
  list: protectedProcedure
    .input(z.object({
      page: z.number(),
      pageSize: z.number(),
    }))
    .query(async ({ input, ctx }) => {
      // 业务逻辑
      return { data: [], total: 0 }
    }),
})
```

2. 在 `server/routers/_app.ts` 注册:

```typescript
import { xxxRouter } from './xxx'

export const appRouter = router({
  xxx: xxxRouter,
})
```

3. 前端调用:

```typescript
const { data } = trpc.xxx.list.useQuery({ page: 1, pageSize: 10 })
```

### 创建新页面

```tsx
'use client'

import { Form, FormField, Button } from '@/components/ui'
import { z } from 'zod'

const schema = z.object({
  name: z.string().min(1, '必填'),
})

export default function MyPage() {
  return (
    <Form schema={schema} onSubmit={handleSubmit}>
      {(form) => (
        <>
          <FormField form={form} name="name" label="名称" />
          <Button type="submit">提交</Button>
        </>
      )}
    </Form>
  )
}
```

## 🗄️ 数据库表

- `system_user` - 用户表
- `system_role` - 角色表
- `system_resources` - 资源/菜单表
- `system_user_role` - 用户角色关联
- `system_role_resources` - 角色资源关联

## 🔧 常用命令

```bash
# 开发
npm run dev

# 构建
npm run build

# 启动生产服务
npm start

# 代码检查
npm run lint

# Prisma 相关
npx prisma studio          # 打开数据库可视化工具
npx prisma generate        # 生成 Prisma Client
npx prisma db push         # 同步数据库结构
npx prisma migrate dev     # 创建迁移
```

## 📝 API 示例

### 登录

```typescript
import { setCookie } from '@/lib/utils'

const login = trpc.auth.login.useMutation({
  onSuccess: (data) => {
    setCookie('token', data.token, 7)
    router.push('/')
  },
})

login.mutate({ username: 'admin', password: '123456' })
```

### 获取用户列表

```typescript
const { data, isLoading } = trpc.user.list.useQuery({
  page: 1,
  pageSize: 10,
  username: 'search',
})
```

### 删除用户

```typescript
const deleteMutation = trpc.user.delete.useMutation({
  onSuccess: () => refetch(),
})

deleteMutation.mutate({ ids: ['1', '2'] })
```

## ⚠️ 注意事项

### BigInt 处理

Prisma 的 `BigInt` 需要转换为字符串：

```typescript
// 后端
id: user.id.toString()

// 前端
const id = BigInt(stringId)
```

### 认证守卫

使用 `protectedProcedure` 自动验证 Token：

```typescript
export const myRouter = router({
  getData: protectedProcedure.query(async ({ ctx }) => {
    // ctx.token 已验证
  }),
})
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 License

MIT

---

**开发时间**: 2026  
**参考项目**: wangsong-react-admin + springboot-app