465 lines
14 KiB
Markdown
465 lines
14 KiB
Markdown
### 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 --> [*]: 账户删除
|
|
``` |