### 2.2 类和对象的设计

本节定义了系统核心业务对象的静态结构，即类图。这些类图展示了系统中的主要实体、它们的属性和方法，以及它们之间的关系。

#### 2.2.1 `UserAccount` 类图

`UserAccount`类是系统中用户账户的核心模型，包含用户的基本信息、认证信息和角色信息。

```mermaid
classDiagram
    class UserAccount {
        -Long id
        -String name
        -String phone
        -String email
        -String password
        -Gender gender
        -UserRole role
        -UserStatus status
        -Integer gridX
        -Integer gridY
        -String region
        -String level
        -List~String~ skills
        -Boolean enabled
        -Double currentLatitude
        -Double currentLongitude
        -Integer failedLoginAttempts
        -LocalDateTime lockoutEndTime
        -LocalDateTime createdAt
        -LocalDateTime updatedAt
        +getId() Long
        +getName() String
        +getPhone() String
        +getEmail() String
        +getPassword() String
        +getRole() UserRole
        +getStatus() UserStatus
        +isEnabled() Boolean
        +setPassword(String) void
        +updateProfile(UserUpdateRequest) void
        +isAccountNonLocked() Boolean
    }
    
    class UserRole {
        <<enumeration>>
        ADMIN
        SUPERVISOR
        GRID_WORKER
        DECISION_MAKER
        PUBLIC_USER
    }
    
    class UserStatus {
        <<enumeration>>
        ACTIVE
        INACTIVE
        SUSPENDED
    }
    
    class Gender {
        <<enumeration>>
        MALE
        FEMALE
        OTHER
    }
    
    UserAccount --> UserRole
    UserAccount --> UserStatus
    UserAccount --> Gender
```

#### 2.2.2 `Feedback` 类图

`Feedback`类表示用户提交的环境问题反馈，是系统的核心业务对象之一。

```mermaid
classDiagram
    class Feedback {
        -Long id
        -String eventId
        -String title
        -String description
        -PollutionType pollutionType
        -SeverityLevel severityLevel
        -FeedbackStatus status
        -String textAddress
        -Integer gridX
        -Integer gridY
        -Double latitude
        -Double longitude
        -UserAccount submitter
        -LocalDateTime createdAt
        -LocalDateTime updatedAt
        -List~Attachment~ attachments
        -Task relatedTask
        +getId() Long
        +getEventId() String
        +getTitle() String
        +getDescription() String
        +getPollutionType() PollutionType
        +getSeverityLevel() SeverityLevel
        +getStatus() FeedbackStatus
        +updateStatus(FeedbackStatus) void
        +addAttachment(Attachment) void
    }
    
    class PollutionType {
        <<enumeration>>
        AIR
        WATER
        SOIL
        NOISE
        LIGHT
        OTHER
    }
    
    class SeverityLevel {
        <<enumeration>>
        LOW
        MEDIUM
        HIGH
        CRITICAL
    }
    
    class FeedbackStatus {
        <<enumeration>>
        SUBMITTED
        AI_REVIEWED
        PENDING_REVIEW
        APPROVED
        REJECTED
        PROCESSED
        CLOSED
    }
    
    class Attachment {
        -Long id
        -String fileName
        -String filePath
        -String fileType
        -Long fileSize
        -LocalDateTime uploadedAt
        +getId() Long
        +getFileName() String
        +getFilePath() String
    }
    
    Feedback --> PollutionType
    Feedback --> SeverityLevel
    Feedback --> FeedbackStatus
    Feedback --> UserAccount : submitter
    Feedback "1" --> "*" Attachment
    Feedback "1" --> "0..1" Task
```

#### 2.2.3 `Task` 类图

`Task`类表示网格员需要执行的工作任务，通常由反馈生成。

