慧企星助开放平台文档

贡献统计与贡献二维码接口

贡献统计接口需要 scores.read 权限，贡献二维码查询需要 scoreQrCodes.read 权限、维护需要 scoreQrCodes.write 权限，依赖企业套餐贡献模块。统计的目标员工缺省为当前操作人，查询他人由服务端按操作人的贡献查看权限判定可见范围；无权限或目标员工不存在时返回 102。

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

单位口径：贡献的统一单位是“点”，所有分值字段均为点；scores 下的接口只做统计与二维码维护，贡献点余额、流水与申请提交见贡献点接口与贡献申请接口。

GET /api/openplatform/scores/home

查询贡献点首页摘要：本周增减、昨日增减与本周、昨日的企业排名。本周区间为本周一 00:00 至今日 24:00，昨日区间为昨天 00:00 至今天 00:00。

参数	类型	必填	说明
`employeeVirtualId`	string	否	目标员工在本 API Key 下的 `virtualId`，不传表示查询当前操作人本人。查询他人需要当前操作人具备贡献查看权限。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "employeeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
    "weekAdd": 12,
    "weekReduce": -2,
    "yesterdayAdd": 3,
    "yesterdayReduce": 0,
    "weekRank": 5,
    "yesterdayRank": 8
  }
}

响应字段

字段	类型	说明
`employeeVirtualId`	string	被统计员工在本 API Key 下的 `virtualId`。
`weekAdd`	decimal	本周正向获得合计，单位点。
`weekReduce`	decimal	本周扣减合计，为负数或 0。
`yesterdayAdd`	decimal	昨日正向获得合计，单位点。
`yesterdayReduce`	decimal	昨日扣减合计，为负数或 0。
`weekRank`	int	本周企业排名，从 1 开始；被企业排行榜配置为不计入排名时为 0。
`yesterdayRank`	int	昨日企业排名，取值口径同 `weekRank`。

GET /api/openplatform/scores/board

查询贡献点看板汇总：指定时间区间内各分类的贡献点合计。分类口径与工作台我的贡献点看板一致，全部聚合自贡献日记录。

参数	类型	必填	说明
`employeeVirtualId`	string	否	目标员工 `virtualId`，不传表示查询当前操作人本人。
`startAt`	datetime	否	统计开始日期（含），ISO 8601 带时区；不传表示不限开始时间。
`endAt`	datetime	否	统计结束日期（含当天 23:59:59），ISO 8601 带时区；不传表示不限结束时间。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "employeeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
    "startAt": "2026-09-01T00:00:00+08:00",
    "endAt": "2026-09-15T00:00:00+08:00",
    "sumScore": 120,
    "taskScore": 60,
    "reportScore": 20,
    "achievementScore": 10,
    "medalScore": 5,
    "baseScore": 10,
    "standardScore": 10,
    "systemStandardScore": 5,
    "customScore": 0,
    "transportScore": 0
  }
}

响应字段

字段	类型	说明
`employeeVirtualId`	string	被统计员工在本 API Key 下的 `virtualId`。
`startAt` / `endAt`	string \| null	实际生效的统计区间；未传对应参数时为 `null`。
`sumScore`	decimal	区间内贡献点合计，单位点。
`taskScore`	decimal	任务贡献：协作、项目、自动化等任务得分与审核、审批得分合计。
`reportScore`	decimal	汇报贡献：日报、周报、月报得分合计。
`achievementScore`	decimal	成就贡献。
`medalScore`	decimal	奖章贡献。
`baseScore`	decimal	基础贡献。
`standardScore`	decimal	行为标准申请贡献。
`systemStandardScore`	decimal	系统调整贡献（管理员调整）。
`customScore`	decimal	自定义建议贡献。
`transportScore`	decimal	结转贡献。

口径说明：各分类合计之和与 sumScore 可能因结转、调整项存在口径差异，展示排行与趋势请以 sumScore 为准。

GET /api/openplatform/scores/trend

查询每日贡献点趋势：返回统计区间内逐日的贡献点合计序列，缺失日期按 0 补齐。

参数	类型	必填	说明
`range`	string	否	统计口径，字符串枚举：`all` 活跃至今（默认）、`week` 本周、`month` 本月、`quarter` 本季度、`year` 本年、`customMonth` 指定月份。传其它值返回 `400`，错误信息为“range 必须为 all、week、month、quarter、year 或 customMonth”。
`month`	string	条件必填	目标月份，格式 `yyyy-MM`；`range=customMonth` 时必须提供，缺失时返回 `400`，错误信息为“range=customMonth 必须提供 month（yyyy-MM）”；格式不合法时返回 `102`，错误信息为“月份选择错误！”。
`employeeVirtualId`	string	否	目标员工 `virtualId`，不传表示查询当前操作人本人。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "startAt": "2026-09-14T00:00:00+08:00",
    "endAt": "2026-09-15T00:00:00+08:00",
    "items": [
      { "time": "2026-09-14T00:00:00+08:00", "sumScore": 3 },
      { "time": "2026-09-15T00:00:00+08:00", "sumScore": 0 }
    ]
  }
}

响应字段

