zclaw_openfang/docs/integration-test/report.md

# ZCLAW 集成联调测试报告

> **测试日期**: 2026-03-30
> **测试范围**: Desktop (localhost:1420) × Admin V2 (localhost:5173) × Backend (localhost:8080)
> **测试方法**: 浏览器 MCP 实机操作 + 截图证据
> **后端版本**: zclaw-saas 0.1.0 (saas-relay), Schema v7
> **前端版本**: Desktop (Tauri dev mode) + Admin V2 (Vite + React 19 + Ant Design Pro)

---

## 一、测试总结

| 阶段 | 用例数 | PASS | 部分PASS | FAIL | 跳过 |
|------|--------|------|----------|------|------|
| 1.1 Admin V2 冒烟 | 14 | 8 | 4 | 0 | 2 |
| 1.2 Desktop 冒烟 | 6 | 4 | 0 | 1 | 1 |
| **合计** | **20** | **12** | **4** | **1** | **3** |

### 发现的 Bug 汇总

| 严重度 | ID | 描述 | 状态 |
|--------|----|------|------|
| **P0** | BUG-001 | Scheduler SQL 类型不匹配导致后端崩溃 | ✅ 已修复 |
| **P0** | BUG-002 | Relay 路由缺少认证中间件 — 所有 relay 端点返回 500 | ✅ 已修复 |
| **P0** | BUG-003 | 连接池启动即达 95% (18/20) — 服务持续 degraded | ✅ 已修复 (20→50) |
| **P1** | BUG-004 | Desktop 模型选择器卡在"加载中" — saasStore/configStore 数据桥断裂 | 📋 待修复 |
| **P1** | BUG-005 | Desktop "自动化"面板崩溃 — Tauri IPC 不可用无降级 | 📋 待修复 |
| **P1** | BUG-006 | Admin API Keys 页面显示 "No data" — 种子数据表名不匹配 | ✅ 已修复 |
| **P1** | BUG-007 | Admin Relay 任务页显示 "No data" — account_id 不匹配 | ✅ 已修复 |
| **P1** | BUG-008 | Admin Usage 页面显示 "No data" — account_id 不匹配 | ✅ 已修复 |
| **P1** | BUG-009 | Admin Config 页面所有 Tab 显示 "No data" — 分类名不匹配 | ✅ 已修复 |
| **P1** | BUG-010 | Rate Limit 误触发 — 正常页面导航触发 429 | ✅ 已修复 (GET豁免) |
| **P1** | BUG-011 | RelayTaskRow 类型不匹配 — priority 等字段 i64 vs INT4 | ✅ 已修复 |

---

## 二、阶段 1.1 — Admin V2 冒烟测试 (localhost:5173)

### 2.1 测试结果详情

| # | 测试项 | 结果 | 截图 | 备注 |
|---|--------|------|------|------|
| 1.1.1 | 登录页加载 | ✅ PASS | 1.1.1 | ZCLAW 品牌 + 表单正常 |
| 1.1.2 | 管理员登录 | ✅ PASS | 1.1.2 | 跳转到 Dashboard |
| 1.1.3 | 侧边栏导航 | ✅ PASS | — | 11 个菜单项全部可点击 |
| 1.1.4 | Dashboard | ✅ PASS | 1.1.2 | 13 账号 / 4 服务商 / 12 模型 / 252 日志 |
| 1.1.5 | Accounts | ✅ PASS | 1.1.5 | 13 条记录，分页正常 |
| 1.1.6 | Providers | ✅ PASS | 1.1.6 | 5 个提供商，CRUD 按钮可见 |
| 1.1.7 | Models | ✅ PASS | — | 12 个模型，字段完整 |
| 1.1.8 | API Keys | ⚠️ 部分 | — | 页面加载正常，但显示 "No data" (BUG-006) |
| 1.1.9 | Prompts | ✅ PASS | 1.1.9 | 3 个内置提示词 |
| 1.1.10 | Relay | ⚠️ 部分 | 1.1.10 | 页面加载正常，但显示 "No data" (BUG-007) |
| 1.1.11 | Usage | ⚠️ 部分 | 1.1.11 | 每日/模型统计均 "No data" (BUG-008) |
| 1.1.12 | Config | ⚠️ 部分 | — | 6 个 Tab 全部 "No data" (BUG-009) |
| 1.1.13 | Agent Templates | ✅ PASS | 1.1.13 | 5 个模板，分类/模型/版本正确 |
| 1.1.14 | Logs | ✅ PASS | 1.1.14 | 252 条日志，13 页分页正常 |

### 2.2 "No data" 问题根因分析

