# Admin 后台管理系统 — ROADMAP

> **最后更新**: 2026-04-19 (v26) — ROADMAP.md Rust依赖表更新：平台会话管理 ✅、审计增强 ✅ 与 PLAN.md 一致；剩余仅平台用户SSO/SAML(Rust) + 多租户(架构)；41 tests 通过
>
> 本文档基于 `C:\工作\code\libs` 代码库分析，规划 Admin 系统的演进路线。

---

## 1. 技术背景

### 1.1 双应用架构

```
┌─────────────────────────────────────────────────────────┐
│                    PostgreSQL (同一数据库)                │
└─────────────────────────────────────────────────────────┘
         │                                    │
   ┌─────┴──────┐                    ┌──────┴──────┐
   │  Rust 主应用  │                    │ Next.js Admin │
   │  (libs/api) │                    │  (自包含)     │
   │  Actix-web │                    │  Route API    │
   │  libs/svc  │                    │  libs/rbac    │
   └────────────┘                    └──────────────┘
```

### 1.2 libs/ 代码库结构

| Crate | 职责 | 与 Admin 的关联 |
|-------|------|----------------|
| `libs/api` | Actix-web HTTP 路由层 | Admin 可通过 `/api/agents/*` 等接口间接调用 |
| `libs/service` | 业务逻辑层 | Workspace 计费/AI 模型同步等核心逻辑所在 |
| `libs/models` | SeaORM 实体定义 | Admin DB 查询直接引用相同表结构 |
| `libs/session` | 会话管理（Redis） | 主应用使用 `session:user_uid:*`，Admin 使用 `admin:session:*` |
| `libs/db` | 数据库连接池 | Admin 直接复用 `DATABASE_URL` |
| `libs/agent` | AI Agent（聊天/Review/Summary/ReAct） | Admin 可触发 `sync_upstream_models()` |
| `libs/queue` | 异步队列（Redis PubSub） | Email 队列等 |
| `libs/email` | SMTP 发送 | 审计通知等 |

### 1.3 关键 API 路由（主应用 Rust）

**Workspace 计费**（`libs/api/workspace/billing.rs`）:
- `GET /api/workspaces/{slug}/billing` — 当前余额/配额
- `GET /api/workspaces/{slug}/billing/history` — 账单历史
- `POST /api/workspaces/{slug}/billing/add-credit` — 充值（需要 workspace 成员权限）

**AI 模型管理**（`libs/api/agent/`）:
- `GET/POST /api/agents/providers` — Provider CRUD
- `GET/POST /api/agents/models` — Model CRUD
- `GET/POST /api/agents/versions` — 版本管理
- `POST /api/agents/versions/{id}/pricing` — 定价设置
- `POST /api/agents/models/{id}/sync` — 同步上游模型
- `POST /api/agents/code-review/{ns}/{repo}` — 触发 Code Review
- `POST /api/agents/pr-description/{ns}/{repo}` — 触发 PR Summary

**Project**（`libs/api/project/`）:
- `GET/POST /api/projects/{namespace}/{name}` — Project CRUD
- `GET /api/projects/{namespace}/{name}/billing` — 项目级计费

**其他**:
- `libs/service/agent/sync.rs` — `sync_upstream_models()` 从 OpenRouter 同步模型
- `libs/service/agent/billing.rs` — `record_ai_usage()` 记录 token 消耗并扣费

---

## 2. 功能路线图

### Phase 1: 补全当前功能（短期）

> 基于现有 libs/api 直接可调用接口，快速实现。

#### [x] Workspace 计费操作（充值/调整配额）✅
**现状**: 已实现（直接写 DB）
- `POST /api/platform/workspaces/{id}/add-credit` — 充值 API（INSERT billing_history + UPDATE billing.balance，事务保护）
- `/admin/workspaces/[id]/page.tsx` — 充值弹窗（输入金额+备注，充值后自动刷新）
- **说明**: 直接写 DB，绕过 Rust service 层（事务内保证原子性）

#### [x] AI 模型同步触发器 ✅
**现状**: 已完成
- `libs/api/admin/sync.rs` — `POST /api/admin/ai/sync`（`x-admin-api-key` 认证）
- `libs/service/agent/sync.rs::sync_upstream_models` — 已直接调用
- `src/app/api/platform/ai/sync/route.ts` — Admin 前端 API 路由（调用 Rust）
- `src/app/admin/ai/page.tsx` — "同步 OpenRouter 模型"按钮 + 结果反馈
- 环境变量：`RUST_BACKEND_URL` + `ADMIN_API_SHARED_KEY`

---

### Phase 2: 平台级管控能力（中期）

