# Admin Console — Enterprise Department-Scoped Management

**Date**: 2026-06-21
**Status**: Draft (revised 2026-06-21 — SaaS multi-tenant → enterprise department-scoped)
**Branch**: `feat/admin-console`
**Author**: brainstorm session

## Outcome

为 Fischer AgentKit 构建统一的企业管理端，采用"嵌入主应用 `/admin` 路由组 + 架构预留拆分能力"方案。Web UI 和 CLI 双通道共享同一套 service 层。核心模型是**单企业部署 + 部门级权限隔离 + 能力按部门绑定**：人事部有人事 skill + 人事系统 DB 权限，研发部有编码 skill，部门间资源隔离、用户可多部门（权限并集）。MVP 覆盖 5 个管理领域：部门与用户、LLM 配置、Skill 与 KB、用量仪表盘与配额。

## Background

当前 AgentKit 没有统一管理端：
- 后端 admin 端点只有 4 个（session 管理），无 user CRUD / LLM 配置 / 用量分用户
- 前端只有 1 个 admin 页面（`/admin/users`，仅会话管理）
- LLM 配置只在 `agentkit.yaml`，运行时不可改
- KB/Skill 有 CRUD API 但不是 admin-only，无部门隔离
- 权限模型有 3 级（member/operator/admin）但实际使用率极低
- 管理工作流是"零散脚本不成体系"

## Actual Usage Scenario (revised)

单企业部署一套 AgentKit，按部门/职能划分权限：
- 人事部：拥有人事专用 skill + 访问人事系统数据库的权限，无编码能力
- 研发部：拥有编码 skill + 代码仓库访问权限
- 财务部：拥有财务分析 skill + 财务系统访问权限
- 个人用户属于一个或多个部门（权限并集），如 CFO 可兼管财务和运营
- 管理员按部门分配能力，用户继承所属部门的能力

**这不是 SaaS 多租户**——不需要租户计费、跨租户数据隔离、租户 CRUD。核心是**部门（能力组）+ 用户多部门归属 + 能力按部门绑定**。

## Primary Actors

- **超级管理员**（企业 IT）：管理所有部门、全局 LLM 配置、跨部门用量监控、用户管理
- **部门管理员**（部门负责人）：管理本部门成员、本部门 Skill/KB、本部门用量
- **普通用户**：属于一个或多个部门，继承部门能力，受部门配额约束
- **运维自动化**：通过 CLI `agentkit admin <domain> <action>` 执行管理操作，与 Web UI 等价

## Scope

### MVP（第一期）

1. **部门与用户管理**
   - 部门 CRUD：创建、列表、编辑、禁用/启用、删除（人事/研发/财务等）
   - 部门能力绑定：每个部门可绑定专属 skill、KB、工具权限、LLM 配额
   - 用户 CRUD：创建、列表、编辑、禁用/启用、删除
   - 用户多部门归属：一个用户可属于多个部门（`user_departments` 多对多表），权限取并集
   - 角色管理：超级管理员 / 部门管理员 / 普通用户
   - 密码重置：管理员重置任意用户密码
   - 当前已有的会话管理（revoke/list）保留并集成
   - 数据隔离：所有资源表（skills、kb_documents、llm_usage 等）加 `department_id` 列，用户访问时只能看到所属部门的资源（多部门取并集）

2. **LLM 配置管理**
   - Provider/Model/API Key CRUD：运行时增删改，不重启服务
   - Fallback 链配置：可视化编辑 provider fallback 顺序
   - 按部门配额：每部门可配置独立的 provider/model 白名单和 token 上限
   - 成本上限：按部门/用户设置日/月成本上限，超限硬拒绝（返回 429）
   - 配置从 `agentkit.yaml` 迁移到数据库，支持运行时热重载
   - 向后兼容：首次启动时自动从 `agentkit.yaml` 导入现有配置

3. **Skill 与 KB 管理**
   - Skill 启停/编辑/导入：admin 可启用/禁用任意 skill，编辑 skill 配置，YAML 导入
   - Skill 按部门绑定：人事 skill 只对人事部可见，编码 skill 只对研发部可见
   - KB 文档 CRUD/同步/重建索引：admin 可管理所有 KB 文档
   - KB 按部门隔离：每部门有独立的 KB 资源池

4. **用量仪表盘 + 配额**
   - 按部门/用户/时间维度查看 LLM token 用量、成本、调用次数
   - 可视化图表：时间序列、按 provider/model 分桶、按用户排行
   - 报表导出：CSV/JSON
   - 配额上限：按部门/用户设置 token/成本上限，超限硬拒绝（429）
   - 告警：配额达到 80%/100% 时触发（MVP 只做日志告警）