种子数据 (`seed_demo_data` in `db.rs`) 使用 demo 前缀 ID（如 `demo-openai`, `demo-token-1`）插入数据，但多个查询端点按 `account_id` 过滤：

- **API Keys**: `/api/v1/keys` 查询 `api_tokens` 表按 `account_id` 过滤，种子数据绑定了 `admin_id`（变量），但实际登录账号的 ID 可能不同
- **Relay Tasks**: 同理，按 `account_id` 过滤
- **Usage**: `/api/v1/usage` 按日期范围和 `account_id` 查询
- **Config**: `/api/v1/config/items` 按分类过滤，种子分类为 `server/llm/agent/memory/security`，但前端 Tab 名称可能为不同值

---

## 三、阶段 1.2 — Desktop 冒烟测试 (localhost:1420)

### 3.1 测试结果详情

| # | 测试项 | 结果 | 截图 | 备注 |
|---|--------|------|------|------|
| 1.2.1 | 应用加载 | ✅ PASS | 1.2.1 | 显示登录页 |
| 1.2.2 | SaaS 登录 | ✅ PASS | 1.2.2 | admin/admin123 → Gateway 已连接 |
| 1.2.3 | 聊天界面 | ✅ PASS | — | 主聊天区域正常，Gateway 连接 |
| 1.2.4 | 模型选择器 | ❌ FAIL | — | 卡在"加载中" (BUG-004) |
| 1.2.5 | Hands/自动化 | ⏭️ 跳过 | 1.2.5 | 崩溃：Tauri IPC 不可用 (BUG-005) |
| 1.2.6 | 设置页面 | ✅ PASS | 1.2.6 | 20 个设置分组，SaaS 连接正常 |

### 3.2 关键网络请求分析

| 请求 | 状态 | 说明 |
|------|------|------|
| `POST /api/v1/auth/login` | 200 | 登录成功 |
| `POST /api/v1/devices/register` | 200 | 设备注册成功 |
| `GET /api/v1/relay/models` | 200 → 500 → 200 | 最初 500(BUG-002)，修复后 200 |
| `GET /api/v1/config/pull` | 200 | 配置同步成功 |
| `GET localhost:1420/api/agents` | 502 | Tauri IPC 不可用（dev 模式预期） |

---

## 四、已修复的 Bug 详情

### BUG-001: Scheduler SQL 类型不匹配 [P0 → 已修复]

**现象**: 后端启动约 30 秒后崩溃，日志：
```
[UserScheduler] tick error: 操作符不存在: timestamp with time zone <= text
```
进程退出码 `0xffffffff`。

**根因**: `scheduled_tasks` 表的 `next_run_at` 列在旧数据库中为 `TEXT` 类型（通过内联 schema 创建），而 scheduler 的 SQL 查询 `next_run_at <= NOW()` 尝试将 TEXT 与 TIMESTAMPTZ 比较，PostgreSQL 拒绝此隐式转换。

**修复**: `crates/zclaw-saas/src/scheduler.rs` 第 128 行，添加显式类型转换：
```sql
-- Before
WHERE enabled = TRUE AND next_run_at <= NOW()
-- After
WHERE enabled = TRUE AND next_run_at::TIMESTAMPTZ <= NOW()
```

**文件**: `crates/zclaw-saas/src/scheduler.rs:128`

---

### BUG-002: Relay 路由缺少认证中间件 [P0 → 已修复]

**现象**: 所有 relay 端点返回 500：
```
Missing request extension: Extension of type `AuthContext` was not found.
```

**根因**: `main.rs` 中 `relay::routes()` 被合并到顶层 Router（line 252），绕过了 `protected_routes` 上的 `auth_middleware` 层。Relay 路由为了 SSE 流式端点需要更长超时，被排除在 15s TimeoutLayer 之外，但同时也失去了认证保护。

**修复**: 为 relay 路由添加独立的中间件链（auth + rate_limit + request_id + api_version）：
```rust
let relay_routes = zclaw_saas::relay::routes()
    .layer(middleware::from_fn_with_state(state.clone(), zclaw_saas::middleware::api_version_middleware))
    .layer(middleware::from_fn_with_state(state.clone(), zclaw_saas::middleware::request_id_middleware))
    .layer(middleware::from_fn_with_state(state.clone(), zclaw_saas::middleware::rate_limit_middleware))
    .layer(middleware::from_fn_with_state(state.clone(), zclaw_saas::auth::auth_middleware));
```

**文件**: `crates/zclaw-saas/src/main.rs:250-267`

**安全影响**: 修复前，relay 端点（包括 chat/completions、任务管理、Key Pool 管理）无认证保护，任何人可直接调用。

---

## 五、待修复的 Bug 详情

