wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/2026-03/17_0928/hl-task-service.md
API Changelog Bot a9bac94ee1 docs: 2026-03/17_0928 sync 13 services (0 breaking)
2026-03-17 09:28:57 +08:00

30 KiB
原始文件 Blame 文件历史

任务服务 API 文档

服务: hl-task-service 接口总数: 27

目录

  • WebSocket 实时推送 (1 个接口)
  • 任务看板管理 (13 个接口)
  • 任务管理 (13 个接口)

WebSocket 实时推送

GET /admin/task/board/ws-doc/info

WebSocket 连接说明

连接信息

项目 值
连接地址 ws://{host}:8092/ws/task
协议 STOMP over WebSocket（SockJS 降级方案）
跨域 允许所有源 (*)

订阅频道

订阅地址 说明
/topic/board/{boardId} 订阅指定看板，接收该看板下的实时任务事件

推送消息格式

{
  "event": "TASK_CREATED",
  "data": { ... },
  "timestamp": 1709539200000
}

事件类型

事件 说明 data 内容
TASK_CREATED 任务创建 任务对象
TASK_UPDATED 任务更新 任务对象
TASK_DELETED 任务删除 任务ID
TASK_MOVED 任务移动（状态变更） 任务对象
COMMENT_ADDED 新增评论 评论对象

前端接入示例 (SockJS + STOMP)

import SockJS from 'sockjs-client'
import { Stomp } from '@stomp/stompjs'

const socket = new SockJS('http://localhost:8092/ws/task')
const stompClient = Stomp.over(socket)

stompClient.connect({}, () => {
  stompClient.subscribe('/topic/board/123', (msg) => {
    const { event, data, timestamp } = JSON.parse(msg.body)
    console.log('Event:', event, 'Data:', data)
  })
})

响应 object

任务看板管理

POST /admin/task/board

创建自定义看板

创建自定义看板，自动添加创建者为看板成员，并创建默认状态列（待办、进行中、已完成）。

权限：需管理员登录。

请求体 创建看板请求

字段 类型 必填 说明
boardName string 是 看板名称
deptId long 部门ID
description string 看板描述
memberIds long[] 成员ID列表

响应 统一响应结果«看板信息»

字段 类型 必填 说明
code int 状态码
data 看板信息 响应数据
  boardId long 看板ID
  boardName string 看板名称
  boardType string 看板类型
  createdAt string 创建时间
  createdBy long 创建人ID
  creatorName string 创建人姓名
  deptId long 部门ID
  deptName string 部门名称
  description string 看板描述
  statuses 看板状态信息[] 状态列表
    isPreset boolean 是否预设状态
    sortOrder int 排序序号
    statusColor string 状态颜色
    statusId long 状态ID
    statusName string 状态名称
    taskCount int 该状态下的任务数量
  taskCount int 任务总数
message string 响应消息

GET /admin/task/board/{boardId}

看板详情

返回看板基本信息（名称、描述、创建者），不含任务数据。查看任务请使用「获取看板任务」接口

路径参数

参数 类型 必填 说明
boardId integer 看板ID

响应 统一响应结果«看板信息»

字段 类型 必填 说明
code int 状态码
data 看板信息 响应数据
  boardId long 看板ID
  boardName string 看板名称
  boardType string 看板类型
  createdAt string 创建时间
  createdBy long 创建人ID
  creatorName string 创建人姓名
  deptId long 部门ID
  deptName string 部门名称
  description string 看板描述
  statuses 看板状态信息[] 状态列表
    isPreset boolean 是否预设状态
    sortOrder int 排序序号
    statusColor string 状态颜色
    statusId long 状态ID
    statusName string 状态名称
    taskCount int 该状态下的任务数量
  taskCount int 任务总数
message string 响应消息

PUT /admin/task/board/{boardId}

更新看板

更新看板的名称和描述。仅看板创建者或超级管理员可操作。

权限：需管理员登录，且为看板创建者或超级管理员。

路径参数

参数 类型 必填 说明
boardId integer 看板ID

请求体 更新看板请求

字段 类型 必填 说明
boardName string 看板名称
description string 看板描述

