# ZCLAW 前端完整验证方案

## 背景

当前 E2E 测试（`functional-scenarios.spec.ts`）主要验证 UI 表面：
- 验证元素是否存在
- 验证按钮能否点击
- 验证对话框能否打开

**问题**：这些测试无法发现真正的功能问题，例如：
- 点击按钮后 API 是否被正确调用
- Store 状态是否正确更新
- 数据是否正确渲染
- 边界情况是否处理

## 目标

设计一套**深度模拟用户操作**的验证方案，确保：
1. **完整操作流程** - 从用户视角完成端到端操作
2. **数据流验证** - 检查 UI → Store → API → 后端的完整链路
3. **状态变化验证** - 验证操作前后状态正确转换
4. **结果展示验证** - 验证返回数据正确渲染到 UI
5. **边界情况验证** - 验证错误处理、空状态、加载状态

---

## 验证架构

### 测试分层

```
┌─────────────────────────────────────────────────────────┐
│                    E2E 用户流程测试                       │
│  (Playwright - 完整用户操作 + 数据流验证)                  │
├─────────────────────────────────────────────────────────┤
│                    Store 状态测试                         │
│  (Vitest - Store 逻辑 + 状态转换验证)                     │
├─────────────────────────────────────────────────────────┤
│                    API 集成测试                           │
│  (MSW Mock - 请求/响应验证)                               │
└─────────────────────────────────────────────────────────┘
```

### 新增测试文件

```
desktop/tests/
├── e2e/
│   ├── specs/
│   │   ├── functional-scenarios.spec.ts  # 现有 - 保留
│   │   ├── data-flow.spec.ts             # 新增 - 数据流深度验证
│   │   ├── store-state.spec.ts           # 新增 - Store 状态验证
│   │   └── edge-cases.spec.ts            # 新增 - 边界情况测试
│   ├── fixtures/
│   │   ├── mock-gateway.ts               # 新增 - Gateway Mock
│   │   ├── test-data.ts                  # 新增 - 测试数据工厂
│   │   └── store-inspectors.ts           # 新增 - Store 检查工具
│   └── utils/
│       ├── network-helpers.ts            # 新增 - 网络拦截工具
│       ├── store-assertions.ts           # 新增 - Store 断言
│       └── user-actions.ts               # 新增 - 用户操作模拟
└── store/
    └── *.test.ts                         # 现有 - 扩展 Store 单元测试
```

---

## 模块验证用例

### 1. 聊天模块 (ChatArea.tsx + chatStore.ts)

#### 数据流验证
```
用户输入 → sendMessage() → gateway-client.chatStream()
  → WebSocket 事件 → initStreamListener() → Store 更新 → UI 渲染
```

#### 深度验证用例

| 用例 ID | 验证场景 | 验证步骤 | 断言点 |
|---------|----------|----------|--------|
| CHAT-DF-01 | 发送消息并接收流式响应 | 1. 输入消息 2. 点击发送 3. 拦截 WebSocket 4. 验证请求格式 5. 模拟流式响应 6. 验证 Store 状态 7. 验证 UI 渲染 | ① 请求包含正确 sessionKey ② isStreaming=true ③ 消息增量追加 ④ streaming=false ⑤ messages 数组更新 |
| CHAT-DF-02 | 模型切换 | 1. 点击模型选择器 2. 选择新模型 3. 发送消息 | ① Store.currentModel 更新 ② 请求使用新模型 ③ UI 显示新模型名 |
| CHAT-DF-03 | Agent 切换 | 1. 当前有消息 2. 切换 Agent 3. 验证状态保存 4. 切换回来 | ① 会话保存到 conversations ② 消息清空 ③ sessionKey 更新 ④ 切回后恢复原消息 |
| CHAT-DF-04 | 新建对话 | 1. 发送消息 2. 点击新建 3. 验证状态 | ① 消息清空 ② currentConversationId=null ③ sessionKey=null |
| CHAT-DF-05 | 网络错误处理 | 1. 模拟网络断开 2. 发送消息 | ① 错误消息显示 ② isStreaming=false ③ error 字段设置 ④ 可重试 |
| CHAT-DF-06 | 流式中断 | 1. 开始流式响应 2. 中途断开连接 | ① 部分消息保留 ② 错误指示器显示 ③ 可恢复 |

