# 阅读任务变更

企业/组织开通事件回调后,可接收阅读任务的发起、完成回调,与自有系统(如 OA 待阅)进行对接。由开放接口触发的变更不会发送回调。

阅读任务按成员维度管理:发起时指定一批需要阅读的成员,每位成员完成阅读各产生一条完成回调,staff_id 标识完成人。

# 发起阅读任务

事件类型:reading_task/create

创建阅读任务并指定阅读成员时触发,每个任务仅触发一次。

# 回调示例

{
  "nonce": "dbf89571-2a77-4bb6-9a18-ba025e1cc6a7",
  "timestamp": 1793254963,
  "sign": "299744be4ddea11e80633827cf97d2a9afff0ddf",
  "operator": "zhangsan",
  "is_anonymous": false,
  "operator_info": {
    "name": "zhangsan"
  },
  "action": "reading_task/create",
  "attributes": {
    "task_id": "a54dfccd34c94a998f88597617fad69c",
    "title": "2026 年信息安全规范",
    "task_type": "reading",
    "target_type": "kb_entry",
    "target_id": "98559125f3674ff585bd083b41416a12",
    "entity_type": "",
    "entity_id": "",
    "created_by": "zhangsan",
    "total_staff_count": 5,
    "finished_staff_count": 0,
    "due_at": 1793375999,
    "url": "https://lexiangla.com/pages/98559125f3674ff585bd083b41416a12?company_from=xxx"
  }
}

# 参数说明:

参数 说明
task_id 阅读任务 ID
title 阅读任务标题,取自关联知识名称
task_type 任务类型,固定为 reading
target_type 关联对象类型,如 kb_entry(知识)
target_id 关联对象 ID,kb_entry 时为知识 ID
entity_type 业务实体类型,当前版本为空字符串
entity_id 业务实体 ID,当前版本为空字符串
created_by 任务发起人账号
total_staff_count 需要阅读的总人数
finished_staff_count 已完成阅读人数
due_at 截止时间,Unix 时间戳(秒)
url 知识跳转链接,可直接打开需要阅读的知识

任务创建瞬间成员可能尚未同步完成,total_staff_count 可能为 0;后续完成回调中的计数为实时值。

# 完成阅读任务

事件类型:reading_task/complete

成员完成阅读时触发,每位成员完成各触发一次。

# 回调示例

{
  "nonce": "7c4e9a2b-3f8d-4b6a-9e1c-5d2f8a7b3c94",
  "timestamp": 1793255800,
  "sign": "8b3e7f1c5a9d2046e8b3c7f1a5d9b402e6c8f173",
  "operator": "lisi",
  "is_anonymous": false,
  "operator_info": {
    "name": "lisi"
  },
  "action": "reading_task/complete",
  "attributes": {
    "task_id": "a54dfccd34c94a998f88597617fad69c",
    "title": "2026 年信息安全规范",
    "task_type": "reading",
    "target_type": "kb_entry",
    "target_id": "98559125f3674ff585bd083b41416a12",
    "entity_type": "",
    "entity_id": "",
    "created_by": "zhangsan",
    "total_staff_count": 5,
    "finished_staff_count": 2,
    "due_at": 1793375999,
    "staff_id": "lisi",
    "url": "https://lexiangla.com/pages/98559125f3674ff585bd083b41416a12?company_from=xxx"
  }
}

# 参数说明:

字段同「发起阅读任务」,额外增加:

参数 说明
staff_id 完成阅读的成员账号,用于核销该成员的待阅

finished_staff_count 为本次完成后的实时计数。接收端应按 (task_id, staff_id) 幂等处理,避免重试导致重复核销。

# 事件时序

reading_task/create(发起,指定 N 位成员)
   └─ reading_task/complete × N(每位成员完成各一次)

# 说明

  • 取消完成不会产生回调:成员取消「已完成」状态目前不会发送事件,接收端以 reading_task/complete 作为最终核销依据时,需注意该场景下的状态差异。
  • 任务删除、成员调整等操作本期未提供回调事件。