字段	类型	说明
`startAt`	string	序列起始日期（含）。
`endAt`	string	序列结束日期（含）。
`data.items`	array	按日期升序的每日序列，首项为 `startAt`、末项为 `endAt`；每项含 `time`（当日 00:00，ISO 8601 带时区）与 `sumScore`（当日贡献点合计，单位点，无记录为 0）。

区间说明：range=0 时起点为被统计员工的激活日期；逐日序列会返回区间内的每一天，数据量大时建议改用 range=1 或 range=2 等短周期口径。

GET /api/openplatform/scores/ranking

分页查询企业贡献点排行榜，按区间贡献点合计倒序。贡献点为 0 的成员不进入排行；时间区间缺省时统计全部历史。

参数	类型	必填	说明
`startAt`	datetime	否	统计开始时间，ISO 8601 带时区；不传表示不限开始时间。
`endAt`	datetime	否	统计结束时间，ISO 8601 带时区；不传表示不限结束时间。
`departmentId`	int	否	部门 Id，传入时只统计该部门成员；传入顶级部门 Id 或不传时按全企业统计。
`page`	int	否	页码，默认 1。
`pageSize`	int	否	每页条数，默认 20，最大 100。

{
  "statusCode": 100,
  "msg": "86.50",
  "data": {
    "total": 42,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "virtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
        "rankNum": 1,
        "name": "张三",
        "score": 320,
        "headImg": "https://cdn.example.com/head/20260914/zhangsan.png",
        "designName": "季度之星"
      }
    ]
  }
}

列表响应字段

字段	类型	说明
`msg`	string	该区间内的人均贡献点（保留两位小数）；无排行数据时为“获取成功”。
`data.total`	long	进入排行的成员总数。
`data.page`	int	当前页码，从 1 开始。
`data.pageSize`	int	当前页返回条数上限，范围为 1 到 100。
`data.items`	RankItem[]	当前页排行列表。

RankItem 字段

字段	类型	说明
`virtualId`	string	成员在本 API Key 下的员工 `virtualId`，可直接用于员工接口与贡献点查询。
`rankNum`	int	名次，从 1 开始。
`name`	string	成员姓名。
`score`	decimal	区间贡献点合计，单位点。
`headImg`	string	成员头像地址；未上传时为空字符串。
`designName`	string	成员称号；未获得称号时为空字符串。

成员识别：排行榜行的 virtualId 与员工接口返回的 virtualId 同一口径，可直接用于查询该成员的贡献点余额或流水。

GET /api/openplatform/scoreQrCodes

分页查询当前操作人创建的行为标准贡献二维码列表，按状态、创建时间倒序。

参数	类型	必填	说明
`page`	int	否	页码，默认 1。
`pageSize`	int	否	每页条数，默认 20，最大 100。
`keyword`	string	否	按二维码名称模糊搜索；不传返回全部。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "items": [
      {
        "id": "4a5b6c7d-8e9f-4a5b-8c7d-6e5f4a3b2c1d",
        "name": "前台贡献二维码",
        "remark": "客户好评扫码",
        "status": 1,
        "qrCodeUrl": "https://cdn.example.com/qrcode/20260901/front.png",
        "count": 0,
        "scanCount": 36,
        "useCount": 21,
        "createdAt": "2026-09-01T10:00:00+08:00"
      }
    ]
  }
}

QrCodeItem 字段

字段	类型	说明
`id`	guid	二维码 Id，用于详情、修改、删除、启用停用与审核路径。
`name`	string	二维码名称。
`remark`	string	二维码说明；未填写时为空字符串。
`status`	int	状态：`1` 正常、`0` 停用。
`qrCodeUrl`	string	二维码图片地址，可直接展示或下载。
`count`	int	关联且处于发布状态的行为标准项数量。
`scanCount`	int	累计扫码次数。
`useCount`	int	累计提交评分次数。
`createdAt`	string	创建时间，ISO 8601 带时区。

GET /api/openplatform/scoreQrCodes/{id}

查询行为标准贡献二维码详情，包含关联的行为标准、评分对象与通知人。只能查询当前企业内的二维码，不存在或跨企业时返回 400，错误信息为“该二维码不存在”。

{
  "statusCode": 100,
  "msg": "获取成功",
  "data": {
    "id": "4a5b6c7d-8e9f-4a5b-8c7d-6e5f4a3b2c1d",
    "name": "前台贡献二维码",
    "remark": "客户好评扫码",
    "status": 1,
    "qrCodeUrl": "https://cdn.example.com/qrcode/20260901/front.png",
    "count": 1,
    "scanCount": 36,
    "useCount": 21,
    "createdAt": "2026-09-01T10:00:00+08:00",
    "isAnonymous": false,
    "isShowAnonymous": true,
    "standardItemList": [
      {
        "id": "8f3b52e4-1c2d-4a5b-9e6f-7a8b9c0d1e2f",
        "name": "客户好评",
        "score": 2
      }
    ],
    "objectUserList": [
      {
        "virtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz",
        "name": "张三",
        "headImg": "https://cdn.example.com/head/20260914/zhangsan.png"
      }
    ],
    "notifyUserList": []
  }
}