#### Store 断言示例
```typescript
// 验证 chatStore 状态
const chatState = await page.evaluate(() => {
  const stored = localStorage.getItem('zclaw-chat-storage');
  return stored ? JSON.parse(stored).state : null;
});

expect(chatState).toMatchObject({
  isStreaming: false,
  messages: expect.arrayContaining([
    expect.objectContaining({ role: 'user', content: 'test' }),
    expect.objectContaining({ role: 'assistant', streaming: false }),
  ]),
});
```

---

### 2. 分身管理 (CloneManager.tsx + agentStore.ts)

#### 数据流验证
```
UI → createClone() → POST /api/clones → Response → clones 更新 → UI 重渲染
```

#### 深度验证用例

| 用例 ID | 验证场景 | 验证步骤 | 断言点 |
|---------|----------|----------|--------|
| CLONE-DF-01 | 创建分身 | 1. 点击创建 2. 填写表单 3. 提交 4. 拦截 API 请求 | ① POST 请求格式正确 ② Store.clones 增加 ③ UI 显示新分身 |
| CLONE-DF-02 | 切换分身 | 1. 当前在 Agent A 2. 切换到 Agent B | ① currentAgent 更新 ② 聊天消息切换 ③ sessionKey 更新 |
| CLONE-DF-03 | 删除分身 | 1. 选择分身 2. 点击删除 3. 确认 | ① DELETE API 调用 ② Store 移除 ③ 回退到默认 |
| CLONE-DF-04 | 修改配置 | 1. 打开设置 2. 修改字段 3. 保存 | ① PATCH 请求含 delta ② Store 更新 ③ UI 显示新值 |

---

### 3. Hands 系统 (HandsPanel.tsx + handStore.ts)

#### 数据流验证
```
组件挂载 → loadHands() → GET /api/hands → 数据映射 → hands 数组 → UI 渲染
触发执行 → triggerHand() → POST /api/hands/:name/trigger → 状态变更 → UI 更新
```

#### 深度验证用例

| 用例 ID | 验证场景 | 验证步骤 | 断言点 |
|---------|----------|----------|--------|
| HAND-DF-01 | 加载 Hands 列表 | 1. 导航到 Hands 2. 拦截 API 3. 验证映射 | ① GET /api/hands 调用 ② 状态徽章正确 ③ requirements_met 显示 |
| HAND-DF-02 | 触发 Hand 执行 | 1. 点击执行 2. 如有参数则填写 3. 提交 | ① POST 触发请求 ② status → running ③ currentRunId 设置 |
| HAND-DF-03 | 参数表单验证 | 1. 展开 Hand 2. 填写各类型参数 3. 验证失败 4. 修正后提交 | ① 类型验证生效 ② 错误提示显示 ③ 正确值传递 |
| HAND-DF-04 | 审批流程 | 1. 触发需审批 Hand 2. 状态 needs_approval 3. 批准/拒绝 | ① 审批对话框显示 ② approveHand API 调用 ③ 状态更新 |
| HAND-DF-05 | 执行历史 | 1. 查看 Hand 详情 2. 历史记录标签 | ① GET /api/hands/:name/runs ② 记录正确显示 |

#### 参数类型验证矩阵

| 参数类型 | 验证项 |
|----------|--------|
| text | 空值、最大长度、正则 pattern |
| number | 边界值、min/max、非数字 |
| boolean | 切换状态、默认值 |
| select | 选项列表、默认选中 |
| array | 添加/删除项、空数组 |
| object | JSON 解析、格式验证 |
| file | 文件选择、大小限制 |

---

### 4. 自动化面板 (AutomationPanel.tsx)