```mermaid
classDiagram
    class Task {
        -Long id
        -Feedback feedback
        -UserAccount assignee
        -UserAccount createdBy
        -TaskStatus status
        -LocalDateTime assignedAt
        -LocalDateTime completedAt
        -LocalDateTime createdAt
        -LocalDateTime updatedAt
        -String title
        -String description
        -PollutionType pollutionType
        -SeverityLevel severityLevel
        -String textAddress
        -Integer gridX
        -Integer gridY
        -Double latitude
        -Double longitude
        -List~TaskHistory~ history
        -Assignment assignment
        -List~TaskSubmission~ submissions
        +getId() Long
        +getStatus() TaskStatus
        +getAssignee() UserAccount
        +updateStatus(TaskStatus) void
        +assign(UserAccount) void
        +addSubmission(TaskSubmission) void
    }
    
    class TaskStatus {
        <<enumeration>>
        CREATED
        ASSIGNED
        ACCEPTED
        IN_PROGRESS
        SUBMITTED
        APPROVED
        REJECTED
        COMPLETED
    }
    
    class TaskHistory {
        -Long id
        -Task task
        -UserAccount actor
        -TaskStatus oldStatus
        -TaskStatus newStatus
        -String remarks
        -LocalDateTime timestamp
        +getId() Long
        +getTask() Task
        +getOldStatus() TaskStatus
        +getNewStatus() TaskStatus
    }
    
    class TaskSubmission {
        -Long id
        -Task task
        -UserAccount submitter
        -String description
        -LocalDateTime submittedAt
        -List~Attachment~ attachments
        +getId() Long
        +getTask() Task
        +getSubmitter() UserAccount
        +addAttachment(Attachment) void
    }
    
    Task --> TaskStatus
    Task --> UserAccount : assignee
    Task --> UserAccount : createdBy
    Task "1" --> "*" TaskHistory
    Task "1" --> "0..1" Assignment
    Task "1" --> "*" TaskSubmission
    Task "0..1" --> "1" Feedback
    TaskHistory --> Task
    TaskHistory --> UserAccount : actor
    TaskSubmission --> Task
    TaskSubmission --> UserAccount : submitter
    TaskSubmission "1" --> "*" Attachment
```

#### 2.2.4 `Grid` 和 `Assignment` 类图

`Grid`类表示地理空间的网格单元，`Assignment`类表示任务分配记录。

```mermaid
classDiagram
    class Grid {
        -Long id
        -Integer gridX
        -Integer gridY
        -String cityName
        -String districtName
        -String description
        -Boolean isObstacle
        +getId() Long
        +getGridX() Integer
        +getGridY() Integer
        +isObstacle() Boolean
    }
    
    class Assignment {
        -Long id
        -Task task
        -UserAccount assigner
        -LocalDateTime assignmentTime
        -LocalDateTime deadline
        -AssignmentStatus status
        -String remarks
        +getId() Long
        +getTask() Task
        +getAssigner() UserAccount
        +getStatus() AssignmentStatus
        +updateStatus(AssignmentStatus) void
    }
    
    class AssignmentStatus {
        <<enumeration>>
        PENDING
        ACCEPTED
        REJECTED
        COMPLETED
    }
    
    Assignment --> Task
    Assignment --> UserAccount : assigner
    Assignment --> AssignmentStatus
```

### 2.3 动态模型设计

本节描述了系统在运行时，对象之间的交互行为。通过时序图和状态图，展示了系统的动态行为和状态转换。

#### 2.3.1 核心时序图

时序图展示了系统中对象之间的交互序列，清晰地表达了业务流程的执行顺序和对象间的消息传递。

**用户登录认证时序图**
```mermaid
sequenceDiagram
    participant User as 用户
    participant AuthController as 认证控制器
    participant AuthService as 认证服务
    participant JwtUtil as JWT工具

    User->>AuthController: POST /api/auth/login (email, password)
    AuthController->>AuthService: signIn(LoginRequest)
    AuthService->>AuthService: 验证凭证
    alt 验证成功
        AuthService->>JwtUtil: generateToken(user)
        JwtUtil-->>AuthService: 返回JWT令牌
        AuthService-->>AuthController: 返回JwtAuthenticationResponse
        AuthController-->>User: 200 OK (token)
    else 验证失败
        AuthService-->>AuthController: 抛出AuthenticationException
        AuthController-->>User: 401 Unauthorized
    end
```

**反馈提交与处理时序图**
```mermaid
sequenceDiagram
    participant User as 用户
    participant FeedbackController as 反馈控制器
    participant FeedbackService as 反馈服务
    participant EventPublisher as 事件发布器
    participant FeedbackAiReviewService as AI审核服务
    participant TaskService as 任务服务

    User->>FeedbackController: POST /api/feedback/submit
    FeedbackController->>FeedbackService: submitFeedback(request, files)
    FeedbackService->>FeedbackService: 生成事件ID
    FeedbackService->>FeedbackService: 保存反馈和附件
    FeedbackService->>EventPublisher: publishEvent(FeedbackSubmittedEvent)
    FeedbackService-->>FeedbackController: 返回反馈信息
    FeedbackController-->>User: 201 Created

    EventPublisher-->>FeedbackAiReviewService: 异步触发AI审核
    FeedbackAiReviewService->>FeedbackAiReviewService: 分析反馈内容
    FeedbackAiReviewService->>FeedbackService: updateFeedbackStatus(AI_REVIEWED)
    
    Note over User,TaskService: 主管审核流程
    
    alt 主管批准反馈
        FeedbackService->>TaskService: createTaskFromFeedback(feedback)
        TaskService->>TaskService: 创建任务
        TaskService-->>FeedbackService: 返回创建的任务
        FeedbackService->>FeedbackService: updateFeedbackStatus(PROCESSED)
    else 主管拒绝反馈
        FeedbackService->>FeedbackService: updateFeedbackStatus(REJECTED)
    end
```