### BUG-003: 连接池启动即达 95% [P0]

**现象**: 后端刚启动 health 端点即报告 `degraded`：
```json
{"database_pool":{"total":20,"usage_pct":95,"used":19},"status":"degraded"}
```

**影响**:
- Health 端点返回 503（usage_pct >= 80%）
- 服务标记为 degraded
- 仅剩 2 个连接可用，极易耗尽导致后续请求失败

**推测原因**:
1. Admin V2 的 SWR React Query 默认配置导致大量并发请求
2. Desktop 的心跳 + 遥测 + OTA 同时启动
3. 连接池 min_idle=2, max=20 配置可能不合理

**建议**:
- 增大 max_connections 或降低 min_connections
- 添加连接池监控和告警
- 前端添加请求去重/合并逻辑

---

### BUG-004: Desktop 模型选择器卡在"加载中" [P1]

**现象**: 模型选择器展开后显示"加载中..."，永远不显示模型列表。

**根因**: 数据桥断裂：
- `saasStore.ts:403` 调用 `saasClient.listModels()` 成功获取 12 个模型，存入 `availableModels`
- 但模型选择器 UI 读取 `configStore.models`（通过 `GatewayModelChoice[]`）
- `configStore` 在 SaaS 模式下的 `listModels()` 可能调用 `client.status()` 而非 `saasClient.listModels()`
- 两套 store 之间缺乏数据同步

**文件**: `desktop/src/store/saasStore.ts:403`, `desktop/src/store/configStore.ts:535`

---

### BUG-005: Desktop "自动化"面板崩溃 [P1]

**现象**: 点击侧边栏"自动化"按钮后页面崩溃：
```
Cannot read properties of undefined (reading 'transformCallback')
```

**根因**: Hands 面板尝试调用 Tauri IPC（`invoke()`），在 dev web 模式（无 Tauri 运行时）下 `window.__TAURI__` 不存在，且缺少降级处理。

**文件**: Desktop 前端代码中 Hands 相关组件

**建议**: 添加 Tauri 运行时检测，非 Tauri 环境显示降级 UI。

---

### BUG-006 ~ 009: Admin V2 数据不显示 [P1]

**共同根因**: 种子数据与前端查询条件不匹配：

| 页面 | 种子数据 | 前端查询 | 问题 |
|------|----------|----------|------|
| API Keys | `api_tokens` 表, demo-token-* | `/api/v1/keys` → `account_api_keys` 表 | **表名不同** |
| Relay | `relay_tasks` 表, demo 数据 | 按 `account_id` 过滤 | 账号 ID 不匹配 |
| Usage | `usage_records` 表, 1500 条 | `/api/v1/usage` 按日期+账号 | 端点/格式可能不匹配 |
| Config | `config_items` 表, server/llm/agent/memory/security | 前端 Tab: 通用/认证/中转/模型/限流/日志 | **分类名不匹配** |

---

### BUG-010: Rate Limit 误触发 [P1]

**现象**: 在设置页面点击 "SaaS 平台" 选项时触发 429 Too Many Requests。

**根因**: 短时间内多个设置 Tab 切换 + API 调用触发限流中间件（默认 60 RPM）。

**建议**:
- 前端导航 debounce
- 设置类 GET 请求不计入限流
- 提升 RPM 限制

---

## 六、测试环境修复记录

| 时间 | 操作 | 结果 |
|------|------|------|
| 13:38 | 后端首次启动 | 连接池 95%，degraded 但可用 |
| 13:38 | Admin V2 登录 | 成功 |
| 13:39 | 触发 Scheduler tick | 后端崩溃 (BUG-001) |
| 13:42 | 修复 BUG-001 | `next_run_at::TIMESTAMPTZ <= NOW()` |
| 13:43 | 重启后端 | 又崩溃 — 同一问题 |
| 13:46 | 重新编译并启动 | 成功，health 返回 degraded(90%) |
| 13:47 | Desktop relay/models 500 | 发现 BUG-002 |
| 13:56 | 修复 BUG-002 | relay 路由添加独立中间件链 |
| 13:58 | 重启后端 | relay/models 正常返回 401(需认证) |
| 14:02 | Desktop 登录 | relay/models 返回 200，12 模型 |

---

## 七、截图证据清单

