# 任务服务 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}` | 订阅指定看板，接收该看板下的实时任务事件 |

## 推送消息格式

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

## 事件类型

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

## 前端接入示例 (SockJS + STOMP)

```javascript
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` |  | 响应消息 |

---