gitdataai/admin/PLAN.md

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. 功能清单

✅ 已完成

认证模块

• 登录页（账号密码）
• OIDC 登录（环境变量配置，完整 OIDC/OAuth2 流程 + JWT 验证 + 用户自动注册）
• 超级管理员（环境变量配置）
• Session 管理（Redis，TTL 可配置）
• 登出

平台概览

• Dashboard 统计（用户/Workspace/项目/聊天室总数）
• 近期注册用户列表
• 近期 Workspace 列表
• 近期项目列表
• Workspace 计划分布统计

Admin 管理

• Admin 用户 CRUD（分页/搜索）
• Admin 用户详情页（角色编辑/密码重置/启用禁用）
• 角色 CRUD + 权限分配
• 权限 CRUD
• 审计日志（分页/筛选/详情弹窗）

在线用户管理

• Redis SCAN 枚举会话（admin:session:*）
• 按用户分组显示
• 单会话下线
• 用户全部下线
• 显示登录时间 / IP / User Agent
• 平台用户会话管理（session:user_uid:*）
• 平台会话下线（单会话/全部下线）

平台数据（只读）

• 平台用户列表（分页/搜索）
• Workspace 列表（分页/搜索/计划筛选）
• Workspace 详情（成员/项目/账单历史）
• Workspace 充值（弹窗表单，直写 DB，含事务保护）
• Workspace 告警配置（余额不足/月度配额/使用量激增规则配置）
• 项目列表（分页/搜索/workspace 筛选/可见性筛选）
• 项目详情（成员/账单历史）
• 房间列表（分页/搜索/项目筛选/成员数/消息数/最后活跃）
• 房间消息详情（消息列表/内容预览/撤回操作）
• 仓库列表（分页/搜索/项目筛选/可见性/协作者数/分支数/AI Review 状态）
• AI Provider / Model / 版本 / 定价管理（新建/编辑/删除，通过 POST|PATCH|DELETE /api/admin/ai/providers|models|versions）

批量操作

• 平台用户批量启用/禁用
• Workspace 批量调整计划

集成测试

• Playwright 测试框架配置（port 3001）
• 认证模块测试（登录页表单/重定向/无效凭据/API 认证）
• Admin 用户管理 API 测试（CRUD/分页/搜索）
• 平台数据 API 测试（统计/用户/Workspace/房间/仓库/活动/审计/会话/项目账单充值）
• 中间件权限控制测试（未登录 401/无效 Token 401）

审计日志

• 审计日志列表（分页/筛选/详情弹窗）
• 审计日志 CSV 导出（携带当前筛选条件）
• Admin API Token 管理（创建/删除，Bearer Token 认证）
• 平台审计日志（user_activity_log + project_audit_log 合并查询）

RBAC

• 中间件级别 API 权限控制
• 前端布局级路由保护
• 16 种默认权限（user:, role:, permission:, log:, session:, platform:）
• 超级管理员（* 权限）

---

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 格式）：

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