feat: 添加 Admin 管理后台
- 数据库新增 Role 枚举、disabled 字段和 McpCallLog 调用日志表 - 后端新增 requireAdmin 中间件和 /api/admin/* 管理接口(统计、用户、项目、日志) - MCP 工具调用自动记录详细日志(耗时、参数、响应大小、客户端IP、token估算) - 前端新增 /admin 路由区域:仪表盘、用户管理、项目管理、调用日志四个页面 - JWT 携带 role 字段,登录/OAuth 增加禁用账号检查 - nginx 配置补充 X-Forwarded-For 透传真实客户端 IP Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
108
docs/superpowers/specs/2026-04-04-admin-dashboard-design.md
Normal file
108
docs/superpowers/specs/2026-04-04-admin-dashboard-design.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# Admin Dashboard Design Spec
|
||||
|
||||
## Overview
|
||||
|
||||
Add an admin web dashboard to the existing Agent Fox SPA, accessible at `/admin/*` routes. Provides real-time platform statistics, user management, project management, and MCP call log viewing.
|
||||
|
||||
## Database Changes
|
||||
|
||||
### User model additions
|
||||
- `role`: enum `Role` (`USER` | `ADMIN`), default `USER`
|
||||
- `disabled`: Boolean, default `false`
|
||||
|
||||
### New model: McpCallLog
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| id | String (UUID) | Primary key |
|
||||
| projectId | String (FK) | Reference to Project |
|
||||
| toolName | String | MCP tool name called |
|
||||
| calledAt | DateTime | Timestamp |
|
||||
| durationMs | Int | Response time in ms |
|
||||
| success | Boolean | Whether call succeeded |
|
||||
| requestParams | Json | Request parameters |
|
||||
| responseSize | Int | Response size in bytes |
|
||||
| clientIp | String | Caller IP address |
|
||||
| estimatedTokens | Int? | Estimated token consumption |
|
||||
|
||||
Indexes: `projectId`, `calledAt`, `toolName`
|
||||
|
||||
## Backend API
|
||||
|
||||
### New middleware
|
||||
- `requireAdmin`: verifies `role === 'ADMIN'` from JWT payload. Returns 403 if not admin.
|
||||
- Login check: `disabled === true` users get 403 on login.
|
||||
|
||||
### New routes (`/api/admin/`)
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | /stats | Aggregate stats (user count, project count, call count, today's active) |
|
||||
| GET | /stats/trends | Time-series data (7d/30d call trends) |
|
||||
| GET | /users | Paginated user list with search/sort |
|
||||
| GET | /users/:id | User detail + their projects |
|
||||
| PATCH | /users/:id/disable | Toggle user disabled status |
|
||||
| GET | /projects | Global paginated project list |
|
||||
| GET | /projects/:id | Project detail |
|
||||
| DELETE | /projects/:id | Delete project |
|
||||
| GET | /call-logs | Paginated call logs with filters |
|
||||
|
||||
### MCP call logging
|
||||
In `packages/mcp`, wrap each tool handler to record a `McpCallLog` entry with timing, params, success/failure, response size, client IP, and token estimate.
|
||||
|
||||
## Frontend
|
||||
|
||||
### Routes
|
||||
```
|
||||
/admin → Dashboard (stats overview)
|
||||
/admin/users → User management list
|
||||
/admin/users/:id → User detail
|
||||
/admin/projects → Project management list
|
||||
/admin/projects/:id → Project detail
|
||||
/admin/logs → Call log viewer
|
||||
```
|
||||
|
||||
### AdminLayout
|
||||
- Left sidebar (200px): nav links for Dashboard / Users / Projects / Logs
|
||||
- Top header: reuse theme toggle + user menu from existing Layout
|
||||
- Route guard: redirect non-admin users to `/dashboard`
|
||||
- Separate from existing `Layout.tsx`, parallel structure
|
||||
|
||||
### Dashboard page
|
||||
| Card | Content |
|
||||
|------|---------|
|
||||
| Registered Users | Total + today's new |
|
||||
| Projects | Total + today's new |
|
||||
| MCP Calls | Total + today's calls |
|
||||
| Active Users (7d) | Users with activity in past 7 days |
|
||||
| Avg Response Time | Mean durationMs of MCP calls |
|
||||
| Success Rate | Percentage of successful calls |
|
||||
|
||||
Below cards: 7-day call trend chart + recent calls table.
|
||||
|
||||
### User Management
|
||||
- Table: name, email, role, projects count, created date, status (active/disabled)
|
||||
- Search by name/email
|
||||
- Actions: view detail, toggle disable
|
||||
- Detail page: user info + list of their projects
|
||||
|
||||
### Project Management
|
||||
- Table: name, owner, endpoints count, modules count, created date
|
||||
- Search by name
|
||||
- Actions: view detail, delete (with confirmation)
|
||||
- Detail page: project info, modules, endpoints summary
|
||||
|
||||
### Call Logs
|
||||
- Table: time, project name, tool name, duration, success, client IP
|
||||
- Filters: project, tool name, date range, success/failure
|
||||
- Pagination
|
||||
|
||||
## Auth Flow
|
||||
- JWT payload adds `role` field
|
||||
- Frontend stores role in auth context
|
||||
- Admin nav entry only visible to admin users
|
||||
- Non-admin accessing `/admin/*` → redirect to `/dashboard`
|
||||
|
||||
## Tech Stack (frontend)
|
||||
- Same React 19 + React Router 7 + Tailwind CSS v4
|
||||
- Reuse existing custom components (Badge, Modal, ConfirmDialog, etc.)
|
||||
- Charts: lightweight solution (CSS-based or small chart lib)
|
||||
- No new component library
|
||||
Reference in New Issue
Block a user