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
313 lines
14 KiB
Markdown
313 lines
14 KiB
Markdown
# Admin 后台管理系统 — 规划文档
|
||
|
||
> **最后更新**: 2026-04-19 (v26) — ROADMAP.md Rust依赖表更新与 PLAN.md 一致；剩余仅平台用户SSO/SAML(Rust) + 多租户(架构)；41 tests 通过
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
### 定位
|
||
|
||
独立部署的 Next.js 16 Admin 后台管理系统，供平台管理员使用。
|
||
**与主应用完全独立** — 拥有独立的认证系统、RBAC 数据库表、Redis session 命名空间。
|
||
|
||
### 技术栈
|
||
|
||
- **Framework**: Next.js 16 (App Router, TypeScript)
|
||
- **UI**: React 19 + Tailwind CSS + 纯 CSS (黑白极简风格 + dark mode)
|
||
- **数据库**: PostgreSQL (复用主应用数据库，独立 `admin_*` 表)
|
||
- **缓存**: Redis Cluster (独立 `admin:session:*` 前缀)
|
||
- **包管理**: bun
|
||
|
||
### 架构特点
|
||
|
||
- **独立 Admin 用户体系** ≠ 平台用户
|
||
- **Session-only** 认证（无 JWT）
|
||
- **RBAC**: 完整 User / Role / Permission 模型
|
||
- **审计日志**: 所有操作自动记录
|
||
- **Redis 集群支持**: SCAN 枚举（无 KEYS）
|
||
|
||
---
|
||
|
||
## 2. 目录结构
|
||
|
||
```
|
||
C:\工作\code\admin\
|
||
├── src/
|
||
│ ├── app/
|
||
│ │ ├── layout.tsx # 根布局
|
||
│ │ ├── page.tsx # 重定向到 /login
|
||
│ │ ├── login/page.tsx # 登录页
|
||
│ │ ├── dashboard/page.tsx # 仪表盘（平台统计）
|
||
│ │ ├── admin/
|
||
│ │ │ ├── layout.tsx # Admin 布局（侧边栏 + 权限守卫）
|
||
│ │ │ ├── users/page.tsx # Admin 用户管理
|
||
│ │ │ ├── users/[id]/page.tsx # Admin 用户详情
|
||
│ │ │ ├── roles/page.tsx # 角色管理
|
||
│ │ │ ├── permissions/page.tsx # 权限管理
|
||
│ │ │ ├── logs/page.tsx # 审计日志
|
||
│ │ │ ├── sessions/page.tsx # 在线用户管理
|
||
│ │ │ ├── api-tokens/page.tsx # API Token 管理
|
||
│ │ │ ├── workspaces/page.tsx # Workspace 列表
|
||
│ │ │ ├── workspaces/[id]/page.tsx # Workspace 详情
|
||
│ │ │ ├── projects/page.tsx # 项目列表
|
||
│ │ │ ├── projects/[id]/page.tsx # 项目详情
|
||
│ │ │ ├── rooms/page.tsx # 房间列表
|
||
│ │ │ ├── rooms/[id]/page.tsx # 房间消息
|
||
│ │ │ ├── repos/page.tsx # 仓库列表
|
||
│ │ │ └── ai/page.tsx # AI 模型管理
|
||
│ │ ├── platform/
|
||
│ │ │ ├── audit/page.tsx # 平台审计日志页面
|
||
│ │ │ ├── users/page.tsx # 平台用户（只读）
|
||
│ │ │ └── sessions/page.tsx # 平台用户会话管理
|
||
│ │ └── api/
|
||
│ │ ├── auth/login/route.ts # 登录
|
||
│ │ ├── auth/logout/route.ts # 登出
|
||
│ │ ├── auth/me/route.ts # 当前会话
|
||
│ │ ├── auth/oidc/... # OIDC 登录
|
||
│ │ ├── users/route.ts # Admin 用户 CRUD
|
||
│ │ ├── users/[id]/route.ts # Admin 用户详情/编辑
|
||
│ │ ├── roles/route.ts # 角色 CRUD
|
||
│ │ ├── permissions/route.ts # 权限 CRUD
|
||
│ │ ├── logs/route.ts # 审计日志查询
|
||
│ │ ├── sessions/route.ts # 在线用户管理
|
||
│ │ ├── platform/stats/route.ts # 平台统计
|
||
│ │ ├── platform/sessions/route.ts # 平台会话管理
|
||
│ │ ├── platform/users/route.ts # 平台用户列表
|
||
│ │ ├── platform/workspaces/route.ts # Workspace 列表
|
||
│ │ ├── platform/workspaces/[id]/route.ts # Workspace 详情
|
||
│ │ ├── admin/projects/route.ts # 项目列表
|
||
│ │ ├── admin/projects/[id]/route.ts # 项目详情
|
||
│ │ ├── platform/rooms/route.ts # 房间列表
|
||
│ │ ├── platform/rooms/[id]/messages/route.ts # 房间消息
|
||
│ │ ├── platform/rooms/[id]/messages/[msgId]/route.ts # 撤回消息
|
||
│ │ ├── platform/workspaces/[id]/alert-config/route.ts # 告警配置 CRUD
|
||
│ │ ├── platform/repos/route.ts # 仓库列表
|
||
│ │ ├── platform/activity-stats/route.ts # DAU/MAU 统计
|
||
│ │ ├── api-tokens/route.ts # API Token CRUD
|
||
│ │ ├── api-tokens/[id]/route.ts # API Token 删除
|
||
│ │ ├── platform/audit-logs/route.ts # 平台审计日志
|
||
│ │ └── platform/ai/route.ts # AI Provider/Model/定价
|
||
│ ├── lib/
|
||
│ │ ├── env.ts # 环境变量（所有配置）
|
||
│ │ ├── db.ts # PostgreSQL 连接池
|
||
│ │ ├── redis.ts # Redis 客户端（支持集群）
|
||
│ │ ├── auth.ts # 认证逻辑（登录/OIDC/Session）
|
||
│ │ ├── rbac.ts # RBAC CRUD（User/Role/Permission）
|
||
│ │ ├── log.ts # 审计日志
|
||
│ │ ├── api-token.ts # API Token 管理
|
||
│ │ └── rbac-middleware.ts # RBAC 中间件（旧，已合并）
|
||
│ ├── middleware.ts # Next.js 中间件（路由保护 + Bearer Token + API RBAC）
|
||
│ └── types/
|
||
│ └── ioredis.d.ts # ioredis 类型声明
|
||
├── .env.local # 实际配置
|
||
├── .env.local.example # 配置示例
|
||
├── package.json
|
||
├── tsconfig.json
|
||
├── next.config.ts
|
||
├── PLAN.md
|
||
└── ROADMAP.md # 功能演进路线（基于 libs/ 代码库分析）
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 功能清单
|
||
|
||
### ✅ 已完成
|
||
|
||
#### 认证模块
|
||
|
||
- [x] 登录页（账号密码）
|
||
- [x] OIDC 登录（环境变量配置，完整 OIDC/OAuth2 流程 + JWT 验证 + 用户自动注册）
|
||
- [x] 超级管理员（环境变量配置）
|
||
- [x] Session 管理（Redis，TTL 可配置）
|
||
- [x] 登出
|
||
|
||
#### 平台概览
|
||
|
||
- [x] Dashboard 统计（用户/Workspace/项目/聊天室总数）
|
||
- [x] 近期注册用户列表
|
||
- [x] 近期 Workspace 列表
|
||
- [x] 近期项目列表
|
||
- [x] Workspace 计划分布统计
|
||
|
||
#### Admin 管理
|
||
|
||
- [x] Admin 用户 CRUD（分页/搜索）
|
||
- [x] Admin 用户详情页（角色编辑/密码重置/启用禁用）
|
||
- [x] 角色 CRUD + 权限分配
|
||
- [x] 权限 CRUD
|
||
- [x] 审计日志（分页/筛选/详情弹窗）
|
||
|
||
#### 在线用户管理
|
||
|
||
- [x] Redis SCAN 枚举会话（`admin:session:*`）
|
||
- [x] 按用户分组显示
|
||
- [x] 单会话下线
|
||
- [x] 用户全部下线
|
||
- [x] 显示登录时间 / IP / User Agent
|
||
- [x] 平台用户会话管理（`session:user_uid:*`）
|
||
- [x] 平台会话下线（单会话/全部下线）
|
||
|
||
#### 平台数据（只读）
|
||
|
||
- [x] 平台用户列表（分页/搜索）
|
||
- [x] Workspace 列表（分页/搜索/计划筛选）
|
||
- [x] Workspace 详情（成员/项目/账单历史）
|
||
- [x] Workspace 充值（弹窗表单，直写 DB，含事务保护）
|
||
- [x] Workspace 告警配置（余额不足/月度配额/使用量激增规则配置）
|
||
- [x] 项目列表（分页/搜索/workspace 筛选/可见性筛选）
|
||
- [x] 项目详情（成员/账单历史）
|
||
- [x] 房间列表（分页/搜索/项目筛选/成员数/消息数/最后活跃）
|
||
- [x] 房间消息详情（消息列表/内容预览/撤回操作）
|
||
- [x] 仓库列表（分页/搜索/项目筛选/可见性/协作者数/分支数/AI Review 状态）
|
||
- [x] AI Provider / Model / 版本 / 定价管理（新建/编辑/删除，通过 `POST|PATCH|DELETE /api/admin/ai/providers|models|versions`）
|
||
|
||
#### 批量操作
|
||
|
||
- [x] 平台用户批量启用/禁用
|
||
- [x] Workspace 批量调整计划
|
||
|
||
#### 集成测试
|
||
|
||
- [x] Playwright 测试框架配置（port 3001）
|
||
- [x] 认证模块测试（登录页表单/重定向/无效凭据/API 认证）
|
||
- [x] Admin 用户管理 API 测试（CRUD/分页/搜索）
|
||
- [x] 平台数据 API 测试（统计/用户/Workspace/房间/仓库/活动/审计/会话/项目账单充值）
|
||
- [x] 中间件权限控制测试（未登录 401/无效 Token 401）
|
||
|
||
#### 审计日志
|
||
|
||
- [x] 审计日志列表（分页/筛选/详情弹窗）
|
||
- [x] 审计日志 CSV 导出（携带当前筛选条件）
|
||
- [x] Admin API Token 管理（创建/删除，Bearer Token 认证）
|
||
- [x] 平台审计日志（user_activity_log + project_audit_log 合并查询）
|
||
|
||
#### RBAC
|
||
|
||
- [x] 中间件级别 API 权限控制
|
||
- [x] 前端布局级路由保护
|
||
- [x] 16 种默认权限（user:*, role:*, permission:*, log:*, session:*, platform:*）
|
||
- [x] 超级管理员（`*` 权限）
|
||
|
||
---
|
||
|
||
## 4. 数据库设计
|
||
|
||
### Admin 表（自主管理）
|
||
|
||
| 表名 | 说明 |
|
||
|-------------------------|----------------|
|
||
| `admin_user` | 管理员用户 |
|
||
| `admin_role` | 角色 |
|
||
| `admin_permission` | 权限（code-based） |
|
||
| `admin_user_role` | 用户-角色关联 |
|
||
| `admin_role_permission` | 角色-权限关联 |
|
||
| `admin_audit_log` | 审计日志 |
|
||
|
||
### 平台表（只读查询）
|
||
|
||
> **Schema 注意事项**：所有主键均为 UUID（`user.uid`、`workspace.id`、`project.id` 等），不能用整数自增 ID。
|
||
|
||
| 表名 | 用途 | 关键列说明 |
|
||
|-----------------------------|-----------------|-----------|
|
||
| `user` | 平台用户列表 | PK=`uid` |
|
||
| `user_password` | 用户密码（is_active）| FK=`user` → `user.uid` |
|
||
| `workspace` | Workspace 列表/详情 | PK=`id`, `slug`, `deleted_at` |
|
||
| `workspace_membership` | Workspace 成员 | FK=`workspace_id`, `user_id` (UUID) |
|
||
| `workspace_billing` | Workspace 余额 | FK=`workspace_id` |
|
||
| `workspace_billing_history` | 账单历史 | FK=`workspace_id`, `user`; `extra` (jsonb) 为描述字段 |
|
||
| `project_billing_history` | 项目账单历史 | FK=`project`, `user`; `extra` (jsonb) 为描述字段 |
|
||
| `project` | 项目列表 | PK=`id`, 无 `slug`/`deleted_at` |
|
||
| `project_members` | 项目成员 | FK=`project_uuid`, `user_uuid` |
|
||
| `project_billing` | 项目余额 | FK=`project_uuid` |
|
||
| `project_billing_history` | 项目账单历史 | FK=`project`, `user` |
|
||
| `room` | 聊天室 | FK=`project` |
|
||
| `room_member` | 聊天室成员 | FK=`room`, `user` |
|
||
| `room_message` | 聊天室消息 | FK=`room`, `sender_id` (UUID) |
|
||
| `repo` | 仓库 | FK=`project` |
|
||
| `repo_collaborator` | 仓库协作者 | FK=`repo` |
|
||
| `ai_model_provider` | AI Provider | 列：`website`, `status` |
|
||
| `ai_model` | AI 模型 | 无 `model_id`/`enabled` |
|
||
| `ai_model_version` | AI 模型版本 | FK=`model_id` → `ai_model.id` |
|
||
| `ai_model_pricing` | AI 定价 | FK=`model_version_id` |
|
||
|
||
---
|
||
|
||
## 5. Redis 设计
|
||
|
||
| Key Pattern | 用途 | TTL |
|
||
|------------------------|---------------|--------|
|
||
| `admin:session:<uuid>` | Admin Session | 7 days |
|
||
|
||
**Session 结构**（兼容 Rust session 格式）：
|
||
|
||
```json
|
||
{
|
||
"v": 1,
|
||
"state": {
|
||
"session:user_uid": -1,
|
||
"session:username": "admin",
|
||
"session:roles": [
|
||
"super_admin"
|
||
],
|
||
"session:permissions": [
|
||
"*"
|
||
],
|
||
...
|
||
}
|
||
}
|
||
```
|
||
|
||
**约束**：
|
||
|
||
- `admin:session:*` 前缀（与业务 `session:user_uid:*` 隔离）
|
||
- SCAN 枚举（禁止 KEYS）
|
||
- Pipeline 批量读取
|
||
|
||
---
|
||
|
||
## 6. 环境变量
|
||
|
||
详见 `.env.local.example`。
|
||
|
||
关键变量：
|
||
|
||
- `DATABASE_URL` — PostgreSQL 连接
|
||
- `REDIS_CLUSTER_URLS` — Redis 集群节点（逗号分隔）
|
||
- `ADMIN_SUPER_USERNAME` / `ADMIN_SUPER_PASSWORD` — 超级管理员
|
||
- `OIDC_ENABLED` / `OIDC_*` — OIDC 配置
|
||
|
||
---
|
||
|
||
## 7. 安全模型
|
||
|
||
- **Admin 认证 ≠ 平台认证** — 完全隔离
|
||
- **Redis key 前缀区分** — `admin:session:*` vs `session:user_uid:*`
|
||
- **超级管理员** — 环境变量配置，拥有 `*` 权限
|
||
- **RBAC 强制** — 中间件层 401/403，返回头 `x-admin-*`
|
||
- **审计日志** — 所有写操作自动记录
|
||
|
||
---
|
||
|
||
## 8. 待完成（未来迭代）
|
||
|
||
详细路线图见 `ROADMAP.md`。
|
||
|
||
- [ ] 平台用户 SSO / SAML（Rust 主应用 OIDC/SAML 中间件，LDAP 集成）
|
||
- [ ] 多租户隔离架构（独立部署 Admin + 配置同步）
|
||
|
||
> **v25 更新 (2026-04-19)**：Playwright 测试补充：项目账单 GET/POST API 测试；41 tests 通过。
|
||
|
||
> **v24 更新 (2026-04-19)**：Admin 项目级账单充值完成：新增 `POST /api/admin/projects/[id]/billing`（Next.js 直连 DB + 事务保护），项目详情页新增充值按钮和弹窗表单；ROADMAP.md P1 项目级账单管理 ✅ 完成。
|
||
|
||
> **v23 更新 (2026-04-19)**：Admin AI Model CRUD 完成：`libs/api/admin/ai_models.rs` 新增 Provider/Model/版本/定价的创建/编辑/删除 Admin API；`src/app/admin/ai/page.tsx` 新增 CRUD 弹窗 UI；Next.js API 路由 `src/app/api/admin/ai/providers|models|versions/pricing/[id]/route.ts`；`/api/platform/ai` 路由新增版本查询。
|
||
|
||
> **v22 更新 (2026-04-19)**：Admin OIDC SSO 完成：`src/lib/auth.ts` 完整 OIDC/OAuth2 流程（`jose` JWT 验证、JWKS 动态公钥获取、用户自动注册/查找）；ROADMAP.md 更新：Admin OIDC SSO ✅，平台用户 SSO/SAML 待完成（Rust 后端），多租户待完成。
|
||
|
||
> **v21 更新 (2026-04-19)**：告警触发 Rust 后端完成：`libs/service/workspace/alert.rs`（每 30 分钟检查所有 Workspace）、`libs/api/admin/alerts.rs::POST /api/admin/alerts/check`、`workspace_alert_config` SeaORM 模型、后台任务随 `apps/app/src/main.rs` 启动；Admin 前端新增"立即检查告警"按钮；39 tests 通过。
|
||
|
||
> **v20 更新 (2026-04-19)**：新增 Rust Admin API（`libs/api/admin/` 模块）：`POST /api/admin/ai/sync`（AI 模型同步）和 `POST /api/admin/workspaces/{slug}/add-credit`（充值）；Admin 前端新增"同步 OpenRouter 模型"按钮和 `src/app/api/platform/ai/sync/route.ts`；环境变量 `RUST_BACKEND_URL` + `ADMIN_API_SHARED_KEY`；38 tests 通过。
|
||
|
||
> **v19 更新 (2026-04-19)**：TypeScript 类型错误修复（Playwright test `ctx` 类型注解 `Awaited<ReturnType<typeof request.newContext>>`），37 tests 全部通过，TypeScript 零错误。Admin Next.js 前端全部完成。
|