# 平台自动化测试可视化系统 - 开发进度报告

> **文档版本**: v1.3
> **创建日期**: 2026-07-10
> **项目状态**: Phase 5 进行中

---

## 一、项目概述

### 1.1 项目目标

构建一个 **Web 可视化自动化测试平台**，核心创新点在于**用例录制器**功能——用户通过在目标网站上进行实际操作，系统自动捕获行为并转换为测试步骤，无需手动编写测试代码。

### 1.2 技术栈

| 层级 | 技术 | 版本 |
|------|------|------|
| 后端框架 | FastAPI | ^0.110.x |
| 前端框架 | Vue 3 + Element Plus | ^3.4.x / ^2.5.x |
| 数据库 | SQLite | 3.x |
| ORM | SQLAlchemy | ^2.0.x |
| 浏览器自动化 | Playwright | ^1.40.x |
| 实时通信 | WebSocket | FastAPI 内置 |
| 图表库 | ECharts | ^5.5.x |

---

## 二、项目结构

```
platform-auto-test/
├── Docs/PRD/自动化测试平台/
│   ├── _PRD_平台自动化测试可视化系统需求文档.md          # PRD 需求文档
│   └── _PRD_平台自动化测试可视化系统需求文档_计划执行.md  # 执行计划文档
│
├── backend/                          # 后端（Python FastAPI）
│   ├── requirements.txt              # Python 依赖
│   └── app/
│       ├── main.py                   # FastAPI 入口（CORS、路由注册、生命周期）
│       ├── config.py                 # 配置管理（环境变量、路径配置）
│       ├── database.py               # SQLite 异步引擎、会话管理、表初始化
│       ├── models/                   # 数据模型层
│       │   ├── module.py             # 模块表
│       │   ├── test_case.py          # 用例表
│       │   ├── execution.py          # 执行记录表
│       │   └── case_result.py        # 用例结果表
│       ├── schemas/                  # Pydantic 数据校验层
│       │   ├── module.py             # 模块 CRUD 模式
│       │   └── test_case.py          # 用例 CRUD + 导入导出模式
│       ├── routers/                  # API 路由层
│       │   ├── modules.py            # 模块管理 API（6 个端点）
│       │   ├── cases.py              # 用例管理 API（8 个端点）
│       │   ├── executions.py         # 执行管理 API（7 个端点 + WebSocket）
│       │   ├── recorder.py           # 录制器 API（6 个端点）
│       │   ├── stats.py              # 统计分析 API（6 个端点）
│       │   └── reports.py            # 报告管理 API（4 个端点）
│       ├── services/                 # 业务逻辑层
│       │   ├── module_service.py     # 模块服务（CRUD + 统计）
│       │   ├── case_service.py       # 用例服务（CRUD + 导入导出 + 复制）
│       │   ├── execution_service.py  # 执行服务（调度 + 实时回调 + 结果统计）
│       │   └── report_service.py     # 报告服务（HTML 生成 + 导出 + 下载）
│       ├── executors/                # 测试执行引擎
│       │   └── playwright_executor.py # Playwright 执行器（11 种动作 + 8 种断言）
│       ├── websocket/                # 实时通信
│       │   └── manager.py            # WebSocket 连接管理（分组广播 + 断线重连）
│       ├── utils/                    # 工具函数
│       │   └── id_generator.py       # UUID ID 生成器
│       └── tasks/                    # 定时任务（预留）
│
├── frontend/                         # 前端（Vue 3 + TypeScript）
│   ├── package.json                  # 依赖配置
│   ├── vite.config.ts                # Vite 构建配置（代理、别名）
│   ├── index.html                    # HTML 入口
│   └── src/
│       ├── main.ts                   # 应用入口（Element Plus、Pinia 注册）
│       ├── App.vue                   # 根组件（侧边栏导航 + 顶部栏 + 路由出口）
│       ├── router/index.ts           # Vue Router（7 个路由，懒加载）
│       ├── types/                    # TypeScript 类型定义
│       │   ├── module.ts             # 模块类型
│       │   ├── case.ts               # 用例类型
│       │   └── execution.ts          # 执行记录类型
│       ├── utils/                    # 工具
│       │   ├── request.ts            # Axios 封装（拦截器、错误处理）
│       │   └── websocket.ts          # WebSocket 客户端（断线重连、事件驱动）
│       ├── api/                      # API 调用层
│       │   ├── modules.ts            # 模块 API
│       │   ├── cases.ts              # 用例 API
│       │   ├── executions.ts         # 执行管理 API
│       │   ├── stats.ts              # 统计分析 API
│       │   ├── reports.ts            # 报告管理 API
│       │   └── recorder.ts           # 录制器 API
│       ├── components/               # 公共组件
│       │   └── StepDetailPanel.vue   # 步骤详情面板
│       └── views/                    # 页面组件
│           ├── Dashboard.vue         # 总览（统计卡片 + 趋势图表 + 快捷操作）
│           ├── Modules.vue           # 模块管理（卡片展示 + CRUD 弹窗）
│           ├── Cases.vue             # 用例管理（列表 + CRUD + 导入导出）
│           ├── Recorder.vue          # 用例录制（录制配置 + 步骤捕获 + 断言）
│           ├── Execution.vue         # 执行中心（实时进度 + WebSocket + 历史列表）
│           ├── Reports.vue           # 报告中心（预览 + 导出 + 下载）
│           └── Settings.vue          # 系统配置（占位）
│
└── data/                             # 数据目录（gitignore）
    └── test_platform.db              # SQLite 数据库文件
```