响应 统一响应结果«看板信息»

字段 类型 必填 说明
code int 状态码
data 看板信息 响应数据
  boardId long 看板ID
  boardName string 看板名称
  boardType string 看板类型
  createdAt string 创建时间
  createdBy long 创建人ID
  creatorName string 创建人姓名
  deptId long 部门ID
  deptName string 部门名称
  description string 看板描述
  statuses 看板状态信息[] 状态列表
    isPreset boolean 是否预设状态
    sortOrder int 排序序号
    statusColor string 状态颜色
    statusId long 状态ID
    statusName string 状态名称
    taskCount int 该状态下的任务数量
  taskCount int 任务总数
message string 响应消息

DELETE /admin/task/board/{boardId}

删除看板

删除看板及其下所有状态列和任务（级联删除）。仅看板创建者或超级管理员可操作

路径参数

参数 类型 必填 说明
boardId integer 看板ID

响应 统一响应结果«Void»

DELETE /admin/task/board/{boardId}/member/{targetAdminId}

移除成员

从看板中移除指定成员。仅看板创建者或超级管理员可操作，不能移除创建者自己

路径参数

参数 类型 必填 说明
boardId integer 看板ID
targetAdminId integer 目标管理员ID

响应 统一响应结果«Void»

GET /admin/task/board/{boardId}/members

获取看板成员

返回看板的所有成员列表，包含成员的管理员ID和姓名

路径参数

参数 类型 必填 说明
boardId integer 看板ID

响应 统一响应结果«List«看板成员信息»»

字段 类型 必填 说明
code int 状态码
data 看板成员信息[] 响应数据
  adminId long 管理员ID
  avatarUrl string 头像地址
  joinedAt string 加入时间
  role string 角色: OWNER/MEMBER
  username string 用户名
message string 响应消息

POST /admin/task/board/{boardId}/members

添加成员

批量添加管理员为看板成员，成为成员后可以查看看板、创建和操作任务。

权限：需管理员登录，且为看板创建者或超级管理员。

路径参数

参数 类型 必填 说明
boardId integer 看板ID

请求体 添加成员请求

字段 类型 必填 说明
adminIds long[] 是 管理员ID列表

响应 统一响应结果«Void»

POST /admin/task/board/{boardId}/status

创建状态列

在看板中创建新的状态列（如测试中、待发布等），自动排到末尾。任务通过拖拽在不同状态列间流转。

权限：需管理员登录且为看板成员。

路径参数

参数 类型 必填 说明
boardId integer 看板ID

请求体 创建状态请求

字段 类型 必填 说明
statusColor string 状态颜色
statusName string 是 状态名称

响应 统一响应结果«看板状态信息»

字段 类型 必填 说明
code int 状态码
data 看板状态信息 响应数据
  isPreset boolean 是否预设状态
  sortOrder int 排序序号
  statusColor string 状态颜色
  statusId long 状态ID
  statusName string 状态名称
  taskCount int 该状态下的任务数量
message string 响应消息

PUT /admin/task/board/{boardId}/status/sort

状态列排序

批量更新状态列的排序顺序。传入状态列ID数组，数组下标即为新的排序值。操作完成后通过WebSocket推送STATUS_REORDERED事件

路径参数

参数 类型 必填 说明
boardId integer 看板ID

请求体 状态排序请求

字段 类型 必填 说明
statusIds long[] 是 状态ID列表(按排序顺序)

响应 统一响应结果«Void»

GET /admin/task/board/{boardId}/statuses

获取看板状态列

返回看板的所有状态列（如待办、进行中、已完成），按排序字段升序排列。拖拽任务到不同状态列实现状态流转

路径参数

参数 类型 必填 说明
boardId integer 看板ID

响应 统一响应结果«List«看板状态信息»»

字段 类型 必填 说明
code int 状态码
data 看板状态信息[] 响应数据
  isPreset boolean 是否预设状态
  sortOrder int 排序序号
  statusColor string 状态颜色
  statusId long 状态ID
  statusName string 状态名称
  taskCount int 该状态下的任务数量
message string 响应消息

