forked from erp-dev/erp
fin
This commit is contained in:
775
docs/api_v2_mission_api_2026-07-03.md
Normal file
775
docs/api_v2_mission_api_2026-07-03.md
Normal file
@@ -0,0 +1,775 @@
|
||||
# Mission 任务模块 API 文档
|
||||
|
||||
更新日期：2026-07-03
|
||||
|
||||
本文档面向前端，描述 `mission` 中立任务模块的对外 API。当前 mission API 仅在 `api_v2` 提供；已检查 `api_v1/urls.py`，`api_v1` 暂无 mission 相关接口。
|
||||
|
||||
## 1. 基本约定
|
||||
|
||||
- Base URL: `/api/v2`
|
||||
- 认证：所有 mission 接口均需要登录。
|
||||
- 当前员工：后端使用 `request.user.employee` 作为当前业务员工。
|
||||
- 商户隔离：任务、任务分类、参与者、回应均按当前员工所属 `merchant` 隔离。
|
||||
- 参与者对象：任务参与者是 `basic_info.Employee`，不是 Django `User`。
|
||||
- 删除任务：不提供物理删除任务接口；业务结束请使用取消接口。
|
||||
- 普通创建/更新接口不允许直接修改状态字段，状态变化必须走独立状态接口。
|
||||
|
||||
普通创建/更新禁止提交字段：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|---|---|
|
||||
| `is_urgent` | 是否紧急，使用 `set-urgent` 接口修改 |
|
||||
| `is_completed` | 是否完成，由结束回应、reopen、reject 流程维护 |
|
||||
| `is_cancelled` | 是否取消，使用 `cancel` 接口修改 |
|
||||
| `cancelled_by` | 取消人，由后端写入 |
|
||||
| `cancelled_at` | 取消时间，由后端写入 |
|
||||
| `rejected_by` | 回应撤销人，由后端写入 |
|
||||
| `rejected_at` | 回应撤销时间，由后端写入 |
|
||||
|
||||
## 2. API v1 状态
|
||||
|
||||
已检查 `api_v1/urls.py` 和 `api_v1/views`，当前没有 mission 模块接口。
|
||||
|
||||
如前端需要任务模块，请使用本文档中的 `/api/v2/...` 接口。
|
||||
|
||||
## 3. 核心数据结构
|
||||
|
||||
### 3.1 EmployeePayload
|
||||
|
||||
任务模块中所有人员字段均使用员工对象摘要：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 21,
|
||||
"name": "李四",
|
||||
"merchant_id": 10
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 MissionCategory
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"merchant": 10,
|
||||
"name": "通用",
|
||||
"payload_processor": "",
|
||||
"speech_enabled": false,
|
||||
"created_at": "2026-07-03T10:00:00+08:00",
|
||||
"updated_at": "2026-07-03T10:00:00+08:00"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `id` | number | 任务分类 ID |
|
||||
| `merchant` | number | 所属商户 ID |
|
||||
| `name` | string | 分类名称，同商户内唯一 |
|
||||
| `payload_processor` | string | payload 增强器，可为空；当前可选 `structured_description_v1` |
|
||||
| `speech_enabled` | boolean | 是否启用任务播报 |
|
||||
| `created_at` | string | 创建时间 |
|
||||
| `updated_at` | string | 更新时间 |
|
||||
|
||||
### 3.3 Mission
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"merchant": 10,
|
||||
"description": "请跟进这张生产单",
|
||||
"category": 1,
|
||||
"category_name": "通用",
|
||||
"is_urgent": false,
|
||||
"is_completed": false,
|
||||
"is_cancelled": false,
|
||||
"notify_if_unreplied": true,
|
||||
"unreplied_notify_interval_minutes": 30,
|
||||
"unreplied_notify_max_count": 5,
|
||||
"unreplied_notify_sent_count": 0,
|
||||
"unreplied_last_notified_at": null,
|
||||
"cancelled_at": null,
|
||||
"creator": {
|
||||
"id": 20,
|
||||
"name": "张三",
|
||||
"merchant_id": 10
|
||||
},
|
||||
"cancelled_by": null,
|
||||
"participants": [
|
||||
{
|
||||
"id": 21,
|
||||
"name": "李四",
|
||||
"merchant_id": 10
|
||||
}
|
||||
],
|
||||
"content_type": 33,
|
||||
"content_type_label": "printing.printingorder",
|
||||
"content_id": 123,
|
||||
"extra": {
|
||||
"source": "printing-order"
|
||||
},
|
||||
"has_ending_reply": false,
|
||||
"can_reply": true,
|
||||
"created_at": "2026-07-03T10:00:00+08:00",
|
||||
"updated_at": "2026-07-03T10:00:00+08:00"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `id` | number | 任务 ID |
|
||||
| `merchant` | number | 所属商户 ID |
|
||||
| `description` | string | 任务描述 |
|
||||
| `category` | number | MissionCategory.id |
|
||||
| `category_name` | string | 分类名称 |
|
||||
| `is_urgent` | boolean | 是否紧急 |
|
||||
| `is_completed` | boolean | 是否完成 |
|
||||
| `is_cancelled` | boolean | 是否取消 |
|
||||
| `notify_if_unreplied` | boolean | 是否开启未回复提醒 |
|
||||
| `unreplied_notify_interval_minutes` | number/null | 未回复提醒间隔，单位分钟 |
|
||||
| `unreplied_notify_max_count` | number | 未回复最大提醒次数，默认 5 |
|
||||
| `unreplied_notify_sent_count` | number | 已发送未回复提醒次数 |
|
||||
| `unreplied_last_notified_at` | string/null | 上一次未回复提醒时间 |
|
||||
| `cancelled_at` | string/null | 取消时间 |
|
||||
| `creator` | EmployeePayload | 创建员工 |
|
||||
| `cancelled_by` | EmployeePayload/null | 取消员工 |
|
||||
| `participants` | EmployeePayload[] | 最终展开后的任务参与员工列表 |
|
||||
| `content_type` | number/null | django_content_type.id |
|
||||
| `content_type_label` | string/null | 可读模型标识，例如 `printing.printingorder` |
|
||||
| `content_id` | number/null | 关联对象 ID |
|
||||
| `extra` | object/null | 扩展字段 |
|
||||
| `has_ending_reply` | boolean | 是否已有结束任务的有效回应 |
|
||||
| `can_reply` | boolean | 当前是否允许继续回应 |
|
||||
| `created_at` | string | 创建时间 |
|
||||
| `updated_at` | string | 更新时间 |
|
||||
|
||||
### 3.4 MissionLite
|
||||
|
||||
`MissionLite` 用于轻量查询，字段与 `Mission` 基本一致，但不返回 `participants`、`has_ending_reply`、`can_reply`。
|
||||
|
||||
### 3.5 MissionReply
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 100,
|
||||
"mission": 1,
|
||||
"merchant": 10,
|
||||
"responder": {
|
||||
"id": 20,
|
||||
"name": "张三",
|
||||
"merchant_id": 10
|
||||
},
|
||||
"content": "已处理",
|
||||
"extra": {
|
||||
"attachment_ids": [1001, 1002]
|
||||
},
|
||||
"replied_at": "2026-07-03T10:10:00+08:00",
|
||||
"ends_task": true,
|
||||
"is_rejected": false,
|
||||
"rejected_by": null,
|
||||
"rejected_at": null,
|
||||
"created_at": "2026-07-03T10:10:00+08:00",
|
||||
"updated_at": "2026-07-03T10:10:00+08:00"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `id` | number | 回应 ID |
|
||||
| `mission` | number | Mission.id |
|
||||
| `merchant` | number | 所属商户 ID |
|
||||
| `responder` | EmployeePayload | 回应员工 |
|
||||
| `content` | string | 回应内容 |
|
||||
| `extra` | object/null | 扩展字段 |
|
||||
| `replied_at` | string | 回应时间 |
|
||||
| `ends_task` | boolean | 是否结束任务 |
|
||||
| `is_rejected` | boolean | 是否已被撤销 |
|
||||
| `rejected_by` | EmployeePayload/null | 撤销员工 |
|
||||
| `rejected_at` | string/null | 撤销时间 |
|
||||
| `created_at` | string | 创建时间 |
|
||||
| `updated_at` | string | 更新时间 |
|
||||
|
||||
### 3.6 MissionWithReplies
|
||||
|
||||
在 `Mission` 结构基础上额外返回 `replies`：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"description": "请跟进这张生产单",
|
||||
"participants": [],
|
||||
"replies": [
|
||||
{
|
||||
"id": 100,
|
||||
"mission": 1,
|
||||
"content": "已处理",
|
||||
"ends_task": true,
|
||||
"is_rejected": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 参与者参数规则
|
||||
|
||||
任务创建和任务更新支持两类参与者参数：
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `participant_ids` | number[] | 显式参与员工列表，传 `Employee.id` |
|
||||
| `employee_type_ids` | number[] | 职位列表，传 `EmployeeType.id`，后端会展开为该职位下的在职员工 |
|
||||
|
||||
最终参与者计算规则：
|
||||
|
||||
```text
|
||||
最终参与者 = participant_ids 中的员工 + employee_type_ids 对应职位下的在职员工
|
||||
```
|
||||
|
||||
详细规则：
|
||||
|
||||
- `participant_ids` 传的是 `Employee.id`。
|
||||
- `employee_type_ids` 传的是 `EmployeeType.id`。
|
||||
- `employee_type_ids` 只允许传当前商户下的职位。
|
||||
- 职位展开时只加入 `status=ACTIVE` 的员工。
|
||||
- 重复员工会自动去重。
|
||||
- 职位下没有员工不会报错。
|
||||
- 传入不存在或跨商户的 `EmployeeType.id` 会返回 400。
|
||||
- `PATCH /missions/{mission_id}/` 中，只要传了 `participant_ids` 或 `employee_type_ids`，即表示重新设置最终参与者列表，不是增量追加。
|
||||
- `PATCH /missions/{mission_id}/` 中，如果两个参数都不传，则不修改原参与者。
|
||||
|
||||
清空参与者：
|
||||
|
||||
```json
|
||||
{
|
||||
"participant_ids": [],
|
||||
"employee_type_ids": []
|
||||
}
|
||||
```
|
||||
|
||||
## 5. content_type 规则
|
||||
|
||||
`content_type` 和 `content_id` 用于把任务挂靠到业务对象上。
|
||||
|
||||
- `content_type` 是 `django_content_type.id`。
|
||||
- `content_id` 是对应业务对象主键。
|
||||
- 两者必须同时提交或同时省略。
|
||||
- 前端不应硬编码 `content_type`，不同环境的 ID 可能不同。
|
||||
- 推荐通过 `GET /api/v2/content-types/` 获取可用值。
|
||||
|
||||
响应中的 `content_type_label` 是只读辅助字段，格式为：
|
||||
|
||||
```text
|
||||
app_label.model
|
||||
```
|
||||
|
||||
例如：
|
||||
|
||||
```text
|
||||
printing.printingorder
|
||||
business.salesorder
|
||||
```
|
||||
|
||||
当前允许前端用于 mission 关联的业务对象：
|
||||
|
||||
| content_type_label | 中文说明 |
|
||||
|---|---|
|
||||
| `printing.plateorder` | 开版单 |
|
||||
| `printing.printingorder` | 印刷单 |
|
||||
| `printing.printingjob` | 印刷任务 |
|
||||
| `business.purchaseorder` | 采购单 |
|
||||
| `business.presalesorder` | 预销售单 |
|
||||
| `business.salesorder` | 销售单 |
|
||||
| `business.prepurchaseorder` | 预采购单 |
|
||||
| `business.purchasereturnorder` | 采购退货单 |
|
||||
| `business.salesreturnorder` | 销售退货单 |
|
||||
| `business.paymentorder` | 付款单 |
|
||||
| `business.receiptorder` | 收款单 |
|
||||
| `stock.transferorder` | 调拨单 |
|
||||
| `shipment.shipment` | 发货单 |
|
||||
| `stateflow.process` | 工艺流程实例 |
|
||||
|
||||
## 6. 接口列表
|
||||
|
||||
### 6.1 查询可用 content_type
|
||||
|
||||
```http
|
||||
GET /api/v2/content-types/
|
||||
```
|
||||
|
||||
响应：`200 OK`
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 33,
|
||||
"app_label": "printing",
|
||||
"model": "printingorder",
|
||||
"label": "printing.printingorder",
|
||||
"name": "印刷单"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 6.2 查询任务分类列表
|
||||
|
||||
```http
|
||||
GET /api/v2/mission-categories/
|
||||
```
|
||||
|
||||
响应：`200 OK`
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"merchant": 10,
|
||||
"name": "通用",
|
||||
"payload_processor": "",
|
||||
"speech_enabled": false,
|
||||
"created_at": "2026-07-03T10:00:00+08:00",
|
||||
"updated_at": "2026-07-03T10:00:00+08:00"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 6.3 创建任务分类
|
||||
|
||||
```http
|
||||
POST /api/v2/mission-categories/
|
||||
```
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "生产跟进",
|
||||
"speech_enabled": true,
|
||||
"payload_processor": "structured_description_v1"
|
||||
}
|
||||
```
|
||||
|
||||
请求字段：
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `name` | string | 是 | 分类名称，同商户内唯一 |
|
||||
| `speech_enabled` | boolean | 否 | 是否启用播报，默认 false |
|
||||
| `payload_processor` | string | 否 | 可为空；可选 `structured_description_v1` |
|
||||
|
||||
响应：`201 Created`，返回 `MissionCategory`。
|
||||
|
||||
常见错误：
|
||||
|
||||
```json
|
||||
{"name": ["分类名称已存在"]}
|
||||
```
|
||||
|
||||
### 6.4 查询任务分类详情
|
||||
|
||||
```http
|
||||
GET /api/v2/mission-categories/{category_id}/
|
||||
```
|
||||
|
||||
响应：`200 OK`，返回 `MissionCategory`。
|
||||
|
||||
### 6.5 更新任务分类
|
||||
|
||||
```http
|
||||
PATCH /api/v2/mission-categories/{category_id}/
|
||||
```
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "售后跟进",
|
||||
"speech_enabled": false,
|
||||
"payload_processor": ""
|
||||
}
|
||||
```
|
||||
|
||||
响应：`200 OK`，返回 `MissionCategory`。
|
||||
|
||||
### 6.6 删除任务分类
|
||||
|
||||
```http
|
||||
DELETE /api/v2/mission-categories/{category_id}/
|
||||
```
|
||||
|
||||
响应：
|
||||
|
||||
- `204 No Content`：删除成功。
|
||||
- `400 Bad Request`：分类已被任务使用，不能删除。
|
||||
|
||||
错误示例：
|
||||
|
||||
```json
|
||||
{"detail": "任务分类已被使用，不能删除"}
|
||||
```
|
||||
|
||||
### 6.7 查询任务列表
|
||||
|
||||
```http
|
||||
GET /api/v2/missions/
|
||||
```
|
||||
|
||||
查询参数：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `category` | number | 否 | 按任务分类 ID 过滤 |
|
||||
| `is_urgent` | boolean | 否 | 按是否紧急过滤，支持 `1/0/true/false/yes/no` |
|
||||
| `is_completed` | boolean | 否 | 按是否完成过滤 |
|
||||
| `is_cancelled` | boolean | 否 | 按是否取消过滤 |
|
||||
| `content_type` | number | 否 | 按 content_type ID 过滤 |
|
||||
| `content_id` | number | 否 | 按关联对象 ID 过滤 |
|
||||
|
||||
响应：`200 OK`，返回 `Mission[]`。
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"description": "请跟进这张生产单",
|
||||
"category": 1,
|
||||
"category_name": "通用",
|
||||
"participants": [],
|
||||
"can_reply": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 6.8 创建任务
|
||||
|
||||
```http
|
||||
POST /api/v2/missions/
|
||||
```
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "请跟进这张生产单",
|
||||
"category": 1,
|
||||
"content_type": 33,
|
||||
"content_id": 123,
|
||||
"extra": {
|
||||
"source": "printing-order"
|
||||
},
|
||||
"participant_ids": [101, 102],
|
||||
"employee_type_ids": [3, 4],
|
||||
"notify_if_unreplied": true,
|
||||
"unreplied_notify_interval_minutes": 30,
|
||||
"unreplied_notify_max_count": 5
|
||||
}
|
||||
```
|
||||
|
||||
请求字段：
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `description` | string | 是 | 任务描述，不能为空 |
|
||||
| `category` | number | 否 | MissionCategory.id；不传则使用默认“通用”分类 |
|
||||
| `content_type` | number/null | 否 | django_content_type.id；与 `content_id` 必须同时提供或同时省略 |
|
||||
| `content_id` | number/null | 否 | 关联业务对象 ID；与 `content_type` 必须同时提供或同时省略 |
|
||||
| `extra` | object/null | 否 | 扩展字段 |
|
||||
| `participant_ids` | number[] | 否 | 显式参与员工 ID 列表，传 Employee.id |
|
||||
| `employee_type_ids` | number[] | 否 | 参与职位 ID 列表，传 EmployeeType.id；展开为在职员工 |
|
||||
| `notify_if_unreplied` | boolean | 否 | 是否开启未回复提醒，默认 false |
|
||||
| `unreplied_notify_interval_minutes` | number/null | 否 | 未回复提醒间隔；开启提醒时必填 |
|
||||
| `unreplied_notify_max_count` | number | 否 | 最大提醒次数，默认 5 |
|
||||
|
||||
响应：`201 Created`，返回 `Mission`。
|
||||
|
||||
常见错误：
|
||||
|
||||
```json
|
||||
{"detail": "参与者不存在或不属于任务所属商户"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"detail": "员工职位不存在或不属于任务所属商户"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"unreplied_notify_interval_minutes": ["开启未回复提醒时必须设置提醒间隔"]}
|
||||
```
|
||||
|
||||
### 6.9 查询任务详情
|
||||
|
||||
```http
|
||||
GET /api/v2/missions/{mission_id}/
|
||||
```
|
||||
|
||||
响应：`200 OK`，返回 `Mission`。
|
||||
|
||||
### 6.10 更新任务
|
||||
|
||||
```http
|
||||
PATCH /api/v2/missions/{mission_id}/
|
||||
```
|
||||
|
||||
请求体示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "更新后的任务描述",
|
||||
"category": 2,
|
||||
"extra": {
|
||||
"channel": "wechat"
|
||||
},
|
||||
"participant_ids": [101],
|
||||
"employee_type_ids": [3],
|
||||
"notify_if_unreplied": true,
|
||||
"unreplied_notify_interval_minutes": 20,
|
||||
"unreplied_notify_max_count": 8
|
||||
}
|
||||
```
|
||||
|
||||
可更新字段：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `description` | string | 任务描述，不能为空 |
|
||||
| `category` | number | MissionCategory.id |
|
||||
| `content_type` | number/null | 与 `content_id` 必须同时提交；可提交 null 清空关联 |
|
||||
| `content_id` | number/null | 与 `content_type` 必须同时提交；可提交 null 清空关联 |
|
||||
| `extra` | object/null | 扩展字段；提交 null 可清空 |
|
||||
| `participant_ids` | number[] | 显式员工参与者列表 |
|
||||
| `employee_type_ids` | number[] | 按职位展开的参与者列表 |
|
||||
| `notify_if_unreplied` | boolean | 是否开启未回复提醒 |
|
||||
| `unreplied_notify_interval_minutes` | number/null | 未回复提醒间隔 |
|
||||
| `unreplied_notify_max_count` | number | 未回复最大提醒次数 |
|
||||
|
||||
响应：`200 OK`，返回 `Mission`。
|
||||
|
||||
注意：
|
||||
|
||||
- `participant_ids` 和 `employee_type_ids` 表示重新设置最终参与者列表，不是增量追加。
|
||||
- 如果两个字段都不传，则不修改参与者。
|
||||
- 若提交 `content_type` 或 `content_id`，两者必须同时出现在请求体中。
|
||||
- 状态字段不能通过该接口更新。
|
||||
|
||||
清空任务关联对象：
|
||||
|
||||
```json
|
||||
{
|
||||
"content_type": null,
|
||||
"content_id": null
|
||||
}
|
||||
```
|
||||
|
||||
清空参与者：
|
||||
|
||||
```json
|
||||
{
|
||||
"participant_ids": [],
|
||||
"employee_type_ids": []
|
||||
}
|
||||
```
|
||||
|
||||
### 6.11 删除任务
|
||||
|
||||
```http
|
||||
DELETE /api/v2/missions/{mission_id}/
|
||||
```
|
||||
|
||||
不支持。
|
||||
|
||||
响应：`405 Method Not Allowed`
|
||||
|
||||
```json
|
||||
{"detail": "Mission 删除接口未提供，请使用 cancel 接口取消任务"}
|
||||
```
|
||||
|
||||
### 6.12 按印刷单查询任务
|
||||
|
||||
```http
|
||||
GET /api/v2/missions/by-printing-order/{printing_order_id}/
|
||||
```
|
||||
|
||||
查询指定印刷单关联的任务。
|
||||
|
||||
查询参数：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `category_ids` | number[]/string | 否 | 分类过滤。支持重复参数或逗号分隔，例如 `?category_ids=1,2` 或 `?category_ids=1&category_ids=2` |
|
||||
| `include_details` | boolean | 否 | 是否返回详情。默认 true；false 时返回 MissionLite[] |
|
||||
|
||||
响应：
|
||||
|
||||
- `include_details=true` 或未传：`200 OK`，返回 `MissionWithReplies[]`。
|
||||
- `include_details=false`：`200 OK`，返回 `MissionLite[]`。
|
||||
|
||||
示例：
|
||||
|
||||
```http
|
||||
GET /api/v2/missions/by-printing-order/123/?category_ids=1,2&include_details=true
|
||||
```
|
||||
|
||||
常见错误：
|
||||
|
||||
```json
|
||||
{"include_details": "必须是布尔值"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"category_ids": "必须是整数 ID 列表"}
|
||||
```
|
||||
|
||||
### 6.13 查询任务回应列表
|
||||
|
||||
```http
|
||||
GET /api/v2/missions/{mission_id}/replies/
|
||||
```
|
||||
|
||||
查询参数：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `ends_task` | boolean | 否 | 按是否结束任务过滤 |
|
||||
| `is_rejected` | boolean | 否 | 按是否已撤销过滤 |
|
||||
|
||||
响应：`200 OK`，返回 `MissionReply[]`。
|
||||
|
||||
### 6.14 创建任务回应
|
||||
|
||||
```http
|
||||
POST /api/v2/missions/{mission_id}/replies/
|
||||
```
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"content": "已处理完成",
|
||||
"ends_task": true,
|
||||
"extra": {
|
||||
"attachment_ids": [1001, 1002]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
请求字段：
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `content` | string | 是 | 回应内容，不能为空 |
|
||||
| `ends_task` | boolean | 否 | 是否结束任务，默认 false |
|
||||
| `extra` | object/null | 否 | 扩展字段 |
|
||||
|
||||
响应：`201 Created`，返回 `MissionReply`。
|
||||
|
||||
行为说明：
|
||||
|
||||
- 回应人固定为当前登录用户关联的 Employee。
|
||||
- 如果 `ends_task=true`，任务会被标记为完成。
|
||||
- 已取消任务或已有未撤销结束回应的任务不可继续回应。
|
||||
|
||||
### 6.15 重新打开任务
|
||||
|
||||
```http
|
||||
POST /api/v2/missions/{mission_id}/reopen/
|
||||
```
|
||||
|
||||
权限要求：当前用户需要 Django 权限 `mission.reopen_mission`。
|
||||
|
||||
响应：`200 OK`，返回 `Mission`。
|
||||
|
||||
行为说明：
|
||||
|
||||
- 用于重新打开已完成任务。
|
||||
- 会撤销已有结束任务效果，使任务回到未完成状态。
|
||||
|
||||
常见错误：
|
||||
|
||||
```json
|
||||
{"detail": "缺少重新打开任务权限"}
|
||||
```
|
||||
|
||||
### 6.16 取消任务
|
||||
|
||||
```http
|
||||
POST /api/v2/missions/{mission_id}/cancel/
|
||||
```
|
||||
|
||||
响应：`200 OK`，返回 `Mission`。
|
||||
|
||||
行为说明：
|
||||
|
||||
- 取消人固定为当前登录用户关联的 Employee。
|
||||
- 取消后 `is_cancelled=true`，`cancelled_by` 和 `cancelled_at` 由后端写入。
|
||||
|
||||
### 6.17 设置任务紧急状态
|
||||
|
||||
```http
|
||||
POST /api/v2/missions/{mission_id}/set-urgent/
|
||||
```
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"is_urgent": true
|
||||
}
|
||||
```
|
||||
|
||||
请求字段：
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `is_urgent` | boolean | 是 | 是否紧急 |
|
||||
|
||||
响应：`200 OK`，返回 `Mission`。
|
||||
|
||||
### 6.18 撤销任务回应
|
||||
|
||||
```http
|
||||
POST /api/v2/mission-replies/{reply_id}/reject/
|
||||
```
|
||||
|
||||
权限要求：当前用户需要 Django 权限 `mission.reject_mission_reply`。
|
||||
|
||||
响应：`200 OK`，返回 `MissionReply`。
|
||||
|
||||
行为说明：
|
||||
|
||||
- 撤销人固定为当前登录用户关联的 Employee。
|
||||
- 如果撤销的是结束任务回应，任务可能会被重新打开。
|
||||
|
||||
常见错误：
|
||||
|
||||
```json
|
||||
{"detail": "缺少撤销任务回应权限"}
|
||||
```
|
||||
|
||||
## 7. 常见状态码
|
||||
|
||||
| 状态码 | 场景 |
|
||||
|---|---|
|
||||
| `200 OK` | 查询、更新、状态操作成功 |
|
||||
| `201 Created` | 创建任务、分类、回应成功 |
|
||||
| `204 No Content` | 删除任务分类成功 |
|
||||
| `400 Bad Request` | 参数非法、跨商户、业务状态不允许 |
|
||||
| `401 Unauthorized` | 未登录 |
|
||||
| `403 Forbidden` | 缺少 `reopen_mission` 或 `reject_mission_reply` 等权限 |
|
||||
| `404 Not Found` | 对象不存在或不属于当前商户 |
|
||||
| `405 Method Not Allowed` | 不支持的删除任务操作 |
|
||||
|
||||
## 8. 前端接入建议
|
||||
|
||||
- 创建/更新任务时，`participant_ids` 使用 `Employee.id`，`employee_type_ids` 使用 `EmployeeType.id`。
|
||||
- 如果只想按职位添加参与者，可以只传 `employee_type_ids`。
|
||||
- 如果 PATCH 不想改变参与者，不要传 `participant_ids` 和 `employee_type_ids`。
|
||||
- 如果 PATCH 想清空参与者，两个字段都传空数组。
|
||||
- `content_type` 不要硬编码，应从 `/api/v2/content-types/` 获取。
|
||||
- 普通任务编辑页不要提交状态字段，紧急、取消、重新打开、撤销回应都走独立接口。
|
||||
- 响应中的 `participants` 是后端最终展开后的员工列表，前端展示以该字段为准。
|
||||
|
||||
更新日期：2026-07-03
|
||||
Reference in New Issue
Block a user