#### 深度验证用例

| 用例 ID | 验证场景 | 验证步骤 | 断言点 |
|---------|----------|----------|--------|
| AUTO-DF-01 | 分类过滤 | 1. 点击分类 2. 验证列表 | ① 请求带 category 参数 ② 列表过滤正确 ③ 空状态处理 |
| AUTO-DF-02 | 搜索功能 | 1. 输入关键词 2. 实时过滤 | ① 匹配名称/描述 ② 高亮显示 ③ 无结果提示 |
| AUTO-DF-03 | 批量执行 | 1. 多选 Hands 2. 批量触发 | ① 选中状态管理 ② 依次触发 API ③ 进度显示 |
| AUTO-DF-04 | 视图切换 | 1. 网格视图 2. 列表视图 | ① 布局变化 ② 数据一致 ③ 响应式适配 |

---

### 5. 工作流编辑 (WorkflowEditor.tsx + workflowStore.ts)

#### 深度验证用例

| 用例 ID | 验证场景 | 验证步骤 | 断言点 |
|---------|----------|----------|--------|
| WF-DF-01 | 创建工作流 | 1. 打开编辑器 2. 添加步骤 3. 配置参数 4. 保存 | ① POST 请求格式 ② steps 数组正确 ③ Store 更新 |
| WF-DF-02 | 步骤操作 | 1. 添加步骤 2. 上移/下移 3. 删除 | ① 顺序更新 ② Hand 选择器 ③ JSON 参数解析 |
| WF-DF-03 | 执行工作流 | 1. 选择工作流 2. 触发执行 | ① POST execute ② 状态 running ③ 步骤进度显示 |
| WF-DF-04 | 验证规则 | 1. 空名称 2. 无步骤 3. 保存 | ① 验证错误显示 ② 禁用保存按钮 |

---

### 6. 技能市场 (SkillMarket.tsx)

#### 深度验证用例

| 用例 ID | 验证场景 | 验证步骤 | 断言点 |
|---------|----------|----------|--------|
| SKILL-DF-01 | 浏览技能 | 1. 加载目录 2. 验证数据 | ① GET /api/skills ② 分类显示 ③ 安装状态 |
| SKILL-DF-02 | 搜索技能 | 1. 输入关键词 2. 验证匹配 | ① 名称/能力/触发词匹配 ② 结果排序 |
| SKILL-DF-03 | 安装技能 | 1. 点击安装 2. 等待完成 | ① 安装 API 调用 ② 状态变更 ③ UI 更新 |
| SKILL-DF-04 | 技能详情 | 1. 展开/点击 2. 查看详情 | ① 触发词列表 ② 工具依赖 ③ 使用示例 |

---

### 7. 团队协作 (TeamList.tsx + teamStore.ts)

#### 深度验证用例

| 用例 ID | 验证场景 | 验证步骤 | 断言点 |
|---------|----------|----------|--------|
| TEAM-DF-01 | 创建团队 | 1. 填写表单 2. 选择成员 3. 选择模式 4. 创建 | ① POST 格式正确 ② members 数组 ③ pattern 字段 |
| TEAM-DF-02 | 成员管理 | 1. 添加成员 2. 分配角色 3. 移除 | ① Store 更新 ② 角色字段 ③ UI 反映 |
| TEAM-DF-03 | 任务分配 | 1. 创建任务 2. 分配成员 3. 更新状态 | ① tasks 数组 ② assigneeId ③ status 变化 |
| TEAM-DF-04 | Dev↔QA 循环 | 1. 启动循环 2. 提交审查 3. 反馈 4. 迭代 | ① activeLoops 更新 ② iteration 递增 ③ state 转换 |

---

### 8. 设置页面 (Settings/*)

#### 深度验证用例

