慧企星助开放平台文档

成就接口

成就接口查询需要 achievements.read 权限、领取需要 achievements.write 权限，依赖企业套餐成就模块。所有查询都围绕当前操作员工展开：类别、待领取、我的成就奖章与成就详情，全部限定在当前企业与当前操作人的可见范围内。

必填请求头：本模块全部接口（含查询）都必须提供 X-Employee-Virtual-Id，未传或不属于当前企业时返回 403，错误信息为“请通过 X-Employee-Virtual-Id 指定当前操作人”。

三个概念：成就（achievement）是按规则累计达成的目标；等级（level）是同一成就下的阶梯，达成后产生一条领取记录；领取是把已达成的等级换成奖励（贡献点、奖章、福利）的动作。因此列表里的 id 是成就 Id，而领取接口需要的是详情里的领取记录 Id。

达成进度：成就的达成情况统一用 progress（0 到 1 的小数，已封顶为 1）加 levelList[].progress（各等级内规则进度）表达；进度依赖源站的成就计算链路，不是实时值。

GET /api/openplatform/achievements/types

查询成就类别列表。返回结果固定包含两个合成类别：“全部成就”（id 为全零 Guid）与“我的成就”（id 为 11111111-1111-1111-1111-111111111111），可直接把 id 作为成就列表接口的 categoryId 传回。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": [
    { "id": "00000000-0000-0000-0000-000000000000", "name": "全部成就", "count": 6, "totalCount": 12, "list": [], "list1": [] },
    { "id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "name": "任务类", "count": 4, "totalCount": 8, "list": [], "list1": [] },
    { "id": "11111111-1111-1111-1111-111111111111", "name": "我的成就", "count": 5, "totalCount": 12, "list": [], "list1": [] }
  ]
}

响应字段

字段	类型	说明
`id`	guid	类别 Id；全零 Guid 为“全部成就”、`11111111-1111-1111-1111-111111111111` 为“我的成就”。
`name`	string	类别名称。
`count`	int	当前操作人在该类别下已获得的成就数（本接口按“我的成就”口径统计）；“全部成就”的 `count` 为各真实类别之和。
`totalCount`	int	该类别下启用中的成就总数。
`list` / `list1`	object[]	本接口恒为空数组，保留字段以兼容源站结构。

GET /api/openplatform/achievements/waiting

查询待领取的成就列表，即已经达成、尚未领取的成就等级。

响应字段（成就列表行）

字段	类型	说明
`id`	guid	成就 Id，不是领取记录 Id；领取需要先查详情取 `receiveId`。
`name`	string	成就名称。
`imgUrl`	string	成就图片地址。
`remark`	string	成就说明。
`count`	int	已获得次数；仅成就列表接口填充，待领取与我的奖章列表为 0。
`receiveStatus`	int	领取状态：0 未获得、1 待领取、2 已获得。
`progress`	decimal	当前达成进度，取值 0 到 1，已封顶为 1。
`currentLevel` / `currentLevelIndex`	int	当前等级与等级下标；无法定位到时下标为 -1。
`levelList`	object[]	等级明细，见下方“等级字段”。
`createdAt` / `receivedAt`	datetime	记录产生时间与领取时间；未领取时 `receivedAt` 为零值时间。

等级字段（`levelList` 元素）

字段	类型	说明
`id`	guid	等级 Id。
`level`	int	等级序号。
`matchMode`	int	规则匹配模式：0 表示全部规则都要匹配，大于等于 1 表示至少匹配 N 条。
`ruleList`	object[]	规则明细，元素含 `categoryId`、`metricId`、`value`（目标值）、`name`（指标名）、`remark`、`cycleDate`（统计周期）、`progress`（本规则进度）、`progressStr`（进度文案）。
`reward`	object	等级奖励：`score` 奖励贡献点（单位点）、`medalIds` 奖励奖章、`welfareIds` 奖励福利；奖章与福利元素含 `categoryId`、`id`、`name`、`img`。
`peopleNumber` / `timesNumber`	int	该等级已达成人次与触发次数。
`status`	int	0 未领取、2 已领取。
`receivedAt`	datetime	该等级领取时间。

领取入口：本接口返回的是成就 Id，不能直接用于领取。请调用成就详情接口，用其 receiveId 发起领取。

GET /api/openplatform/achievements/mine

查询我已经获得的成就奖章列表。字段与待领取列表完全一致，语义上有两处差异：receiveStatus 恒为 2（已获得）、progress 恒为 1；createdAt 与 receivedAt 取领取记录时间。

GET /api/openplatform/achievements/mine

GET /api/openplatform/achievements

分页查询指定类别下的成就列表；不传 categoryId 时查询全部当前操作人可见成就。行字段与待领取列表一致，区别是 count 有值（该成就的全企业获得次数）。

参数	类型	必填	说明
`categoryId`	guid	否	成就类别 Id，取自类别列表；不传或传全零 Guid 时返回全部类别。
`page`	int	否	页码，默认 1。
`pageSize`	int	否	每页条数，默认 20，最大 100。

