fb91f5a6c5
- Add libs/api/admin with admin API endpoints: sync models, workspace credit, billing alert check - Add workspace_alert_config model and alert service - Add Session::no_op() for background tasks without user context - Add admin/ Next.js admin panel (AI models, billing, workspaces, audit) - Start billing alert background task every 30 minutes
343 lines
16 KiB
Markdown
343 lines
16 KiB
Markdown
# 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
|
||
```
|