### 产品形态

- **Web UI**：`/admin/*` 路由组，独立 `AdminLayout` + 左侧导航 + 5 个管理页面
- **CLI**：`agentkit admin <domain> <action>` 镜像所有 Web UI 操作
- **后端**：独立 `admin_router` APIRouter 实例，未来可拆分到独立 FastAPI 应用
- **认证**：共享现有 JWT 认证，admin 端点要求 admin 角色

### 架构决策

- **部门隔离**：共享数据库 + `department_id` 列。`DepartmentContextMiddleware` 在请求级别注入用户所属部门列表，所有 repository 层强制按 `department_id IN (...)` 过滤（多部门取并集）。
- **配置存储**：LLM 配置从 `agentkit.yaml` 迁移到数据库（`llm_providers` / `llm_models` / `llm_api_keys` 表），支持运行时热重载。首次启动自动从 YAML 导入。
- **CLI/Web 一致性**：CLI 和 Web UI 调用同一套 service 层，避免双份业务逻辑。
- **预留拆分**：`admin_router` 是独立 `APIRouter` 实例，`AdminLayout` 是独立路由树。未来需要独立部署时，把 `admin_router` 挂到独立 FastAPI 实例，前端 `AdminLayout` 独立构建即可。

## Success Criteria

- 超级管理员可在 Web UI 或 CLI 完成全部 4 个领域的管理操作，无需手动编辑 YAML 或操作数据库
- 部门隔离通过安全测试：人事部用户无法访问研发部的 skill/KB/用量数据（除非同时属于两个部门）
- LLM 配置可在运行时修改并立即生效，无需重启服务
- 用量仪表盘可按部门/用户/时间维度展示，数据延迟 < 1 分钟
- 配额超限时系统返回 429，不会超支
- CLI 与 Web UI 操作结果一致，调用同一 service 层
- 用户多部门归属正确：CFO 兼管财务和运营时，可访问两个部门的所有资源

## Non-Goals

- **SaaS 多租户**（外部多客户、租户计费、跨租户物理隔离）——本场景是单企业部署
- **物理隔离的独立数据库**（部门数据隔离靠 `department_id` 列，不靠物理隔离）
- **计费系统集成**（只做用量采集和配额，不做实际计费/扣款）
- **审计日志**（第二期）
- **SLA 监控**（第二期）
- **独立管理应用部署**（架构预留但不实现，MVP 嵌入主应用）
- **SSO/SAML 集成**（第二期）

## Dependencies / Assumptions

- **假设**：现有 `users` / `auth_sessions` 表可平滑加 `department_id` 列（SQLite ALTER TABLE 支持 ADD COLUMN，NULL 表示未分配部门的全局用户）
- **假设**：LLM 配置从 YAML 迁移到数据库后，`agentkit.yaml` 仍可作为首次导入源，不破坏现有部署
- **依赖**：现有 JWT 认证 + RBAC 权限模型（3 级）可扩展支持部门管理员角色
- **依赖**：现有 `agentkit` CLI 框架（Typer）支持新增 `admin` 命令组
- **风险**：部门隔离 middleware 完整性是关键风险——任何遗漏 `department_id` 过滤的查询都是数据泄露漏洞。通过 repository 层强制 `department_id IN (...)` 参数缓解，但需要安全测试覆盖。
- **风险**：LLM 配置热重载需要处理并发修改冲突（乐观锁或版本号）
- **风险**：用户多部门归属的权限并集计算可能产生意外权限提升（如用户从 A 部门调离但未及时移除归属）

## Open Questions (Resolved)

- ~~租户的粒度是"组织"还是"工作空间"？~~ → **已明确**：单企业部署 + 部门级隔离，不是 SaaS 多租户
- ~~跨租户用户的关系如何建模？~~ → **已明确**：`user_departments` 多对多表，权限取并集
- ~~配额超限时的行为：硬拒绝还是软降级？~~ → **已明确**：硬拒绝（429）

## Delivery Strategy

MVP 范围较大（4 领域），建议按领域分批交付：
1. **批次 1**：部门与用户管理（部门 CRUD + 用户多部门归属 + 隔离 middleware，其他领域依赖）
2. **批次 2**：LLM 配置管理（含 YAML→DB 迁移）
3. **批次 3**：Skill 与 KB 管理（按部门绑定/隔离）
4. **批次 4**：用量仪表盘 + 配额（依赖前 3 批的 department_id 埋点）

每批次独立可交付、可测试、可合并。