# 测试用例管理优化 - 第一阶段完成报告

## 执行日期
2026-07-12

---

## 一、完成情况

### ✅ 已完成任务

| 任务 | 状态 | 文件 | 说明 |
|------|------|------|------|
| #1 创建 CaseDependency 模型 | ✅ 完成 | `backend/app/models/case_dependency.py` | 用例依赖关系模型，支持硬依赖和软依赖 |
| #2 扩展 TestCase 模型 | ✅ 完成 | `backend/app/models/test_case.py` | 新增 depends_on, parameters, condition, order, version 字段 |
| #3 实现 DependencyService | ✅ 完成 | `backend/app/services/dependency_service.py` | 依赖管理服务，包含拓扑排序和循环依赖检测算法 |
| #4 实现 BatchService | ✅ 完成 | `backend/app/services/batch_service.py` | 批量操作服务，支持批量删除/更新/复制/标签/优先级 |
| #5 新增依赖管理 API | ✅ 完成 | `backend/app/routers/dependencies.py` | 依赖管理相关 API 接口 |
| #6 新增批量操作 API | ✅ 完成 | `backend/app/routers/batch.py` | 批量操作相关 API 接口 |
| #7 编写数据库迁移脚本 | ✅ 完成 | `backend/scripts/migration_add_dependencies.py` | 数据库迁移脚本，已成功执行 |

---

## 二、新增文件清单

### 数据模型层
- `backend/app/models/case_dependency.py` - 用例依赖关系模型

### Schema层
- `backend/app/schemas/dependency.py` - 依赖管理相关 Schema
- `backend/app/schemas/batch.py` - 批量操作相关 Schema

### 服务层
- `backend/app/services/dependency_service.py` - 依赖管理服务
- `backend/app/services/batch_service.py` - 批量操作服务

### API路由层
- `backend/app/routers/dependencies.py` - 依赖管理 API 路由
- `backend/app/routers/batch.py` - 批量操作 API 路由

### 脚本
- `backend/scripts/migration_add_dependencies.py` - 数据库迁移脚本

---

## 三、修改文件清单

| 文件 | 修改内容 |
|------|----------|
| `backend/app/models/test_case.py` | 添加新字段：depends_on, parameters, condition, order, version<br>添加关联关系：dependencies, dependents |
| `backend/app/main.py` | 注册新路由：batch, dependencies |
| `backend/app/database.py` | 数据库表结构自动创建（通过Base.metadata） |

---

## 四、核心功能实现

### 1. 依赖管理

**CaseDependency 模型：**
```python
class CaseDependency(Base):
    id: str                    # 依赖关系ID
    case_id: str               # 用例ID（依赖方）
    depends_on_case_id: str    # 被依赖的用例ID
    dependency_type: str       # hard(强依赖)/soft(弱依赖)
    order: int                 # 依赖顺序
    created_at: datetime       # 创建时间
```

**DependencyService 核心方法：**
- `get_case_dependencies()` - 获取用例依赖关系
- `set_case_dependencies()` - 设置用例依赖关系（含验证）
- `validate_dependencies()` - 验证依赖关系（检测循环）
- `topological_sort()` - 拓扑排序（Kahn算法）
- `get_execution_order()` - 计算执行顺序（拓扑+优先级）
- `check_dependency_status()` - 检查依赖状态

**关键算法：**
```python
# 拓扑排序（Kahn算法）
def topological_sort(case_ids):
    # 构建依赖图
    # 计算入度
    # 零入度队列
    # 在依赖级别内按优先级排序
    # 检测循环依赖
    return ordered_ids, cycle
```

### 2. 批量操作

**BatchService 核心方法：**
- `batch_delete()` - 批量删除用例
- `batch_update()` - 批量更新用例
- `batch_copy()` - 批量复制用例
- `batch_assign_tags()` - 批量分配标签
- `batch_set_priority()` - 批量设置优先级
- `batch_enable()` - 批量启用
- `batch_disable()` - 批量禁用
- `batch_move_to_module()` - 批量移动到模块

---

## 五、API 接口

### 依赖管理接口