GET /admin/task/boards

获取可见看板列表

返回当前管理员可见的看板列表：超级管理员可见所有看板，普通管理员仅可见自己创建的或作为成员的看板

响应 统一响应结果«List«看板信息»»

字段 类型 必填 说明
code int 状态码
data 看板信息[] 响应数据
  boardId long 看板ID
  boardName string 看板名称
  boardType string 看板类型
  createdAt string 创建时间
  createdBy long 创建人ID
  creatorName string 创建人姓名
  deptId long 部门ID
  deptName string 部门名称
  description string 看板描述
  statuses 看板状态信息[] 状态列表
    isPreset boolean 是否预设状态
    sortOrder int 排序序号
    statusColor string 状态颜色
    statusId long 状态ID
    statusName string 状态名称
    taskCount int 该状态下的任务数量
  taskCount int 任务总数
message string 响应消息

PUT /admin/task/status/{statusId}

更新状态列

更新状态列的名称和颜色。

权限：需管理员登录且为看板成员。

路径参数

参数 类型 必填 说明
statusId integer 状态列ID

请求体 更新状态请求

字段 类型 必填 说明
statusColor string 状态颜色
statusName string 状态名称

响应 统一响应结果«看板状态信息»

字段 类型 必填 说明
code int 状态码
data 看板状态信息 响应数据
  isPreset boolean 是否预设状态
  sortOrder int 排序序号
  statusColor string 状态颜色
  statusId long 状态ID
  statusName string 状态名称
  taskCount int 该状态下的任务数量
message string 响应消息

DELETE /admin/task/status/{statusId}

删除状态列

删除看板的状态列。如果状态列下有任务则不允许删除，需先移动或删除任务

路径参数

参数 类型 必填 说明
statusId integer 状态列ID

响应 统一响应结果«Void»

任务管理

POST /admin/task

创建任务

在指定看板和状态列下创建任务。创建成功后通过WebSocket推送TASK_CREATED事件，并通知被分配的负责人

关联字典：

  • task_priority：任务优先级（创建时选择）

请求体 创建任务请求

字段 类型 必填 说明
assigneeIds long[] 负责人ID列表
boardId long 是 看板ID
description string 任务描述
dueDate string 截止日期
priority string 优先级: LOW/MEDIUM/HIGH/URGENT
statusId long 状态ID
title string 是 任务标题

响应 统一响应结果«任务信息»

字段 类型 必填 说明
code int 状态码
data 任务信息 响应数据
  assignees 负责人信息[] 负责人列表
    adminId long 管理员ID
    avatarUrl string 头像地址
    username string 用户名
    wechatName string 企微昵称
  boardId long 看板ID
  createdAt string 创建时间
  createdBy long 创建人ID
  creatorName string 创建人姓名
  description string 任务描述
  dueDate string 截止日期
  overdue boolean 是否逾期
  parentId long 父任务ID
  priority string 优先级: LOW/MEDIUM/HIGH/URGENT
  sortOrder int 排序序号
  statusColor string 状态颜色
  statusId long 状态ID
  statusName string 状态名称
  subtaskCompleted int 已完成子任务数
  subtaskTotal int 子任务总数
  subtasks 子任务信息[] 子任务列表
    completed boolean 是否已完成
    createdAt string 创建时间
    createdBy long 创建人ID
    creatorName string 创建人姓名
    taskId long 子任务ID
    title string 子任务标题
  taskId long 任务ID
  title string 任务标题
  updatedAt string 更新时间
message string 响应消息

GET /admin/task/board/{boardId}/tasks

获取看板任务(按状态分组)

返回看板下所有任务，按状态列分组。支持按优先级(HIGH/MEDIUM/LOW)和负责人筛选，每组内按排序值升序排列

关联字典：

  • task_priority：任务优先级（列表筛选+显示）

路径参数

参数 类型 必填 说明
boardId integer 看板ID

查询参数

参数 类型 必填 说明 示例
assigneeId integer(int64) 负责人ID
priority string 优先级

响应 统一响应结果«List«看板任务分组信息»»

