# AgentTeam Admin Dashboard Spec

> Status: draft-spec
> Canonical path: `specs/admin/dashboard.md`
> Created: 2026-04-18
> Scope: deployment-level admin dashboard, usage metrics, user statistics, and invite-only registration allowlist management

## 1. 背景

AgentTeam 已经有 workspace / organization / invite / machine / agent 等管理能力，但这些能力主要面向单个 workspace 或 organization。运营侧现在需要一个更高层的后台，用来回答：

- 这个部署里有多少 workspace、用户、agent、machine？
- 哪些 workspace 在使用，哪些没有使用？
- 最近访问量和错误情况怎么样？
- 邀请制注册之后，哪些邮箱被允许注册，谁加的白名单，什么时候过期？

老板的反馈是“后台界面无所谓”，因此本 spec 的重点不是做复杂 UI，而是定义清楚数据口径、权限边界和最小可用管理动作。

## 2. 目标

### 2.1 MVP 必须满足

- 提供一个只有 system admin 可访问的后台入口。
- 提供全局概览指标：
  - workspace 总数 / 新增数 / 活跃数
  - 用户总数 / 已验证用户数 / 新增用户数 / 活跃用户数
  - agent 总数 / 活跃 agent 数
  - machine 总数 / 在线 machine 数
  - pending invite 数（MVP 当前先展示 workspace invite）
- 提供 workspace 列表和详情，用于查看：
  - workspace owner
  - human member 数
  - agent 数
  - machine 数
  - 最近消息时间
  - 最近活跃时间
- 提供用户统计列表，用于查看：
  - email / display name
  - 是否 system admin
  - email 是否验证
  - 创建时间
  - 所属 workspace 数
  - 最近活跃时间
- 提供注册白名单管理：
  - 添加邮箱到白名单
  - 禁用 / 删除白名单项
  - 查看白名单项创建人、创建时间、原因、过期时间
- 第一版不阻塞于完整 audit log；若后续要保留管理写操作审计，再补专门审计表。

### 2.2 非目标

- 不做复杂 BI 系统。
- 不做漂亮的高保真 UI。
- 不做完整 RBAC / 多角色后台权限系统。
- 不在 MVP 里做用户封禁、workspace 删除、强制转移 owner 等高风险操作。
- 不把 API 访问量、CPU、内存等 infra observability 全部自研进业务库；这类指标可先接现有日志 / Prometheus / Grafana。

## 3. 用户与权限

### 3.1 角色

MVP 只引入一个后台访问角色：

- `system admin`：`users.is_admin = true`

`workspace owner/admin` 和 `organization owner/admin` 不能自动访问全局后台。原因：

- 全局后台会跨 workspace 暴露用户、workspace、agent、machine 统计。
- 后台白名单管理会影响整个 deployment 的注册入口。

### 3.2 入口

建议新增：

- Web route: `/admin`
- API prefix: `/api/admin/*`

前端入口只对 `session.user.isAdmin === true` 的用户展示。后端必须独立校验 `users.is_admin`，不能只依赖前端隐藏入口。

## 4. 信息架构

MVP 后台分 4 个 tab：

1. `Overview`
2. `Workspaces`
3. `Users`
4. `Registration Allowlist`

后续可增加：

5. `Traffic`
6. `Audit Log`

## 5. 指标口径

### 5.1 Overview 指标

| 指标 | MVP 口径 | 数据来源 | 备注 |
| --- | --- | --- | --- |
| Total workspaces | `workspaces` 总数 | DB | 包括个人 workspace |
| New workspaces | 时间窗口内创建的 workspace 数 | DB | 默认窗口：24h / 7d |
| Active workspaces | 时间窗口内有消息发送的 workspace 数 | `scope_messages` | 不以登录或页面访问计算 |
| Total users | `users` 总数 | DB | 包含未验证用户 |
| Verified users | `email_verified_at IS NOT NULL` 的用户数 | DB | 邮件验证关闭时可能接近总数 |
| Active users | 时间窗口内发送过 human message 的用户数 | `scope_messages + members` | MVP 使用“协作活跃”，不是网页 UV |
| Total agents | `agents` 总数 | DB | 包含 inactive agent |
| Active agents | 时间窗口内有 agent message 的 agent 数；可选叠加当前进程内 realtime running-agent snapshot，但该 snapshot 不能落 TiDB | `scope_messages` / ephemeral runtime state | MVP 主口径使用 durable message activity |
| Total machines | `machines` 总数 | DB | 包含 offline machine |
| Online machines | 当前有 authenticated daemon WebSocket 连接的 machine 数 | ephemeral runtime state | 以 server 连接状态为准；不得用 `machines.disconnected_at` 作为在线事实 |
| Pending invites | 未接受、未撤销、未过期的 workspace invite 数 | DB | MVP 当前先只统计 workspace invite |

