docs: audit reports + feature docs + skills + admin-v2 + config sync

Update audit tracker, roadmap, architecture docs, add admin-v2 Roles page + Billing tests, sync CLAUDE.md, Cargo.toml, docker-compose.yml, add deep-research / frontend-design / chart-visualization skills Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-02 19:25:00 +08:00
parent 28299807b6
commit 8898bb399e
48 changed files with 7388 additions and 173 deletions
--- a/docs/features/SYSTEM_ARCHITECTURE.md
+++ b/docs/features/SYSTEM_ARCHITECTURE.md
@@ -1,6 +1,6 @@
 # ZCLAW 多端系统架构文档

-> 版本: 1.1 | 日期: 2026-03-29 | 状态: 已更新 (Worker + Scheduler + SQL 迁移 + 多环境配置)
+> 版本: 1.2 | 日期: 2026-04-01 | 状态: 已更新 (DeerFlow 视觉复刻 + 安全审计 V1 修复 + Admin V2 迁移)

 ---

@@ -29,9 +29,9 @@ ZCLAW 是面向中文用户的 AI Agent 桌面客户端，由 **4 个独立服
 ├─────────────────────────────────────────────────────────────────┤
 │                                                                 │
 │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
-│  │  Desktop App  │  │  Admin Web   │  │  SaaS Backend        │  │
-│  │  (Tauri+React)│  │  (Next.js)   │  │  (Axum + PostgreSQL) │  │
-│  │  Port: 1420   │  │  Port: 3000  │  │  Port: 8080          │  │
+│  │  Desktop App  │  │  Admin V2    │  │  SaaS Backend        │  │
+│  │  (Tauri+React)│  │  (Vite+AntD) │  │  (Axum + PostgreSQL) │  │
+│  │  Port: 1420   │  │  Port: 5173  │  │  Port: 8080          │  │
 │  │               │  │              │  │                      │  │
 │  │  内核模式:     │  │  管理后台     │  │  REST API            │  │
 │  │  Tauri IPC    │  │  JWT 鉴权     │  │  JWT + API Token     │  │
@@ -67,7 +67,8 @@ ZCLAW 是面向中文用户的 AI Agent 桌面客户端，由 **4 个独立服
 | 端口 | 服务 | 协议 | 用途 | 启动方式 |
 |------|------|------|------|----------|
 | 1420 | Vite Dev Server | HTTP | 桌面端前端开发服务 (仅 dev) | `pnpm tauri dev` |
-| 3000 | Next.js Dev Server | HTTP | Admin 管理后台开发服务 | `pnpm dev` (admin/) |
+| 3000 | ~~Next.js Dev Server~~ | HTTP | ~~旧 Admin 管理后台~~ (已废弃) | ~~`pnpm dev` (admin/)~~ |
+| 5173 | Vite Dev Server | HTTP | Admin V2 管理后台开发服务 | `pnpm dev` (admin-v2/) |
 | 4200 | ZCLAW Gateway/Kernel | WebSocket + REST | 网关备用端口 | ZCLAW 二进制 |
 | 50051 | ZCLAW Gateway | WebSocket + REST | 网关主端口 | ZCLAW 二进制 |
 | 5432 | PostgreSQL | PostgreSQL Wire | SaaS 后端数据库 | Docker/start-all.ps1 |
@@ -89,14 +90,21 @@ ZCLAW 是面向中文用户的 AI Agent 桌面客户端，由 **4 个独立服
 | 样式方案 | Tailwind CSS | 原子化 CSS，暗色主题友好 |
 | 数据存储 | SQLite (本地) | 离线优先，FTS5 全文搜索 |

-### 3.2 Admin 管理后台
+### 3.2 Admin V2 管理后台

 | 层级 | 技术 | 选型理由 |
 |------|------|----------|