---

## 三、进度总览

### 3.1 各阶段完成情况

| 阶段 | 内容 | 计划 | 状态 | 完成度 |
|------|------|------|------|--------|
| Phase 1 | 基础框架搭建 | 2-3 天 | ✅ 已完成 | 100% |
| Phase 2 | 核心功能开发 | 4-5 天 | ✅ 已完成 | 100% |
| Phase 3 | 执行与可视化 | 3-4 天 | ✅ 已完成 | 100% |
| Phase 4 | 分析与报告 | 2-3 天 | ✅ 已完成 | 100% |
| Phase 5 | 扩展与优化 | 2-3 天 | 进行中 | 30% |

### 3.2 任务完成详情

#### Phase 1: 基础框架搭建（已完成）

| 任务ID | 任务名称 | 状态 | 说明 |
|--------|---------|------|------|
| P1-001 | 创建项目目录结构 | ✅ 完成 | backend/ + frontend/ 目录结构 |
| P1-002 | 后端框架搭建 | ✅ 完成 | FastAPI 入口、配置、CORS |
| P1-003 | 数据库初始化 | ✅ 完成 | SQLite 引擎 + 4 个 ORM 模型 |
| P1-004 | 模块 CRUD API | ✅ 完成 | 模块服务 + 路由 |
| P1-005 | 前端框架搭建 | ✅ 完成 | Vue3 + Element Plus + 布局 |
| P1-006 | 前端路由配置 | ✅ 完成 | 7 个路由配置 + 侧边栏导航 |

#### Phase 2: 核心功能开发（已完成）

| 任务ID | 任务名称 | 状态 | 说明 |
|--------|---------|------|------|
| P2-001 | 用例数据模型 | ✅ 完成 | TestCase 模型 + 步骤 JSON 结构 |
| P2-002 | 用例 CRUD API | ✅ 完成 | 8 个端点 + 导入导出 + 复制 |
| P2-003 | 录制器核心实现 | ✅ 完成 | Playwright 浏览器录制 + 事件捕获 |
| P2-004 | 录制器 API | ✅ 完成 | 启动/停止/保存/断言 API |
| P2-005 | 前端模块页面 | ✅ 完成 | 卡片展示 + 创建/编辑弹窗 |
| P2-006 | 前端用例列表 | ✅ 完成 | 表格 + 筛选搜索 |
| P2-007 | 前端录制器页面 | ✅ 完成 | 录制窗口 + 步骤列表 + 保存 |

#### Phase 3: 执行与可视化（已完成）

