ZhenYi/gitdataai
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
208b6ed84e
gitdataai/admin/ROADMAP.md
ZhenYi fb91f5a6c5 feat(admin): add admin panel with billing alerts and model sync 
- 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
2026-04-19 20:48:59 +08:00

343 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
```
Reference in New Issue View Git Blame Copy Permalink