129 lines
4.6 KiB
Markdown
129 lines
4.6 KiB
Markdown
# 主管审核与任务分配功能 - 设计文档
|
||
|
||
## 1. 功能描述
|
||
本功能模块是NEPM（后台管理端）的核心组成部分，专为`主管 (SUPERVISOR)`和`管理员 (ADMIN)`角色设计。它弥合了AI自动审核与人工任务分配之间的鸿沟，确保了只有经过人工确认的有效反馈才能进入网格员的处理流程。
|
||
|
||
主要职责包括：
|
||
- **审核**: 对AI初审通过的反馈 (`PENDING_REVIEW`) 进行人工复核。
|
||
- **决策**: 决定该反馈是应该继续流转 (`PENDING_ASSIGNMENT`) 还是直接关闭 (`CLOSED_INVALID`)。
|
||
- **分配**: 将审核通过的有效反馈手动指派给特定的`网格员 (GRID_WORKER)`。
|
||
|
||
## 2. 业务流程
|
||
```mermaid
|
||
graph TD
|
||
subgraph "AI自动审核"
|
||
A[反馈状态: PENDING_REVIEW]
|
||
end
|
||
|
||
subgraph "主管人工审核 (Supervisor/Admin 操作)"
|
||
A --> B{主管查看待审核列表};
|
||
B --> C{审核决策};
|
||
C -- 审核通过 --> D[调用 Approve API<br>/api/supervisor/reviews/{id}/approve];
|
||
C -- 审核拒绝 --> E[调用 Reject API<br>/api/supervisor/reviews/{id}/reject];
|
||
end
|
||
|
||
subgraph "后端服务"
|
||
D --> F[反馈状态变为<br>PENDING_ASSIGNMENT];
|
||
E --> G[反馈状态变为<br>CLOSED_INVALID];
|
||
end
|
||
|
||
subgraph "主管手动分配"
|
||
F --> H{主管在任务分配界面<br>查看待分配列表};
|
||
H --> I{选择反馈 + 选择网格员};
|
||
I --> J[调用 Assign API<br>/api/task-assignment/assign];
|
||
end
|
||
|
||
subgraph "后端服务"
|
||
J --> K[创建 Assignment 记录<br>反馈状态变为 ASSIGNED];
|
||
end
|
||
|
||
style F fill:#C8E6C9,stroke:#333
|
||
style G fill:#FFCDD2,stroke:#333
|
||
style K fill:#B3E5FC,stroke:#333
|
||
```
|
||
|
||
## 3. API 接口设计
|
||
|
||
### 3.1 主管审核接口 (SupervisorController)
|
||
|
||
#### 3.1.1 获取待审核反馈列表
|
||
- **URL**: `GET /api/supervisor/reviews`
|
||
- **描述**: 获取所有状态为 `PENDING_REVIEW` 的反馈，供主管进行人工审核。
|
||
- **权限**: `SUPERVISOR`, `ADMIN`
|
||
- **成功响应** (`200 OK`): 返回 `Feedback` 对象数组。
|
||
```json
|
||
[
|
||
{
|
||
"id": 101,
|
||
"eventId": "uuid-...",
|
||
"title": "...",
|
||
"status": "PENDING_REVIEW",
|
||
...
|
||
}
|
||
]
|
||
```
|
||
|
||
#### 3.1.2 批准反馈
|
||
- **URL**: `POST /api/supervisor/reviews/{feedbackId}/approve`
|
||
- **描述**: 主管批准一个反馈，使其进入待分配状态。
|
||
- **权限**: `SUPERVISOR`, `ADMIN`
|
||
- **路径参数**: `feedbackId` (Long) - 要批准的反馈ID。
|
||
- **成功响应** (`200 OK`): 无内容。
|
||
- **失败响应**:
|
||
- `400 Bad Request`: 如果反馈状态不是 `PENDING_REVIEW`。
|
||
- `404 Not Found`: 如果 `feedbackId` 不存在。
|
||
|
||
#### 3.1.3 拒绝反馈
|
||
- **URL**: `POST /api/supervisor/reviews/{feedbackId}/reject`
|
||
- **描述**: 主管拒绝一个反馈，将其关闭。
|
||
- **权限**: `SUPERVISOR`, `ADMIN`
|
||
- **路径参数**: `feedbackId` (Long) - 要拒绝的反馈ID。
|
||
- **成功响应** (`200 OK`): 无内容。
|
||
- **失败响应**:
|
||
- `400 Bad Request`: 如果反馈状态不是 `PENDING_REVIEW`。
|
||
- `404 Not Found`: 如果 `feedbackId` 不存在。
|
||
|
||
|
||
### 3.2 任务分配接口 (TaskAssignmentController)
|
||
|
||
#### 3.2.1 获取待分配反馈列表
|
||
- **URL**: `GET /api/task-assignment/unassigned-feedback`
|
||
- **描述**: 获取所有状态为 `PENDING_ASSIGNMENT` 的反馈，即已通过主管审核，等待分配。
|
||
- **权限**: `SUPERVISOR`, `ADMIN`
|
||
- **成功响应** (`200 OK`): 返回 `Feedback` 对象数组。
|
||
|
||
#### 3.2.2 获取可用网格员列表
|
||
- **URL**: `GET /api/task-assignment/available-workers`
|
||
- **描述**: 获取所有角色为 `GRID_WORKER` 的用户列表，用于分配任务时的选择器。
|
||
- **权限**: `SUPERVISOR`, `ADMIN`
|
||
- **成功响应** (`200 OK`): 返回 `UserAccount` 对象数组。
|
||
|
||
#### 3.2.3 分配任务
|
||
- **URL**: `POST /api/task-assignment/assign`
|
||
- **描述**: 将一个反馈任务指派给一个网格员。
|
||
- **权限**: `SUPERVISOR`, `ADMIN`
|
||
- **请求体**:
|
||
```json
|
||
{
|
||
"feedbackId": 101,
|
||
"assigneeId": 205
|
||
}
|
||
```
|
||
- **成功响应** (`201 Created`): 返回新创建的 `Assignment` 对象。
|
||
- **失败响应**:
|
||
- `400 Bad Request`: 如果反馈状态不是 `PENDING_ASSIGNMENT` 或用户不是网格员。
|
||
- `404 Not Found`: 如果 `feedbackId` 或 `assigneeId` 不存在。
|
||
|
||
## 4. 状态机详解
|
||
```mermaid
|
||
stateDiagram-v2
|
||
state "AI审核通过" as PendingReview
|
||
state "待分配" as PendingAssignment
|
||
state "已关闭" as ClosedInvalid
|
||
state "已分配" as Assigned
|
||
|
||
PendingReview --> PendingAssignment: 主管批准
|
||
PendingReview --> ClosedInvalid: 主管拒绝
|
||
|
||
PendingAssignment --> Assigned: 主管分配任务
|
||
``` |