**主管分配任务时序图**
```mermaid
sequenceDiagram
    participant Supervisor as 主管
    participant TaskMgmtController as 任务管理控制器
    participant TaskService as 任务服务
    participant AssignmentService as 分配服务
    participant NotificationService as 通知服务
    participant GridWorker as 网格员

    Supervisor->>TaskMgmtController: POST /tasks/{taskId}/assign (workerId)
    TaskMgmtController->>TaskService: assignTask(taskId, workerId)
    TaskService->>TaskService: 验证任务状态
    TaskService->>AssignmentService: createAssignment(task, worker)
    AssignmentService->>AssignmentService: 创建分配记录
    AssignmentService-->>TaskService: 返回Assignment
    TaskService->>TaskService: 更新任务状态为ASSIGNED
    TaskService->>NotificationService: notifyWorker(workerId, taskId)
    NotificationService->>NotificationService: 创建通知
    TaskService-->>TaskMgmtController: 分配成功
    TaskMgmtController-->>Supervisor: 200 OK
    
    NotificationService-->>GridWorker: 发送任务通知
```

**网格员处理任务时序图**
```mermaid
sequenceDiagram
    participant GridWorker as 网格员
    participant WorkerTaskController as 网格员任务控制器
    participant TaskService as 任务服务
    participant PathfindingService as 寻路服务
    participant Supervisor as 主管

    GridWorker->>WorkerTaskController: POST /api/worker/tasks/{taskId}/accept
    WorkerTaskController->>TaskService: acceptTask(taskId, workerId)
    TaskService->>TaskService: 更新任务状态为ACCEPTED
    TaskService-->>WorkerTaskController: 返回更新后的任务
    WorkerTaskController-->>GridWorker: 200 OK
    
    GridWorker->>WorkerTaskController: GET /api/pathfinding/find?start=x,y&end=a,b
    WorkerTaskController->>PathfindingService: findPath(start, end)
    PathfindingService->>PathfindingService: 执行A*算法
    PathfindingService-->>WorkerTaskController: 返回路径点列表
    WorkerTaskController-->>GridWorker: 200 OK (路径数据)
    
    GridWorker->>WorkerTaskController: POST /api/worker/tasks/{taskId}/submit
    WorkerTaskController->>TaskService: submitTaskCompletion(taskId, workerId, request, files)
    TaskService->>TaskService: 验证并更新任务状态为SUBMITTED
    TaskService->>TaskService: 保存处理结果和附件
    TaskService-->>WorkerTaskController: 返回更新后的任务
    WorkerTaskController-->>GridWorker: 200 OK
    
    Note over GridWorker,Supervisor: 主管审核流程
    
    alt 主管批准任务完成
        TaskService->>TaskService: 更新任务状态为COMPLETED
    else 主管拒绝任务完成
        TaskService->>TaskService: 更新任务状态为REJECTED
        TaskService->>NotificationService: 通知网格员重新处理
    end
```

#### 2.3.2 核心状态图

状态图展示了系统中关键对象的状态变化和转换条件，帮助理解对象的生命周期。

**反馈状态机 (Feedback Status)**
```mermaid
stateDiagram-v2
    [*] --> SUBMITTED: 用户提交反馈
    SUBMITTED --> AI_REVIEWED: AI自动审核
    AI_REVIEWED --> PENDING_REVIEW: 进入人工审核队列
    PENDING_REVIEW --> APPROVED: 主管批准
    PENDING_REVIEW --> REJECTED: 主管拒绝
    APPROVED --> PROCESSED: 创建关联任务
    PROCESSED --> CLOSED: 任务完成
    REJECTED --> [*]
    CLOSED --> [*]
```

**任务状态机 (Task Status)**
```mermaid
stateDiagram-v2
    [*] --> CREATED: 创建任务
    CREATED --> ASSIGNED: 分配给网格员
    ASSIGNED --> ACCEPTED: 网格员接受
    ASSIGNED --> CREATED: 网格员拒绝
    ACCEPTED --> IN_PROGRESS: 开始处理
    IN_PROGRESS --> SUBMITTED: 提交处理结果
    SUBMITTED --> APPROVED: 主管批准
    SUBMITTED --> REJECTED: 主管拒绝
    REJECTED --> IN_PROGRESS: 重新处理
    APPROVED --> COMPLETED: 完成归档
    COMPLETED --> [*]
```

**用户状态机 (User Status)**
```mermaid
stateDiagram-v2
    [*] --> ACTIVE: 创建账户
    ACTIVE --> SUSPENDED: 管理员暂停
    SUSPENDED --> ACTIVE: 管理员重新激活
    ACTIVE --> INACTIVE: 长期未使用
    INACTIVE --> ACTIVE: 用户登录
    INACTIVE --> [*]: 账户删除
    SUSPENDED --> [*]: 账户删除
```