慧企星助开放平台文档

奖章接口

奖章接口查询需要 medals.read 权限、写操作需要 medals.write 权限，依赖企业套餐的自动勋章或手动勋章模块（任一在售即可使用）。接口覆盖奖章类别与列表、待领取与我的奖章、奖章详情与领取记录、奖章排行与排行维护，以及手动颁发奖章。全部查询都限定在当前企业与当前操作人的可见范围内。

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

自动奖章与手动奖章：自动奖章由规则触发、达到条件后进入“待领取”；手动奖章由具备颁发权限的成员主动颁发。颁发与领取都走奖章队列，服务端等待处理完成后返回结果。

奖章标识字段：全部奖章接口（列表、待领取、我的奖章、详情、领取记录、排行）统一使用 id 承载奖章标识，值就是奖章 Id 本身；不要与员工标识 virtualId 混用。

GET /api/openplatform/medals/categories

查询奖章类别列表。返回结果固定包含两个合成类别：“全部奖章”（id 为全零 Guid）与“我的奖章”（id 为 11111111-1111-1111-1111-111111111111）。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": [
    { "id": "00000000-0000-0000-0000-000000000000", "name": "全部奖章", "count": 9 },
    { "id": "8d2e3f40-5b6c-4d7e-9f80-1a2b3c4d5e6f", "name": "成长类", "count": 5 },
    { "id": "11111111-1111-1111-1111-111111111111", "name": "我的奖章", "count": 4 }
  ]
}

响应字段

字段	类型	说明
`id`	guid	类别 Id；全零 Guid 为“全部奖章”、`11111111-1111-1111-1111-111111111111` 为“我的奖章”，可直接作为奖章列表的 `categoryId` 传回。
`name`	string	类别名称。
`count`	int	当前操作人在该类别下可见的奖章数（团队奖章按部门可见性计算，并叠加可颁发判定）。

GET /api/openplatform/medals

分页查询奖章列表；不传 categoryId 时查询全部当前操作人可见奖章。列表先按置顶截断，再分页。

参数	类型	必填	说明
`categoryId`	guid	否	奖章类别 Id，取自类别列表；不传或传全零 Guid 时返回全部类别。
`top`	int	否	置顶截断数量，默认 0 表示不截断；传大于 0 时只返回前 N 个置顶奖章。
`onlyEnablePublish`	bool	否	为 `true` 时只返回当前操作人可手动颁发的奖章，用于渲染“颁发奖章”选择列表。
`page`	int	否	页码，默认 1。
`pageSize`	int	否	每页条数，默认 20，最大 100。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 9,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "name": "季度之星",
        "imgUrl": "https://cdn.example.com/medal/20260914/quarter-star.png",
        "count": 12,
        "remark": "季度考核排名前三",
        "medalRemark": "9 月目标超额达成",
        "createdAt": "2026-09-10T14:00:00+08:00",
        "rewardedAt": "0001-01-01T00:00:00",
        "trueName": "李四",
        "isGet": true,
        "isAuto": false,
        "isDepartment": false,
        "depName": "",
        "noticeType": 1,
        "ruleMatchMode": 0,
        "ruleList": [],
        "issuePerson": { "virtualId": "emp_K3mR9xQw2vTn6bY8cL4dF1gH5jS7pZ0a", "name": "李四" },
        "rewardPerson": { "virtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz", "name": "张三" },
        "noticeUserList": []
      }
    ]
  }
}

奖章列表行字段（列表 / waiting / mine 共用）