| 任务ID | 任务名称 | 状态 | 说明 |
|--------|---------|------|------|
| P3-001 | 执行记录模型 | ✅ 完成 | Execution + CaseResult 模型 |
| P3-002 | 执行调度器 | ✅ 完成 | 任务队列 + 并发控制 |
| P3-003 | Playwright 执行器 | ✅ 完成 | 11 种动作 + 8 种断言 + 截图 |
| P3-004 | WebSocket 推送 | ✅ 完成 | 连接管理 + 分组广播 + 断线重连 |
| P3-005 | 执行 API | ✅ 完成 | 创建/运行/取消 + WebSocket 端点 |
| P3-006 | 前端执行页面 | ✅ 完成 | 实时进度 + 历史列表 + 结果展开 |
| P3-007 | 步骤详情组件 | ✅ 完成 | 截图展示 + 日志查看器 + 错误详情 |

#### Phase 4: 分析与报告（已完成）

| 任务ID | 任务名称 | 状态 | 说明 |
|--------|---------|------|------|
| P4-001 | 统计分析 API | ✅ 完成 | 6 个端点：总览/趋势/模块/优先级/状态 |
| P4-002 | 报告生成服务 | ✅ 完成 | HTML 报告生成 + 导出 + 下载 |
| P4-003 | 报告管理 API | ✅ 完成 | 4 个端点：生成/导出/下载/列表 |
| P4-004 | 前端总览页面 | ✅ 完成 | ECharts 趋势图 + 饼图 + 统计卡片 |
| P4-005 | 前端报告页面 | ✅ 完成 | 报告预览 + 导出 + 下载 |

#### Phase 5: 扩展与优化（进行中 30%）

| 任务ID | 任务名称 | 状态 | 说明 |
|--------|---------|------|------|
| P5-001 | Excel 用例导入 | ✅ 完成 | 从 Excel 导入 61 个模块、80 条用例（含 JSON 步骤） |
| P5-002 | 执行引擎调通 | ✅ 完成 | Playwright 同步执行方式验证通过，支持有头/无头模式 |
| P5-003 | 数据库锁修复 | ✅ 完成 | SQLite check_same_thread + pool_pre_ping 配置 |
| P5-004 | 用例步骤增强 | ✅ 完成 | 导入时自动添加 navigate 导航步骤 |
| P5-005 | 前端请求修复 | ✅ 完成 | baseURL 双重 /api 路径修复、代理端口更新 |
| P5-006 | 系统配置页面 | ⏳ 待开始 | Settings.vue 功能实现 |
| P5-007 | Pinia 状态管理 | ⏳ 待开始 | 创建 executionStore / settingsStore |
| P5-008 | 单元测试 | ⏳ 待开始 | 后端 pytest + 前端 Vitest |
| P5-009 | 数据库迁移 | ⏳ 待开始 | Alembic 配置和管理 |
| P5-010 | 定时任务 | ⏳ 待开始 | 定时执行 + 数据清理 |
| P5-011 | 前端布局抽取 | ⏳ 待开始 | 独立 Layout 组件 + 侧边栏折叠 |
| P5-012 | 开发环境完善 | ⏳ 待开始 | ESLint/Prettier/.env/测试框架 |
| P5-013 | Docker 部署 | ⏳ 待开始 | Docker Compose 配置 |
| P5-014 | 后台执行优化 | ⏳ 待开始 | Windows 下子进程/队列方式实现异步执行 |

---

## 四、代码统计

### 4.1 文件统计

| 类别 | 文件数 | 占比 |
|------|--------|------|
| 后端 Python 文件 | 31 | 57% |
| 前端 Vue/TS 文件 | 23 | 43% |
| **总计** | **54** | **100%** |

### 4.2 代码行数统计

| 模块 | 代码行数 |
|------|---------|
| 后端（31 个 Python 文件） | ~5,600 |
| 前端（23 个 Vue/TS 文件） | ~950 |
| **总计** | **~6,560** |

---

## 五、API 接口清单

### 5.1 模块管理

| 方法 | 路径 | 说明 | 状态 |
|------|------|------|------|
| GET | `/api/modules` | 获取模块列表（分页） | ✅ |
| POST | `/api/modules` | 创建模块 | ✅ |
| GET | `/api/modules/{id}` | 获取模块详情 | ✅ |
| PUT | `/api/modules/{id}` | 更新模块 | ✅ |
| DELETE | `/api/modules/{id}` | 删除模块（级联删除用例） | ✅ |
| GET | `/api/modules/{id}/stats` | 获取模块统计 | ✅ |