字段 类型 必填 说明
code int 状态码
data 看板任务分组信息[] 响应数据
  sortOrder int 排序序号
  statusColor string 状态颜色
  statusId long 状态ID
  statusName string 状态名称
  tasks 任务信息[] 该状态下的任务列表
    assignees 负责人信息[] 负责人列表
    boardId long 看板ID
    createdAt string 创建时间
    createdBy long 创建人ID
    creatorName string 创建人姓名
    description string 任务描述
    dueDate string 截止日期
    overdue boolean 是否逾期
    parentId long 父任务ID
    priority string 优先级: LOW/MEDIUM/HIGH/URGENT
    sortOrder int 排序序号
    statusColor string 状态颜色
    statusId long 状态ID
    statusName string 状态名称
    subtaskCompleted int 已完成子任务数
    subtaskTotal int 子任务总数
    subtasks 子任务信息[] 子任务列表
    taskId long 任务ID
    title string 任务标题
    updatedAt string 更新时间
message string 响应消息

DELETE /admin/task/comment/{commentId}

删除评论

仅评论作者本人可删除自己的评论，系统自动生成的活动记录不可删除

路径参数

参数 类型 必填 说明
commentId integer 评论ID

响应 统一响应结果«Void»

DELETE /admin/task/subtask/{subtaskId}

删除子任务

删除指定子任务。

权限：需管理员登录且为看板成员。

路径参数

参数 类型 必填 说明
subtaskId integer 子任务ID

响应 统一响应结果«Void»

PUT /admin/task/subtask/{subtaskId}/toggle

切换子任务完成状态

切换子任务的完成/未完成状态（toggle），完成状态切换会自动记录到任务时间线

路径参数

参数 类型 必填 说明
subtaskId integer 子任务ID

响应 统一响应结果«Void»

GET /admin/task/{taskId}

任务详情

返回任务完整信息，包含子任务列表、负责人信息、附件列表等

关联字典：

  • task_priority：任务优先级（显示）

路径参数

参数 类型 必填 说明
taskId integer 任务ID

响应 统一响应结果«任务信息»

字段 类型 必填 说明
code int 状态码
data 任务信息 响应数据
  assignees 负责人信息[] 负责人列表
    adminId long 管理员ID
    avatarUrl string 头像地址
    username string 用户名
    wechatName string 企微昵称
  boardId long 看板ID
  createdAt string 创建时间
  createdBy long 创建人ID
  creatorName string 创建人姓名
  description string 任务描述
  dueDate string 截止日期
  overdue boolean 是否逾期
  parentId long 父任务ID
  priority string 优先级: LOW/MEDIUM/HIGH/URGENT
  sortOrder int 排序序号
  statusColor string 状态颜色
  statusId long 状态ID
  statusName string 状态名称
  subtaskCompleted int 已完成子任务数
  subtaskTotal int 子任务总数
  subtasks 子任务信息[] 子任务列表
    completed boolean 是否已完成
    createdAt string 创建时间
    createdBy long 创建人ID
    creatorName string 创建人姓名
    taskId long 子任务ID
    title string 子任务标题
  taskId long 任务ID
  title string 任务标题
  updatedAt string 更新时间
message string 响应消息

PUT /admin/task/{taskId}

更新任务

更新任务的标题、描述、优先级、截止日期、负责人等信息。更新后通过WebSocket推送TASK_UPDATED事件，如果修改了负责人则额外通知新负责人。

权限：需管理员登录且为看板成员。

关联字典：

  • task_priority：任务优先级（编辑时选择）

路径参数

参数 类型 必填 说明
taskId integer 任务ID

请求体 更新任务请求

字段 类型 必填 说明
assigneeIds long[] 负责人ID列表
description string 任务描述
dueDate string 截止日期
priority string 优先级: LOW/MEDIUM/HIGH/URGENT
title string 任务标题

响应 统一响应结果«任务信息»