-| 框架 | Next.js 14 (App Router) | SSR/CSR 灵活切换，API 代理 |
-| 数据获取 | SWR 2.x | 缓存+去重+自动重验证，stale-while-revalidate |
-| UI 组件 | shadcn/ui | 暗色主题原生支持，可定制 |
-| 图表 | Recharts | React 原生集成，轻量 |
+| 框架 | React 19 + Vite 8 | 纯 SPA，快速构建 |
+| 语言 | TypeScript 5.9 | 类型安全 |
+| UI 组件 | Ant Design 6 + Pro Components | 企业级组件库，暗色主题 |
+| 状态管理 | Zustand 5 | 轻量灵活 |
+| 数据获取 | TanStack React Query 5 | 缓存+去重+自动重验证 |
+| 路由 | React Router 7 | SPA 路由 |
+| HTTP | Axios | 拦截器 + 401 自动刷新 |
+| 样式 | Tailwind CSS v4 | 原子化 CSS |
+| 测试 | Vitest + Testing Library + MSW | 完整测试覆盖 |
+
+> **Admin V2 迁移说明**: 从 Next.js + SWR + shadcn/ui 迁移到 Vite + React Query + Ant Design Pro，认证改为 HttpOnly Cookie 模式，11 个管理页面全部重写，含 71 个测试用例。

 ### 3.3 SaaS 后端

@@ -118,30 +126,33 @@ ZCLAW 是面向中文用户的 AI Agent 桌面客户端，由 **4 个独立服
 ```
 zclaw-types        → 基础类型 (AgentId, Message, Error)
 zclaw-memory       → 存储层 (SQLite, FTS5, TF-IDF, Embeddings)
-zclaw-runtime      → 运行时 (LLM 驱动, 工具, Agent 循环)
-zclaw-kernel       → 核心协调 (注册, 调度, 事件, 工作流)
-zclaw-skills       → 技能系统 (SKILL.md 解析, WASM 执行器)
-zclaw-hands        → 自主能力 (Hand/Trigger 注册管理)
+zclaw-runtime      → 运行时 (LLM 驱动, 11 层中间件, 工具, Agent 循环)
+zclaw-kernel       → 核心协调 (注册, 调度, 事件, 9 Hands, 76 Skills)
+zclaw-skills       → 技能系统 (SKILL.md 解析, 语义路由, DAG 编排)
+zclaw-hands        → 自主能力 (9 个内置 Hand 实现)
 zclaw-protocols    → 协议支持 (MCP, A2A)
-zclaw-saas         → SaaS 后端 (独立服务, 8080 端口)
+zclaw-pipeline     → 流水线引擎 (v1/v2 DSL, Smart Presentation)
+zclaw-growth       → 成长系统 (记忆提取/检索/注入, OpenViking 分层)
+zclaw-saas         → SaaS 后端 (独立服务, 8080 端口, 58 API)
 ```

 ---

 ## 4. 数据流向

-### 4.1 Admin 管理后台数据流
+### 4.1 Admin V2 管理后台数据流

 ```
-用户操作 → React UI → SWR Hook → api-client.ts → Next.js Rewrites → SaaS 后端 (:8080)
+用户操作 → React UI → React Query → request.ts (Axios) → Vite Proxy → SaaS 后端 (:8080)
                ↑                                                          ↓
-                └── SWR Cache ←── JSON Response ←── PostgreSQL (:5432) ←─┘
+                └── React Query Cache ←── JSON Response ←── PostgreSQL (:5432) ←─┘
 ```

 **关键路径:**
- Admin 前端所有请求通过 `next.config.js rewrites` 代理到 `localhost:8080`
+- Admin V2 所有请求通过 `vite.config.ts proxy` 代理到 `localhost:8080`
 - API 基路径: `/api/v1/*` (前端) → `http://localhost:8080/api/v1/*` (后端)
- SWR 缓存: 页面切换后缓存 5s 去重，stale-while-revalidate 模式
+- React Query 缓存: 自动去重 + stale-while-revalidate 模式
+- SSE 端点 (`/relay/chat/completions`) 超时配置 10 分钟

 ### 4.2 桌面端数据流 (Tauri 模式)