#### [x] 仓库（Repository）管理视图 ✅
**现状**: 已实现
- `/admin/repos/page.tsx` — 仓库列表（分页/搜索/仓库名/项目/可见性/协作者数/分支数/AI Review 状态）
- `GET /api/platform/repos` — 仓库列表 API

#### [x] 房间（Room）管理视图 ✅
**现状**: 已实现
- `/admin/rooms/page.tsx` — 房间列表（按项目筛选/搜索/成员数/消息数/最后活跃）
- `/admin/rooms/[id]/page.tsx` — 房间消息详情（消息列表/撤回操作）
- `GET /api/platform/rooms` — 房间列表 API
- `GET /api/platform/rooms/[id]/messages` — 房间消息 API
- `DELETE /api/platform/rooms/[id]/messages/[msgId]` — 撤回消息（admin session 认证）

#### [x] 项目（Project）管理视图 ✅
**现状**: 已实现
- `/admin/projects/page.tsx` — 项目列表（分页/搜索/workspace 筛选/可见性筛选）
- `/admin/projects/[id]/page.tsx` — 项目详情（成员/账单历史）
- `/api/admin/projects/route.ts` — 项目列表 API
- `/api/admin/projects/[id]/route.ts` — 项目详情 API
**现状**: Workspace 下有项目，但 Admin 无项目列表

新增：
- `/admin/projects/page.tsx` — 项目列表（分页/搜索/workspace 筛选）
- `/admin/projects/[id]/page.tsx` — 项目详情（成员/账单/仓库）

#### [x] 平台用户会话管理 ✅
**现状**: 已实现
- `/platform/sessions/page.tsx` — 扫描 `session:user_uid:*` Redis 前缀
- 按用户分组显示（用户名/UID/IP/UserAgent/登录时间）
- 单会话下线 / 用户全部下线
- `/api/platform/sessions/route.ts` — 平台会话 API
- RBAC: `platform:read` (GET) / `platform:manage` (DELETE)

#### [x] 审计日志导出（CSV/Excel） ✅
**现状**: 已实现
- `GET /api/logs?format=csv` — 导出 CSV（含当前筛选条件，最多 10,000 条）
- `/admin/logs/page.tsx` — "导出 CSV" 按钮，自动携带当前筛选参数

#### [x] 批量操作 ✅
**现状**: 已实现
- 平台用户：批量启用/禁用（`PATCH /api/platform/users`，更新 `user_password.is_active`）
- Workspace：批量调整计划（`PATCH /api/platform/workspaces`，UPDATE `workspace.plan`）
- 全选/反选/已选计数 UI

---

### Phase 3: 安全与合规（中期）

#### [x] Admin API 令牌 ✅
**现状**: 已实现
- `src/lib/api-token.ts` — Token 生成（SHA-256 哈希）、验证、创建、删除
- `admin_api_token` 表（id, name, token_hash, token_prefix, permissions, created_by, expires_at, last_used_at, is_active）
- `POST /api/api-tokens` — 创建 Token（返回明文，仅此一次）
- `GET /api/api-tokens` — 列出 Token（不返回 hash）
- `DELETE /api/api-tokens/[id]` — 删除 Token
- `/admin/api-tokens/page.tsx` — Token 管理页面（创建弹窗含权限选择，到期日）
- `middleware.ts` — Bearer Token 认证优先于 Session（`x-admin-auth-type: token` header）
- RBAC: Token 管理页面需要 session（不允许 token 访问自己）

#### [x] 平台级审计日志 ✅
**现状**: 已实现
- `GET /api/platform/audit-logs` — 查询 `user_activity_log` + `project_audit_log`，按时间合并排序
- 支持 `source` 筛选（all/user/project）和 `action` 搜索（ILIKE）
- `/platform/audit/page.tsx` — 平台审计页面（来源标签/操作类型/用户UID/IP）

#### [x] Admin OIDC SSO ✅
**现状**: 已完成（Admin 前端 Next.js）
- `src/lib/auth.ts` — 完整 OIDC/OAuth2 流程实现
- `jose` 库 JWT 验证（JWKS 端点动态获取公钥）
- `buildOidcAuthUrl()` — 构造授权 URL（`openid profile email` scopes）
- `exchangeOidcCode()` — Token 交换 + JWT 验证 + 用户自动创建/查找
- `/api/auth/oidc/authorize` — OIDC 授权重定向
- `/api/auth/oidc/callback` — 授权回调处理
- 审计日志记录 OIDC 登录
- 环境变量：`OIDC_ENABLED` / `OIDC_ISSUER` / `OIDC_CLIENT_ID` / `OIDC_CLIENT_SECRET` / `OIDC_REDIRECT_URI`

