# 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 前端全部完成。
