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

16 KiB

Raw Blame History

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 无法直接调用。

解决方案：

共享 Session 存储：Admin 验证后注入 fake session 到 Redis，主应用可读取
Admin 专用 API：Rust 新增 /api/admin/* 路由，验证 admin_session cookie
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

16 KiB Raw Blame History Unescape Escape

Admin 后台管理系统 — ROADMAP

1. 技术背景

1.1 双应用架构

1.2 libs/ 代码库结构

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

2. 功能路线图

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

[x] Workspace 计费操作（充值/调整配额）✅

[x] AI 模型同步触发器 ✅

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

[x] 仓库（Repository）管理视图 ✅

[x] 房间（Room）管理视图 ✅

[x] 项目（Project）管理视图 ✅

[x] 平台用户会话管理 ✅

[x] 审计日志导出（CSV/Excel） ✅

[x] 批量操作 ✅

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

[x] Admin API 令牌 ✅

[x] 平台级审计日志 ✅

[x] Admin OIDC SSO ✅

[ ] 平台用户 SSO / SAML（Rust 后端）

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

[x] 平台使用分析仪表盘 ✅

[x] 告警与自动化规则 ✅

[ ] 多租户隔离架构

3. 依赖 Rust 主应用的功能

4. 技术债务与改进

4.1 Admin ↔ 主应用集成模式

4.2 跨应用认证问题

4.3 数据库 Schema 演进

4.4 Redis 命名空间

5. 版本计划

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

16 KiB

Raw Blame History