#### [ ] 平台用户 SSO / SAML（Rust 后端）
**现状**: 平台用户（Rust 主应用）尚未支持 SSO
- 需要在 Rust Actix-web 中实现 OIDC/SAML 中间件
- 需要用户自动注册/登录流程
- 企业级需求（LDAP / SAML 2.0）

---

### Phase 4: 平台洞察与自动化（长期）

#### [x] 平台使用分析仪表盘 ✅
**现状**: 已实现
- `/dashboard` — 新增聊天室总数统计
- `/dashboard` — Workspace 计划分布（饼图替代文字，数量+百分比）
- `/dashboard` — 近期项目列表
- `GET /api/platform/stats` — 新增 roomCount, planDistribution, recentProjects
- `/dashboard` — DAU 趋势图（近30天 SVG 折线图，MAU/总登录/近24h 统计）
- `GET /api/platform/activity-stats` — DAU/MAU 统计 API

#### [x] 告警与自动化规则 ✅
**现状**: 已完成
- `workspace_alert_config` 模型（`libs/models/workspaces/workspace_alert_config.rs`）
- `libs/service/workspace/alert.rs::check_billing_alerts()` — 核心检查逻辑
- 后台任务 `start_billing_alert_task()` — 每 30 分钟自动检查所有 Workspace
- `POST /api/admin/alerts/check` — Admin API 手动触发检查
- `src/app/api/platform/alerts/check/route.ts` — Admin 前端 API 路由
- Workspace 详情页「告警配置」Tab — "立即检查告警"按钮 + 结果反馈
- 支持三种告警类型：`low_balance`（余额不足）/ `monthly_quota`（配额超标）/ `usage_surge`（用量激增）
- 邮件发送给 Workspace owner/admin，检测用户通知偏好设置
- `apps/app/src/main.rs` — 后台任务随应用启动

#### [ ] 多租户隔离架构
**现状**: 长期目标
- 支持独立部署的 Admin（当前是单实例）
- Admin 配置同步（多集群场景）

---

## 3. 依赖 Rust 主应用的功能

以下功能需要 Rust 后端支持或新增接口：

| 功能 | Rust 依赖 | 优先级 |
|------|---------|--------|
| Workspace 充值 | `libs/api/admin/billing.rs::admin_workspace_add_credit` ✅ 已完成 | P0 ✅ |
| AI 模型同步触发 | `libs/api/admin/sync.rs::admin_sync_models` ✅ 已完成 | P0 ✅ |
| 告警触发逻辑 | `libs/service/workspace/alert.rs` + 后台任务 ✅ 已完成 | P0 ✅ |
| AI 模型 CRUD | `libs/api/admin/ai_models.rs` ✅ Admin CRUD 新建/编辑/删除（Provider/Model/版本/定价） | P1 ✅ |
| 项目级账单管理 | `POST /api/admin/projects/[id]/billing` (Next.js 直连 DB，事务保护) ✅ | P1 ✅ |
| 平台用户会话管理 | `/platform/sessions/page.tsx` + `session:user_uid:*` Redis 扫描 ✅ | P2 ✅ |
| 审计日志增强 | `user_activity_log` + `project_audit_log` 直接查询 ✅ | P2 ✅ |
| 平台用户 SSO/SAML | Rust OIDC/SAML 中间件（企业场景） | P2 |
| Admin API Token | 已实现（Next.js 直连 DB） | P3 ✅ |

---

## 4. 技术债务与改进

### 4.1 Admin ↔ 主应用集成模式

当前问题：Admin 直接查询 DB，绕过 Rust 业务逻辑层。

两种集成方案：

**方案 A: Admin 直接写 DB（现状）**
- 优点：简单，无跨服务依赖
- 缺点：无法复用 service 层逻辑（计费原子性、事务）
- 适用：只读操作、非关键数据

**方案 B: Admin 调用 Rust API（推荐）**
- 优点：复用业务逻辑，数据一致性有保障
- 缺点：需处理跨应用认证
- 适用：计费操作、AI 模型管理等

**建议**：核心写操作（计费）通过 Rust API，查询类操作可直连 DB。

### 4.2 跨应用认证问题

Rust 主应用 API 需要 `session:user_uid` cookie，Admin 无法直接调用。

解决方案：
1. **共享 Session 存储**：Admin 验证后注入 fake session 到 Redis，主应用可读取
2. **Admin 专用 API**：Rust 新增 `/api/admin/*` 路由，验证 `admin_session` cookie
3. **API Token**：Rust API 支持 Bearer Token，Admin 用服务账号 token 调用