| 用例 ID | 验证场景 | 验证步骤 | 断言点 |
|---------|----------|----------|--------|
| SET-DF-01 | 通用设置 | 1. 修改字段 2. 保存 | ① PATCH 请求 ② Store 更新 ③ 成功提示 |
| SET-DF-02 | 模型配置 | 1. 添加 API Key 2. 测试连接 | ① 密钥掩码显示 ② 连接测试 API ③ 模型列表加载 |
| SET-DF-03 | MCP 服务 | 1. 查看列表 2. 启用/禁用 | ① GET /api/plugins ② PATCH 状态 ③ UI 更新 |
| SET-DF-04 | 审计日志 | 1. 打开日志 2. 筛选 3. 分页 | ① 日志加载 ② 过滤参数 ③ 分页正确 |

---

### 9. 审批系统 (ApprovalQueue.tsx)

#### 深度验证用例

| 用例 ID | 验证场景 | 验证步骤 | 断言点 |
|---------|----------|----------|--------|
| APPROVE-DF-01 | 查看队列 | 1. 加载审批列表 | ① GET /api/approvals?status=pending ② 详情显示 |
| APPROVE-DF-02 | 批准操作 | 1. 选择审批 2. 批准 | ① POST respond (approved=true) ② 队列移除 ③ 状态更新 |
| APPROVE-DF-03 | 拒绝操作 | 1. 选择审批 2. 拒绝 3. 填写原因 | ① 原因字段 ② POST respond (approved=false) ③ 队列更新 |

---

## 边界情况验证清单

### 网络边界

| 场景 | 预期行为 | 验证方法 |
|------|----------|----------|
| Gateway 断开 | 连接指示器红色，输入禁用，错误消息 | 模拟断开，检查 UI 状态 |
| WebSocket 重连 | 自动重连尝试，状态保留，指示器显示 | 断开后恢复，验证状态 |
| 请求超时 | 超时错误显示，重试选项可用 | 设置短超时，检查处理 |
| 无效响应 | 解析错误处理，优雅降级 | 返回畸形 JSON |
| 限流 (429) | 用户通知，自动退避重试 | 模拟 429 响应 |

### 数据边界

| 场景 | 预期行为 | 验证方法 |
|------|----------|----------|
| 空消息列表 | 欢迎状态，开始提示 | 清空数据，检查 UI |
| 超长消息 | 容器内滚动，布局不破 | 输入 10000+ 字符 |
| 空 Hands 列表 | "无可用 Hands" + 连接提示 | Mock 空响应 |
| 无效 JSON 参数 | 解析错误显示，原值保留 | 输入畸形 JSON |
| 大文件上传 | 进度指示，大小限制检查 | 选择超大文件 |

### 状态边界

| 场景 | 预期行为 | 验证方法 |
|------|----------|----------|
| 快速连续点击 | 防抖，单次操作，正确最终状态 | 连续点击 10 次 |
| 流式响应中切换 | 取消/完成当前，干净切换 | 发消息后立即切换 |
| 浏览器刷新 | 从 localStorage 恢复，会话保留 | 刷新后检查状态 |
| 标签页切换 | 操作继续，返回时状态同步 | 切换标签再返回 |

---

## 实现方案

### 1. 网络拦截工具

```typescript
// tests/e2e/utils/network-helpers.ts
export const networkHelpers = {
  // 拦截并记录所有 API 请求
  async interceptAllAPI(page: Page) {
    const requests: Array<{ url: string; method: string; body?: any }> = [];

    await page.route('**/api/**', async (route) => {
      const request = route.request();
      requests.push({
        url: request.url(),
        method: request.method(),
        body: request.postDataJSON(),
      });
      await route.continue();
    });

    return requests;
  },

  // Mock API 响应
  async mockAPI(page: Page, path: string, response: any, status = 200) {
    await page.route(`**/api/${path}**`, async (route) => {
      await route.fulfill({
        status,
        contentType: 'application/json',
        body: JSON.stringify(response),
      });
    });
  },

  // 模拟网络错误
  async simulateNetworkError(page: Page, path: string) {
    await page.route(`**/api/${path}**`, async (route) => {
      await route.abort('failed');
    });
  },

  // 模拟延迟响应
  async simulateDelay(page: Page, path: string, delayMs: number) {
    await page.route(`**/api/${path}**`, async (route) => {
      await new Promise(r => setTimeout(r, delayMs));
      await route.continue();
    });
  },
};
```

