# 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:` | 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>`），37 tests 全部通过，TypeScript 零错误。Admin Next.js 前端全部完成。