### 4.3 数据库 Schema 演进

Admin 表（`admin_*`）与平台表（`workspace`、`user` 等）共存于同一 DB。

建议：
- Admin 表命名统一加前缀 `adm_*`（当前 `admin_*`，兼容）
- 避免跨表事务（admin 写操作不影响平台数据，除非明确）

### 4.4 Redis 命名空间

| Key Pattern | 用途 |
|------------|------|
| `session:user_uid:{uuid}` | 平台用户 Session |
| `admin:session:{uuid}` | Admin Session |
| `user:session:{uuid}` | （别名，同上）|

注意：平台 session key 实际前缀为 `session:user_uid:`，不是 `user:session:`。

---

## 5. 版本计划

| 版本 | 目标 | 主要交付 |
|------|------|---------|
| **v0.1** | MVP（已完成） | 登录/RBAC/审计/在线用户/平台用户/Workspace/AI 模型 |
| **v0.2** | 补全（已完成） | 用户详情页 / Workspace 计费操作 / AI 同步触发 |
| **v0.3** | 平台级管控（已完成） | 项目管理视图 / 批量操作 / 日志导出 |
| **v0.4** | 安全合规（已完成） | API Token ✅ / 平台审计日志 ✅ / SSO/SAML 待完成 |
| **v0.5** | 管控增强（已完成） | 房间管理 ✅ / 仓库管理 ✅ / 告警配置 ✅ (UI + Rust 触发) / 多租户待完成 |
| **v1.0** | 完整版 ✅ Next.js + Rust Admin API 完成 | Playwright 集成测试 ✅ (41 tests) / AI 同步触发器 ✅ / Workspace 充值 ✅ / 告警触发 ✅ / Admin OIDC SSO ✅ / Admin AI Model CRUD ✅ / 项目充值 ✅ / 平台会话管理 ✅ / 审计增强 ✅ / 平台用户SSO/SAML待完成 / 多租户待完成 |

---

## 6. 附录：libs/ 关键文件索引

```
C:\工作\code\libs\
├── api/
│   ├── lib.rs              # 路由注册入口
│   ├── route.rs            # web::ServiceConfig 初始化
│   ├── auth/               # 认证（登录/注册/OIDC）
│   ├── workspace/          # Workspace API
│   │   ├── billing.rs      # 余额/充值/账单历史
│   │   ├── members.rs      # 成员管理
│   │   ├── info.rs         # Workspace 信息
│   │   └── stats.rs        # 统计
│   ├── project/            # Project API
│   │   └── billing.rs      # 项目级计费
│   ├── agent/              # AI 模型/Provider/定价 CRUD
│   │   ├── model.rs        # 模型 CRUD
│   │   ├── provider.rs     # Provider CRUD
│   │   ├── model_pricing.rs # 定价管理
│   │   ├── code_review.rs  # Code Review 触发
│   │   └── pr_summary.rs   # PR Summary 触发
│   ├── room/               # 聊天室 WebSocket API
│   ├── git/                # Git 操作 API
│   ├── issue/              # Issue API
│   ├── pull_request/       # PR API
│   ├── user/               # 用户设置 API
│   └── search/             # 搜索 API
├── service/
│   ├── lib.rs              # AppService 聚合所有 service
│   ├── workspace/
│   │   ├── billing.rs       # workspace_billing_add_credit()
│   │   └── mod.rs
│   ├── project/
│   │   └── billing.rs      # 项目级计费
│   ├── agent/
│   │   ├── billing.rs      # record_ai_usage()
│   │   ├── sync.rs         # sync_upstream_models()
│   │   ├── client.rs       # AI 客户端（重试/熔断）
│   │   ├── tokent.rs       # Token 估算
│   │   └── react/          # ReAct 模式
│   ├── auth/               # 登录/注册/OIDC 逻辑
│   ├── user/               # 用户服务
│   └── room/               # 聊天室服务
├── models/
│   ├── users/              # platform user 实体
│   ├── workspaces/         # workspace/workspace_membership/workspace_billing
│   ├── projects/           # project/project_members/project_billing
│   ├── agents/             # ai_model_provider/model/version/pricing
│   └── rooms/              # room/room_message/room_member
├── session/
│   ├── lib.rs              # SessionMiddleware
│   ├── storage/            # Redis 存储实现
│   └── session.rs          # Session 结构
├── db/
│   ├── database.rs         # AppDatabase (sqlx pool)
│   └── cache.rs            # AppCache (Redis cache)
└── queue/
    ├── lib.rs              # Redis PubSub 队列
    └── email.rs            # Email worker
```