# 查询各周期的完成情况

按计划 ID 和时间范围查询各周期的完成、未完成数量，周期状态和跳过原因。range_limit.truncated 为 true 时按 next_end_time 继续查询；只读，不创建或修改计划。

## 请求

```text
POST https://open.cli.im/api/v2/rpc/cycleTasks/getCompletion
```

| 项目 | 要求 |
|---|---|
| 最低权限 | 只读，见[权限档位](https://cli.im/open-api/openapi/v2/auth.md#org-policy) |
| 需要的 scope | `records.read` |
| 组织 Key | 不能调用，返回 403 `credential_type_not_allowed`，见[历史组织 Key](https://cli.im/open-api/openapi/v2/auth.md#org-key) |

## 请求参数

请求体为 JSON。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `project_id` | integer | 否 | 计划所在分区 ID，0 为默认分区。默认 `0` |
| `plan_id` | string | 是 | 周期计划 ID，取自 cyclePlans/list |
| `start_time` | string | 是 | 查询范围的开始时间，格式 YYYY-MM-DD HH:mm:ss，如 2026-11-18 00:00:00 |
| `end_time` | string | 是 | 查询范围的结束时间，格式 YYYY-MM-DD HH:mm:ss，如 2026-11-18 23:59:59；与开始时间最多相隔 366 天 |
| `period_limit` | integer | 否 | 最多返回的周期数，默认 60，最大 120。默认 `60`。范围 1–120 |
| `plan_scope` | string | 否 | 计划所处阶段：running（默认）已启用且未结束，包含 active 和 not_started；active 已开始且生效中；not_started 已启用但未到开始时间；closed 已暂停；finished 计划已结束（不代表各周期的任务都已完成）。它与 cycleTasks/listQrcodes 的 status（某个周期内各码的完成状态）不是同一个概念。可选值：`running`、`active`、`not_started`、`closed`、`finished`。默认 `"running"` |

## 请求示例

示例里的 ID、幂等键等换成实际值。

```bash
curl -sS -X POST 'https://open.cli.im/api/v2/rpc/cycleTasks/getCompletion' \
  -H "Authorization: Bearer ${CAOLIAO_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_id": 0,
  "plan_id": "40021",
  "start_time": "2026-11-17 00:00:00",
  "end_time": "2026-11-18 23:59:59"
}'
```

## 响应

成功时 HTTP 状态码为 200，顶层 `code` 为 `0`，结果在 `data` 里。失败时的返回见[错误码与调用额度](https://cli.im/open-api/openapi/v2/error-codes.md)和[业务错误码](https://cli.im/open-api/openapi/v2/error-catalog.md)。

| 字段 | 类型 | 一定返回 | 说明 |
|---|---|---|---|
| `data.plan` | object | 是 | 计划概况 |
| `data.plan.plan_id` | any | 否 | 周期计划 ID |
| `data.periods` | object[] | 是 | 时间范围内的各个周期。空数组不代表全部完成 |
| `data.periods[].period_key` | string | 是 | 周期标识。查询该周期内各码的执行情况时原样传给 cycleTasks/listQrcodes |
| `data.periods[].label` | string | 否 | 周期名称 |
| `data.periods[].short_label` | string | 否 | 周期简称 |
| `data.periods[].weekday` | any | 否 | 周期对应的星期 |
| `data.periods[].start_time` | string | 否 | 周期开始时间 |
| `data.periods[].end_time` | string | 否 | 周期结束时间 |
| `data.periods[].period_state` | string | 否 | 周期状态 |
| `data.periods[].is_skipped` | boolean | 否 | 该周期是否被跳过（如节假日） |
| `data.periods[].skip_reason` | string | 否 | 跳过原因；未跳过时为空字符串 |
| `data.periods[].required_times` | integer | 否 | 该周期要求完成的次数 |
| `data.periods[].time_slots` | any[] | 否 | 周期内的执行时段 |
| `data.periods[].total_code_count` | integer | 否 | 计划覆盖的码数量 |
| `data.periods[].should_check_code_count` | integer | 否 | 该周期应执行的码数量 |
| `data.periods[].finished_code_count` | integer | 否 | 已完成的码数量 |
| `data.periods[].unfinished_code_count` | integer | 否 | 未完成的码数量 |
| `data.periods[].skip_code_count` | integer | 否 | 无需执行的码数量 |
| `data.periods[].finish_percent` | number | 否 | 完成比例 |
| `data.periods[].code_status_counts` | any | 否 | 按码状态统计的数量 |
| `data.periods[].code_status_detail_counts` | any | 否 | 按码状态明细统计的数量 |
| `data.range_limit` | object | 是 | 结果是否被截断 |
| `data.range_limit.max_periods` | integer | 是 | 本次最多返回的周期数 |
| `data.range_limit.truncated` | boolean | 是 | 是否还有更早的周期没有返回 |
| `data.range_limit.covered_start_time` | any | 否 | 本次结果覆盖的开始时间 |
| `data.range_limit.covered_end_time` | any | 否 | 本次结果覆盖的结束时间 |
| `data.range_limit.next_end_time` | string | 是 | truncated 为 true 时，把它作为下一次请求的 end_time 继续查询更早的周期 |

### 响应示例

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "plan": {
      "plan_id": "40021"
    },
    "periods": [
      {
        "period_key": "2026-11-18",
        "label": "11月18日",
        "start_time": "2026-11-18 00:00:00",
        "end_time": "2026-11-18 23:59:59",
        "period_state": "in_progress",
        "is_skipped": false,
        "skip_reason": "",
        "required_times": 1,
        "total_code_count": 12,
        "should_check_code_count": 12,
        "finished_code_count": 9,
        "unfinished_code_count": 3,
        "skip_code_count": 0,
        "finish_percent": 75
      }
    ],
    "range_limit": {
      "max_periods": 60,
      "truncated": false,
      "covered_start_time": "2026-11-17 00:00:00",
      "covered_end_time": "2026-11-18 23:59:59",
      "next_end_time": null
    }
  }
}
```

## 常见错误

`PERMISSION_DENIED`、`CYCLE_QUERY_REJECTED`、`CYCLE_QUERY_UNAVAILABLE`。含义和处理方式见[业务错误码](https://cli.im/open-api/openapi/v2/error-catalog.md)。

---

本页由 [openapi.json](https://cli.im/open-api/openapi/v2/overview.md#%E6%8E%A5%E5%8F%A3%E8%A7%84%E8%8C%83-openapi-json) 生成。全部接口见[接口清单](https://cli.im/open-api/openapi/v2/api-index.md)。
