Environment-Monitoring-System/Design/主管审核与任务分配功能设计.md

主管审核与任务分配功能 - 设计文档

1. 功能描述

本功能模块是NEPM（后台管理端）的核心组成部分，专为主管 (SUPERVISOR)和管理员 (ADMIN)角色设计。它弥合了AI自动审核与人工任务分配之间的鸿沟，确保了只有经过人工确认的有效反馈才能进入网格员的处理流程。

主要职责包括：

• 审核: 对AI初审通过的反馈 (PENDING_REVIEW) 进行人工复核。
• 决策: 决定该反馈是应该继续流转 (PENDING_ASSIGNMENT) 还是直接关闭 (CLOSED_INVALID)。
• 分配: 将审核通过的有效反馈手动指派给特定的网格员 (GRID_WORKER)。

2. 业务流程

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 对象数组。

  [
    {
      "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
• 请求体:

  {
    "feedbackId": 101,
    "assigneeId": 205
  }
  

• 成功响应 (201 Created): 返回新创建的 Assignment 对象。
• 失败响应:
  • 400 Bad Request: 如果反馈状态不是 PENDING_ASSIGNMENT 或用户不是网格员。
  • 404 Not Found: 如果 feedbackId 或 assigneeId 不存在。

4. 状态机详解

stateDiagram-v2
    state "AI审核通过" as PendingReview
    state "待分配" as PendingAssignment
    state "已关闭" as ClosedInvalid
    state "已分配" as Assigned

    PendingReview --> PendingAssignment: 主管批准
    PendingReview --> ClosedInvalid: 主管拒绝
    
    PendingAssignment --> Assigned: 主管分配任务