### 2. Store 检查工具

```typescript
// tests/e2e/fixtures/store-inspectors.ts
export const storeInspectors = {
  // 获取持久化的 Store 状态
  async getPersistedState(page: Page, storeName: string) {
    return page.evaluate((name) => {
      const stored = localStorage.getItem(`zclaw-${name}-storage`);
      return stored ? JSON.parse(stored).state : null;
    }, storeName);
  },

  // 等待 Store 状态变化
  async waitForStateChange(page: Page, storeName: string, path: string, expectedValue: any) {
    await page.waitForFunction(
      ({ store, path, expected }) => {
        const stored = localStorage.getItem(`zclaw-${store}-storage`);
        if (!stored) return false;
        const state = JSON.parse(stored).state;
        const value = path.split('.').reduce((obj, key) => obj?.[key], state);
        return JSON.stringify(value) === JSON.stringify(expected);
      },
      { store: storeName, path, expected: expectedValue },
      { timeout: 5000 }
    );
  },

  // 验证 Store 状态
  async assertStoreState(page: Page, storeName: string, expected: Record<string, any>) {
    const state = await this.getPersistedState(page, storeName);
    for (const [key, value] of Object.entries(expected)) {
      expect(state?.[key]).toEqual(value);
    }
  },
};
```

### 3. 用户操作模拟

```typescript
// tests/e2e/utils/user-actions.ts
export const userActions = {
  // 完整聊天流程
  async sendChatMessage(page: Page, message: string) {
    const chatInput = page.locator('textarea').first();
    await chatInput.waitFor({ state: 'visible' });
    await chatInput.fill(message);

    // 拦截请求
    const [request] = await Promise.all([
      page.waitForRequest('**/api/chat**'),
      page.getByRole('button', { name: '发送消息' }).click(),
    ]);

    return request;
  },

  // 创建分身完整流程
  async createClone(page: Page, data: { name: string; role?: string }) {
    await page.getByRole('button', { name: /创建|new/i }).click();
    await page.waitForSelector('[role="dialog"]');

    const dialog = page.locator('[role="dialog"]');
    await dialog.locator('input').first().fill(data.name);

    const [response] = await Promise.all([
      page.waitForResponse('**/api/clones'),
      dialog.getByRole('button', { name: /确认|创建|save/i }).click(),
    ]);

    return response;
  },

  // 触发 Hand 完整流程
  async triggerHand(page: Page, handName: string, params?: Record<string, any>) {
    // 导航到 Hands
    await page.getByRole('tab', { name: 'Hands' }).click();

    // 找到并点击 Hand
    const handCard = page.locator(`[data-hand-name="${handName}"]`).or(
      page.getByRole('button', { name: new RegExp(handName, 'i') })
    );
    await handCard.click();

    // 如果有参数表单，填写参数
    if (params) {
      for (const [key, value] of Object.entries(params)) {
        const input = page.locator(`[name="${key}"]`).or(
          page.locator(`label:has-text("${key}")`).locator('..').locator('input, textarea, select')
        );
        if (await input.isVisible()) {
          await input.fill(String(value));
        }
      }
    }

    // 触发执行
    const [request] = await Promise.all([
      page.waitForRequest(`**/api/hands/${handName}/trigger`),
      page.getByRole('button', { name: /执行|触发|run/i }).click(),
    ]);

    return request;
  },
};
```

### 4. 数据流测试示例

