feat(admin): Admin V2 — Ant Design Pro 纯 SPA 重写
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled

Next.js SSR/hydration 与 SWR fetch-on-mount 存在根本冲突:
hydration 卸载组件时 abort 的请求仍占用后端 DB 连接,
retry 循环耗尽 PostgreSQL 连接池导致后端完全卡死。

admin-v2 使用 Vite + React + antd 纯 SPA 彻底消除此问题:
- 12 页面全部完成(Login, Dashboard, Accounts, Providers, Models,
  API Keys, Usage, Relay, Config, Prompts, Logs, Agent Templates)
- ProTable + ProForm + ProLayout 统一 UI 模式
- TanStack Query + Axios + Zustand 数据层
- JWT 自动刷新 + 401 重试机制
- 全部 18 网络请求 200 OK,零 ERR_ABORTED

同时更新 troubleshooting 第 13 节和 SaaS 平台文档。
This commit is contained in:
iven
2026-03-30 09:35:59 +08:00
parent 13c0b18bbc
commit a7d33d0207
52 changed files with 8102 additions and 118 deletions

View File

@@ -1,6 +1,6 @@
# ZCLAW SaaS 平台 — 总览
> 最后更新: 2026-03-29 | 实施状态: Phase 1-4 全部完成 + 架构重构完成9 个后端模块 + Worker + Scheduler + Admin 管理后台 + 桌面端完整集成
> 最后更新: 2026-03-30 | 实施状态: Phase 1-4 全部完成 + 架构重构完成9 个后端模块 + Worker + Scheduler + Admin V2 (Ant Design Pro) + 桌面端完整集成
## 架构概述
@@ -13,7 +13,7 @@ ZCLAW SaaS 平台为桌面端用户提供云端能力包括模型中转Key
├── Mode B: Gateway WebSocket (本地中转)
└── Mode C: SaaS Cloud ──→ Rust/Axum 后端 (端口 8080) ──→ 上游 LLM Provider
├── Admin Web (Next.js 管理后台)
├── Admin V2 (Ant Design Pro 纯 SPA)
└── PostgreSQL (数据持久化)
```
@@ -22,7 +22,7 @@ ZCLAW SaaS 平台为桌面端用户提供云端能力包括模型中转Key
| 层级 | 技术 | 说明 |
|------|------|------|
| 后端 | Rust + Axum + sqlx + PostgreSQL | JWT + API Token 双认证RBAC 权限 |
| Admin | Next.js 14 + shadcn/ui + Tailwind | 暗色 OLED 主题20+ 页面 |
| Admin V2 | Vite 6 + React 19 + antd v5 + ProComponents | 纯 SPA替代 Next.js消除 SSR/hydration 问题) |
| 桌面端 | React 18 + Zustand + TypeScript | saas-client.ts 30+ API 方法 |
| 安全 | Argon2id + TOTP 2FA (AES-256-GCM) + RBAC | 速率限制 + 操作审计 + SSRF 防护 |
@@ -219,20 +219,30 @@ ZCLAW SaaS 平台为桌面端用户提供云端能力包括模型中转Key
| `src/scheduler.rs` | 声明式 Scheduler (TOML 定时任务配置 + DB 清理任务) |
| `migrations/` | SQL 迁移文件 (Schema v6, TIMESTAMPTZ) |
### Admin 管理后台 (admin/)
### Admin 管理后台 (admin-v2/)
> **迁移说明**: 原有 `admin/`Next.js 14因 SSR/hydration 与 SWR 的根本冲突导致后端连接池耗尽,
> 已用 `admin-v2/`Vite + React + Ant Design Pro 纯 SPA完全替代。
> 详见 [故障排查 13 节](../../knowledge-base/troubleshooting.md)
| 文件 | 职责 |
|------|------|
| `src/lib/api-client.ts` | 类型化 HTTP 客户端 (自动 Token 刷新 + 重试) |
| `src/lib/types.ts` | 全部 TypeScript 类型定义 |
| `src/lib/auth.ts` | JWT Token 管理 (localStorage) |
| `src/app/(dashboard)/layout.tsx` | Dashboard 布局 + 导航 |
| `src/app/(dashboard)/providers/page.tsx` | Provider 管理 |
| `src/app/(dashboard)/config/page.tsx` | 配置管理 |
| `src/app/(dashboard)/usage/page.tsx` | 用量统计 |
| `src/app/(dashboard)/prompts/` | Prompt 模板管理 |
| `src/app/(dashboard)/agent-templates/` | Agent 模板管理 |
| `src/app/login/page.tsx` | 登录页 |
| `src/services/request.ts` | Axios 实例 + JWT 拦截器 + 401 自动刷新 |
| `src/services/auth.ts` | 认证 API (login/refresh/me) |
| `src/stores/authStore.ts` | Zustand: token + account + permissions |
| `src/types/index.ts` | 全部 TypeScript 类型定义 |
| `src/layouts/AdminLayout.tsx` | ProLayout 侧边栏 + 用户信息 |
| `src/pages/Dashboard.tsx` | 仪表盘 (统计卡片 + 趋势图 + 操作日志) |
| `src/pages/Accounts.tsx` | 账号管理 (CRUD + 角色筛选) |
| `src/pages/Providers.tsx` | 服务商管理 + Key Pool 子表 |
| `src/pages/Models.tsx` | 模型管理 |
| `src/pages/ApiKeys.tsx` | API 密钥管理 |
| `src/pages/Usage.tsx` | 用量统计 (时间范围 + Tab 切换) |
| `src/pages/Relay.tsx` | 中转任务管理 |
| `src/pages/Config.tsx` | 系统配置 (分类 Tab) |
| `src/pages/Prompts.tsx` | 提示词管理 (版本历史 + 回滚) |
| `src/pages/Logs.tsx` | 操作日志 |
| `src/pages/AgentTemplates.tsx` | Agent 模板管理 |
### 桌面端 (desktop/src/)
@@ -247,4 +257,4 @@ ZCLAW SaaS 平台为桌面端用户提供云端能力包括模型中转Key
---
**最后更新**: 2026-03-28
**最后更新**: 2026-03-30