### 5.2 用例管理

| 方法 | 路径 | 说明 | 状态 |
|------|------|------|------|
| GET | `/api/cases` | 获取用例列表（筛选/搜索/分页） | ✅ |
| POST | `/api/cases` | 创建用例 | ✅ |
| GET | `/api/cases/{id}` | 获取用例详情 | ✅ |
| PUT | `/api/cases/{id}` | 更新用例 | ✅ |
| DELETE | `/api/cases/{id}` | 删除用例 | ✅ |
| POST | `/api/cases/{id}/copy` | 复制用例 | ✅ |
| POST | `/api/cases/import` | 批量导入用例 | ✅ |
| POST | `/api/cases/export` | 导出用例 | ✅ |

### 5.3 执行管理

| 方法 | 路径 | 说明 | 状态 |
|------|------|------|------|
| GET | `/api/executions` | 获取执行记录列表 | ✅ |
| POST | `/api/executions` | 创建执行任务 | ✅ |
| GET | `/api/executions/{id}` | 获取执行详情 | ✅ |
| POST | `/api/executions/{id}/run` | 启动执行 | ✅ |
| POST | `/api/executions/{id}/cancel` | 取消执行 | ✅ |
| GET | `/api/executions/{id}/results` | 获取执行结果列表 | ✅ |
| GET | `/api/executions/{id}/results/{case_id}` | 获取单个用例结果 | ✅ |
| WS | `/api/executions/ws/{id}` | 执行状态实时推送 | ✅ |

### 5.4 统计分析

| 方法 | 路径 | 说明 | 状态 |
|------|------|------|------|
| GET | `/api/stats/overview` | 总览统计 | ✅ |
| GET | `/api/stats/trend` | 趋势统计 | ✅ |
| GET | `/api/stats/modules` | 模块统计 | ✅ |
| GET | `/api/stats/module/{id}` | 模块详情统计 | ✅ |
| GET | `/api/stats/priority` | 优先级分布 | ✅ |
| GET | `/api/stats/status` | 状态分布 | ✅ |

### 5.5 报告管理

| 方法 | 路径 | 说明 | 状态 |
|------|------|------|------|
| GET | `/api/reports/generate/{id}` | 生成 HTML 报告 | ✅ |
| POST | `/api/reports/export/{id}` | 导出报告文件 | ✅ |
| GET | `/api/reports/download/{id}` | 下载报告文件 | ✅ |
| GET | `/api/reports/list` | 获取可生成报告的执行列表 | ✅ |

### 5.6 录制器

| 方法 | 路径 | 说明 | 状态 |
|------|------|------|------|
| POST | `/api/recorder/start` | 启动录制会话 | ✅ |
| GET | `/api/recorder/steps` | 获取已录制步骤 | ✅ |
| POST | `/api/recorder/step` | 添加录制步骤 | ✅ |
| POST | `/api/recorder/assertion` | 添加断言 | ✅ |
| POST | `/api/recorder/stop` | 停止录制 | ✅ |
| POST | `/api/recorder/save` | 保存为用例 | ✅ |

---

## 六、执行引擎能力

### 6.1 支持的动作类型（13 种）

| 动作 | 说明 | 参数 |
|------|------|------|
| `navigate` | 页面导航（等待网络空闲） | `{url: string}` |
| `click` | 点击元素 | `{selector: string}` |
| `fill` | 填充输入框（先清空） | `{selector, value}` |
| `select` | 选择下拉框 | `{selector, value}` |
| `hover` | 鼠标悬停 | `{selector}` |
| `wait` | 等待元素出现 | `{selector, timeout}` |
| `scroll` | 滚动页面 | `{direction, distance}` |
| `press` | 按键操作 | `{key, selector?}` |
| `check` | 勾选复选框 | `{selector}` |
| `uncheck` | 取消勾选 | `{selector}` |
| `assert` | 断言验证 | `{selector, type, expected}` |
| `screenshot` | 手动截图 | `{path, full_page}` |
| `upload` | 文件上传 | `{selector, file}` |

