# pytest + Jenkins 自动化执行接入后端详细方案（MVC / 可直接交付 AI 编码）

## 1. 目标与边界

### 1.1 目标
基于当前项目 `D:\zhyy\effekt-interface` 的现有 MVC 结构，为“计划中的自动化用例执行”设计一套可直接落地的后端方案，支持：

1. 单条功能用例触发自动化执行。
2. 测试计划维度批量触发自动化执行。
3. 自动化项目基于 `pytest` 执行指定 `case_id` 对应的用例。
4. Jenkins 作为统一调度入口。
5. 平台记录执行任务、执行明细、状态流转、Jenkins 构建信息、回调结果。
6. 方案需适配当前项目的 MVC 分层：
   - controller: `app/api/controller/*.py`
   - service: `app/api/service/*.py`
   - dao: `app/api/dao/*.py`
   - model: `app/api/model/*.py`
   - route: `app/api/views.py`

### 1.2 已知现状
经代码结构确认：

- 当前项目是 Flask + SQLAlchemy Session 的轻量 MVC。
- 已有测试计划、计划用例、测试用例表：
  - `test_plan`
  - `plan_case`
  - `test_case`
- 当前计划执行 `plan_case_execute` 仅支持手工回填结果，不支持自动化编排。
- 功能用例与自动化用例的桥梁是 `case_id`。
- `test_case.is_auto` 已可区分是否自动化。
- 当前 controller/service/dao 的风格是：
  - controller 做参数校验和聚合返回
  - service 主要转发 dao 或封装少量业务
  - dao 负责数据库 CRUD
- 当前项目已有 HTTP 请求封装：`common/getRequest.py -> Request.go(...)`
- 当前有 `common/cronRequest.py` 作为外部系统请求示例，但不适合直接复用为 Jenkins 客户端，建议新增独立 Jenkins 请求封装。

### 1.3 本期边界
只设计后端逻辑，不做前端实现，不写自动化项目代码，但会定义自动化项目与平台的接口契约。

---

## 2. 总体架构设计

推荐采用：

**平台编排 + Jenkins 参数化触发 + pytest 项目按 execution_id 拉取执行清单 + 回调平台写回结果**

### 2.1 责任划分

#### 平台（本项目）
负责：
- 识别单条/计划执行请求
- 校验用例是否可自动化执行
- 创建执行记录
- 调用 Jenkins Job
- 提供执行清单查询接口给 pytest 项目拉取
- 接收执行中/执行完成回调
- 聚合执行结果并更新计划状态

#### Jenkins
负责：
- 接收平台触发请求
- 以参数化方式启动自动化项目
- 记录构建号、日志、报告地址
- 失败兜底回调平台

#### pytest 自动化项目
负责：
- 接收 Jenkins 参数
- 通过 `execution_id` 调平台接口获取待执行 case 列表
- 按 `case_id` 映射执行 pytest 用例
- 回调平台单条结果和最终结果
- 输出 junit/allure/json 等结果

### 2.2 为什么不直接把 case_id 列表塞进 Jenkins 参数
不推荐直接传长列表，理由：
- 计划内用例多时参数长度不可控。
- URL/参数转义复杂。
- 后续扩展环境、标签、重跑等字段时耦合变高。
- 执行审计不清晰。

推荐只传 `execution_id`，由 pytest 项目回平台拉取清单。

---

## 3. 与当前 MVC 框架的集成方式

### 3.1 新增模块建议
在现有 `case / plan / report` 域外，新增一个独立“自动化执行域”：

- controller: `app/api/controller/automationController.py`
- service: `app/api/service/automationService.py`
- dao: `app/api/dao/automationDao.py`
- model: `app/api/model/automationModel.py`
- util/client: `common/jenkinsRequest.py`

### 3.2 为什么独立成 automation 域
不要把自动化执行逻辑继续塞进 `planController.py` 或 `caseController.py`，原因：
- 自动化执行有独立生命周期，不只是计划或用例的附属字段。
- 涉及外部系统 Jenkins 调用、结果回写、状态机、执行明细聚合。
- 拆成独立域后，controller/service/dao 责任更清晰。

### 3.3 与现有域的关系

#### 与 Case 域的关系
- `test_case.id` 作为桥梁。
- 通过 `test_case.is_auto=1` 判断可自动化。
- 后续如需补充自动化元信息，可扩展 `test_case` 字段或新增自动化映射表。

#### 与 Plan 域的关系
- 批量执行来源于 `plan_case`。
- 自动化执行结果需要同步回写 `plan_case.status / actual_result / executed_time / execution_duration`。
- 自动化执行完成后，要复用或增强当前 `_update_plan_status` 的逻辑，更新 `test_plan.status`。

---

## 4. 数据库表结构设计

本方案采用：
- 尽量复用现有 `test_case / plan_case / test_plan`
- 新增执行主表和执行明细表
- 可选新增执行事件表（如要完整审计）

---

## 5. 现有表改造建议

### 5.1 `test_case` 表改造
当前已有：
- `id`
- `case_key`
- `is_auto`

由于你说明桥梁就是 `case_id`，pytest 项目也按 `case_id` 执行，因此**本期不强制新增自动化用例定位字段**。

但建议增加以下可选字段，便于后续扩展：

```sql
ALTER TABLE test_case
ADD COLUMN auto_status SMALLINT DEFAULT 0,
ADD COLUMN auto_updated_time TIMESTAMP,
ADD COLUMN auto_meta JSONB DEFAULT '{}'::jsonb;
```

字段说明：
- `auto_status`: 0未接入 1已接入 2已失效
- `auto_updated_time`: 自动化信息最近更新时间
- `auto_meta`: 预留字段，后续可存 pytest marker、目录、owner 等

> 如果你要严格最小改动，这 3 个字段可以不做。

---

## 6. 新增核心表结构

### 6.1 自动化执行主表 `auto_execution`

用途：记录一次自动化执行任务，支持单条执行和计划执行。