### 5.2 “访问量”口径

老板当前更关心“有没有人在用、哪些 workspace 在活跃、agent / machine 有没有跑起来”，所以 MVP 先统一按 **Product activity** 展示，口径尽量简单可解释：

- messages：最近窗口内的总消息量 / human message / agent message
- active users：最近窗口内登录过或发送过 human message 的用户
- active workspaces：最近窗口内有消息的 workspace
- recent logins：最近窗口内成功建立 session 的用户数

MVP **不做** HTTP 请求量、PV、UV、5xx、延迟等 traffic volume 指标。这些更适合从 nginx / app logs / Prometheus / Grafana 获取，后续若老板确实要看，再单独接观测系统。

### 5.3 时间窗口

所有趋势指标默认支持：

- last 24h
- last 7d
- last 30d

如果直接查 DB 会影响线上性能，应先只实现 `last 24h` 和 `last 7d`，并限制分页 / limit。

## 6. Workspaces 页面

### 6.1 列表字段

- Workspace ID
- Workspace name
- Owner email / display name
- Created at
- Human members count
- Agents count
- Machines count
- Channels count
- Messages in selected window
- Last message at
- Pending invites count

### 6.2 筛选

MVP 支持：

- 按 workspace name / slug / id 搜索
- 按 owner email 搜索
- 只看最近 7 天活跃 / 不活跃

### 6.3 操作

MVP 不提供 destructive action。

允许的只读跳转：

- 打开 workspace 当前前台页面
- 查看该 workspace 的成员 / agents / machines 聚合详情

## 7. Users 页面

### 7.1 列表字段

- User ID
- Email
- Display name
- Is system admin
- Email verified
- Created at
- Last human message at
- Workspace count
- Owned workspace count

### 7.2 筛选

MVP 支持：

- 按 email 搜索
- 是否 verified
- 是否 system admin
- 最近 7 天是否活跃

### 7.3 操作

MVP 不提供：

- 删除用户
- 禁用用户
- 重置密码
- 修改 system admin

这些都是高风险动作，后续必须单独 spec。

## 8. Registration Allowlist 页面

### 8.1 背景

邀请制注册需要支持后台白名单管理。当前注册策略已经支持 allowlist 邮箱概念；MVP 需要把它从静态环境变量演进为可审计、可查询、可修改的数据模型。

### 8.2 白名单对象

建议新增持久化对象：

```text
registration_allowlist_entries
- id
- pattern
- reason
- expires_at nullable
- created_by_user_id
- created_at
- disabled_at nullable
- updated_at
```

`pattern` 支持两种格式：

- 精确邮箱：`alice@example.com`
- 域名规则：`@example.com`

匹配规则：

- 精确邮箱按归一化后的完整邮箱匹配
- 域名规则只匹配同域邮箱，例如 `alice@example.com` 命中 `@example.com`
- 不匹配子域，例如 `alice@sub.example.com` 不命中 `@example.com`

### 8.3 操作

MVP 支持：

- 添加邮箱
- 禁用邮箱
- 查看列表

MVP 不支持：

- 批量导入
- 自动审批
- IP 白名单

### 8.4 注册链路规则

当系统初始化完成且注册模式为 invite-only：

注册邮箱满足任一条件即可注册：

1. 有效 workspace invite
2. 有效 organization invite
3. active registration allowlist entry

如果同一个邮箱既在 allowlist 又有 invite，不改变 invite accept 行为；allowlist 只允许创建账号，不自动加入 workspace。