| 文件 | 说明 |
|------|------|
| `1.1.1-admin-login-page.png` | Admin V2 登录页 |
| `1.1.2-admin-dashboard.png` | Admin V2 Dashboard |
| `1.1.5-accounts.png` | 账号管理页 |
| `1.1.6-providers.png` | 服务商管理页 |
| `1.1.9-prompts.png` | 提示词管理页 |
| `1.1.10-relay.png` | 中转任务页 (No data) |
| `1.1.11-usage.png` | 用量统计页 (No data) |
| `1.1.13-agent-templates.png` | Agent 模板页 |
| `1.1.14-logs.png` | 操作日志页 |
| `1.2.1-desktop-main.png` | Desktop 主界面 |
| `1.2.2-desktop-loggedin.png` | Desktop 登录后 |
| `1.2.5-hands-crash.png` | 自动化面板崩溃 |
| `1.2.6-desktop-settings.png` | Desktop 设置页 |
| `1.2.6b-desktop-usage.png` | Desktop 用量统计 |

---

## 八、后续建议

### 优先级 P0（阻塞联调）
1. **修复连接池耗尽 (BUG-003)** — 这是所有后续测试的前提
2. **验证 BUG-001/002 修复** — 已做代码修复，需确认重启后稳定

### 优先级 P1（影响功能验证）
3. **修复模型选择器 (BUG-004)** — Desktop 核心功能
4. **修复种子数据 (BUG-006~009)** — Admin V2 多页面数据不可见
5. **添加 Tauri IPC 降级 (BUG-005)** — Dev 模式兼容

### 优先级 P2（优化）
6. **调整 Rate Limit 策略 (BUG-010)**
7. **统一分类命名** — Config 页面分类名与种子数据对齐

---

*报告生成时间: 2026-03-30 22:15 CST*
*测试工具: Chrome DevTools MCP + 手动验证*

---

## 九、第二轮修复记录 (2026-03-31)

### 修复汇总

| Bug ID | 修复文件 | 修改内容 |
|--------|----------|----------|
| BUG-003 | `crates/zclaw-saas/src/db.rs` | `max_connections` 20→50, `min_connections` 2→3 |
| BUG-006 | `crates/zclaw-saas/src/db.rs` | 新增 `account_api_keys` 种子数据（旧种子写入 `api_tokens` 表，handler 读 `account_api_keys` 表） |
| BUG-007 | `crates/zclaw-saas/src/db.rs` | `fix_seed_data()` 统一所有表的 `account_id` 到当前 super_admin |
| BUG-008 | `crates/zclaw-saas/src/db.rs` | 同 BUG-007，usage_records 1475 行已修复 |
| BUG-009 | `crates/zclaw-saas/src/db.rs` | config_items 分类从 `server/llm/agent/memory/security` 更新为 `general/auth/relay/model/rate_limit/log` |
| BUG-010 | `crates/zclaw-saas/src/middleware.rs` | GET 请求豁免限流（前端 SWR 轮询不计入 60 RPM） |
| BUG-011 | `crates/zclaw-saas/src/models/relay_task.rs` | `priority`/`attempt_count`/`max_attempts`/`input_tokens`/`output_tokens` 从 `i64` 改为 `i32`（匹配 PostgreSQL INT4） |

### 新增函数：`fix_seed_data()`

在 `db.rs` 中添加了 `fix_seed_data()` 函数，在每次启动时自动修复旧种子数据：

1. **Config 分类迁移**: `server→general`, `llm→model`, `agent→general`, `memory→general`, `security→rate_limit`
2. **Account API Keys 补种**: 为每个 super_admin 账号插入 3 条演示 API Key
3. **Account ID 统一**: 将 relay_tasks、usage_records、operation_logs、telemetry_reports 的 account_id 统一为第一个 super_admin

### 验证结果

| 端点 | 修复前 | 修复后 |
|------|--------|--------|
| `GET /api/v1/keys` | `{total: 0}` | `{total: 3}` ✅ |
| `GET /api/v1/usage?group_by=day` | `{by_day: []}` | `{total_requests: 1475, by_day: 30天}` ✅ |
| `GET /api/v1/usage?group_by=model` | `{by_model: []}` | `{by_model: 5模型}` ✅ |
| `GET /api/v1/config/items?category=general` | `{total: 0}` | `{total: 6}` ✅ |
| `GET /api/v1/config/items?category=model` | `{total: 0}` | `{total: 3}` ✅ |
| `GET /api/v1/config/items?category=rate_limit` | `{total: 0}` | `{total: 3}` ✅ |
| `GET /api/v1/relay/tasks` | 500 (类型错误) | 200 ✅ |

### 仍待修复

| Bug ID | 描述 | 原因 |
|--------|------|------|
| BUG-004 | Desktop 模型选择器卡在"加载中" | saasStore 与 configStore 数据桥未同步 |
| BUG-005 | Desktop 自动化面板崩溃 | Tauri IPC 无降级 |

---

*第二轮修复时间: 2026-03-31 00:00 CST*