```sql
CREATE TABLE auto_execution (
    id BIGSERIAL PRIMARY KEY,
    execution_no VARCHAR(64) NOT NULL UNIQUE,
    trigger_type SMALLINT NOT NULL,
    project_id BIGINT NOT NULL,
    plan_id BIGINT,
    plan_round_no INTEGER,
    source_case_id BIGINT,
    env_code VARCHAR(32) NOT NULL,
    run_mode SMALLINT DEFAULT 1,
    status SMALLINT NOT NULL DEFAULT 0,
    jenkins_job_name VARCHAR(128),
    jenkins_queue_id BIGINT,
    jenkins_build_number BIGINT,
    jenkins_build_url VARCHAR(512),
    console_url VARCHAR(512),
    report_url VARCHAR(512),
    total_count INTEGER DEFAULT 0,
    pending_count INTEGER DEFAULT 0,
    running_count INTEGER DEFAULT 0,
    passed_count INTEGER DEFAULT 0,
    failed_count INTEGER DEFAULT 0,
    blocked_count INTEGER DEFAULT 0,
    skipped_count INTEGER DEFAULT 0,
    not_found_count INTEGER DEFAULT 0,
    trigger_by BIGINT,
    trigger_source VARCHAR(32) DEFAULT 'platform',
    trigger_message TEXT,
    start_time TIMESTAMP,
    end_time TIMESTAMP,
    duration_seconds INTEGER,
    callback_token VARCHAR(128),
    ext JSONB DEFAULT '{}'::jsonb,
    created_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

字段定义：

- `execution_no`: 平台执行编号，建议格式 `AE202502120001`
- `trigger_type`:
  - 1 单条用例执行
  - 2 计划批量执行
- `project_id`: 冗余存项目，方便查询
- `plan_id`: 计划执行时必填，单条执行可空
- `plan_round_no`: 若按轮次执行可记录
- `source_case_id`: 单条执行来源 case_id
- `env_code`: 执行环境编码，如 `st/dev/pre`
- `run_mode`:
  - 1 串行
  - 2 并行
- `status`: 执行主状态，见后文状态机
- `jenkins_job_name / queue_id / build_number / build_url`
- `console_url / report_url`: 用于前端直接跳转
- `*_count`: 执行汇总
- `trigger_by`: 触发用户
- `trigger_message`: 触发失败或备注
- `callback_token`: Jenkins/pytest 回调鉴权
- `ext`: 预留字段，记录 branch、pytest args、report meta 等

索引建议：

```sql
CREATE INDEX idx_auto_execution_plan_id ON auto_execution(plan_id);
CREATE INDEX idx_auto_execution_project_id ON auto_execution(project_id);
CREATE INDEX idx_auto_execution_status ON auto_execution(status);
CREATE INDEX idx_auto_execution_created_time ON auto_execution(created_time DESC);
CREATE INDEX idx_auto_execution_trigger_by ON auto_execution(trigger_by);
```

---

### 6.2 自动化执行明细表 `auto_execution_case`

用途：记录本次执行下每个 `case_id` 的状态和结果。

```sql
CREATE TABLE auto_execution_case (
    id BIGSERIAL PRIMARY KEY,
    execution_id BIGINT NOT NULL,
    plan_case_id BIGINT,
    case_id BIGINT NOT NULL,
    case_key VARCHAR(64),
    case_title VARCHAR(255),
    run_order INTEGER DEFAULT 0,
    status SMALLINT NOT NULL DEFAULT 0,
    pytest_nodeid VARCHAR(512),
    result_message TEXT,
    error_message TEXT,
    stack_trace TEXT,
    report_url VARCHAR(512),
    duration_seconds INTEGER,
    started_time TIMESTAMP,
    finished_time TIMESTAMP,
    retry_count INTEGER DEFAULT 0,
    ext JSONB DEFAULT '{}'::jsonb,
    created_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

字段定义：
- `execution_id`: 对应 `auto_execution.id`
- `plan_case_id`: 如果来源于计划执行，则关联 `plan_case.id`
- `case_id`: 功能用例主键，也是自动化桥梁
- `case_key / case_title`: 冗余快照，避免后续名称变化影响历史展示
- `run_order`: 执行顺序
- `status`: 单用例执行状态，见后文状态机
- `pytest_nodeid`: pytest 的 nodeid，如 `tests/test_login.py::test_xxx`
- `result_message`: 简要结果，如断言失败摘要
- `error_message / stack_trace`: 异常信息
- `report_url`: 若支持单用例报告可记录
- `retry_count`: 失败重跑预留
- `ext`: 可存截图、附件、标签等

索引建议：

```sql
CREATE INDEX idx_auto_execution_case_execution_id ON auto_execution_case(execution_id);
CREATE INDEX idx_auto_execution_case_case_id ON auto_execution_case(case_id);
CREATE INDEX idx_auto_execution_case_plan_case_id ON auto_execution_case(plan_case_id);
CREATE INDEX idx_auto_execution_case_status ON auto_execution_case(status);
CREATE UNIQUE INDEX uk_auto_execution_case_unique ON auto_execution_case(execution_id, case_id, plan_case_id);
```

> 如果同一计划允许相同 `case_id` 在不同轮次、多次加入，则唯一索引可调整成 `(execution_id, plan_case_id, case_id)`，其中 `plan_case_id` 允许为空时要注意 PostgreSQL 对 NULL 唯一性的行为。

---

### 6.3 可选事件表 `auto_execution_event`

如果你希望保留每次回调、状态变化、Jenkins 交互轨迹，建议加事件表。

```sql
CREATE TABLE auto_execution_event (
    id BIGSERIAL PRIMARY KEY,
    execution_id BIGINT NOT NULL,
    execution_case_id BIGINT,
    event_type VARCHAR(64) NOT NULL,
    event_status VARCHAR(32),
    payload JSONB DEFAULT '{}'::jsonb,
    created_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

事件类型示例：
- `TRIGGER_REQUESTED`
- `JENKINS_QUEUED`
- `JENKINS_STARTED`
- `CASE_STARTED`
- `CASE_FINISHED`
- `EXECUTION_FINISHED`
- `CALLBACK_FAILED`

> 若第一期追求最小化，可先不建此表，把关键日志写到应用日志中。

---

## 7. SQLAlchemy Model 设计（贴合当前项目风格）

建议新增文件：`app/api/model/automationModel.py`

包含：
- `AutoExecution`
- `AutoExecutionCase`
- （可选）`AutoExecutionEvent`

建模风格应与当前 `planModel.py / caseModel.py` 一致：
- 使用 `declarative_base()`
- `Base.to_dict = to_dict`
- 字段命名与数据库下划线保持一致
- `JSONB / TIMESTAMP / SmallInteger / BigInteger`

---

## 8. 状态流转设计

这是后端实现的核心。

### 8.1 主执行状态 `auto_execution.status`

建议枚举：

- `0` 待触发（平台已建单，尚未请求 Jenkins）
- `1` 触发中（正在调用 Jenkins）
- `2` 排队中（Jenkins 已接收，尚未开始构建）
- `3` 执行中（Jenkins/pytest 已开始）
- `4` 成功（全部执行完成且失败数=0）
- `5` 失败（已结束，但存在失败/异常）
- `6` 已取消
- `7` 触发失败（Jenkins API 调用失败）
- `8` 回调异常（任务可能跑完，但平台未完整接收结果）

推荐状态流：

```text
0待触发
 -> 1触发中
   -> 2排队中
     -> 3执行中
       -> 4成功
       -> 5失败
       -> 6已取消
   -> 7触发失败
```

补偿状态：
- 任意执行中状态，如果最终结果缺失但监控发现 Jenkins 已完成，可修正到 4/5。
- 回调鉴权失败/数据异常时，可标记 `8 回调异常`。

### 8.2 明细状态 `auto_execution_case.status`

建议枚举：
- `0` 待执行
- `1` 执行中
- `2` 通过
- `3` 失败
- `4` 阻塞
- `5` 跳过
- `6` 未找到自动化实现
- `7` 已取消

推荐状态流：

```text
0待执行 -> 1执行中 -> 2通过
                    -> 3失败
                    -> 4阻塞
                    -> 5跳过
                    -> 6未找到自动化实现
                    -> 7已取消
```

### 8.3 与现有 `plan_case.status` 的映射关系

当前 `plan_case.status`：
- `0` 未开始
- `1` 通过
- `2` 失败
- `3` 阻塞

自动化结果回写时建议映射：

- `auto_execution_case.status=2` -> `plan_case.status=1`
- `auto_execution_case.status=3` -> `plan_case.status=2`
- `auto_execution_case.status=4` -> `plan_case.status=3`
- `auto_execution_case.status in (5,6,7)` -> **不自动覆盖为通过/失败**，建议保留原值或按业务约定：
  - 若原来是 `0`，可保持 `0`
  - 并把细节记入 `actual_result`

### 8.4 与 `test_plan.status` 的映射关系

当前 `TestPlan.status`：
- `0` 草稿
- `1` 进行中
- `2` 已完成
- `3` 已归档
- `4` 已通过

建议复用现有 `_update_plan_status(plan_id)` 逻辑，但将其抽到 `PlanService` 或 `AutomationService` 中统一调用。

执行过程中：
- 计划中存在未执行 -> `1 进行中`
- 全部完成，且无失败/阻塞 -> `4 已通过`
- 全部完成，存在失败/阻塞 -> `2 已完成`
- 若原来 `3 已归档`，不自动改动

---

## 9. 接口设计

接口分三类：
1. 前端触发接口
2. 自动化项目拉取执行清单接口
3. Jenkins/pytest 回调接口

以下设计遵循当前项目风格：
- 路由统一注册在 `app/api/views.py`
- `GET` 查列表/详情
- `POST` 创建/更新/触发
- 返回结构统一 `ApiResponse.build_success/build_failure`

---

## 10. 前端触发接口设计

### 10.1 单条用例执行

#### 路由
`POST /api/automation/case/run`

#### 权限
建议新增：`automation:run`

#### 请求体
```json
{
  "caseId": 1001,
  "envCode": "st",
  "runMode": 1,
  "jenkinsJobName": "pytest-auto-runner",
  "remark": "单条回归验证"
}
```

#### 字段说明
- `caseId`: 必填
- `envCode`: 必填
- `runMode`: 可选，默认 1 串行
- `jenkinsJobName`: 可选，未传则走系统默认配置
- `remark`: 可选

#### 返回
```json
{
  "id": 123,
  "executionId": 123,
  "executionNo": "AE202502120001",
  "status": 2
}
```

#### 处理逻辑
1. 校验 `caseId` 是否存在。
2. 校验 `test_case.is_auto == 1`。
3. 创建 `auto_execution`：
   - `trigger_type=1`
   - `source_case_id=caseId`
   - `project_id` 从 `test_case.project_id` 带出
4. 创建一条 `auto_execution_case`。
5. 调用 Jenkins。
6. 若调用成功：
   - 更新主表 `status=2`
   - 记录 `queue_id / job_name`
7. 若调用失败：
   - 更新主表 `status=7`
   - 返回失败原因

---

### 10.2 计划自动化执行

#### 路由
`POST /api/automation/plan/run`

#### 权限
`automation:run`

#### 请求体
```json
{
  "planId": 2001,
  "roundNo": 1,
  "envCode": "st",
  "runMode": 1,
  "caseIds": [1001, 1002, 1003],
  "jenkinsJobName": "pytest-auto-runner",
  "remark": "计划批量回归"
}
```

#### 说明
- `caseIds` 可选：
  - 不传或空：执行当前计划下全部自动化用例
  - 传值：执行计划中指定子集
- `roundNo` 可选：如果你已有轮次概念，则仅执行该轮次下的 `plan_case`

#### 返回
```json
{
  "id": 124,
  "executionId": 124,
  "executionNo": "AE202502120002",
  "totalCount": 15,
  "status": 2
}
```

#### 处理逻辑
1. 校验 `planId`。
2. 查询 `plan_case + test_case`：
   - 必须属于该计划
   - `test_case.is_auto=1`
   - 若传 `caseIds`，则限制子集
   - 若传 `roundNo`，则限制轮次
3. 若无可执行自动化用例，直接报错。
4. 创建 `auto_execution`：
   - `trigger_type=2`
   - `plan_id=planId`
   - `plan_round_no=roundNo`
5. 批量创建 `auto_execution_case`。
6. 调 Jenkins。
7. 更新状态与 Jenkins 信息。

---

### 10.3 自动化执行列表

#### 路由
`GET /api/automation/execution/list`

#### 请求参数
- `projectId`
- `planId`
- `status`
- `triggerType`
- `pageNo`
- `pageSize`

#### 返回字段
- `id`
- `execution_no`
- `trigger_type`
- `plan_id`
- `source_case_id`
- `env_code`
- `status`
- `total_count`
- `passed_count`
- `failed_count`
- `report_url`
- `jenkins_build_number`
- `created_time`
- `start_time`
- `end_time`

---

### 10.4 自动化执行详情

#### 路由
`GET /api/automation/execution/detail`

#### 请求参数
- `executionId`

#### 返回
主表 + 汇总 + Jenkins 信息 + 用例统计。

---

### 10.5 自动化执行明细列表

#### 路由
`GET /api/automation/execution/case/list`

#### 请求参数
- `executionId`
- `status` 可选
- `pageNo`
- `pageSize`

#### 返回
每条 `auto_execution_case` 的详情。

---

## 11. 自动化项目拉取执行清单接口

这是 pytest 项目的核心入口。

### 11.1 获取执行清单

#### 路由
`GET /api/automation/execution/case/pull`

#### 鉴权
建议两层：
1. 正常 token 鉴权（如果自动化项目能拿到平台 token）
2. 或使用 `executionId + callbackToken` 鉴权

建议本期采用：
- query: `executionId`
- header: `X-CALLBACK-TOKEN`

#### 请求参数
- `executionId`

#### 请求头
- `X-CALLBACK-TOKEN: xxx`

#### 返回
```json
{
  "executionId": 124,
  "executionNo": "AE202502120002",
  "triggerType": 2,
  "projectId": 88,
  "planId": 2001,
  "envCode": "st",
  "runMode": 1,
  "items": [
    {
      "executionCaseId": 501,
      "planCaseId": 9001,
      "caseId": 1001,
      "caseKey": "TC-ZHYY-001",
      "caseTitle": "登录成功",
      "runOrder": 1
    }
  ]
}
```

#### 处理逻辑
1. 校验 `executionId`。
2. 校验回调 token。
3. 查询 `auto_execution` 和 `auto_execution_case`。
4. 返回待执行清单。

> 如果未来 pytest 项目还需要额外上下文，如环境 URL、测试账号、marker，也可以从 `ext` 中一起返回。

---

## 12. 回调接口设计

推荐分 4 个回调点：
1. Jenkins 入队成功
2. Jenkins 开始执行
3. 单条用例结果回写
4. 整体执行完成回写

---

### 12.1 Jenkins 入队回写

#### 路由
`POST /api/automation/execution/queued`

#### 作用
Jenkins 已接受构建，回传 queue/build 基本信息。

#### 请求体
```json
{
  "executionId": 124,
  "queueId": 5678,
  "jobName": "pytest-auto-runner",
  "buildNumber": null,
  "buildUrl": null
}
```

#### 处理
- 主表状态 `1/2 -> 2`
- 回写 `queue_id / job_name / build_number / build_url`

> 如果平台触发 Jenkins 后拿不到 queueId，也可省略这个接口，由后续 started 回调补齐。

---

### 12.2 Jenkins/pytest 开始执行回写

#### 路由
`POST /api/automation/execution/start`

#### 请求体
```json
{
  "executionId": 124,
  "jobName": "pytest-auto-runner",
  "buildNumber": 89,
  "buildUrl": "http://jenkins/job/pytest-auto-runner/89/",
  "consoleUrl": "http://jenkins/job/pytest-auto-runner/89/console",
  "startTime": "2025-02-12 10:00:00"
}
```

#### 处理
- 主表状态更新为 `3 执行中`
- 记录 `buildNumber / buildUrl / consoleUrl / start_time`

---

### 12.3 单条用例结果回写

#### 路由
`POST /api/automation/execution/case/result`

#### 请求体
```json
{
  "executionId": 124,
  "caseId": 1001,
  "executionCaseId": 501,
  "status": 2,
  "pytestNodeid": "tests/test_login.py::test_login_success",
  "resultMessage": "assert success",
  "errorMessage": "",
  "stackTrace": "",
  "durationSeconds": 12,
  "reportUrl": "http://allure/case/1001",
  "startedTime": "2025-02-12 10:01:00",
  "finishedTime": "2025-02-12 10:01:12",
  "ext": {
    "attachments": []
  }
}
```

#### 处理逻辑
1. 按 `executionCaseId` 优先定位明细；若无则退化为 `executionId + caseId`。
2. 更新 `auto_execution_case`。
3. 若有关联 `plan_case_id`，同步回写 `plan_case`：
   - `status`
   - `actual_result`
   - `executed_time`
   - `execution_duration`
4. 重新聚合更新 `auto_execution` 汇总字段。
5. 若是计划执行，可调用计划状态更新逻辑。

---

### 12.4 整体执行完成回写

#### 路由
`POST /api/automation/execution/finish`

#### 请求体
```json
{
  "executionId": 124,
  "status": 4,
  "buildNumber": 89,
  "buildUrl": "http://jenkins/job/pytest-auto-runner/89/",
  "consoleUrl": "http://jenkins/job/pytest-auto-runner/89/console",
  "reportUrl": "http://allure/report/89",
  "startTime": "2025-02-12 10:00:00",
  "endTime": "2025-02-12 10:08:00",
  "durationSeconds": 480,
  "summary": {
    "total": 15,
    "passed": 12,
    "failed": 2,
    "blocked": 0,
    "skipped": 1,
    "notFound": 0
  },
  "message": "执行完成"
}
```

#### 处理逻辑
1. 更新主表 Jenkins 信息与时间。
2. 若请求体有 summary，则直接写回；否则后台实时聚合明细表得到。
3. 根据汇总决定主状态：
   - `failed > 0 or blocked > 0 or notFound > 0` -> `5失败`
   - 否则 -> `4成功`
4. 若是计划执行，调用计划状态刷新。

---

### 12.5 失败/取消回调

#### 路由
`POST /api/automation/execution/abort`

#### 请求体
```json
{
  "executionId": 124,
  "status": 6,
  "message": "Jenkins aborted",
  "buildNumber": 89,
  "consoleUrl": "http://jenkins/job/pytest-auto-runner/89/console"
}
```

#### 处理
- 主表置 `6 已取消` 或 `5 失败`
- 所有仍为 `0/1` 的明细置为 `7 已取消`
- 刷新汇总

---

## 13. Jenkins 参数设计

推荐只使用少量稳定参数。

### 13.1 Jenkins Job 名称
建议固定为一个或少数几个通用参数化任务，例如：
- `pytest-auto-runner`
- 如果分项目，可 `pytest-auto-runner-zhyy`

不建议“一计划一 Job”。

### 13.2 构建参数

```text
EXECUTION_ID
CALLBACK_TOKEN
PLATFORM_BASE_URL
ENV_CODE
RUN_MODE
TRIGGER_TYPE
```

#### 含义
- `EXECUTION_ID`: 平台执行主键
- `CALLBACK_TOKEN`: 回调鉴权 token
- `PLATFORM_BASE_URL`: 平台地址，如 `http://xxx/api`
- `ENV_CODE`: st/dev/pre
- `RUN_MODE`: 1串行 2并行
- `TRIGGER_TYPE`: 1单条 2计划

### 13.3 可选参数

```text
GIT_BRANCH
PYTEST_ARGS
REPORT_BASE_URL
```

存放位置建议：
- 平台配置中心 / 环境变量 / 常量文件
- 不建议写死在 controller

### 13.4 Jenkins Build API 请求方式

推荐后端调用：

```text
POST /job/{jobName}/buildWithParameters
```

鉴权建议：
- Basic Auth + API Token
- 若 Jenkins 开启 crumb 防护，还要先请求 crumb

---

## 14. Jenkins 回调与结果回写逻辑

### 14.1 平台触发 Jenkins 时的处理

`AutomationService.trigger_execution(...)` 需要：

1. 生成 `callback_token`
2. 创建执行单和明细
3. 更新主状态 `0 -> 1`
4. 调 Jenkins API
5. 成功：
   - 主状态 `1 -> 2`
   - 保存 queue/build 基础信息
6. 失败：
   - 主状态 `1 -> 7`
   - 保存错误信息到 `trigger_message`

### 14.2 pytest 项目开始时的处理

pytest 启动脚本：
1. 根据 Jenkins 参数拿到 `EXECUTION_ID`
2. 调平台 `/execution/case/pull`
3. 成功拿清单后调用 `/execution/start`
4. 开始逐条执行

### 14.3 pytest 每执行一条用例

执行器需要：
1. 将 `case_id` 定位到 pytest 对应测试项
2. 执行完成后回调 `/execution/case/result`
3. 回调内容至少包括：
   - executionCaseId / caseId
   - status
   - durationSeconds
   - nodeid
   - errorMessage/resultMessage

### 14.4 pytest 全量执行结束

执行器需要：
1. 汇总总数
2. 计算开始/结束时间
3. 发布 report_url（如 Allure）
4. 调 `/execution/finish`

### 14.5 Jenkins 失败兜底

即使 pytest 未回调成功，Jenkins `post { failure { ... } }` 阶段也应该：
- 至少调用 `/execution/abort` 或 `/execution/finish(status=5)`
- 避免平台主单永久卡在 `2/3`

---

## 15. 详细执行流程

### 15.1 单条用例执行流程

```text
前端点击“执行自动化”
-> POST /api/automation/case/run
-> controller 校验参数
-> service 查询 test_case
-> 校验 is_auto=1
-> dao 创建 auto_execution
-> dao 创建 auto_execution_case
-> service 调 Jenkins
-> Jenkins 接受构建
-> 平台主单状态变更为排队中
-> pytest 项目启动
-> 拉取 execution 清单
-> 回调 start
-> 执行 case_id 对应 pytest 用例
-> 回调 case/result
-> 回调 finish
-> 平台更新 execution 汇总
```

### 15.2 计划批量执行流程

```text
前端点击“执行自动化用例”
-> POST /api/automation/plan/run
-> controller 校验参数
-> service 查询 plan_case + test_case
-> 过滤 is_auto=1
-> dao 创建 auto_execution
-> dao 批量创建 auto_execution_case
-> service 调 Jenkins
-> Jenkins 启动 pytest 项目
-> pytest 按 execution_id 拉取清单
-> 回调 execution/start
-> 按顺序或并行执行每个 case_id
-> 每条执行后回调 case/result
-> 平台同步回写 plan_case
-> 全部完成后回调 finish
-> 平台刷新 auto_execution 汇总
-> 平台刷新 test_plan 状态
```

---

## 16. Controller / Service / DAO 详细职责设计

### 16.1 Controller 层
新增 `AutomationController`，建议方法：

- `case_run()`
- `plan_run()`
- `execution_list()`
- `execution_detail()`
- `execution_case_list()`
- `execution_case_pull()`
- `execution_queued()`
- `execution_start()`
- `execution_case_result()`
- `execution_finish()`
- `execution_abort()`

Controller 责任：
- 参数读取 `_get`
- 基础必填校验
- 调 service
- 返回统一结构

不要在 controller 里直接写 SQL 或请求 Jenkins。

---

### 16.2 Service 层
新增 `AutomationService`，建议职责：

#### 触发类
- `create_case_execution(session, req_data, user_id)`
- `create_plan_execution(session, req_data, user_id)`
- `trigger_jenkins(session, execution_id, job_name)`

#### 查询类
- `get_execution_detail(session, execution_id)`
- `list_executions(session, filters, page, size)`
- `list_execution_cases(session, execution_id, filters, page, size)`
- `pull_execution_cases(session, execution_id, callback_token)`

#### 回调类
- `mark_execution_queued(...)`
- `mark_execution_started(...)`
- `save_case_result(...)`
- `finish_execution(...)`
- `abort_execution(...)`

#### 聚合类
- `refresh_execution_summary(session, execution_id)`
- `sync_plan_case_result(session, execution_case)`
- `refresh_plan_status(session, plan_id)`

Service 层应承接主要业务逻辑与状态流转。

---

### 16.3 DAO 层
新增 `AutomationDao`，建议方法：

#### 主表
- `create_execution(session, add_info)`
- `update_execution_by_id(session, execution_id, update_info)`
- `get_execution_by_id(session, execution_id)`
- `list_execution_by_filters(session, filters, page, size)`

#### 明细表
- `batch_create_execution_cases(session, batch_info_list)`
- `get_execution_case_by_id(session, execution_case_id)`
- `get_execution_case_by_unique(session, execution_id, case_id, plan_case_id=None)`
- `update_execution_case_by_id(session, execution_case_id, update_info)`
- `list_execution_case_by_filters(session, filters, page, size)`

#### 聚合
- `count_execution_case_summary(session, execution_id)`

#### 执行清单查询
- `query_plan_auto_cases(session, plan_id, round_no=None, case_ids=None)`
- `query_case_auto_item(session, case_id)`

DAO 保持与当前项目风格一致：
- 独立 CRUD
- `session.done(close=False)`
- 失败返回 `(0, err_msg)` / 查询返回对象

---

## 17. 与现有代码的修改点清单

### 17.1 新增文件

1. `app/api/model/automationModel.py`
2. `app/api/dao/automationDao.py`
3. `app/api/service/automationService.py`
4. `app/api/controller/automationController.py`
5. `common/jenkinsRequest.py`

### 17.2 修改文件

#### `app/api/views.py`
新增路由注册：
- `/automation/case/run`
- `/automation/plan/run`
- `/automation/execution/list`
- `/automation/execution/detail`
- `/automation/execution/case/list`
- `/automation/execution/case/pull`
- `/automation/execution/queued`
- `/automation/execution/start`
- `/automation/execution/case/result`
- `/automation/execution/finish`
- `/automation/execution/abort`

#### `app/api/service/planService.py`
建议增加公共方法：
- `refresh_plan_status(session, plan_id)`

把 `PlanController._update_plan_status()` 中的逻辑迁移出来，避免 controller 内部藏业务逻辑。

#### `app/api/controller/planController.py`
- `plan_case_execute()` 仍保留手工执行。
- 自动化执行入口不要继续加到这个方法里，而是走新 automation 接口。

#### `const.py`
建议新增 Jenkins 配置：
- `JENKINS_BASE_URL`
- `JENKINS_USER`
- `JENKINS_TOKEN`
- `JENKINS_DEFAULT_JOB`
- `AUTOMATION_CALLBACK_SECRET`
- `PLATFORM_BASE_URL`

> 生产上更建议来自环境变量，但当前项目已有常量直写风格，第一期可先保持一致。

---

## 18. `common/jenkinsRequest.py` 设计建议

参考 `common/getRequest.py` 风格，但 Jenkins 需要更灵活处理：

建议封装：
- `get_crumb()`
- `build_with_parameters(job_name, params)`
- `get_build_info(job_name, build_number)` 可选

### 建议返回内容
触发后尽量返回：
- success
- status_code
- queue_id（如果能解析到）
- location header
- error_message

如果当前 Jenkins 网关层不方便拿 queueId，也可以第一期只判断触发成功与否。

---

## 19. 回写 `plan_case` 的规则细化

每次 `/execution/case/result` 到达后：

如果 `auto_execution_case.plan_case_id` 不为空，则同步：

### 19.1 状态映射
- `2 通过` -> `plan_case.status = 1`
- `3 失败` -> `plan_case.status = 2`
- `4 阻塞` -> `plan_case.status = 3`
- `5 跳过 / 6未找到 / 7取消` -> 默认不改 `plan_case.status`

### 19.2 文本字段
- `plan_case.actual_result`：
  - 成功：记录 `resultMessage`
  - 失败：优先写 `errorMessage`
- `plan_case.executed_time`：写 `finished_time` 或当前时间
- `plan_case.execution_duration`：写 `duration_seconds`
- `defect_links / attachments`：本期不自动写，后续有缺陷系统集成再扩展

### 19.3 幂等性
同一个 `executionCaseId` 多次回调时：
- 允许覆盖 `status / duration / message`
- 但如果主状态已结束（4/5/6），应限制后续异常回调只做日志记录或按最后一次有效值覆盖，避免状态混乱

---

## 20. 聚合汇总逻辑

### 20.1 执行汇总字段计算规则
基于 `auto_execution_case` 统计：
- `total_count = count(*)`
- `pending_count = status=0`
- `running_count = status=1`
- `passed_count = status=2`
- `failed_count = status=3`
- `blocked_count = status=4`
- `skipped_count = status=5`
- `not_found_count = status=6`

### 20.2 主状态自动判定规则
在 `refresh_execution_summary` 中：

1. 若存在 `running_count > 0` -> 主状态至少为 `3`
2. 若全部结束：
   - `failed + blocked + not_found > 0` -> `5`
   - 否则 -> `4`
3. 若任务被外部取消 -> `6`
4. 若触发阶段失败 -> `7`

### 20.3 结束时间规则
当全部明细都进入结束态（2/3/4/5/6/7）时：
- 自动补 `end_time`
- 若 `start_time` 已有，则计算 `duration_seconds`

---

## 21. 计划执行选取逻辑

计划执行时，从 `plan_case` 选出真正需要跑的明细。

### 21.1 查询条件
- `PlanCase.plan_id = planId`
- 如果传 `roundNo`：`PlanCase.round_no = roundNo`
- 如果传 `caseIds`：`PlanCase.case_id in caseIds`
- 关联 `TestCase.is_delete = 0`
- `TestCase.is_auto = 1`
- 如有需要，也可加 `TestCase.status = 1 or 4`（正常/评审通过）

### 21.2 排序规则
默认：
- `plan_case.id asc`

### 21.3 去重规则
如果同一计划下同一轮次允许一个 `case_id` 出现多次：
- 不去重，按 `plan_case.id` 逐条执行
- 这样更符合计划执行场景

如果你明确保证不重复，也可唯一化。

---

## 22. 单条执行选取逻辑

输入 `caseId` 后：
- 直接查询 `test_case`
- 校验 `is_auto=1`
- 创建 1 条 `auto_execution_case`
- `plan_case_id` 为空

这样单条执行与计划执行复用同一套执行主流程。

---

## 23. 幂等与并发控制

### 23.1 重复点击执行按钮
建议在创建任务前校验：
- 是否存在同一 `planId + envCode + status in (0,1,2,3)` 的运行中任务
- 是否存在同一 `caseId + envCode + status in (0,1,2,3)` 的运行中任务

策略建议：
- 默认不允许重复触发，返回“已有执行中任务”
- 如果后续需要“强制重跑”，再加 `force=true`

### 23.2 回调幂等
对于 `/execution/case/result`：
- 若同一条记录已是最终状态，再收到相同状态回调，应视为幂等成功
- 若收到不同终态，以最后一次回调覆盖，但写日志

### 23.3 事务一致性
`save_case_result()` 推荐事务内做：
1. 更新 `auto_execution_case`
2. 更新 `plan_case`
3. 提交
4. 再调用聚合更新 `auto_execution`

如果要更强一致性，也可在同一事务完成，但当前项目的 session 风格是轻量提交，可分两步。

---

## 24. 错误场景与兜底策略

### 24.1 用例不存在
- 单条执行：直接返回失败
- 计划执行：忽略已删除用例，仅对有效自动化用例建单；若最终为空则报错

### 24.2 用例未接入自动化
- 单条执行：直接报错“该用例未实现自动化”
- 计划执行：过滤掉 `is_auto=0`；若全部都不是自动化则报错

### 24.3 Jenkins 触发失败
- `auto_execution.status = 7`
- `trigger_message` 存失败原因

### 24.4 pytest 找不到 `case_id` 对应实现
- 回调单条明细 `status = 6`
- 主单最终通常为 `5`

### 24.5 部分用例执行完，finish 回调丢失
- Jenkins `post` 阶段兜底调 `/finish` 或 `/abort`
- 平台可后续增加定时补偿任务，扫描长时间停留在 `3 执行中` 的记录

### 24.6 平台回调接口鉴权失败
- 返回失败
- 自动化项目应重试
- 平台日志记录 `executionId`

---

## 25. 接口返回码与错误语义建议

当前项目 `const.py` 中错误码较泛，第一期可以沿用现有：
- 40009 新增失败
- 40011 获取失败
- 40012 更新失败

但为了 AI 编码更明确，建议新增语义化错误码：

```python
40020: '自动化执行任务创建失败'
40021: '自动化用例不存在'
40022: '该用例未接入自动化'
40023: '计划下无可执行自动化用例'
40024: 'Jenkins 触发失败'
40025: '执行记录不存在'
40026: '回调鉴权失败'
40027: '执行结果回写失败'
```

> 若你想最小改动，也可先不加新错误码，统一用已有 `40009/40011/40012`。

---

## 26. 权限设计建议

建议新增权限点：
- `automation:run`
- `automation:list`
- `automation:detail`
- `automation:callback`

其中：
- 前端用户接口需要登录 + `automation:run/list/detail`
- Jenkins/pytest 回调接口建议：
  - 放到 `should_skip_auth()` 白名单中，绕过用户 token
  - 改为内部 token/header 校验

否则自动化项目拿用户 token 不稳定。

---

## 27. 回调鉴权设计

### 27.1 推荐方案
每次创建执行任务时生成 `callback_token`，存 `auto_execution.callback_token`。

Jenkins/pytest 回调时传：
```text
X-CALLBACK-TOKEN: {callback_token}
```

平台校验：
- `executionId` 存在
- header token 与库中一致

### 27.2 好处
- 不依赖用户登录 token
- 每次执行隔离
- token 泄露影响范围仅单次任务

---

## 28. pytest 自动化项目对接契约

虽然本期不写自动化项目代码，但后端方案必须给到契约。

### 28.1 自动化项目输入
来自 Jenkins 参数：
- `EXECUTION_ID`
- `CALLBACK_TOKEN`
- `PLATFORM_BASE_URL`
- `ENV_CODE`
- `RUN_MODE`

### 28.2 自动化项目行为
1. 调 `/execution/case/pull`
2. 将 `case_id` 映射到 pytest 测试项
3. 单条执行后调 `/execution/case/result`
4. 全部结束调 `/execution/finish`

### 28.3 `case_id` 到 pytest 的映射方式
你已经确定桥梁是 `case_id`，建议自动化项目采用以下之一：

#### 方式 A：pytest marker
```python
@pytest.mark.case_id(1001)
def test_login_success():
    ...
```

执行器启动时收集 marker，建立 `case_id -> nodeid` 映射。

#### 方式 B：维护映射文件
如 `case_map.json`

但从维护性看，**推荐 marker 方式**。

### 28.4 找不到映射时
回调：
- `status=6`
- `resultMessage='case_id 未映射到 pytest 用例'`

---

## 29. MVC 代码落地顺序建议（交给 AI 编码的实施计划）

### Phase 1：数据层
1. 新建数据库表：
   - `auto_execution`
   - `auto_execution_case`
2. 新建 `automationModel.py`
3. 新建 `automationDao.py`
4. 编写：
   - 创建主单
   - 批量创建明细
   - 查询详情/列表
   - 聚合汇总

### Phase 2：服务层
1. 新建 `automationService.py`
2. 实现：
   - 单条执行建单
   - 计划执行建单
   - Jenkins 触发
   - 执行清单拉取
   - 单条结果回写
   - 整体完成回写
   - 汇总刷新
3. 把 `PlanController._update_plan_status()` 逻辑迁移成服务方法

### Phase 3：控制器与路由
1. 新建 `automationController.py`
2. 在 `views.py` 注册接口
3. 增加回调接口白名单处理

### Phase 4：Jenkins 客户端
1. 新建 `common/jenkinsRequest.py`
2. 封装 Basic Auth + buildWithParameters
3. 在 service 中接入

### Phase 5：联调准备
1. 给 pytest 项目提供接口文档
2. 给 Jenkins Pipeline 提供参数清单
3. 约定回调协议

---

## 30. 推荐的 AI 编码拆分任务

为了让 AI 更稳地写代码，建议拆成 5 个子任务：

### 任务 1：建模与 DAO
输出：
- `automationModel.py`
- `automationDao.py`

### 任务 2：查询与列表接口
输出：
- execution list/detail/case list

### 任务 3：单条执行 / 计划执行建单逻辑
输出：
- case run
- plan run
- Jenkins trigger

### 任务 4：回调与状态流转
输出：
- pull/start/case_result/finish/abort
- plan_case 回写
- plan 状态更新

### 任务 5：Jenkins 客户端与配置收口
输出：
- `common/jenkinsRequest.py`
- `const.py` 新配置
- 回调白名单

---

## 31. 最终推荐实现决策

### 必做
1. 新增 `auto_execution`、`auto_execution_case`
2. 独立 automation MVC 模块
3. 平台只传 `execution_id` 给 Jenkins
4. pytest 项目按 `execution_id` 拉清单
5. 单条回写 + 整体回写
6. 回写 `plan_case` 和 `test_plan` 状态

### 建议做
1. `callback_token` 鉴权
2. 主/明细状态机
3. 幂等处理
4. Jenkins 失败兜底回调

### 可后置
1. 并行执行
2. 失败重跑
3. 定时补偿
4. 执行事件表
5. 自动创建缺陷/附件

---

## 32. 可直接交给 AI 的开发说明摘要

你可以把下面这段直接给 AI 作为实现要求：

1. 基于当前 Flask MVC 结构，新增 automation 域：controller/service/dao/model。
2. 新增表 `auto_execution`、`auto_execution_case`，字段按本方案实现。
3. 提供接口：
   - `POST /api/automation/case/run`
   - `POST /api/automation/plan/run`
   - `GET /api/automation/execution/list`
   - `GET /api/automation/execution/detail`
   - `GET /api/automation/execution/case/list`
   - `GET /api/automation/execution/case/pull`
   - `POST /api/automation/execution/queued`
   - `POST /api/automation/execution/start`
   - `POST /api/automation/execution/case/result`
   - `POST /api/automation/execution/finish`
   - `POST /api/automation/execution/abort`
4. 单条执行通过 `test_case.id` 建单，计划执行通过 `plan_case + test_case.is_auto=1` 批量建单。
5. 主状态与明细状态按本方案的枚举实现。
6. `/case/result` 回调时同步更新 `plan_case.status / actual_result / executed_time / execution_duration`。
7. 每次明细回写后聚合更新 `auto_execution` 的计数和主状态。
8. 计划执行时，执行结果变化后要刷新 `test_plan.status`，把当前 `PlanController._update_plan_status()` 逻辑迁到 service 层复用。
9. 新增 `common/jenkinsRequest.py`，封装 Jenkins `buildWithParameters` 调用。
10. Jenkins 参数至少包含：`EXECUTION_ID`、`CALLBACK_TOKEN`、`PLATFORM_BASE_URL`、`ENV_CODE`、`RUN_MODE`、`TRIGGER_TYPE`。
11. 回调接口采用 `X-CALLBACK-TOKEN` 鉴权，并加入免登录白名单。

---

## 33. PostgreSQL 建表 SQL（可直接落库）

> 说明：以下 SQL 仅覆盖本次自动化执行接入新增对象，不包含已有 `test_case / plan_case / test_plan` 表。
> 当前代码已按 PostgreSQL + SQLAlchemy 映射实现，建议先在测试环境执行 SQL，再启动服务联调。

### 33.1 自动化执行主表

```sql
CREATE TABLE IF NOT EXISTS auto_execution (
    id BIGSERIAL PRIMARY KEY,
    execution_no VARCHAR(64) NOT NULL UNIQUE,
    trigger_type SMALLINT NOT NULL,
    project_id BIGINT NOT NULL,
    plan_id BIGINT,
    plan_round_no INTEGER,
    source_case_id BIGINT,
    env_code VARCHAR(32) NOT NULL,
    run_mode SMALLINT DEFAULT 1,
    status SMALLINT NOT NULL DEFAULT 0,
    jenkins_job_name VARCHAR(128),
    jenkins_queue_id BIGINT,
    jenkins_build_number BIGINT,
    jenkins_build_url VARCHAR(512),
    console_url VARCHAR(512),
    report_url VARCHAR(512),
    total_count INTEGER DEFAULT 0,
    pending_count INTEGER DEFAULT 0,
    running_count INTEGER DEFAULT 0,
    passed_count INTEGER DEFAULT 0,
    failed_count INTEGER DEFAULT 0,
    blocked_count INTEGER DEFAULT 0,
    skipped_count INTEGER DEFAULT 0,
    not_found_count INTEGER DEFAULT 0,
    trigger_by BIGINT,
    trigger_source VARCHAR(32) DEFAULT 'platform',
    trigger_message TEXT,
    start_time TIMESTAMP,
    end_time TIMESTAMP,
    duration_seconds INTEGER,
    callback_token VARCHAR(128),
    ext JSONB DEFAULT '{}'::jsonb,
    created_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### 33.2 自动化执行明细表

```sql
CREATE TABLE IF NOT EXISTS auto_execution_case (
    id BIGSERIAL PRIMARY KEY,
    execution_id BIGINT NOT NULL,
    plan_case_id BIGINT,
    case_id BIGINT NOT NULL,
    case_key VARCHAR(64),
    case_title VARCHAR(255),
    run_order INTEGER DEFAULT 0,
    status SMALLINT NOT NULL DEFAULT 0,
    pytest_nodeid VARCHAR(512),
    result_message TEXT,
    error_message TEXT,
    stack_trace TEXT,
    report_url VARCHAR(512),
    duration_seconds INTEGER,
    started_time TIMESTAMP,
    finished_time TIMESTAMP,
    retry_count INTEGER DEFAULT 0,
    ext JSONB DEFAULT '{}'::jsonb,
    created_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### 33.3 索引

```sql
CREATE INDEX IF NOT EXISTS idx_auto_execution_plan_id ON auto_execution(plan_id);
CREATE INDEX IF NOT EXISTS idx_auto_execution_project_id ON auto_execution(project_id);
CREATE INDEX IF NOT EXISTS idx_auto_execution_status ON auto_execution(status);
CREATE INDEX IF NOT EXISTS idx_auto_execution_created_time ON auto_execution(created_time DESC);
CREATE INDEX IF NOT EXISTS idx_auto_execution_trigger_by ON auto_execution(trigger_by);

CREATE INDEX IF NOT EXISTS idx_auto_execution_case_execution_id ON auto_execution_case(execution_id);
CREATE INDEX IF NOT EXISTS idx_auto_execution_case_case_id ON auto_execution_case(case_id);
CREATE INDEX IF NOT EXISTS idx_auto_execution_case_plan_case_id ON auto_execution_case(plan_case_id);
CREATE INDEX IF NOT EXISTS idx_auto_execution_case_status ON auto_execution_case(status);
```

### 33.4 唯一约束建议

当前代码在 `get_execution_case_by_unique()` 中按：
- `execution_id + case_id`
- 有 `plan_case_id` 时再附加 `plan_case_id`

如果你确认同一执行内允许同一个 `case_id` 因不同 `plan_case_id` 出现多次，建议使用下面唯一索引：

```sql
CREATE UNIQUE INDEX IF NOT EXISTS uk_auto_execution_case_exec_plan_case
ON auto_execution_case(execution_id, plan_case_id, case_id);
```

如果你确认同一执行中 `case_id` 不会重复，则可改为更强约束：

```sql
CREATE UNIQUE INDEX IF NOT EXISTS uk_auto_execution_case_exec_case
ON auto_execution_case(execution_id, case_id);
```

> 推荐和当前业务保持一致：计划里可能重复挂同一个 case 时，用第一种。

### 33.5 外键建议

如果你当前库中已有规范外键管理，可以加；如果历史库本身较轻、线上变更风险高，第一期可不加外键，只保留业务层约束。

可选外键：

```sql
ALTER TABLE auto_execution_case
ADD CONSTRAINT fk_auto_execution_case_execution_id
FOREIGN KEY (execution_id) REFERENCES auto_execution(id);

ALTER TABLE auto_execution_case
ADD CONSTRAINT fk_auto_execution_case_plan_case_id
FOREIGN KEY (plan_case_id) REFERENCES plan_case(id);

ALTER TABLE auto_execution_case
ADD CONSTRAINT fk_auto_execution_case_case_id
FOREIGN KEY (case_id) REFERENCES test_case(id);
```

### 33.6 updated_time 自动更新时间建议

当前 SQLAlchemy 已声明 `server_onupdate`，但 PostgreSQL 本身不会仅靠字段定义自动刷新 `updated_time`。
如果你希望数据库层自动维护更新时间，建议补 trigger：

```sql
CREATE OR REPLACE FUNCTION update_modified_column()
RETURNS TRIGGER AS $
BEGIN
    NEW.updated_time = CURRENT_TIMESTAMP;
    RETURN NEW;
END;
$ language 'plpgsql';

DROP TRIGGER IF EXISTS trg_auto_execution_updated_time ON auto_execution;
CREATE TRIGGER trg_auto_execution_updated_time
BEFORE UPDATE ON auto_execution
FOR EACH ROW
EXECUTE PROCEDURE update_modified_column();

DROP TRIGGER IF EXISTS trg_auto_execution_case_updated_time ON auto_execution_case;
CREATE TRIGGER trg_auto_execution_case_updated_time
BEFORE UPDATE ON auto_execution_case
FOR EACH ROW
EXECUTE PROCEDURE update_modified_column();
```

### 33.7 权限初始化 SQL

你当前代码新增了以下权限点：
- `automation:run`
- `automation:list`
- `automation:detail`

如果你们 RBAC 表结构支持直接插入权限编码，可参考下面 SQL，字段名按你实际库调整：

```sql
-- 以下为示例，请按实际 rbac_permission 表结构调整字段
INSERT INTO rbac_permission (name, code, type, parent_id, created_time, updated_time)
VALUES
('自动化执行', 'automation:run', 2, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('自动化执行列表', 'automation:list', 2, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP),
('自动化执行详情', 'automation:detail', 2, NULL, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
ON CONFLICT (code) DO NOTHING;
```

如果你们权限还要挂菜单或角色，再补：
- 角色权限关联表
- 菜单权限关联表

---

## 34. pytest + Jenkins 联调请求示例

以下示例是按你当前后端已实现接口整理的，可直接给自动化项目同学或 Jenkins Pipeline 使用。

### 34.1 Jenkins 触发参数约定

平台调用 Jenkins `buildWithParameters` 时传：

```text
EXECUTION_ID=123
CALLBACK_TOKEN=abc123token
PLATFORM_BASE_URL=http://127.0.0.1:5010/it/api
ENV_CODE=st
RUN_MODE=1
TRIGGER_TYPE=2
```

其中：
- `CALLBACK_TOKEN`：用于 `/automation/execution/case/pull`
- `X-CALLBACK-SECRET`：用于回调写入接口，由 Jenkins 环境变量统一注入

---

### 34.2 Jenkins Pipeline 示例

```groovy
pipeline {
    agent any
    parameters {
        string(name: 'EXECUTION_ID', defaultValue: '', description: '平台执行ID')
        string(name: 'CALLBACK_TOKEN', defaultValue: '', description: '拉取执行清单token')
        string(name: 'PLATFORM_BASE_URL', defaultValue: 'http://127.0.0.1:5010/it/api', description: '平台地址')
        string(name: 'ENV_CODE', defaultValue: 'st', description: '环境编码')
        string(name: 'RUN_MODE', defaultValue: '1', description: '1串行 2并行')
        string(name: 'TRIGGER_TYPE', defaultValue: '2', description: '1单条 2计划')
    }
    environment {
        CALLBACK_SECRET = credentials('AUTOMATION_CALLBACK_SECRET')
    }
    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }
        stage('Notify Start') {
            steps {
                bat '''
                curl -X POST "%PLATFORM_BASE_URL%/automation/execution/start" ^
                  -H "Content-Type: application/json" ^
                  -H "X-CALLBACK-SECRET: %CALLBACK_SECRET%" ^
                  -d "{\"executionId\": %EXECUTION_ID%, \"jobName\": \"pytest-auto-runner\", \"buildNumber\": %BUILD_NUMBER%, \"buildUrl\": \"%BUILD_URL%\", \"consoleUrl\": \"%BUILD_URL%console\"}"
                '''
            }
        }
        stage('Run Pytest') {
            steps {
                bat '''
                python run_execution.py ^
                  --execution-id %EXECUTION_ID% ^
                  --callback-token %CALLBACK_TOKEN% ^
                  --platform-base-url %PLATFORM_BASE_URL% ^
                  --env-code %ENV_CODE% ^
                  --run-mode %RUN_MODE% ^
                  --callback-secret %CALLBACK_SECRET%
                '''
            }
        }
    }
    post {
        failure {
            bat '''
            curl -X POST "%PLATFORM_BASE_URL%/automation/execution/abort" ^
              -H "Content-Type: application/json" ^
              -H "X-CALLBACK-SECRET: %CALLBACK_SECRET%" ^
              -d "{\"executionId\": %EXECUTION_ID%, \"status\": 5, \"message\": \"Jenkins failed\", \"buildNumber\": %BUILD_NUMBER%, \"consoleUrl\": \"%BUILD_URL%console\"}"
            '''
        }
        aborted {
            bat '''
            curl -X POST "%PLATFORM_BASE_URL%/automation/execution/abort" ^
              -H "Content-Type: application/json" ^
              -H "X-CALLBACK-SECRET: %CALLBACK_SECRET%" ^
              -d "{\"executionId\": %EXECUTION_ID%, \"status\": 6, \"message\": \"Jenkins aborted\", \"buildNumber\": %BUILD_NUMBER%, \"consoleUrl\": \"%BUILD_URL%console\"}"
            '''
        }
    }
}
```

---

### 34.3 pytest 项目：拉取执行清单示例

```bash
curl -X GET "http://127.0.0.1:5010/it/api/automation/execution/case/pull?executionId=123" \
  -H "X-CALLBACK-TOKEN: abc123token"
```

响应示例：

```json
{
  "code": 20000,
  "data": {
    "executionId": 123,
    "executionNo": "AE202502120001",
    "triggerType": 2,
    "projectId": 88,
    "planId": 2001,
    "envCode": "st",
    "runMode": 1,
    "items": [
      {
        "executionCaseId": 501,
        "planCaseId": 9001,
        "caseId": 1001,
        "caseKey": "TC-ZHYY-001",
        "caseTitle": "登录成功",
        "runOrder": 1
      }
    ]
  },
  "msg": "success"
}
```

---

### 34.4 pytest 项目：开始执行回调示例

```bash
curl -X POST "http://127.0.0.1:5010/it/api/automation/execution/start" \
  -H "Content-Type: application/json" \
  -H "X-CALLBACK-SECRET: your-callback-secret" \
  -d '{
    "executionId": 123,
    "jobName": "pytest-auto-runner",
    "buildNumber": 89,
    "buildUrl": "http://jenkins/job/pytest-auto-runner/89/",
    "consoleUrl": "http://jenkins/job/pytest-auto-runner/89/console",
    "startTime": "2025-02-12 10:00:00"
  }'
```

---

### 34.5 pytest 项目：单条用例结果回调示例

#### 通过

```bash
curl -X POST "http://127.0.0.1:5010/it/api/automation/execution/case/result" \
  -H "Content-Type: application/json" \
  -H "X-CALLBACK-SECRET: your-callback-secret" \
  -d '{
    "executionId": 123,
    "executionCaseId": 501,
    "caseId": 1001,
    "status": 2,
    "pytestNodeid": "tests/test_login.py::test_login_success",
    "resultMessage": "assert success",
    "errorMessage": "",
    "stackTrace": "",
    "durationSeconds": 12,
    "reportUrl": "http://allure/case/1001",
    "startedTime": "2025-02-12 10:01:00",
    "finishedTime": "2025-02-12 10:01:12",
    "ext": {
      "attachments": []
    }
  }'
```

#### 失败

```bash
curl -X POST "http://127.0.0.1:5010/it/api/automation/execution/case/result" \
  -H "Content-Type: application/json" \
  -H "X-CALLBACK-SECRET: your-callback-secret" \
  -d '{
    "executionId": 123,
    "executionCaseId": 502,
    "caseId": 1002,
    "status": 3,
    "pytestNodeid": "tests/test_login.py::test_login_fail",
    "resultMessage": "assert failed",
    "errorMessage": "AssertionError: 登录失败提示不匹配",
    "stackTrace": "Traceback ...",
    "durationSeconds": 8,
    "reportUrl": "http://allure/case/1002",
    "startedTime": "2025-02-12 10:01:13",
    "finishedTime": "2025-02-12 10:01:21"
  }'
```

#### 未找到自动化实现

```bash
curl -X POST "http://127.0.0.1:5010/it/api/automation/execution/case/result" \
  -H "Content-Type: application/json" \
  -H "X-CALLBACK-SECRET: your-callback-secret" \
  -d '{
    "executionId": 123,
    "executionCaseId": 503,
    "caseId": 1003,
    "status": 6,
    "resultMessage": "case_id 未映射到 pytest 用例",
    "errorMessage": "",
    "durationSeconds": 0,
    "finishedTime": "2025-02-12 10:01:22"
  }'
```

---

### 34.6 pytest 项目：执行完成回调示例

```bash
curl -X POST "http://127.0.0.1:5010/it/api/automation/execution/finish" \
  -H "Content-Type: application/json" \
  -H "X-CALLBACK-SECRET: your-callback-secret" \
  -d '{
    "executionId": 123,
    "buildNumber": 89,
    "buildUrl": "http://jenkins/job/pytest-auto-runner/89/",
    "consoleUrl": "http://jenkins/job/pytest-auto-runner/89/console",
    "reportUrl": "http://allure/report/89",
    "startTime": "2025-02-12 10:00:00",
    "endTime": "2025-02-12 10:08:00",
    "durationSeconds": 480,
    "summary": {
      "total": 15,
      "passed": 12,
      "failed": 2,
      "blocked": 0,
      "skipped": 1,
      "notFound": 0
    },
    "message": "执行完成"
  }'
```

> 注意：当前后端实现里 `finish_execution()` 最终仍会以明细表聚合结果为准刷新主单状态，所以 pytest 回传 `summary` 更像补充信息，不是唯一可信来源。

---

### 34.7 Jenkins 失败/取消兜底回调示例

#### 失败

```bash
curl -X POST "http://127.0.0.1:5010/it/api/automation/execution/abort" \
  -H "Content-Type: application/json" \
  -H "X-CALLBACK-SECRET: your-callback-secret" \
  -d '{
    "executionId": 123,
    "status": 5,
    "message": "Jenkins failed",
    "buildNumber": 89,
    "consoleUrl": "http://jenkins/job/pytest-auto-runner/89/console"
  }'
```

#### 取消

```bash
curl -X POST "http://127.0.0.1:5010/it/api/automation/execution/abort" \
  -H "Content-Type: application/json" \
  -H "X-CALLBACK-SECRET: your-callback-secret" \
  -d '{
    "executionId": 123,
    "status": 6,
    "message": "Jenkins aborted",
    "buildNumber": 89,
    "consoleUrl": "http://jenkins/job/pytest-auto-runner/89/console"
  }'
```

---

### 34.8 pytest 侧最小执行脚本伪代码

```python
import requests
import pytest


def pull_cases(base_url, execution_id, callback_token):
    resp = requests.get(
        f"{base_url}/automation/execution/case/pull",
        params={"executionId": execution_id},
        headers={"X-CALLBACK-TOKEN": callback_token},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["data"]


def callback_case_result(base_url, callback_secret, payload):
    requests.post(
        f"{base_url}/automation/execution/case/result",
        json=payload,
        headers={"X-CALLBACK-SECRET": callback_secret},
        timeout=30,
    ).raise_for_status()


if __name__ == '__main__':
    # 1. 拉取 execution 清单
    # 2. 建立 case_id -> pytest nodeid 映射
    # 3. 逐条执行
    # 4. 每条回调结果
    # 5. 最后回调 finish
    pass
```

---

## 35. 结论

最适合你当前项目的方案不是改造现有 `plan_case_execute`，而是：

- **在现有 MVC 上新增独立 automation 执行域**
- **以 `case_id` 作为功能用例与 pytest 自动化用例的桥梁**
- **平台负责建单、编排、回写和状态聚合**
- **Jenkins 负责调度**
- **pytest 项目负责按 `execution_id` 拉取清单并执行**

这样设计：
- 和你当前项目结构最兼容
- AI 最容易按层写代码
- 后续扩展单条执行、计划批量、并行、重跑都不会推翻重来