# API 文档 - 代码覆盖率功能

## 元数据
- 需求编号：002-04
- 需求名称：代码覆盖率
- 创建时间：2026-02-03
- 创建人：AI Assistant
- 版本号：v1.0.0
- 状态：已完成

## API 概述
代码覆盖率 API 提供 Salesforce Apex 代码覆盖率的查询和统计功能。通过本 API，可以查询代码覆盖率列表、查看代码覆盖率详情、统计总体代码覆盖率、按类型统计代码覆盖率等。本 API 复用 002-03 测试执行功能的数据库表，通过独立的 Service 层提供代码覆盖率相关的查询和统计能力。

## 接口列表

### 接口 1：查询代码覆盖率列表

**功能描述**：查询代码覆盖率列表，支持多条件筛选、分页查询、覆盖率范围筛选。

**请求方式**：GET

**请求路径**：`/api/apex/coverage`

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| testResultId | Long | 否 | 测试结果 ID，筛选指定测试结果的代码覆盖率 |
| name | String | 否 | 类/触发器名称，支持模糊查询 |
| namespace | String | 否 | 命名空间，支持模糊查询 |
| type | String | 否 | 类型，可选值：Class、Trigger |
| minCoverage | Double | 否 | 最小覆盖率（0-100），在内存中筛选 |
| maxCoverage | Double | 否 | 最大覆盖率（0-100），在内存中筛选 |
| pageNum | Integer | 否 | 页码，默认 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 |
| orderByColumn | String | 否 | 排序字段，可选值：createTime、coveragePercent |
| isAsc | String | 否 | 是否升序，可选值：asc、desc，默认 desc |

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| rows | Array | 代码覆盖率列表 |
| rows[].id | Long | 覆盖率记录 ID |
| rows[].testResultId | Long | 测试结果 ID |
| rows[].name | String | 类/触发器名称 |
| rows[].type | String | 类型（Class/Trigger） |
| rows[].namespace | String | 命名空间 |
| rows[].numLocations | Integer | 总位置数 |
| rows[].numLocationsNotCovered | Integer | 未覆盖的位置数 |
| rows[].coveragePercent | Double | 覆盖率百分比（0-100） |
| rows[].createTime | String | 创建时间（yyyy-MM-dd HH:mm:ss） |
| total | Long | 总记录数 |

**成功示例**：
```json
{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1,
      "testResultId": 100,
      "name": "AccountTrigger",
      "type": "Trigger",
      "namespace": "",
      "numLocations": 50,
      "numLocationsNotCovered": 10,
      "coveragePercent": 80.00,
      "createTime": "2026-02-03 10:30:00"
    },
    {
      "id": 2,
      "testResultId": 100,
      "name": "AccountService",
      "type": "Class",
      "namespace": "",
      "numLocations": 100,
      "numLocationsNotCovered": 20,
      "coveragePercent": 80.00,
      "createTime": "2026-02-03 10:30:00"
    }
  ],
  "total": 2
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "查询代码覆盖率列表失败：数据库访问异常"
}
```

**权限要求**：`apex:coverage:query`

---

### 接口 2：查询代码覆盖率详情

**功能描述**：根据 ID 查询单条代码覆盖率记录的详细信息。

**请求方式**：GET

**请求路径**：`/api/apex/coverage/{id}`

**路径参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 覆盖率记录 ID |

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 代码覆盖率详情 |
| data.id | Long | 覆盖率记录 ID |
| data.testResultId | Long | 测试结果 ID |
| data.name | String | 类/触发器名称 |
| data.type | String | 类型（Class/Trigger） |
| data.namespace | String | 命名空间 |
| data.numLocations | Integer | 总位置数 |
| data.numLocationsNotCovered | Integer | 未覆盖的位置数 |
| data.coveragePercent | Double | 覆盖率百分比（0-100） |
| data.createTime | String | 创建时间（yyyy-MM-dd HH:mm:ss） |

