# 管理员后台（Admin Dashboard）

本模块提供 Whale Town 的管理员后台能力，包含：

- 管理员登录（role=9）
- 用户列表管理
- 用户密码重置
- 运行日志查看（读取 logs/ 下最新日志）

> 说明：本项目用户系统原本的 `access_token` 为演示用 Base64 令牌。为了不影响现有用户端流程，管理员后台使用单独的签名 Token（HMAC-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"
}
```

### 3.5 运行日志（tail）

- `GET /admin/logs/runtime?lines=200`
- 需要管理员 Token

说明：

- 开发环境默认读取 `logs/dev.log`
- 生产环境默认读取 `logs/app.log`
- `lines` 默认 200，最大 2000

### 3.6 下载全部运行日志（archive）

- `GET /admin/logs/archive`
- 需要管理员 Token

说明：

- 返回一个 `tar.gz` 文件（浏览器会触发下载）
- 内容为整个 `logs/` 目录（例如开发环境的 `dev.log`，生产环境的 `app.log/access.log/error.log` 等）

---

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

页面说明：

- 用户管理：`/users`
- 运行日志：`/logs`

在“运行日志”页面可点击“下载日志压缩包”获取整个 `logs/` 目录的打包文件。

### 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`：用户管理页（列表+重置密码）
  - `client/src/pages/LogsPage.tsx`：运行日志页