慧企星助开放平台文档

目标与复盘接口

目标、关键结果和周期接口使用 objectives.read 或 objectives.write；复盘接口使用独立的 objectiveReviews.read 或 objectiveReviews.write。所有资源均按当前企业和操作员工权限校验。

标识规则：目标、关键结果、周期和复盘资源均使用 id（Guid）作为资源标识；员工对象只返回公开展示字段和当前 API Key 范围内的 virtualId，不会返回手机号、账号、部门内部 Id 或真实员工 Guid，不得用员工 virtualId 替代业务资源 id。

目标接口

GET/api/openplatform/objectives

查询目标列表。

参数	类型	必填	说明
`page`	int	否	页码。
`pageSize`	int	否	每页条数。
`keyword`	string	否	目标关键字。
`group`	int	否	目标分组。
`level`	string	否	目标层级筛选（字符串枚举：`all` 全部、`personal` 个人级、`department` 部门级、`company` 公司级）。
`cycle`	string	否	周期类型筛选（字符串枚举：`all` 全部、`week` 周、`month` 月、`quarter` 季、`year` 年、`custom` 自定义）。目标归属的具体周期用创建/修改目标时的 `cycleId`（guid）指定。
`departmentId`	int	否	部门标识。

列表响应字段

字段	类型	说明
`data.total`	long	符合筛选条件的目标总数。
`data.page`	int	当前页码，从 1 开始。
`data.pageSize`	int	当前页返回条数上限，范围为 1 到 100。
`data.items`	Objective[]	当前页目标列表；单项目字段见下表。

Objective 通用字段

目标列表的单项与 GET /api/openplatform/objectives/{id} 详情共用以下资源字段。详情包含完整目标数据，列表按当前员工的可见范围返回相应字段。

字段	类型	说明
`id`	guid	目标资源标识。
`name`	string	目标名称。
`content`	string	目标内容或备注；未填写时为空字符串。
`group`	int	目标分组值。
`level`	int	目标层级值（1 个人目标、2 部门目标、3 公司目标）。
`levelStr`	string	目标层级中文文案，与 `level` 配套返回。
`cycleId`	guid	所属目标周期标识。
`date`	string	周期内日期数据的 JSON 字符串。
`parentObjectiveId`	guid \| null	父目标标识；顶层目标为 `null`。
`departmentId`	guid \| null	关联部门标识；未关联时为 `null`。
`visibleRange`	int	目标可见范围配置值。
`score`	decimal	目标贡献点，单位为“点”。
`isLockScore`	bool	是否锁定目标贡献点。
`owners`	object[]	目标责任人的成员对象数组（每项含 `virtualId`、`name` 与掩码 `phone`）。
`participants`	object[]	目标参与人的成员对象数组（每项含 `virtualId`、`name` 与掩码 `phone`）。
`createdAt`	string	创建时间，ISO 8601 带时区字符串。
`updatedAt`	string \| null	最后更新时间，ISO 8601 带时区字符串；未更新时可能为空或 `null`。

POST/api/openplatform/objectives

创建目标。人员字段请使用 ownerVirtualIds、participantVirtualIds，不得传内部员工 Guid。

GET/api/openplatform/objectives/{id}

查询目标详情。

路径参数：id 为目标 Guid。

响应字段：返回一个完整 Objective 对象，字段、类型和含义见上方“Objective 通用字段”；目标详情中的 keyResults 字段为关键结果列表，单项结构见下方说明。

PATCH/api/openplatform/objectives/{id}

修改目标字段。

路径参数：id 为目标 Guid。

DELETE/api/openplatform/objectives/{id}

删除目标。

路径参数：id 为目标 Guid。

GET/api/openplatform/objectives/{id}/children

查询子目标，支持 page 和 pageSize 分页参数。

路径参数：id 为父目标 Guid。

响应字段：data 使用 total、page、pageSize、items 分页包装，items 单项为 Objective，字段见上方通用字段表。

GET/api/openplatform/objectives/{id}/keyResults

查询目标的关键结果。

路径参数：id 为目标 Guid。

响应字段

字段	类型	说明
`data`	KeyResult[]	关键结果列表。
`id`	guid	关键结果标识。
`name`	string	关键结果名称。
`content`	string	关键结果说明。
`weight`	decimal	关键结果权重。
`targetValue`	decimal	目标值。
`startingValue`	decimal	起始值。
`currentValue`	decimal	当前完成值。
`progress`	decimal	完成进度。
`confidence`	int	信心指数。
`unit`	string	数值单位。

POST/api/openplatform/objectives/{id}/keyResults

新增目标关键结果。

路径参数：id 为目标 Guid。

PATCH/api/openplatform/objectives/{objectiveId}/keyResults/{keyResultId}

修改关键结果。

路径参数：objectiveId 为所属目标 Guid，keyResultId 为关键结果 Guid。

DELETE/api/openplatform/objectives/{objectiveId}/keyResults/{keyResultId}

删除关键结果。

路径参数：objectiveId 为所属目标 Guid，keyResultId 为关键结果 Guid。

GET/api/openplatform/objectives/{objectiveId}/keyResults/{keyResultId}/progress

查询关键结果进度记录。

路径参数：objectiveId 为所属目标 Guid，keyResultId 为关键结果 Guid。

字段	类型	说明
`data`	KeyResultProgress[]	进度记录列表。
`createdAt`	string	记录创建时间，ISO 8601 带时区字符串。
`currentValue`	decimal	本次记录后的当前值。
`progress`	decimal	本次记录后的完成进度。
`content`	string	进度说明。

GET/api/openplatform/objectives/cycles

查询当前企业的目标周期。

字段	类型	说明
`data`	ObjectiveCycle[]	目标周期列表。
`id`	guid	周期标识，用于创建目标的 `cycleId`。
`name`	string	周期名称。
`type`	int	周期类型值，与 `name`（周期名称）配套使用；创建/修改目标时按本接口返回的 `id` 传 `cycleId`。
`startAt`	string	周期开始时间，ISO 8601 带时区字符串。
`endAt`	string	周期结束时间，ISO 8601 带时区字符串。

目标复盘接口

复盘字段：复盘独立于绩效评价模块。复盘内容使用 valueAndGain（价值与收获）、deficiencyAndMethod（不足与改进方法）、improvementPlan（改进计划）、participantVirtualIds 和 attachmentUrls（附件）。

GET/api/openplatform/objectives/{id}/reviews

查询目标复盘列表。

路径参数：id 为目标 Guid。

字段	类型	说明
`data`	ObjectiveReview[]	目标复盘列表。
`id`	guid	复盘标识，用于修改复盘。
`valueAndGain`	string	价值与收获。
`deficiencyAndMethod`	string	不足与改进方法。
`improvementPlan`	string	改进计划。
`participants`	object[]	复盘参与人的成员对象数组（每项含 `virtualId`、`name` 与掩码 `phone`）。
`attachmentUrls`	string[]	复盘附件公开 URL 列表。
`createdAt`	string	提交时间，ISO 8601 带时区字符串。

POST/api/openplatform/objectives/{id}/reviews

提交目标复盘。

路径参数：id 为目标 Guid。

{
  "valueAndGain": "达成了跨部门交付目标",
  "deficiencyAndMethod": "前期排期沟通不足",
  "improvementPlan": "下周期提前完成资源评审",
  "participantVirtualIds": ["emp_xxx"],
  "attachmentUrls": []
}

PATCH/api/openplatform/objectives/{objectiveId}/reviews/{reviewId}

修改目标复盘。objectiveId 为所属目标 Guid，reviewId 为复盘 Guid。