feat:简单添加管理员后台功能

This commit is contained in:
jianuo
2025-12-19 19:17:47 +08:00
parent 17c16588aa
commit dd4fb6edd3
29 changed files with 1431 additions and 3 deletions

View File

@@ -0,0 +1,156 @@
# 管理员后台Admin Dashboard
本模块提供 Whale Town 的管理员后台能力,包含:
- 管理员登录role=9
- 用户列表管理
- 用户密码重置
> 说明:本项目用户系统原本的 `access_token` 为演示用 Base64 令牌。为了不影响现有用户端流程,管理员后台使用单独的签名 TokenHMAC-SHA256做鉴权。
---
## 1. 管理员账号设计
### 1.1 角色约定
用户表 `users.role`
- `1`:普通用户
- `9`:管理员(可访问后台)
### 1.2 启动引导创建管理员(可选)
通过环境变量启用启动引导在服务启动时如果不存在指定用户名的用户则自动创建一个管理员账户role=9
`.env` 中配置:
- `ADMIN_BOOTSTRAP_ENABLED=true`
- `ADMIN_USERNAME=admin`
- `ADMIN_PASSWORD=Admin123456`需满足密码强度至少8位包含字母和数字
- `ADMIN_NICKNAME=管理员`(可选)
注意:
- 建议仅在首次部署/开发环境开启,引导创建成功后可关闭。
- 生产环境务必设置强随机密码与强随机 `ADMIN_TOKEN_SECRET`
---
## 2. 管理员鉴权 Token
### 2.1 配置项
- `ADMIN_TOKEN_SECRET`签名密钥至少16字符生产环境建议≥32并随机
- `ADMIN_TOKEN_TTL_SECONDS`Token 有效期(秒),默认 `28800`8小时
### 2.2 使用方式
管理员登录成功后返回 `access_token`,后续请求在 Header 中携带:
- `Authorization: Bearer <access_token>`
---
## 3. 后端接口
### 3.1 管理员登录
- `POST /admin/auth/login`
请求:
```json
{
"identifier": "admin",
"password": "Admin123456"
}
```
响应(成功):
```json
{
"success": true,
"data": {
"admin": { "id": "1", "username": "admin", "nickname": "管理员", "role": 9 },
"access_token": "...",
"expires_at": 1766102400000
},
"message": "管理员登录成功"
}
```
### 3.2 用户列表
- `GET /admin/users?limit=100&offset=0`
- 需要管理员 Token
### 3.3 用户详情
- `GET /admin/users/:id`
- 需要管理员 Token
### 3.4 重置用户密码
- `POST /admin/users/:id/reset-password`
- 需要管理员 Token
请求:
```json
{
"new_password": "NewPass1234"
}
```
---
## 4. 前端后台Ant Design
前端工程位于 `client/`,使用 Vite + React + Ant Design。
### 4.1 安装依赖
在项目根目录执行:
```bash
pnpm install
```
### 4.2 启动后端
```bash
pnpm run dev
```
### 4.3 启动前端后台
```bash
pnpm -C client dev
```
默认访问:
- 前端:`http://localhost:5173`
- 后端:`http://localhost:3000`
- Swagger`http://localhost:3000/api-docs`
### 4.4 前端配置
- 复制 `client/.env.example``client/.env.local`
- 可通过 `VITE_API_BASE_URL` 指向后端地址
---
## 5. 代码位置
- 后端:
- `src/core/admin_core/`:管理员核心逻辑
- `src/core/guards/admin.guard.ts`:管理员接口鉴权
- `src/business/admin/`管理员HTTP API
- `src/dto/admin*.ts`:管理员请求/响应 DTO
- 前端:
- `client/src/pages/LoginPage.tsx`:管理员登录页
- `client/src/pages/UsersPage.tsx`:用户管理页(列表+重置密码)