字段 类型 必填 说明
code int 状态码
data 任务信息 响应数据
  assignees 负责人信息[] 负责人列表
    adminId long 管理员ID
    avatarUrl string 头像地址
    username string 用户名
    wechatName string 企微昵称
  boardId long 看板ID
  createdAt string 创建时间
  createdBy long 创建人ID
  creatorName string 创建人姓名
  description string 任务描述
  dueDate string 截止日期
  overdue boolean 是否逾期
  parentId long 父任务ID
  priority string 优先级: LOW/MEDIUM/HIGH/URGENT
  sortOrder int 排序序号
  statusColor string 状态颜色
  statusId long 状态ID
  statusName string 状态名称
  subtaskCompleted int 已完成子任务数
  subtaskTotal int 子任务总数
  subtasks 子任务信息[] 子任务列表
    completed boolean 是否已完成
    createdAt string 创建时间
    createdBy long 创建人ID
    creatorName string 创建人姓名
    taskId long 子任务ID
    title string 子任务标题
  taskId long 任务ID
  title string 任务标题
  updatedAt string 更新时间
message string 响应消息

DELETE /admin/task/{taskId}

删除任务

删除任务及其所有子任务、评论和时间线记录（级联删除）。删除后通过WebSocket推送TASK_DELETED事件。

权限：需管理员登录且为看板成员。

路径参数

参数 类型 必填 说明
taskId integer 任务ID

响应 统一响应结果«Void»

POST /admin/task/{taskId}/comment

添加评论

在任务时间线中添加评论，添加后自动通知任务负责人

路径参数

参数 类型 必填 说明
taskId integer 任务ID

请求体 创建评论请求

字段 类型 必填 说明
content string 是 评论内容

响应 统一响应结果«时间线条目»

字段 类型 必填 说明
code int 状态码
data 时间线条目 响应数据
  action string 操作类型
  adminAvatar string 管理员头像
  adminId long 管理员ID
  adminName string 管理员姓名
  content string 内容
  createdAt string 创建时间
  id long 条目ID
  newValue string 新值
  oldValue string 旧值
  type string 类型: COMMENT/ACTIVITY
message string 响应消息

PUT /admin/task/{taskId}/sort

任务排序

更新任务在同一状态列内的排序位置，用于拖拽排序

路径参数

参数 类型 必填 说明
taskId integer 任务ID

请求体 任务排序请求

字段 类型 必填 说明
statusId long 是 状态ID
taskIds long[] 是 任务ID列表(按排序顺序)

响应 统一响应结果«Void»

PUT /admin/task/{taskId}/status

变更任务状态

将任务移动到指定状态列（拖拽操作），自动记录状态变更到时间线，并通过WebSocket推送TASK_STATUS_CHANGED事件

路径参数

参数 类型 必填 说明
taskId integer 任务ID

请求体 变更任务状态请求

字段 类型 必填 说明
statusId long 是 目标状态ID

响应 统一响应结果«Void»

POST /admin/task/{taskId}/subtask

创建子任务

在指定任务下创建子任务（待办项），用于拆分任务的执行步骤。子任务默认为未完成状态。

权限：需管理员登录且为看板成员。

路径参数

参数 类型 必填 说明
taskId integer 任务ID

请求体 创建子任务请求

字段 类型 必填 说明
title string 是 子任务标题

响应 统一响应结果«子任务信息»

字段 类型 必填 说明
code int 状态码
data 子任务信息 响应数据
  completed boolean 是否已完成
  createdAt string 创建时间
  createdBy long 创建人ID
  creatorName string 创建人姓名
  taskId long 子任务ID
  title string 子任务标题
message string 响应消息

GET /admin/task/{taskId}/timeline

获取任务时间线

返回任务的完整操作记录，包含评论和系统自动记录的状态变更、人员分配等活动，按时间正序排列

路径参数

参数 类型 必填 说明
taskId integer 任务ID

响应 统一响应结果«List«时间线条目»»

字段 类型 必填 说明
code int 状态码
data 时间线条目[] 响应数据
  action string 操作类型
  adminAvatar string 管理员头像
  adminId long 管理员ID
  adminName string 管理员姓名
  content string 内容
  createdAt string 创建时间
  id long 条目ID
  newValue string 新值
  oldValue string 旧值
  type string 类型: COMMENT/ACTIVITY
message string 响应消息