```typescript
// tests/e2e/specs/data-flow.spec.ts
import { test, expect } from '@playwright/test';
import { networkHelpers } from '../utils/network-helpers';
import { storeInspectors } from '../fixtures/store-inspectors';
import { userActions } from '../utils/user-actions';

test.describe('聊天数据流验证', () => {
  test('CHAT-DF-01: 发送消息完整数据流', async ({ page }) => {
    // 1. 设置网络拦截
    const requests = await networkHelpers.interceptAllAPI(page);

    // 2. Mock 流式响应
    await networkHelpers.mockAPI(page, 'chat', {
      type: 'stream',
      messages: [
        { delta: '你好', phase: 'start' },
        { delta: '！我是', phase: 'delta' },
        { delta: 'AI 助手', phase: 'delta' },
        { phase: 'end' },
      ],
    });

    // 3. 发送消息
    await page.goto('http://localhost:1420');
    const request = await userActions.sendChatMessage(page, '测试消息');

    // 4. 验证请求格式
    const requestBody = request.postDataJSON();
    expect(requestBody).toMatchObject({
      message: '测试消息',
      sessionKey: expect.any(String),
    });

    // 5. 验证 Store 状态
    const chatState = await storeInspectors.getPersistedState(page, 'chat');
    expect(chatState.messages).toContainEqual(
      expect.objectContaining({ role: 'user', content: '测试消息' })
    );

    // 6. 验证 UI 渲染
    await expect(page.locator('[class*="message"]').filter({ hasText: '测试消息' })).toBeVisible();
    await expect(page.locator('[class*="assistant"]')).toBeVisible();
  });
});
```

---

## 验证执行

### 运行命令

```bash
# 运行所有 E2E 测试
pnpm --filter desktop test:e2e

# 运行数据流测试
pnpm --filter desktop playwright test -- --grep "数据流|data-flow"

# 运行边界情况测试
pnpm --filter desktop playwright test -- --grep "边界|edge-case"

# 调试模式
pnpm --filter desktop playwright test -- --headed --debug

# 生成报告
pnpm --filter desktop playwright show-report
```

### CI 集成

```yaml
# .github/workflows/frontend-verification.yml
name: Frontend Verification
on: [push, pull_request]

jobs:
  e2e-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install
      - run: pnpm --filter desktop exec playwright install --with-deps
      - name: Run E2E tests
        run: pnpm --filter desktop test:e2e
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: desktop/test-results/
```

---

## 关键文件清单

### 需要创建的文件

| 文件路径 | 用途 |
|----------|------|
| `desktop/tests/e2e/specs/data-flow.spec.ts` | 数据流深度验证测试 |
| `desktop/tests/e2e/specs/store-state.spec.ts` | Store 状态验证测试 |
| `desktop/tests/e2e/specs/edge-cases.spec.ts` | 边界情况测试 |
| `desktop/tests/e2e/fixtures/mock-gateway.ts` | Gateway Mock 工具 |
| `desktop/tests/e2e/fixtures/test-data.ts` | 测试数据工厂 |
| `desktop/tests/e2e/fixtures/store-inspectors.ts` | Store 检查工具 |
| `desktop/tests/e2e/utils/network-helpers.ts` | 网络拦截工具 |
| `desktop/tests/e2e/utils/store-assertions.ts` | Store 断言工具 |
| `desktop/tests/e2e/utils/user-actions.ts` | 用户操作模拟 |

### 需要修改的文件

| 文件路径 | 修改内容 |
|----------|----------|
| `desktop/tests/e2e/playwright.config.ts` | 添加新测试配置 |
| `desktop/src/store/*.ts` | 添加测试辅助方法（可选） |

---

## 成功标准

### 覆盖率目标

| 层级 | 目标 | 度量方式 |
|------|------|----------|
| E2E 用户流程 | 100% | 10 个模块全覆盖 |
| 数据流路径 | 100% | UI → Store → API → UI 验证 |
| 边界情况 | 80% | 网络/数据/状态边界 |
| 错误处理 | 100% | 所有错误状态 |

### 质量门槛

- [ ] 所有测试在 CI 中通过
- [ ] 正常流程无控制台错误
- [ ] 网络故障优雅处理
- [ ] 刷新后状态持久化
- [ ] 所有用户输入有验证
- [ ] 加载状态正确显示