字段	类型	说明
`id`	guid	奖章标识，与详情、领取记录、排行等接口同名同义。
`name`	string	奖章名称。
`imgUrl`	string	奖章图片地址。
`count`	int	累计获得次数。
`remark`	string	奖章说明（在领取记录详情中为领取备注）。
`medalRemark`	string	最近一次颁发原因。
`createdAt`	datetime	最近一次颁发时间；未颁发时为零值时间。
`rewardedAt`	datetime	记录产生时间；仅领取记录详情填充。
`trueName`	string	最近一次颁发人姓名。
`isGet` / `isAuto`	bool	当前操作人是否已领取 / 该奖章是否由规则自动执行。
`isDepartment` / `depName`	bool \| string	是否为团队奖章与所属部门名称；团队奖章按部门颁发。
`noticeType`	int	通报范围数值：0 不通报、1 全公司、2 本部门及下级、3 本部门、4 自定义名单。
`noticeUserList`	object[]	自定义通报人列表，元素为员工对象（含 `virtualId`、`name`）。
`issuePerson` / `rewardPerson`	object	颁发人与获奖人的员工对象，含 `virtualId`、`name`、`headImg`、`positionName`、`depName`；电话号码与登录账号不下发。
`ruleList`	object[]	自动奖章的达成规则：`categoryId`、`metricId`、`value` 目标值、`name` 指标名、`remark`、`cycleDate` 统计周期。
`ruleMatchMode`	int	规则匹配模式：0 表示全部规则都要匹配，大于等于 1 表示至少匹配 N 条。

GET /api/openplatform/medals/waiting

查询待领取的奖章列表，即已经达成或已被颁发、尚未领取的奖章。行字段与奖章列表一致。

GET /api/openplatform/medals/waiting

领取入口：本接口返回的是奖章标识，不能直接用于领取。请调用奖章详情接口，用其 receiveId 发起领取。

GET /api/openplatform/medals/mine

查询我的奖章列表，即当前操作人已领取的奖章。行字段与奖章列表一致，isGet 恒为 true。

GET /api/openplatform/medals/mine

GET /api/openplatform/medals/{id}

查询单个奖章详情，包含我的获得次数、获得时间、领取记录 Id 与随机奖励内容。奖章不存在时返回 101，错误信息为“奖章不存在！”。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "季度之星",
    "imgUrl": "https://cdn.example.com/medal/20260914/quarter-star.png",
    "remark": "季度考核排名前三",
    "ruleRemark": "季度考核排名前 3 名自动获得",
    "count": 12,
    "myCount": 1,
    "receiveStatus": 1,
    "receiveId": "3c4d5e6f-7081-4a92-8b03-1c2d3e4f5061",
    "achievedAt": "2026-09-14T09:00:00+08:00",
    "isDepartment": false,
    "depName": "",
    "ruleMatchMode": 0,
    "ruleList": [],
    "reward": { "score": 10, "achievementIds": [], "welfareIds": [] }
  }
}

响应字段

字段	类型	说明
`id`	guid	奖章 Id，与全部奖章接口同名字段保持一致。
`name` / `imgUrl` / `remark`	string	奖章名称、图片地址与说明。
`ruleRemark`	string	规则说明（人类可读的达成条件）。
`count` / `myCount`	int	全企业获得次数与当前操作人获得次数。
`receiveStatus`	int	领取状态：0 未获得、1 待领取、2 已获得。
`receiveId`	guid	领取记录 Id，领取奖章时作为路径参数 `{id}` 传入。未获得或已领取时为零值 Guid。
`achievedAt`	datetime	获得时间。
`isDepartment` / `depName`	bool \| string	是否为团队奖章与所属部门名称。
`ruleMatchMode` / `ruleList`	int \| object[]	规则匹配模式与规则明细，元素字段同奖章列表行的 `ruleList`。
`reward`	object	奖励内容：`score` 奖励贡献点（单位点）、`achievementIds` 关联成就（含 `categoryId`、`id`、`name`、`img`、`level`）、`welfareIds` 关联福利（含 `categoryId`、`id`、`name`、`img`）。

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

查询奖章领取记录详情，用于展示“谁在什么时候因为什么获得了哪枚奖章”。路径 {id} 为领取记录 Id（源站为奖章执行记录）。记录不存在时返回 101，错误信息为“未找到奖章信息！”。

响应字段

