14 KiB
14 KiB
2.2 类和对象的设计
本节定义了系统核心业务对象的静态结构，即类图。这些类图展示了系统中的主要实体、它们的属性和方法，以及它们之间的关系。
2.2.1 UserAccount 类图
UserAccount类是系统中用户账户的核心模型，包含用户的基本信息、认证信息和角色信息。
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类表示用户提交的环境问题反馈，是系统的核心业务对象之一。
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类表示网格员需要执行的工作任务，通常由反馈生成。
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类表示任务分配记录。
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 核心时序图
时序图展示了系统中对象之间的交互序列，清晰地表达了业务流程的执行顺序和对象间的消息传递。
用户登录认证时序图
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
反馈提交与处理时序图
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
主管分配任务时序图
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: 发送任务通知
网格员处理任务时序图
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)
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)
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)
stateDiagram-v2
[*] --> ACTIVE: 创建账户
ACTIVE --> SUSPENDED: 管理员暂停
SUSPENDED --> ACTIVE: 管理员重新激活
ACTIVE --> INACTIVE: 长期未使用
INACTIVE --> ACTIVE: 用户登录
INACTIVE --> [*]: 账户删除
SUSPENDED --> [*]: 账户删除