YANG JIANKUAN
6fe04f4893
- 数据库新增 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>
109 lines
3.8 KiB
Markdown
109 lines
3.8 KiB
Markdown
# 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
|