字段	类型	说明
`id`	guid	本接口中该字段是领取记录 Id，不是奖章 Id。
`name` / `imgUrl`	string	奖章名称与图片地址。
`remark`	string	领取备注。
`medalRemark`	string	颁发原因。
`rewardedAt`	datetime	记录产生时间。
`createdAt`	datetime	颁发时间。
`isGet` / `isAuto`	bool	是否已领取 / 是否为规则自动颁发。
`isDepartment` / `depName`	bool \| string	是否为团队奖章与部门名称。
`noticeType` / `noticeUserList`	int \| object[]	通报范围数值与自定义通报人列表。
`issuePerson` / `rewardPerson`	object	颁发人与获奖人：`virtualId`、`name`、`headImg`、`positionName`、`depName` 等。
`trueName`	string	颁发人姓名。

GET /api/openplatform/medals/ranking

查询奖章排行列表，分为“已加入排行”与“未加入排行”两组，用于渲染排行配置界面。addedList 按配置顺序（DisplayOrder 升序）返回，notAddedList 按奖章自身展示顺序与创建时间升序返回；两组都返回全部奖章，不做截断。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "addedList": [
      { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "name": "季度之星", "imgUrl": "https://cdn.example.com/medal/20260914/quarter-star.png", "remark": "季度考核排名前三" }
    ],
    "notAddedList": [
      { "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e", "name": "全勤标兵", "imgUrl": "https://cdn.example.com/medal/20260914/full-attendance.png", "remark": "当月无缺勤" }
    ]
  }
}

响应字段

字段	类型	说明
`data.addedList`	object[]	已加入排行的奖章，按排行顺序（即 `DisplayOrder` 升序）。
`data.notAddedList`	object[]	尚未加入排行的奖章。
`id`	guid	奖章 Id。本接口字段名为 `id`，可直接作为 `PUT /medals/ranking` 的排序数组元素。
`name` / `imgUrl` / `remark`	string	奖章名称、图片地址与说明。

GET /api/openplatform/medals/permission

查询当前操作人的奖章操作权限，用于判断是否展示“颁发奖章”入口。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "publish": true
  }
}

响应字段

字段	类型	说明
`publish`	bool	是否可手动颁发奖章。企业管理员恒为 `true`；其余成员按企业奖章应用的“颁发设置”判定：命中本部门及下级部门、命中本人角色或按人指定到当前员工时为 `true`。

仅一个权限位：本接口只返回颁发权限；奖章排行的维护权限（设置排行）由企业奖章应用的排行设置名单决定，不在本接口返回。

POST /api/openplatform/medals/{medalId}/actions/publish

手动颁发奖章，把指定奖章颁发给一批员工（或部门，团队奖章由部门负责人接收）。需要手动勋章套餐与颁发权限。

字段	类型	必填	说明
`targetEmployeeVirtualIds`	string[]	是	颁发对象的员工 `virtualId` 列表，至少 1 个、最多 50 个。为空返回 `400`“颁发对象不能为空”；元素不是有效 `virtualId` 返回 `400`“{字段名} 包含无效的 virtualId”。
`remark`	string	否	颁发原因，最长 500 字符；为空时队列侧返回 `105`“颁发原因必须填写”，超长返回 `106`“颁发原因字数应小于500字”。
`notifyScope`	string	否	通报范围，字符串枚举：`none` 不通报（0）、`all` 全公司（1）、`departments` 本部门及下级部门（2）、`department` 本部门（3）、`custom` 自定义名单（4）。传其它值返回 `400`“notifyScope 必须为 none、all、departments、department 或 custom”；不传时不产生通报。
`notifyVirtualIds`	string[]	条件必填	自定义通报名单的员工 `virtualId` 列表，最多 50 个；`notifyScope=custom` 时必填，缺失返回 `400`“自定义通报（notifyScope=custom）必须提供 notifyVirtualIds 名单”。