### 6.2 支持的断言类型（8 种）

| 断言 | 说明 | 示例 |
|------|------|------|
| `visible` | 元素可见 | `.user-info` 应可见 |
| `hidden` | 元素隐藏 | `.loading` 应隐藏 |
| `text` | 文本精确匹配 | `.title` 文本应为 "首页" |
| `contains` | 文本包含 | `.msg` 应包含 "成功" |
| `value` | 输入框值匹配 | `#username` 应为 "admin" |
| `count` | 元素数量匹配 | `.item` 应有 5 个 |
| `url` | URL 匹配 | 当前URL 包含 "/home" |
| `title` | 页面标题匹配 | 标题包含 "系统" |

### 6.3 选择器优先级策略

| 优先级 | 策略 | 示例 |
|--------|------|------|
| 1 | test-id 属性 | `[data-testid="login-btn"]` |
| 2 | id 属性 | `#login-btn` |
| 3 | 语义化属性 | `[aria-label="登录"]` |
| 4 | role 属性 | `button[role="button"]` |
| 5 | 文本内容 | `text=登录` |
| 6 | CSS 类名 | `.login-button` |
| 7 | 层级组合 | `div > button.submit` |

---

## 七、WebSocket 实时推送

### 7.1 消息类型

| 类型 | 触发时机 | 数据内容 |
|------|---------|---------|
| `execution_start` | 执行任务开始 | 执行记录完整数据 |
| `case_start` | 单个用例开始 | execution_id, case_id, case_name |
| `step_update` | 步骤完成 | execution_id, case_id, step_order, status, duration, screenshot, error |
| `case_complete` | 单个用例完成 | 用例结果完整数据 |
| `execution_complete` | 执行全部完成 | 执行记录完整数据 |
| `execution_cancelled` | 执行被取消 | 执行记录完整数据 |

### 7.2 前端 WebSocket 客户端特性

- 自动断线重连（最多 3 次）
- 事件驱动架构（on/off 模式）
- 自动解析 JSON 消息
- 支持通配符监听器 `*`

---

## 八、被测系统信息

### 8.1 系统概况

| 项目 | 内容 |
|------|------|
| 系统名称 | 统一管理平台 |
| 登录 URL | https://192.168.5.44 |
| 登录方式 | 密码登录 |
| 登录用户 | admin@xty |
| 登录密码 | Ubains@13579 |
| 验证码 | csba（固定值） |

### 8.2 功能模块

| 模块 | 子功能 |
|------|--------|
| 会议管理 | 新建会议、会议模板、会议列表、预定数据 |
| 日程管理 | 个人日程、会议室列表 |
| 数据分析 | 使用数据、故障数据、会议统计、Welink 会议统计、SMC3.0 会议统计 |
| 运维管理 | 运维数据、运维统计、巡检报表 |
| 管理看板 | 管理看板、会议室概览、会议概览、通知统计 |

---

## 九、待办事项

### 9.1 Phase 5 任务清单

| 优先级 | 任务 | 状态 | 说明 |
|--------|------|------|------|
| 🟢 P0 | Excel 用例导入 | ✅ 已完成 | 61 个模块、80 条用例 |
| 🟢 P0 | 执行引擎调通 | ✅ 已完成 | Playwright 同步执行验证通过 |
| 🟢 P0 | 数据库锁修复 | ✅ 已完成 | check_same_thread + pool_pre_ping |
| 🟢 P0 | 前端请求修复 | ✅ 已完成 | baseURL + 代理 + 超时 |
| 🔴 P0 | 系统配置页面 | ⏳ 待开始 | Settings.vue 功能实现 |
| 🔴 P0 | Pinia 状态管理 | ⏳ 待开始 | 创建 executionStore / settingsStore |
| 🔴 P0 | 单元测试 | ⏳ 待开始 | 后端 pytest + 前端 Vitest |
| 🟡 P1 | 数据库迁移 | ⏳ 待开始 | Alembic 配置和管理 |
| 🟡 P1 | 后台执行优化 | ⏳ 待开始 | Windows 子进程/队列异步执行 |
| 🟡 P1 | 前端布局抽取 | ⏳ 待开始 | 独立 Layout 组件 + 侧边栏折叠 |
| 🔵 P2 | 定时任务 | ⏳ 待开始 | Celery/APScheduler 定时执行 |
| 🔵 P2 | 开发环境完善 | ⏳ 待开始 | ESLint/Prettier/.env/测试框架 |
| 🔵 P2 | Docker 部署 | ⏳ 待开始 | Docker Compose 配置 |