### 8.5 审计边界

当前实现先聚焦 allowlist 功能本身，不把完整 audit log 作为 MVP 阻塞项。

后续如果需要补审计，建议优先覆盖：

- `registration_allowlist.create`
- `registration_allowlist.disable`

并且避免在审计数据中落 secret、token、SMTP password、machine api key 等敏感信息。

## 9. API 草案

## 10. API 草案

### 10.1 Read APIs

```text
GET /api/admin/overview?window=24h|7d|30d
GET /api/admin/workspaces?query=&active=&limit=
GET /api/admin/users?query=&active=&limit=
GET /api/admin/registration-allowlist?query=&includeDisabled=
```

### 10.2 Write APIs

```text
POST /api/admin/registration-allowlist
  { "pattern": "...", "reason": "...", "expiresAt": "..." }

POST /api/admin/registration-allowlist/:entryId/disable
  {}
```

所有 API 必须使用：

- authenticated user
- verified identity
- system admin authorization

## 11. 前端草案

MVP 用现有 Web app 实现即可，不单独搭服务。

建议组件：

- `AdminRoute`
- `AdminOverviewTab`
- `AdminWorkspacesTab`
- `AdminUsersTab`
- `AdminRegistrationAllowlistTab`

UI 标准：

- 表格 + 搜索 + 简单卡片
- 不引入新 UI 框架
- 文案必须同时提供 `en` / `zh-CN` i18n

## 12. 数据与性能

### 12.1 查询策略

MVP 可以直接查主库，但必须满足：

- 所有列表分页
- 所有趋势查询有时间窗口
- 默认 limit 不超过 50
- 大聚合查询必须有索引或可接受的 explain

### 12.2 后续优化

如果直接聚合 `scope_messages` 影响线上，可新增按小时汇总表：

```text
admin_metric_hourly_snapshots
- hour
- workspace_id nullable
- metric_name
- metric_value
```

MVP 不强制做 snapshot，除非线上数据量已经导致查询不可接受。

## 13. 安全要求

- 后台不展示 password hash。
- 后台不展示 refresh token / session token。
- 后台不展示 machine api key，只允许展示已有 prefix。
- 后台不展示 SMTP password、Feishu secret、GitHub/Gitea app secret。
- 所有后台 API 错误必须带上下文，便于定位。

## 14. 实施建议

### Phase 1: Spec Review

- 对齐指标口径。
- 确认只做注册邮箱白名单，且支持精确邮箱与域名规则。
- 确认谁是 system admin。

### Phase 2: Read-only Dashboard MVP

- `/api/admin/overview`
- `/api/admin/workspaces`
- `/api/admin/users`
- `/admin` 前端只读页面

### Phase 3: Registration Allowlist

- 数据表
- allowlist CRUD API
- 注册链路接入 DB allowlist
- allowlist 前端页面

### Phase 4: Traffic / Infra Metrics

- 若已有 Prometheus / Grafana：后台放链接或 iframe。
- 若没有：先从 nginx/app logs 做日级统计，不直接把日志明细写进业务库。

## 15. 需要向老板确认的问题

1. 活跃 agent 口径是：
   - 过去 N 小时发过消息？
   - 当前 online / working？
   - 还是被用户创建但未删除？
2. 管理后台访问者是否只允许 `users.is_admin=true` 的系统管理员？
3. MVP 是否需要跨 organization 统计？还是只看整个 deployment？
4. 是否需要在后台展示用户 email 明文？如果以后有外部用户，是否需要脱敏？
5. 是否需要导出 CSV？MVP 建议不做，除非老板明确需要。

## 16. 当前理解

我的理解是：老板要的不是“申请表”，也不是复杂权限后台，而是一个能快速支撑运营判断的 deployment-level admin dashboard。第一版应先做只读统计和注册白名单管理，指标口径先简单、稳定、可解释：

- 访问量 / 使用量先按 product usage 看，不做 HTTP PV/UV
- 活跃用户按“最近登录过或发过消息”算
- 白名单是注册邮箱白名单，支持精确邮箱和 `@domain.com`
- 管理后台仅对 system admin 开放，可展示用户 email 明文