| 方法 | 路径 | 功能 |
|------|------|------|
| GET | `/api/cases/{case_id}/dependencies` | 获取用例依赖关系 |
| POST | `/api/cases/{case_id}/dependencies` | 设置用例依赖关系 |
| POST | `/api/validate` | 验证依赖关系（检测循环） |
| POST | `/api/execution-order` | 计算执行顺序 |
| GET | `/api/cases/{case_id}/dependency-status` | 检查依赖状态 |

### 批量操作接口

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/api/batch/delete` | 批量删除 |
| POST | `/api/batch/update` | 批量更新 |
| POST | `/api/batch/copy` | 批量复制 |
| POST | `/api/batch/assign-tags` | 批量分配标签 |
| POST | `/api/batch/set-priority` | 批量设置优先级 |
| POST | `/api/batch/enable` | 批量启用 |
| POST | `/api/batch/disable` | 批量禁用 |

---

## 六、数据库变更

### 新增表

**case_dependencies 表：**
- id (TEXT PRIMARY KEY)
- case_id (TEXT NOT NULL)
- depends_on_case_id (TEXT NOT NULL)
- dependency_type (TEXT DEFAULT 'hard')
- "order" (INTEGER DEFAULT 0)
- created_at (TIMESTAMP)

### 扩展字段

**test_cases 表：**
- depends_on (JSON DEFAULT '[]')
- parameters (JSON DEFAULT '{}')
- condition (JSON DEFAULT '{}')
- "order" (INTEGER DEFAULT 0)
- version (INTEGER DEFAULT 1)

**executions 表：**
- execution_mode (TEXT DEFAULT 'sequential')
- max_parallel (INTEGER DEFAULT 1)
- param_values (JSON DEFAULT '{}')

**case_results 表：**
- param_instance (JSON DEFAULT '{}')
- dependency_status (TEXT DEFAULT 'ok')
- condition_met (BOOLEAN DEFAULT 1)

---

## 七、使用示例

### 1. 设置用例依赖关系

```python
# 用例 case_002 依赖 case_001
POST /api/cases/case_002/dependencies
{
    "dependencies": [
        {
            "depends_on_case_id": "case_001",
            "dependency_type": "hard",
            "order": 1
        }
    ]
}
```

### 2. 验证依赖关系

```python
POST /api/validate?case_ids=case_001,case_002,case_003

# 响应
{
    "valid": true,
    "cycle": null,
    "message": "依赖关系有效，无循环"
}
```

### 3. 计算执行顺序

```python
POST /api/execution-order?case_ids=case_001,case_002,case_003

# 响应
{
    "ordered_case_ids": ["case_001", "case_002", "case_003"],
    "has_cycle": false,
    "cycle_path": null
}
```

### 4. 批量删除用例

```python
POST /api/batch/delete
{
    "case_ids": ["case_001", "case_002", "case_003"]
}

# 响应
{
    "success": 3,
    "failed": 0,
    "total": 3,
    "message": "成功删除 3 个用例"
}
```

---

## 八、下一步计划

### 第二阶段：参数化和条件执行

**待完成任务：**
1. 创建 CaseParameter 模型
2. 创建 ParameterSet 模型
3. 实现 ParameterService（变量替换）
4. 实现 ConditionService（条件评估）
5. 改造 PlaywrightExecutor（支持参数化）
6. 扩展 ExecutionService（参数解析）

**预计工作量：** 3-5天

---

## 九、注意事项

### 已知问题
1. SQLite 的 order 字段是保留关键字，需要用双引号包围
2. 数据库迁移脚本中的 ALTER TABLE 可能因字段已存在而失败（已处理）
3. 循环依赖检测使用 DFS 算法，可能需要优化性能

### 建议
1. 在生产环境部署前，先在测试环境验证迁移脚本
2. 为 case_dependencies 表添加复合索引以提升查询性能
3. 考虑使用 Alembic 进行正式的数据库版本管理

---

## 十、测试建议

### 单元测试
```python
# tests/test_dependency_service.py
def test_topological_sort():
    # 测试拓扑排序算法
    pass

def test_detect_cycle():
    # 测试循环依赖检测
    pass
```

### 集成测试
```python
# tests/test_dependency_api.py
def test_set_dependencies():
    # 测试设置依赖关系API
    pass

def test_validate_dependencies():
    # 测试验证依赖关系API
    pass
```

---

**完成日期：** 2026-07-12
**下一阶段启动时间：** 待定