### 9.2 远期规划

| 任务 | 说明 |
|------|------|
| 升级数据库为 PostgreSQL | 解决 SQLite 性能瓶颈 |
| 添加用户权限管理 | 多用户、角色权限 |
| 支持分布式执行 | 多节点并行执行 |
| 对接 CI/CD 系统 | Jenkins/GitLab CI 集成 |
| 用例预览功能 | 预览用例执行过程（不保存结果） |
| 多浏览器录制 | 支持 Firefox/Edge 录制 |

---

## 十、启动指南

### 10.1 环境要求

| 环境 | 版本要求 |
|------|---------|
| Python | ^3.10 |
| Node.js | ^18.0 |
| SQLite | ^3.0 |

### 10.2 启动命令

```bash
# 1. 安装后端依赖
cd backend
pip install -r requirements.txt

# 2. 安装 Playwright 浏览器
playwright install chromium

# 3. 启动后端（端口 8000）
uvicorn app.main:app --reload --port 8000

# 4. 安装前端依赖
cd frontend
npm install

# 5. 启动前端（端口 3000）
npm run dev
```

### 10.3 访问地址

| 服务 | 地址 |
|------|------|
| 前端页面 | http://localhost:3000 |
| API 文档 | http://localhost:8001/docs |
| ReDoc 文档 | http://localhost:8001/redoc |
| 健康检查 | http://localhost:8001/health |

---

## 十一、2026-07-10 修复记录

### 11.1 数据库相关
| 问题 | 原因 | 修复 |
|------|------|------|
| SQLite database is locked | 同步执行期间并发写入冲突 | 添加 `check_same_thread=False` 和 `pool_pre_ping=True` |
| NOT NULL constraint failed: error_message | 模型字段 `nullable=False` 但执行成功后 error_message 为 None | 改为 `nullable=True` |

### 11.2 前端相关
| 问题 | 原因 | 修复 |
|------|------|------|
| 加载用例列表 404 | `baseURL: '/api'` 与 API 路径 `/api/cases` 组合成 `/api/api/cases` | `baseURL` 改为空字符串 |
| 导入用例 JSON 语法错误 | Cases.vue 连续两个 catch 块 | 合并为单个 catch，用 instanceof 区分 |
| 执行请求超时 | axios 30s 超时，Playwright 执行需要更长时间 | 超时改为 5 分钟 |

### 11.3 后端相关
| 问题 | 原因 | 修复 |
|------|------|------|
| 后台执行不工作 | Windows + uvicorn 下 asyncio.create_task/threading/multiprocessing 均失败 | 改为同步阻塞执行 |
| 执行报"状态为 running" | 同步执行中状态已改为 running 但前端超时后再请求冲突 | 同步执行 + 前端超时 5 分钟 |
| 用例缺少 navigate 步骤 | 导入时未提取 Excel JSON 中的 base_url | 导入脚本自动添加 navigate 第一步 |
| Playwright 浏览器未安装 | 安装依赖时未安装浏览器 | `playwright install chromium` |

### 11.4 已导入数据
- 模块：61 个（对应 Excel 所有 Sheet）
- 用例：80 条（含 JSON 步骤定义的用例）
- 执行记录：5 条（1 条成功执行完成）

### 11.5 当前运行状态
- 后端：8001 端口（同步执行模式）
- 前端：3000 端口（代理指向 8001）
- 执行引擎：Playwright Chromium，支持有头/无头模式
- 目标网站：https://192.168.5.44/（需手动更新用例 URL）

---

**文档结束**

*本文档由 Claude 生成，记录截至 2026-07-10 的开发进度。*