秒客来AI 开放平台文档

项目接口

项目接口以当前 X-Employee-Virtual-Id 对应员工的项目可见范围和业务权限为准。查询使用 projects.read，项目与分组的创建、修改、删除、排序使用 projects.write。

标识规则：请求体中的责任人和参与人只能传 virtualId，不得传内部员工 Guid。响应中的员工对象只返回公开展示字段和当前 API Key 范围内的 virtualId，不会返回手机号、账号、部门内部 Id 或真实员工 Guid；项目自身仍使用 id（Guid）作为详情、修改、删除等资源路径参数。

GET/api/openplatform/projects

查询当前员工可见的项目列表。

参数	类型	必填	说明
`page`	int	否	页码。
`pageSize`	int	否	每页条数。
`keyword`	string	否	项目名称关键字。
`status`	string	否	项目状态筛选：`new` 新计划、`tobeRelease` 待执行、`ing` 进行中（正常）、`atRisk` 进行中-有风险、`outOfControl` 进行中-失控、`paused` 进行中-暂停、`needJudge` 待评定、`finish` 已结束。不传查询当前操作人全部可见状态的项目。
`creatorVirtualId`	string	否	创建人员工 `virtualId` 过滤；无效时返回 `400`“creatorVirtualId 不存在或不属于当前企业”。
`ownerVirtualId`	string	否	责任人员工 `virtualId` 过滤；无效时返回 `400`。
`startAtFrom` / `startAtTo`	string	否	项目开始时间范围，ISO 8601 带时区字符串（如 `2026-08-18T00:00:00+08:00`）；非 ISO 8601 格式返回 `400`。

列表响应字段

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

Project 通用字段

项目列表中的单项与 GET /api/openplatform/projects/{id} 详情共用以下资源字段。详情会返回完整字段，列表会按源站可见范围返回相应字段。

字段	类型	说明
`id`	guid	项目资源标识，用于详情、修改、删除和关联查询。
`name`	string	项目名称。
`content`	string	项目内容；未填写时为空字符串。
`startAt`	string \| null	项目开始时间，ISO 8601 带时区字符串；未设置时为 `null`。
`endAt`	string \| null	项目结束时间，ISO 8601 带时区字符串；未设置时为 `null`。
`priority`	int	项目优先级。
`status`	int	项目状态数值：0 新计划、1 待执行、2 进行中、3 待评定、4 已结束。
`statusStr`	string	项目状态中文文案，与 `status` 配套返回。
`totalScore`	decimal	项目总贡献点，单位为“点”。
`visibleRange`	int	项目可见范围配置值。
`objectiveId`	guid \| null	关联目标标识；没有关联目标时为 `null`。
`owners`	object[]	项目责任人的成员对象数组（每项含 `virtualId`、`name` 与掩码 `phone`）。
`participants`	object[]	项目参与人的成员对象数组（每项含 `virtualId`、`name` 与掩码 `phone`）。
`requiresCompletionAttachment`	bool	项目内任务完成时是否要求上传附件。
`disallowsDecomposition`	bool	是否禁止项目内任务分解。
`allowsTaskAfterEnd`	bool	项目结束后是否允许新增任务。
`attachmentUrls`	string[]	项目附件的公开访问 URL 列表。
`createdAt`	string	创建时间，ISO 8601 带时区字符串。
`updatedAt`	string \| null	最后更新时间，ISO 8601 带时区字符串；未更新时可能为空或 `null`。

POST/api/openplatform/projects

创建项目。

字段	类型	必填	说明
`name`	string	是	项目名称。
`startAt`	string	否	项目开始时间，ISO 8601。
`endAt`	string	否	项目结束时间，ISO 8601。
`ownerVirtualIds`	string[]	否	项目责任人 `virtualId` 列表；建议创建时显式指定，不传时项目无责任人。
`content`	string	否	项目内容。建议传 HTML 富文本（支持 p、h1-h6、ul/ol、strong、table 等标签，工作台按富文本渲染）；传纯文本时自动包装为段落（换行转 <br/>）但无标题/列表等结构化格式；Markdown 不会被渲染。
`priority`	int	否	优先级。
`totalScore`	decimal	否	项目总贡献点，单位为“点”。
`visibleRange`	int	否	项目可见范围。
`participantVirtualIds`	string[]	否	项目参与人 `virtualId` 列表。
`objectiveId`	guid	否	关联目标 ID。
`requiresCompletionAttachment`	bool	否	完成任务时是否必须上传附件。
`disallowsDecomposition`	bool	否	是否禁止分解任务。
`allowsTaskAfterEnd`	bool	否	项目结束后是否允许新增任务。
`attachmentUrls`	string[]	否	项目附件 URL 列表。

