whale-town-end/docs/systems/admin-dashboard/README.md

管理员后台（Admin Dashboard）

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

• 管理员登录（role=9）
• 用户列表管理
• 用户密码重置

说明：本项目用户系统原本的 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

请求：

{
  "identifier": "admin",
  "password": "Admin123456"
}

响应（成功）：

{
  "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

请求：

{
  "new_password": "NewPass1234"
}

---

4. 前端后台（Ant Design）

前端工程位于 client/，使用 Vite + React + Ant Design。

4.1 安装依赖

在项目根目录执行：

pnpm install

4.2 启动后端

pnpm run dev

4.3 启动前端后台

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：用户管理页（列表+重置密码）