**成功示例**：
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "id": 1,
    "testResultId": 100,
    "name": "AccountTrigger",
    "type": "Trigger",
    "namespace": "",
    "numLocations": 50,
    "numLocationsNotCovered": 10,
    "coveragePercent": 80.00,
    "createTime": "2026-02-03 10:30:00"
  }
}
```

**失败示例**：
```json
{
  "code": 404,
  "msg": "代码覆盖率记录不存在"
}
```

**权限要求**：`apex:coverage:query`

---

### 接口 3：查询总体代码覆盖率

**功能描述**：查询总体代码覆盖率统计，包括总体覆盖率、类覆盖率、触发器覆盖率、总类数、总触发器数等。

**请求方式**：GET

**请求路径**：`/api/apex/coverage/total`

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| testResultId | Long | 否 | 测试结果 ID，统计指定测试结果的代码覆盖率；不传则统计所有数据 |

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 总体覆盖率统计 |
| data.testResultId | Long | 测试结果 ID |
| data.totalCoverage | Double | 总体覆盖率（0-100） |
| data.totalClasses | Integer | 总类数 |
| data.totalTriggers | Integer | 总触发器数 |
| data.totalLocations | Integer | 总位置数 |
| data.totalNotCovered | Integer | 未覆盖位置数 |
| data.coveredLocations | Integer | 已覆盖位置数 |
| data.classCoverage | Double | 类覆盖率（0-100） |
| data.triggerCoverage | Double | 触发器覆盖率（0-100） |
| data.testTime | String | 测试时间（yyyy-MM-dd HH:mm:ss） |

**成功示例**：
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "testResultId": 100,
    "totalCoverage": 82.50,
    "totalClasses": 10,
    "totalTriggers": 5,
    "totalLocations": 800,
    "totalNotCovered": 140,
    "coveredLocations": 660,
    "classCoverage": 85.00,
    "triggerCoverage": 78.00,
    "testTime": "2026-02-03 10:30:00"
  }
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "查询总体代码覆盖率失败：数据库访问异常"
}
```

**权限要求**：`apex:coverage:query`

---

### 接口 4：按类型统计代码覆盖率

**功能描述**：按 Class/Trigger 类型分别统计代码覆盖率，返回每种类型的覆盖率、总位置数、未覆盖位置数等。

**请求方式**：GET

**请求路径**：`/api/apex/coverage/summary`

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| testResultId | Long | 否 | 测试结果 ID，统计指定测试结果的代码覆盖率；不传则统计所有数据 |

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 按类型统计结果 |
| data.testResultId | Long | 测试结果 ID |
| data.classSummary | Object | 类统计信息 |
| data.classSummary.type | String | 类型（Class） |
| data.classSummary.count | Integer | 类数量 |
| data.classSummary.totalLocations | Integer | 总位置数 |
| data.classSummary.notCovered | Integer | 未覆盖位置数 |
| data.classSummary.coveragePercent | Double | 覆盖率（0-100） |
| data.triggerSummary | Object | 触发器统计信息 |
| data.triggerSummary.type | String | 类型（Trigger） |
| data.triggerSummary.count | Integer | 触发器数量 |
| data.triggerSummary.totalLocations | Integer | 总位置数 |
| data.triggerSummary.notCovered | Integer | 未覆盖位置数 |
| data.triggerSummary.coveragePercent | Double | 覆盖率（0-100） |