@@ -546,11 +557,15 @@ React UI → saas-client.ts → HTTPS REST → SaaS 后端 (:8080)
 | 命令组 | 文件 | 命令数 | 用途 |
 |--------|------|--------|------|
 | 进程管理 | lib.rs | 10 | zclaw_start/stop/restart, doctor, health_check |
-| 内核操作 | kernel_commands.rs | 20+ | agent_create/chat_stream, skill_execute, hand_execute |
-| 工作流 | pipeline_commands.rs | 9 | pipeline_run/progress/cancel, route_intent |
-| 持久记忆 | memory_commands.rs | 12 | memory_store/get/search/export |
-| Viking 存储 | viking_commands.rs | 9 | viking_add/find/grep/read |
-| 智能钩子 | intelligence_hooks.rs | 2 | pre/post_conversation_hook |
+| 内核操作 | kernel_commands.rs | 34 | agent_create/chat_stream, skill_execute, hand_execute, trigger, workflow |
+| 工作流 | pipeline_commands.rs | 10 | pipeline_run/progress/cancel, route_intent |
+| 浏览器自动化 | browser_commands.rs | 22 | navigate/click/fill/screenshot/evaluate |
+| 智能层 | intelligence_commands.rs | 35 | memory/identity/reflection/heartbeat/autonomy |
+| 持久记忆 | memory_commands.rs | 14 | memory_store/get/search/export/graph |
+| Viking 存储 | viking_commands.rs | 13 | viking_add/find/grep/read |
+| CLI 工具 | cli_commands.rs | 13 | doctor/health/export/import |
+| 安全存储 | secure_storage.rs | 4 | store/get/delete/list |
+| LLM 管理 | llm_commands.rs | 3 | list_providers/test_connection |

 ### 6.2 WebSocket 事件类型

@@ -602,16 +617,16 @@ React UI → saas-client.ts → HTTPS REST → SaaS 后端 (:8080)

 ```
 ┌───────────────────────────────────────────────────────────┐
-│  Admin 浏览器 (localhost:3000)                             │
+│  Admin V2 浏览器 (localhost:5173)                          │
 │                                                           │
-│  ┌──────────┐  SWR Cache  ┌──────────────┐               │
-│  │ React UI │◄────────────►│ api-client   │               │
-│  │ 11 页面   │             │ JWT 鉴权      │               │
-│  └──────────┘             └──────┬───────┘               │
-│                                  │ fetch()                │
+│  ┌──────────┐  React Query ┌──────────────┐              │
+│  │ React UI │◄────────────►│ Axios        │              │
+│  │ 11 页面   │  Cache       │ Cookie 认证   │              │
+│  └──────────┘             └──────┬───────┘              │
+│                                  │ axios()                │
 └──────────────────────────────────┼────────────────────────┘
                                   │
-                    Next.js Rewrite│ /api/* → localhost:8080/api/*
+                    Vite Proxy     │ /api/* → localhost:8080/api/*
                                   │
 ┌──────────────────────────────────┼────────────────────────┐
 │  SaaS Backend (:8080)            │                        │
@@ -625,7 +640,7 @@ React UI → saas-client.ts → HTTPS REST → SaaS 后端 (:8080)
 │                           └──────┬───────┘               │
 │                                  │                        │
 │                    ┌─────────────▼──────────────┐        │
-│                    │  Handlers (72 个端点)       │        │
+│                    │  Handlers (58 个端点)       │        │
 │                    │  auth/account/model/relay/  │        │
 │                    │  config/prompt/telemetry/   │        │
 │                    └─────────────┬──────────────┘        │
@@ -807,4 +822,4 @@ run_on_start = false

 ---

-> **文档统计**: 84 个 API 端点 | 5 个通信通道 | 12 种权限 | 4 个独立服务 | 5 个 Workers | 声明式 Scheduler | SQL Schema v6
+> **文档统计**: 58 个 API 端点 | 5 个通信通道 | 12 种权限 | 4 个独立服务 | 5 个 Workers | 声明式 Scheduler | SQL Schema v8