响应字段

字段	类型	说明
`data.total`	long	该类别下的成就总数。
`data.page` / `data.pageSize`	int	当前页码与每页条数。
`data.items`	object[]	成就列表行，字段同待领取列表。

GET /api/openplatform/achievements/{id}

查询单个成就详情，包含我的获得次数、达成时间与领取记录 Id。成就不存在或已删除时返回 101，错误信息为“成就不存在或已删除！”。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "name": "任务达人",
    "imgUrl": "https://cdn.example.com/achievement/20260914/task-master.png",
    "remark": "累计完成 100 个任务",
    "count": 86,
    "myCount": 3,
    "receiveStatus": 1,
    "progress": 1,
    "currentLevel": 3,
    "currentLevelIndex": 2,
    "receiveId": "2b3c4d5e-6f70-4a81-9b92-0c1d2e3f4051",
    "achievedAt": "2026-09-14T10:20:00+08:00",
    "receivedAt": "0001-01-01T00:00:00",
    "levelList": []
  }
}

在列表行基础上追加的字段

字段	类型	说明
`myCount`	int	当前操作人获得该成就的次数；`count` 为全企业获得次数。
`receiveId`	guid	领取记录 Id，领取成就时作为路径参数 `{id}` 传入。未达成或已领取时为零值 Guid。
`achievedAt`	datetime	达成时间。
`levelList`	object[]	等级明细，此处为“等级级进度”视图，字段同待领取列表的等级字段。

GET /api/openplatform/achievements/{id}/receiveDetail

查询成就领取记录详情，用于展示“谁在什么时候领取了什么成就”。路径 {id} 为领取记录 Id。记录不存在时返回 101 或 102，错误信息为“成就不存在！”。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "name": "任务达人",
    "imgUrl": "https://cdn.example.com/achievement/20260914/task-master.png",
    "remark": "累计完成 100 个任务",
    "receivedAt": "2026-09-14T10:25:00+08:00",
    "rewardPerson": { "virtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz", "name": "张三", "headImg": "https://cdn.example.com/head/20260914/zhangsan.png" }
  }
}

在成就详情基础上追加的字段

字段	类型	说明
`rewardPerson`	object	获奖员工：`virtualId`、`name`、`headImg`、`positionName`、`depName` 等；电话号码与登录账号不下发。
`receivedAt`	datetime	领取时间。

字段口径：本接口只保证 id、name、imgUrl、remark、receivedAt、rewardPerson 有业务含义，其余继承字段为类型默认值。

POST /api/openplatform/achievements/{id}/actions/receive

领取成就奖章，把已达成的成就等级兑换成奖励。

参数	类型	必填	说明
`id`	guid	是	路径参数，领取记录 Id，取自成就详情接口的 `receiveId`。传成就 Id 会返回“领取的成就不存在”。

POST /api/openplatform/achievements/2b3c4d5e-6f70-4a81-9b92-0c1d2e3f4051/actions/receive

异步处理：领取请求会进入成就队列，服务端等待处理完成后返回结果。“成就已领取”“成就不是待领取状态”这类校验同样在队列消费阶段执行，因此重试前必须先重新查询详情确认状态。同一领取记录重复调用会返回“成就已领取”。

MCP 工具 achievement_query

成就查询工具，需要 achievements.read 权限，覆盖上述全部 GET 查询能力。queryType 取值：typeList 成就类别、waitList 待领取成就、myMedalList 我的成就奖章、list 分页成就列表、detail 成就详情、receiveDetail 领取记录详情。

{
  "queryType": "list",
  "categoryId": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "page": 1,
  "pageSize": 20
}

参数映射：queryType=list 对应 REST 的 GET /achievements；detail 与 receiveDetail 的目标用 achievementId 传入，对应 REST 路径 {id}；categoryId、page、pageSize 语义与 REST 一致。缺失目标时提示“查询类型 detail 必须提供 achievementId”（receiveDetail 同理），pageSize 超过 100 提示“参数 pageSize 必须在 1 到 100 之间”。

MCP 工具 achievement_action

成就写操作工具，需要 achievements.write 权限，当前仅支持 action=receive 领取成就。

{
  "action": "receive",
  "recordId": "2b3c4d5e-6f70-4a81-9b92-0c1d2e3f4051"
}

参数说明：recordId 对应 REST 路径 {id}，必须是领取记录 Id（来自 achievement_query 的 detail 返回 receiveId），缺失时提示“receive 动作必须提供 recordId”。

调用约束：领取会把贡献点、奖章或福利实际发放给当前操作人且不可撤销，调用前必须向用户确认成就名称与奖励内容。工具返回的 msg 是队列消费后的真实结论。

成就接口

响应字段

响应字段（成就列表行）

等级字段（levelList 元素）

响应字段

在列表行基础上追加的字段

在成就详情基础上追加的字段

等级字段（`levelList` 元素）