**成功示例**：
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "testResultId": 100,
    "classSummary": {
      "type": "Class",
      "count": 10,
      "totalLocations": 600,
      "notCovered": 90,
      "coveragePercent": 85.00
    },
    "triggerSummary": {
      "type": "Trigger",
      "count": 5,
      "totalLocations": 200,
      "notCovered": 50,
      "coveragePercent": 75.00
    }
  }
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "按类型统计代码覆盖率失败：数据库访问异常"
}
```

**权限要求**：`apex:coverage:query`

---

## 错误码

| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 200 | 成功 | - |
| 401 | 未授权 | 检查用户是否已登录 |
| 403 | 禁止访问 | 检查用户是否具有 `apex:coverage:query` 权限 |
| 404 | 资源不存在 | 检查请求的资源 ID 是否正确 |
| 500 | 服务器内部错误 | 查看服务器日志，联系管理员 |
| 1001 | 参数错误 | 检查请求参数是否符合要求 |
| 1002 | 无效的测试结果 ID | 检查测试结果 ID 是否正确 |
| 1003 | 无效的覆盖率 ID | 检查覆盖率 ID 是否正确 |
| 1004 | 无效的覆盖率类型 | 覆盖率类型必须是 "Class" 或 "Trigger" |
| 1005 | 无效的覆盖率值 | 覆盖率值必须在 0 到 100 之间 |
| 1006 | 查询失败 | 数据库查询失败，请联系管理员 |
| 1007 | 数据访问失败 | 数据库访问失败，请联系管理员 |

## 覆盖率计算说明

### 单个类/触发器覆盖率
```
coveragePercent = (1 - numLocationsNotCovered / numLocations) * 100
```

### 总体覆盖率
```
totalCoverage = (1 - totalNotCovered / totalLocations) * 100
```

### 类覆盖率
```
classCoverage = (1 - classNotCovered / classTotalLocations) * 100
```

### 触发器覆盖率
```
triggerCoverage = (1 - triggerNotCovered / triggerTotalLocations) * 100
```

### 计算规则
- 保留两位小数（四舍五入）
- 除零保护：当总位置数为 0 时，返回 0.0

## 使用示例

### 示例 1：查询所有代码覆盖率
```bash
curl -X GET "http://localhost:8080/api/apex/coverage?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer {token}"
```

### 示例 2：查询指定测试结果的代码覆盖率
```bash
curl -X GET "http://localhost:8080/api/apex/coverage?testResultId=100&pageNum=1&pageSize=10" \
  -H "Authorization: Bearer {token}"
```

### 示例 3：查询覆盖率在 70% 到 90% 之间的代码
```bash
curl -X GET "http://localhost:8080/api/apex/coverage?minCoverage=70&maxCoverage=90&pageNum=1&pageSize=10" \
  -H "Authorization: Bearer {token}"
```

### 示例 4：查询代码覆盖率详情
```bash
curl -X GET "http://localhost:8080/api/apex/coverage/1" \
  -H "Authorization: Bearer {token}"
```

### 示例 5：查询总体代码覆盖率
```bash
curl -X GET "http://localhost:8080/api/apex/coverage/total?testResultId=100" \
  -H "Authorization: Bearer {token}"
```

### 示例 6：按类型统计代码覆盖率
```bash
curl -X GET "http://localhost:8080/api/apex/coverage/summary?testResultId=100" \
  -H "Authorization: Bearer {token}"
```

## 注意事项

1. **数据依赖**：代码覆盖率数据由测试执行功能（002-03）生成，本 API 只提供查询和统计功能。

2. **权限控制**：所有接口需要 `apex:coverage:query` 权限。

3. **覆盖率范围筛选**：由于覆盖率是计算字段，范围筛选（minCoverage、maxCoverage）在内存中进行，对于大数据量可能影响性能。

4. **数据一致性**：本功能复用 002-03 的 `datai_apex_code_coverage` 表，数据格式和字段含义与 002-03 保持一致。

5. **分页查询**：使用 PageHelper 进行物理分页，默认每页 10 条记录。

6. **排序**：支持按创建时间（createTime）和覆盖率（coveragePercent）排序。

## 相关文档

- [需求文档](../requirements/sub/2026-01-28-002-04-代码覆盖率.md)
- [设计文档](../design/2026-02-03-002-04-代码覆盖率-设计.md)
- [决策记录](../decisions/2026-02-03-002-04-ADR-代码覆盖率技术选型.md)
- [变更日志](../changelog/2026-02-03-002-04-changelog.md)
- [复盘文档](../retros/2026-02-03-002-04-retro.md)