{
  "targetEmployeeVirtualIds": ["emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"],
  "remark": "项目攻坚纪念",
  "notifyScope": "custom",
  "notifyVirtualIds": ["emp_K3mR9xQw2vTn6bY8cL4dF1gH5jS7pZ0a"]
}

异步处理：颁发请求进入奖章队列，服务端等待消费完成后返回结果。颁发权限、“至少选择一个需要颁发奖章的用户”、团队奖章的部门负责人校验都在队列侧执行，因此同步响应里的 msg 就是最终结论（例如“您没有颁发奖章的权限！”“不能颁发奖章给外部成员X”）。团队奖章可参考“至少选择一个需要颁发奖章的部门”“第N个部门不存在！”“部门X还没有负责人！”。

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

领取奖章，把待领取的奖章兑换给当前操作人。

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

POST /api/openplatform/medals/3c4d5e6f-7081-4a92-8b03-1c2d3e4f5061/actions/receive

异步处理：领取请求进入奖章队列，服务端等待消费完成后返回结果。重复领取返回“奖章已领取”，状态不是待领取返回“奖章不存在”。

PUT /api/openplatform/medals/ranking

设置奖章排行：按数组顺序重写本企业的排行配置，数组下标决定展示顺序。需要企业奖章应用的排行设置权限，否则返回 103“无权限进行此操作”。

字段	类型	必填	说明
`medalIds`	guid[]	是	排序后的奖章 Id 顺序，数组下标 + 1 即该奖章的展示顺序。为空返回 `400`“奖章排行列表不能为空”；全部无法解析时返回 `101`“请选择要排行的奖章”。

{
  "medalIds": [
    "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
  ]
}

覆盖语义：本接口是整体覆盖而不是增量追加——每次调用都会先清空当前企业的排行配置再按新数组重建。不在本企业内的奖章 Id 会被跳过，但下标仍继续递增，可能出现序号空洞。保存失败返回 93“操作异常”。

MCP 工具 medal_query

奖章查询工具，需要 medals.read 权限，覆盖上述全部 GET 查询能力。queryType 取值：categoryList 奖章类别、list 分页奖章列表、waitList 待领取奖章、mine 我的奖章、detail 奖章详情、receiveDetail 领取记录详情、rankList 奖章排行、permission 颁发权限。

{
  "queryType": "list",
  "categoryId": "8d2e3f40-5b6c-4d7e-9f80-1a2b3c4d5e6f",
  "onlyEnablePublish": true,
  "page": 1,
  "pageSize": 20
}

参数映射：queryType=list 对应 REST 的 GET /medals；detail 与 receiveDetail 的目标用 medalId 传入，对应 REST 路径 {id}；categoryId、onlyEnablePublish、page、pageSize 与 REST 语义一致。工具不暴露 top，内部固定按不截断查询。

取值提醒：全部奖章接口的奖章标识统一为 id；领取必须使用 detail 返回的 receiveId 作为路径参数。

MCP 工具 medal_action

奖章写操作工具，需要 medals.write 权限。action 取值：publish 颁发奖章、receive 领取奖章、setRankMedal 设置奖章排行。

{
  "action": "publish",
  "medalId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "targetEmployeeVirtualIds": ["emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"],
  "remark": "项目攻坚纪念",
  "notifyScope": "all"
}

参数说明：medalId 用于 publish（必填，缺失提示“publish 动作必须提供 medalId”）；recordId 用于 receive（必填，取自奖章详情的 receiveId）；medalIds 用于 setRankMedal（1 到 50 个有效奖章 Id，非法时提示“medalIds 必须全部是有效的奖章 Id”）；targetEmployeeVirtualIds（1 到 50 个）、remark（最长 500 字符）、notifyScope 与 notifyVirtualIds（最多 50 个）仅用于 publish。

调用约束：颁发奖章带有通报效果、会把奖章发给他人，领取会把奖励实际发放到当前操作人且不可撤销，设置排行会整体覆盖企业排行配置。调用前必须把奖章名称、颁发对象、通报范围或排序结果完整展示给用户并取得明确确认。