# 分页查询某个周期内各码的执行情况

按码分页返回某个周期内各码的执行情况。period_key 先从 cycleTasks/getCompletion 取得并原样传入；status 筛选的是该周期的任务状态，与筛选计划生命周期的 plan_scope 不同。

## 请求

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

| 项目 | 要求 |
|---|---|
| 最低权限 | 只读，见[权限档位](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 |
| `plan_scope` | string | 否 | 计划所处阶段：running（默认）已启用且未结束，包含 active 和 not_started；active 已开始且生效中；not_started 已启用但未到开始时间；closed 已暂停；finished 计划已结束（不代表各周期的任务都已完成）。它与 cycleTasks/listQrcodes 的 status（某个周期内各码的完成状态）不是同一个概念。可选值：`running`、`active`、`not_started`、`closed`、`finished`。默认 `"running"` |
| `period_key` | string | 是 | 周期标识，原样使用 cycleTasks/getCompletion 返回的 period_key，不要自行拼接。最长 128 个字符 |
| `status` | string | 否 | 按该周期内各码的完成状态筛选：all（默认）全部；finished 已完成；unfinished 未完成（包含 not_started、in_progress、expired_unfinished）；no_need 无需执行；expired_unfinished 逾期未完成；in_progress 进行中；not_started 未开始。可选值：`all`、`finished`、`unfinished`、`no_need`、`expired_unfinished`、`in_progress`、`not_started`。默认 `"all"` |
| `page` | integer | 否 | 页码，从 1 开始。默认 `1`。范围 1–10000 |
| `page_size` | integer | 否 | 每页条数。默认 `20`。范围 1–100 |

## 请求示例

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

```bash
curl -sS -X POST 'https://open.cli.im/api/v2/rpc/cycleTasks/listQrcodes' \
  -H "Authorization: Bearer ${CAOLIAO_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_id": 0,
  "plan_id": "40021",
  "period_key": "2026-11-18",
  "status": "unfinished",
  "page": 1,
  "page_size": 20
}'
```

## 响应

成功时 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.list` | object[] | 是 | 各码的执行情况 |
| `data.list[].code_id` | string | 是 | 码 ID |
| `data.list[].code_name` | string | 否 | 码名称 |
| `data.list[].code_number` | any | 否 | 码编号 |
| `data.list[].code_status` | any | 否 | 该码在这个周期的状态 |
| `data.list[].code_status_detail` | any | 否 | 更细的状态 |
| `data.list[].code_status_text` | string | 否 | 状态文字 |
| `data.list[].finished_times` | any | 否 | 已完成次数 |
| `data.list[].required_times` | any | 否 | 要求完成次数 |
| `data.list[].configured_required_times` | any | 否 | 计划配置的要求次数 |
| `data.list[].effective_required_times` | any | 否 | 实际生效的要求次数 |
| `data.list[].times` | object[] | 是 | 各执行时段的情况 |
| `data.list[].times[].seq` | any | 否 | 时段序号 |
| `data.list[].times[].task_instance_id` | any | 否 | 任务实例 ID |
| `data.list[].times[].execute_status` | any | 否 | 执行状态 |
| `data.list[].times[].execute_status_text` | any | 否 | 执行状态文字 |
| `data.list[].times[].real_execute_time` | any | 否 | 实际执行时间 |
| `data.list[].times[].start_time` | any | 否 | 时段开始时间 |
| `data.list[].times[].end_time` | any | 否 | 时段结束时间 |
| `data.list[].times[].is_applicable` | any | 否 | 该时段是否需要执行 |
| `data.list[].times[].skip_reason` | any | 否 | 无需执行的原因 |
| `data.list[].times[].record_id` | any | 否 | 对应的填写记录 ID；没有填写记录时为空 |
| `data.list[].times[].auto_rule_id` | any | 否 | 自动判定完成的规则 ID |
| `data.list[].times[].auto_reason` | any | 否 | 自动判定完成的原因 |
| `data.pagination` | object | 是 | 分页信息 |
| `data.pagination.page` | integer | 是 | 当前页码，从 1 开始 |
| `data.pagination.page_size` | integer | 是 | 每页条数 |
| `data.pagination.total` | integer | 是 | 符合条件的总条数 |
| `data.pagination.has_more` | boolean | 是 | 是否还有下一页。为 true 时即使当前页为空也应继续翻页 |
| `data.period_key` | string | 是 | 本次查询的周期标识 |
| `data.status` | string | 是 | 本次查询使用的状态筛选 |

### 响应示例

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "code_id": "7001234",
        "code_name": "1 号空压机",
        "code_status": "unfinished",
        "code_status_detail": "not_started",
        "code_status_text": "未开始",
        "finished_times": 0,
        "required_times": 1,
        "times": [
          {
            "seq": 1,
            "execute_status": "not_started",
            "start_time": "2026-11-18 00:00:00",
            "end_time": "2026-11-18 23:59:59",
            "is_applicable": true,
            "record_id": null
          }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 3,
      "has_more": false
    },
    "period_key": "2026-11-18",
    "status": "unfinished"
  }
}
```

## 常见错误

`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)。