详情响应字段

详情返回包含上述 QrCodeItem 的全部字段，并额外包含以下字段。

字段	类型	说明
`isAnonymous`	bool	是否匿名评分；匿名时评分人不记录到贡献流水。
`isShowAnonymous`	bool	企业是否开启了匿名评分开关。
`standardItemList`	array	关联的行为标准项，每项含 `id`、`name` 与分值相关字段；无关联时为空数组。
`objectUserList`	array	指定评分对象，每项以 `virtualId` 标识员工并含 `name`、`headImg`；未限定对象时为空数组。
`notifyUserList`	array	评分通知人，字段口径同 `objectUserList`；未设置时为空数组。

POST /api/openplatform/scoreQrCodes

新增行为标准贡献二维码。行为标准项 Id 可先用行为标准查询接口获取。

参数	类型	必填	说明
`name`	string	是	二维码名称；为空时返回 `400`，错误信息为“二维码名称不能为空”。
`remark`	string	否	二维码说明。
`isAnonymous`	bool	否	是否匿名评分，默认 `false`；企业未开启匿名评分时会被源站拒绝。
`standardItemIds`	guid[]	否	关联的行为标准项 Id 列表。
`objectVirtualIds`	string[]	否	限定评分对象的员工 `virtualId` 列表；不传表示不限定。包含无法解析的 `virtualId` 时返回 `400`，错误信息为“objectVirtualIds 包含无效的 virtualId”。
`notifyVirtualIds`	string[]	否	评分提交后通知的员工 `virtualId` 列表；校验口径同 `objectVirtualIds`。

{
  "name": "前台贡献二维码",
  "remark": "客户好评扫码",
  "isAnonymous": false,
  "standardItemIds": ["8f3b52e4-1c2d-4a5b-9e6f-7a8b9c0d1e2f"],
  "objectVirtualIds": ["emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"]
}

员工标识：评分对象与通知人只能传 virtualId，不接受内部员工 Id；响应中同样只返回 virtualId。

PATCH /api/openplatform/scoreQrCodes/{id}

修改行为标准贡献二维码的名称或说明，一次只能修改一个字段。

参数	类型	必填	说明
`name`	string	条件必填	新的二维码名称，与 `remark` 二选一。
`remark`	string	条件必填	新的二维码说明，与 `name` 二选一。

{
  "name": "前台服务评分二维码"
}

参数约束：name 与 remark 必须且只能提供一个。两个都传或两个都不传时返回 400，错误信息为“修改请求必须且只能提供 name 或 remark 之一”。

DELETE /api/openplatform/scoreQrCodes/{id}

删除行为标准贡献二维码。该操作不可撤销，删除后已生成的二维码图片立即失效。

DELETE /api/openplatform/scoreQrCodes/4a5b6c7d-8e9f-4a5b-8c7d-6e5f4a3b2c1d
X-Employee-Virtual-Id: emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz

调用约束：删除动作不需要请求体；调用前必须把二维码名称与影响范围展示给用户并取得明确确认。

POST /api/openplatform/scoreQrCodes/{id}/actions/setStatus

切换行为标准贡献二维码的启用与停用状态：正常状态调用后停用，停用状态调用后启用。

POST /api/openplatform/scoreQrCodes/4a5b6c7d-8e9f-4a5b-8c7d-6e5f4a3b2c1d/actions/setStatus

状态说明：停用后扫码不再产生贡献申请，历史记录保留；响应中 status 字段反映切换后的新状态。

POST /api/openplatform/scoreQrCodes/{id}/actions/check

审核行为标准贡献二维码，与工作台二维码审核同源。审核通过后二维码进入可扫码状态。

POST /api/openplatform/scoreQrCodes/4a5b6c7d-8e9f-4a5b-8c7d-6e5f4a3b2c1d/actions/check

MCP 工具 score_stats

贡献统计查询工具，需要 scores.read 权限，覆盖上述全部 GET 查询能力。queryType 取值：home 首页摘要、board 看板汇总、trend 每日趋势、ranking 企业排行榜（分页）、qrStandardList 二维码列表（分页）、qrStandardDetail 二维码详情。

{
  "queryType": "trend",
  "range": "month",
  "employeeVirtualId": "emp_T7dQ2mYk8rLp4cN1sVx3bH9wAe6fJuKz"
}

参数映射：qrCodeId 对应 REST 的二维码 id；趋势口径在 MCP 侧为字符串枚举 all、week、month、quarter、year、customMonth（默认 all），REST 侧为数值枚举，两者语义一一对应。

MCP 工具 score_qr_code

行为标准贡献二维码写操作工具，需要 scoreQrCodes.write 权限。action 取值：create 新增、update 修改单字段、delete 删除、setStatus 启用停用、check 审核。

{
  "action": "create",
  "name": "前台贡献二维码",
  "standardItemIds": ["8f3b52e4-1c2d-4a5b-9e6f-7a8b9c0d1e2f"]
}

调用约束：删除会立即让已生成的二维码失效；调用前必须把二维码名称与影响范围展示给用户并取得明确确认。