# 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-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WangSong TypeScript Admin

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

## 🚀 技术栈

- **前端框架**: Next.js 16 (App Router)
- **类型系统**: TypeScript
- **API 层**: tRPC (端到端类型安全)
- **数据访问**: Prisma ORM
- **数据库**: MySQL
- **状态管理**: TanStack Query (通过 tRPC 集成)
- **样式**: Tailwind CSS
- **认证**: JWT (jsonwebtoken)

## 📋 项目结构

```
wangsong-typescript-admin/
├── app/                      # Next.js App Router
│   ├── api/
│   │   └── trpc/
│   │       └── [trpc]/
│   │           └── route.ts  # tRPC API 路由
│   ├── login/
│   │   └── page.tsx          # 登录页面
│   ├── system/
│   │   └── user/
│   │       └── page.tsx      # 用户管理页面
│   ├── layout.tsx            # 根布局
│   └── page.tsx              # 首页
├── server/                   # 服务端代码
│   ├── routers/
│   │   ├── _app.ts           # 主路由
│   │   ├── auth.ts           # 认证路由
│   │   ├── user.ts           # 用户路由
│   │   ├── role.ts           # 角色路由
│   │   └── resources.ts      # 资源路由
│   └── trpc/
│       ├── context.ts        # tRPC 上下文
│       └── index.ts          # tRPC 实例
├── lib/
│   ├── prisma.ts             # Prisma 客户端单例
│   └── trpc.ts               # tRPC 客户端
├── providers/
│   └── TRPCProvider.tsx      # tRPC Provider
├── prisma/
│   └── schema.prisma         # Prisma Schema
├── .env                      # 环境变量
└── package.json
```

## 🎯 核心功能

### ✅ 已完成

1. **认证系统**
   - 用户登录（JWT Token）
   - MD5 密码加密（与 Spring Boot 兼容）
   - Token 验证中间件

2. **用户管理**
   - 用户列表（分页 + 搜索）
   - 用户新增
   - 用户编辑
   - 用户删除
   - 查询用户详情

3. **角色管理**
   - 角色列表（分页 + 搜索）
   - 角色新增（含资源关联）
   - 角色编辑
   - 角色删除

4. **资源/权限管理**
   - 资源树形列表
   - 资源新增
   - 资源编辑
   - 资源删除
   - 自动构建父子关系树

## 🛠️ 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置数据库

编辑 `.env` 文件，配置 MySQL 数据库连接：

```env
DATABASE_URL="mysql://root:root@localhost:3306/springboot-app"
NEXTAUTH_SECRET="your-secret-key"
JWT_SECRET="your-jwt-secret"
```

### 3. 生成 Prisma Client

```bash
npx prisma generate
```

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

```bash
npm run dev
```

访问 http://localhost:3000

### 5. 测试账号

- 用户名: `wangsong`
- 密码: `123456` (MD5: `e10adc3949ba59abbe56e057f20f883e`)

## 📊 数据库表结构

### 核心表

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

## 🔌 tRPC API 使用示例

### 前端调用

```typescript
import { trpc } from '@/lib/trpc'

// 登录
const loginMutation = trpc.auth.login.useMutation({
  onSuccess: (data) => {
    localStorage.setItem('token', data.token)
  },
})

loginMutation.mutate({ 
  username: 'wangsong', 
  password: '123456' 
})

// 获取用户列表
const { data, isLoading } = trpc.user.list.useQuery({
  page: 1,
  pageSize: 10,
  username: 'search_term',
})

// 删除用户
const deleteMutation = trpc.user.delete.useMutation({
  onSuccess: () => {
    refetch()
  },
})

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

### 后端路由

```typescript
// server/routers/user.ts
export const userRouter = router({
  list: protectedProcedure
    .input(z.object({
      page: z.number(),
      pageSize: z.number(),
      username: z.string().optional(),
    }))
    .query(async ({ input, ctx }) => {
      // 业务逻辑
    }),
})
```

## 🔄 从 Spring Boot 迁移对照

| Spring Boot | Next.js + tRPC | 说明 |
|------------|----------------|------|
| `@RestController` | tRPC Router | API 端点 |
| `MyBatis-Plus Mapper` | Prisma Client | 数据访问 |
| `Axios` | tRPC Client | HTTP 客户端 |
| `JWT Filter` | tRPC Middleware | 认证中间件 |
| `@RequestMapping` | File-based Routing | 路由系统 |
| `Service Layer` | tRPC Procedures | 业务逻辑 |

## ⚙️ 开发说明

### 添加新的 tRPC 路由

1. 在 `server/routers/` 创建新路由文件
2. 在 `server/routers/_app.ts` 中注册路由
3. 前端通过 `trpc.{router}.{procedure}.useQuery/useMutation()` 调用

### BigInt 处理

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

```typescript
// 后端返回
return {
  id: user.id.toString(), // BigInt → String
}

// 前端使用
const userId = BigInt(id) // String → BigInt
```

### 认证守卫

所有需要认证的 procedure 使用 `protectedProcedure`：

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

## 📝 待办事项

- [ ] 完善角色管理页面
- [ ] 完善资源管理页面
- [ ] 添加表单验证（react-hook-form + zod）
- [ ] 实现权限控制（基于角色的菜单显示）
- [ ] 添加加载状态和错误处理
- [ ] 优化 UI 组件（使用 shadcn/ui）
- [ ] 添加单元测试
- [ ] 部署配置

## 🐛 常见问题

### 1. 数据库连接失败

确保 MySQL 服务正在运行，并且 `.env` 中的数据库配置正确。

### 2. Prisma Client 未生成

运行 `npx prisma generate` 重新生成。

### 3. Token 验证失败

检查 `.env` 中的 `JWT_SECRET` 是否与生成 token 时使用的密钥一致。

## 📄 License

MIT

---

**迁移完成时间**: 2026-04-15  
**参考项目**: 
- 前端: `D:\app\vscode\wangsong-react-admin`
- 后端: `D:\app\IdeaProjects\springboot-app`