{
  "name": "客户交付项目",
  "content": "交付范围与阶段目标",
  "startAt": "2026-08-18T09:00:00+08:00",
  "endAt": "2026-09-30T18:00:00+08:00",
  "priority": 3,
  "totalScore": 100,
  "visibleRange": 0,
  "ownerVirtualIds": ["emp_xxx"],
  "participantVirtualIds": ["emp_yyy"]
}

GET/api/openplatform/projects/{id}

查询项目详情。

路径参数：id 为项目 Guid。

响应字段：返回一个完整 Project 对象，字段、类型和含义见上方“Project 通用字段”。

PATCH/api/openplatform/projects/{id}

修改项目的单个字段，请求体必须且只能包含一个可修改字段。

路径参数：id 为项目 Guid。

字段	类型	必填	说明
`name`	string	否	项目名称。
`content`	string	否	项目内容。
`totalScore`	decimal	否	项目总贡献点。
`priority`	int	否	项目优先级。
`endAt`	string	否	项目结束时间，ISO 8601。
`ownerVirtualIds`	string[]	否	项目负责人 `virtualId` 列表。
`startAt`	string	否	项目开始时间，ISO 8601。

{
  "name": "更新后的项目名称"
}

DELETE/api/openplatform/projects/{id}

删除项目。

路径参数：id 为项目 Guid。

POST/api/openplatform/projects/{id}/actions/{action}

执行项目动作。当前支持 execute：把待执行（status=0，新计划/待执行）项目启动为进行中，成功后项目任务按规则自动发送（无未完成前置且已到发送时间的任务立即发出，其余进入“待发送”等待），无需再逐个人工调用项目任务的 send。

路径参数：id 为项目 Guid；action 当前仅支持 execute，其他值返回 400“不支持的项目操作”。

请求体：无（可传空对象）。

业务约束：仅项目创建人或其被托管人可执行；全部责任人（除创建人外）须已完成任务分解，否则返回“尚有责任人未完成分解，暂不能执行”；项目不是待执行状态时返回“只有待执行的项目才能执行该操作”。

{
  "statusCode": 100,
  "msg": "操作成功",
  "data": { "status": 2, "statusStr": "进行中" }
}

GET/api/openplatform/projects/{id}/groups

查询项目分组。

路径参数：id 为项目 Guid。

字段	类型	说明
`data`	ProjectGroup[]	项目分组列表。
`id`	guid	分组标识。
`name`	string	分组名称。

POST/api/openplatform/projects/{id}/groups

创建项目分组。分组名称在同一项目下不允许重名；调用方需对该项目拥有管理权限（以下分组写接口同）。

参数	类型	必填	说明
`name`	string	是	分组名称。

{
  "statusCode": 100,
  "msg": "分组保存成功",
  "data": { "id": "8f2c1d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f" }
}

PATCH/api/openplatform/projects/{id}/groups/{groupId}

重命名项目分组。

路径参数：id 为项目 Guid，groupId 为分组 Guid。

参数	类型	必填	说明
`name`	string	是	新的分组名称。

DELETE/api/openplatform/projects/{id}/groups/{groupId}

删除项目分组。

路径参数：id 为项目 Guid，groupId 为分组 Guid。分组下仍有关联数据时由业务校验拒绝并返回提示。

PUT/api/openplatform/projects/{id}/groups/order

保存项目分组排序（按数组顺序展示）。

参数	类型	必填	说明
`groupIds`	guid[]	是	排序后的分组 Id 列表。

GET/api/openplatform/projects/{id}/members

查询项目责任人。

路径参数：id 为项目 Guid。

字段	类型	说明
`data`	Employee[]	项目责任人列表。
`virtualId`	string	员工在当前 API Key 下的公开标识。
`name`	string	员工姓名。

GET/api/openplatform/projects/activeProgress

查询当前员工进行中项目的进度。

字段	类型	说明
`data`	ProjectProgress[]	进行中项目进度列表。
`id`	guid	项目标识。
`name`	string	项目名称。
`progress`	decimal	项目完成进度。