648 lines
18 KiB
Markdown
648 lines
18 KiB
Markdown
## 3. ER图
|
||
|
||
```mermaid
|
||
erDiagram
|
||
USER_ACCOUNT {
|
||
BIGINT id PK
|
||
VARCHAR username
|
||
VARCHAR password
|
||
VARCHAR email
|
||
VARCHAR phone
|
||
BIGINT role_id FK
|
||
BIGINT grid_id FK
|
||
}
|
||
|
||
ROLE {
|
||
BIGINT id PK
|
||
VARCHAR name
|
||
}
|
||
|
||
FEEDBACK {
|
||
BIGINT id PK
|
||
TEXT content
|
||
VARCHAR location
|
||
VARCHAR status
|
||
BIGINT submitter_id FK
|
||
}
|
||
|
||
TASK {
|
||
BIGINT id PK
|
||
TEXT description
|
||
VARCHAR status
|
||
BIGINT feedback_id FK
|
||
BIGINT assignee_id FK
|
||
}
|
||
|
||
GRID {
|
||
BIGINT id PK
|
||
INT grid_x
|
||
INT grid_y
|
||
}
|
||
|
||
OPERATION_LOG {
|
||
BIGINT id PK
|
||
VARCHAR operation_type
|
||
TEXT details
|
||
BIGINT operator_id FK
|
||
}
|
||
|
||
ATTACHMENT {
|
||
BIGINT id PK
|
||
BIGINT feedback_id FK
|
||
VARCHAR file_url
|
||
}
|
||
|
||
USER_ACCOUNT ||--o{ ROLE : "has"
|
||
USER_ACCOUNT ||--o{ FEEDBACK : "submits"
|
||
USER_ACCOUNT ||--o{ TASK : "assigned"
|
||
USER_ACCOUNT ||--o{ GRID : "belongs to"
|
||
FEEDBACK ||--o{ TASK : "leads to"
|
||
USER_ACCOUNT ||--o{ OPERATION_LOG : "performs"
|
||
FEEDBACK ||--o{ ATTACHMENT : "has"
|
||
```
|
||
participant Database as 数据库
|
||
|
||
Admin->>+OperationLogController: GET /api/logs (过滤条件)
|
||
OperationLogController->>+OperationLogService: queryOperationLogs(filters)
|
||
OperationLogService->>+OperationLogRepository: findByCriteria(filters)
|
||
OperationLogRepository->>+Database: SELECT * FROM operation_logs WHERE ...
|
||
Database-->>-OperationLogRepository: 返回日志记录
|
||
OperationLogRepository-->>-OperationLogService: 返回日志DTO列表
|
||
OperationLogService-->>-OperationLogController: 返回日志DTO列表
|
||
OperationLogController-->>-Admin: 200 OK (日志列表)
|
||
```
|
||
|
||
### 1.16 管理员创建新用户
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Admin as 管理员
|
||
participant PersonnelController as 人员控制器
|
||
participant PersonnelService as 人员服务
|
||
participant UserAccountRepository as 用户账户仓库
|
||
participant PasswordEncoder as 密码编码器
|
||
participant Database as 数据库
|
||
|
||
Admin->>+PersonnelController: POST /api/personnel/users (用户信息)
|
||
PersonnelController->>+PersonnelService: createUser(request)
|
||
PersonnelService->>+UserAccountRepository: findByUsername(username)
|
||
UserAccountRepository-->>-PersonnelService: (检查用户是否存在)
|
||
PersonnelService->>+PasswordEncoder: encode(password)
|
||
PasswordEncoder-->>-PersonnelService: 返回加密后的密码
|
||
PersonnelService->>+UserAccountRepository: save(user)
|
||
UserAccountRepository->>+Database: INSERT INTO user_accounts
|
||
Database-->>-UserAccountRepository: 返回已保存的用户
|
||
UserAccountRepository-->>-PersonnelService: 返回已保存的用户
|
||
PersonnelService-->>-PersonnelController: 返回创建的用户
|
||
PersonnelController-->>-Admin: 201 CREATED (用户详情)
|
||
```
|
||
|
||
### 1.17 用户获取自己的反馈历史
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant ProfileController as 个人资料控制器
|
||
participant UserFeedbackService as 用户反馈服务
|
||
participant CustomUserDetails as 用户认证详情
|
||
participant Database as 数据库
|
||
|
||
User->>+ProfileController: GET /api/me/feedback
|
||
ProfileController->>+CustomUserDetails: 获取用户ID
|
||
CustomUserDetails-->>-ProfileController: 返回用户ID
|
||
ProfileController->>+UserFeedbackService: getFeedbackHistoryByUserId(userId, pageable)
|
||
UserFeedbackService->>+Database: SELECT * FROM feedback WHERE user_id = ?
|
||
Database-->>-UserFeedbackService: 返回反馈记录
|
||
UserFeedbackService-->>-ProfileController: 返回反馈摘要DTO列表
|
||
ProfileController-->>-User: 200 OK (反馈历史列表)
|
||
```
|
||
|
||
### 1.18 公众提交反馈
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Public as 公众
|
||
participant PublicController as 公共控制器
|
||
participant FeedbackService as 反馈服务
|
||
participant FileStorageService as 文件存储服务
|
||
participant FeedbackRepository as 反馈仓库
|
||
participant Database as 数据库
|
||
|
||
Public->>+PublicController: POST /api/public/feedback (反馈信息和文件)
|
||
PublicController->>+FeedbackService: createPublicFeedback(request, files)
|
||
alt 如果有文件
|
||
FeedbackService->>+FileStorageService: store(file)
|
||
FileStorageService-->>-FeedbackService: 返回文件路径
|
||
end
|
||
FeedbackService->>+FeedbackRepository: save(feedback)
|
||
FeedbackRepository->>+Database: INSERT INTO feedback
|
||
Database-->>-FeedbackRepository: 返回已保存的反馈
|
||
FeedbackRepository-->>-FeedbackService: 返回已保存的反馈
|
||
FeedbackService-->>-PublicController: 返回创建的反馈
|
||
PublicController-->>-Public: 201 CREATED (反馈详情)
|
||
```
|
||
|
||
### 1.19 分配任务给工作人员
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Supervisor as 主管
|
||
participant TaskAssignmentController as 任务分配控制器
|
||
participant TaskAssignmentService as 任务分配服务
|
||
participant AssignmentRepository as 分配仓库
|
||
participant FeedbackRepository as 反馈仓库
|
||
participant Database as 数据库
|
||
|
||
Supervisor->>+TaskAssignmentController: POST /api/tasks/assign (任务ID, 分配对象ID)
|
||
TaskAssignmentController->>+TaskAssignmentService: assignTask(feedbackId, assigneeId, assignerId)
|
||
TaskAssignmentService->>+FeedbackRepository: findById(feedbackId)
|
||
FeedbackRepository-->>-TaskAssignmentService: 返回任务详情
|
||
TaskAssignmentService->>+AssignmentRepository: save(assignment)
|
||
AssignmentRepository->>+Database: INSERT INTO assignments
|
||
Database-->>-AssignmentRepository: 返回已保存的分配
|
||
AssignmentRepository-->>-TaskAssignmentService: 返回已保存的分配
|
||
TaskAssignmentService-->>-TaskAssignmentController: 返回新的分配
|
||
TaskAssignmentController-->>-Supervisor: 200 OK (分配详情)
|
||
```
|
||
|
||
### 1.20 从反馈创建任务
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Supervisor as 主管
|
||
participant TaskManagementController as 任务管理控制器
|
||
participant TaskManagementService as 任务管理服务
|
||
participant FeedbackRepository as 反馈仓库
|
||
participant TaskRepository as 任务仓库
|
||
participant Database as 数据库
|
||
|
||
Supervisor->>+TaskManagementController: POST /api/management/tasks/feedback/{feedbackId}/create-task (任务信息)
|
||
TaskManagementController->>+TaskManagementService: createTaskFromFeedback(feedbackId, request)
|
||
TaskManagementService->>+FeedbackRepository: findById(feedbackId)
|
||
FeedbackRepository-->>-TaskManagementService: 返回反馈详情
|
||
TaskManagementService->>+TaskRepository: save(task)
|
||
TaskRepository->>+Database: INSERT INTO tasks
|
||
Database-->>-TaskRepository: 返回已保存的任务
|
||
TaskRepository-->>-TaskManagementService: 返回已保存的任务
|
||
TaskManagementService-->>-TaskManagementController: 返回创建的任务详情DTO
|
||
TaskManagementController-->>-Supervisor: 201 CREATED (任务详情)
|
||
```
|
||
|
||
## 2. UML类图
|
||
|
||
### 2.1 核心领域模型类图
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class UserAccount {
|
||
-Long id
|
||
-String name
|
||
-String phone
|
||
-String email
|
||
-String password
|
||
-Gender gender
|
||
-Role role
|
||
-UserStatus status
|
||
-Level level
|
||
-String department
|
||
-List~String~ skills
|
||
-LocalDateTime createdAt
|
||
-LocalDateTime updatedAt
|
||
+login() boolean
|
||
+updateProfile() void
|
||
+changePassword() void
|
||
}
|
||
|
||
class Feedback {
|
||
-Long id
|
||
-String eventId
|
||
-String title
|
||
-String description
|
||
-PollutionType pollutionType
|
||
-SeverityLevel severityLevel
|
||
-FeedbackStatus status
|
||
-String location
|
||
-Double latitude
|
||
-Double longitude
|
||
-String cityName
|
||
-String districtName
|
||
-UserAccount submitter
|
||
-LocalDateTime createdAt
|
||
-LocalDateTime updatedAt
|
||
+updateStatus() void
|
||
+assignToTask() Task
|
||
}
|
||
|
||
class Task {
|
||
-Long id
|
||
-Feedback feedback
|
||
-UserAccount assignee
|
||
-UserAccount createdBy
|
||
-TaskStatus status
|
||
-String title
|
||
-String description
|
||
-String location
|
||
-LocalDateTime assignedAt
|
||
-LocalDateTime completedAt
|
||
-LocalDateTime createdAt
|
||
+assign(UserAccount) void
|
||
+complete() void
|
||
+updateProgress() void
|
||
}
|
||
|
||
class Assignment {
|
||
-Long id
|
||
-Task task
|
||
-UserAccount assigner
|
||
-LocalDateTime assignmentTime
|
||
-LocalDateTime deadline
|
||
-AssignmentStatus status
|
||
-String remarks
|
||
+setDeadline() void
|
||
+updateStatus() void
|
||
}
|
||
|
||
class Grid {
|
||
-Long id
|
||
-Integer gridX
|
||
-Integer gridY
|
||
-String cityName
|
||
-String districtName
|
||
-String description
|
||
-Boolean isObstacle
|
||
+getCoordinates() Point
|
||
+isAccessible() boolean
|
||
}
|
||
|
||
class Attachment {
|
||
-Long id
|
||
-String fileName
|
||
-String filePath
|
||
-String fileType
|
||
-Long fileSize
|
||
-LocalDateTime uploadedAt
|
||
}
|
||
|
||
class TaskHistory {
|
||
-Long id
|
||
-Task task
|
||
-UserAccount updatedBy
|
||
-TaskStatus oldStatus
|
||
-TaskStatus newStatus
|
||
-String remarks
|
||
-LocalDateTime updatedAt
|
||
}
|
||
|
||
%% 枚举类
|
||
class Role {
|
||
<<enumeration>>
|
||
PUBLIC_SUPERVISOR
|
||
SUPERVISOR
|
||
GRID_WORKER
|
||
ADMIN
|
||
DECISION_MAKER
|
||
}
|
||
|
||
class FeedbackStatus {
|
||
<<enumeration>>
|
||
PENDING_REVIEW
|
||
AI_REVIEWING
|
||
AI_PROCESSING
|
||
PENDING_ASSIGNMENT
|
||
ASSIGNED
|
||
CONFIRMED
|
||
RESOLVED
|
||
REJECTED
|
||
}
|
||
|
||
class TaskStatus {
|
||
<<enumeration>>
|
||
PENDING_ASSIGNMENT
|
||
ASSIGNED
|
||
IN_PROGRESS
|
||
SUBMITTED
|
||
COMPLETED
|
||
CANCELLED
|
||
}
|
||
|
||
class PollutionType {
|
||
<<enumeration>>
|
||
AIR
|
||
WATER
|
||
SOIL
|
||
NOISE
|
||
WASTE
|
||
OTHER
|
||
}
|
||
|
||
class SeverityLevel {
|
||
<<enumeration>>
|
||
LOW
|
||
MEDIUM
|
||
HIGH
|
||
CRITICAL
|
||
}
|
||
|
||
%% 关系
|
||
UserAccount "1" -- "0..*" Feedback : submits
|
||
UserAccount "1" -- "0..*" Task : assigned_to
|
||
UserAccount "1" -- "0..*" Task : created_by
|
||
UserAccount "1" -- "0..*" Assignment : assigns
|
||
Feedback "1" -- "1" Task : generates
|
||
Task "1" -- "1" Assignment : has
|
||
Task "1" -- "0..*" TaskHistory : logs
|
||
Feedback "1" -- "0..*" Attachment : has
|
||
UserAccount -- Role
|
||
Feedback -- FeedbackStatus
|
||
Feedback -- PollutionType : categorized_as
|
||
Feedback -- SeverityLevel : rated_as
|
||
Task -- TaskStatus"}]}}}
|
||
```
|
||
|
||
### 2.2 控制器层类图
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class AuthController {
|
||
-AuthService authService
|
||
-VerificationCodeService verificationCodeService
|
||
+signUp(SignUpRequest) ResponseEntity
|
||
+signIn(LoginRequest) ResponseEntity
|
||
+logout() ResponseEntity
|
||
+sendVerificationCode(String) ResponseEntity
|
||
+requestPasswordReset(String) ResponseEntity
|
||
+resetPassword(PasswordResetRequest) ResponseEntity
|
||
}
|
||
|
||
class FeedbackController {
|
||
-FeedbackService feedbackService
|
||
+submitFeedback(FeedbackSubmissionRequest, MultipartFile[]) ResponseEntity
|
||
+submitFeedbackJson(FeedbackSubmissionRequest) ResponseEntity
|
||
+submitPublicFeedback(PublicFeedbackRequest, MultipartFile[]) ResponseEntity
|
||
+getAllFeedback(filters, Pageable) ResponseEntity
|
||
+getFeedbackById(Long) ResponseEntity
|
||
+getFeedbackStats(filters) ResponseEntity
|
||
+processFeedback(Long, ProcessFeedbackRequest) ResponseEntity
|
||
}
|
||
|
||
class UserController {
|
||
-UserService userService
|
||
+getCurrentUser() ResponseEntity
|
||
+updateProfile(UserProfileUpdateRequest) ResponseEntity
|
||
+getAllUsers(Pageable) ResponseEntity
|
||
+getUserById(Long) ResponseEntity
|
||
+updateUserRole(Long, Role) ResponseEntity
|
||
+deactivateUser(Long) ResponseEntity
|
||
}
|
||
|
||
%% 服务层接口
|
||
class AuthService {
|
||
<<interface>>
|
||
+registerUser(SignUpRequest) void
|
||
+signIn(LoginRequest) JwtAuthenticationResponse
|
||
+logout() void
|
||
+requestPasswordReset(String) void
|
||
+resetPassword(String, String) void
|
||
}
|
||
|
||
class FeedbackService {
|
||
<<interface>>
|
||
+submitFeedback(FeedbackSubmissionRequest, MultipartFile[]) Feedback
|
||
+getAllFeedback(filters, Pageable) Page~Feedback~
|
||
+getFeedbackById(Long) Feedback
|
||
+processFeedback(Long, ProcessFeedbackRequest) Feedback
|
||
+getFeedbackStats(filters) FeedbackStatsResponse
|
||
}
|
||
|
||
%% 关系
|
||
AuthController --> AuthService : uses
|
||
FeedbackController --> FeedbackService : uses
|
||
UserController --> UserService : uses
|
||
```
|
||
|
||
### 2.3 服务层实现类图
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class AuthServiceImpl {
|
||
-UserRepository userRepository
|
||
-PasswordEncoder passwordEncoder
|
||
-JwtService jwtService
|
||
-VerificationCodeService verificationCodeService
|
||
+registerUser(SignUpRequest) void
|
||
+signIn(LoginRequest) JwtAuthenticationResponse
|
||
+logout() void
|
||
+requestPasswordReset(String) void
|
||
+resetPassword(String, String) void
|
||
-validateUser(UserAccount) void
|
||
-generateJwtToken(UserAccount) String
|
||
}
|
||
|
||
class FeedbackServiceImpl {
|
||
-FeedbackRepository feedbackRepository
|
||
-UserRepository userRepository
|
||
-ApplicationEventPublisher eventPublisher
|
||
-FileStorageService fileStorageService
|
||
+submitFeedback(FeedbackSubmissionRequest, MultipartFile[]) Feedback
|
||
+getAllFeedback(filters, Pageable) Page~Feedback~
|
||
+getFeedbackById(Long) Feedback
|
||
+processFeedback(Long, ProcessFeedbackRequest) Feedback
|
||
-generateEventId() String
|
||
-validateFeedbackData(FeedbackSubmissionRequest) void
|
||
}
|
||
|
||
class TaskServiceImpl {
|
||
-TaskRepository taskRepository
|
||
-UserRepository userRepository
|
||
-AssignmentRepository assignmentRepository
|
||
+createTask(TaskCreationRequest) Task
|
||
+assignTask(Long, Long) Assignment
|
||
+updateTaskStatus(Long, TaskStatus) Task
|
||
+getTasksByAssignee(Long, Pageable) Page~Task~
|
||
-validateTaskAssignment(Task, UserAccount) void
|
||
}
|
||
|
||
%% 接口实现关系
|
||
AuthServiceImpl ..|> AuthService : implements
|
||
FeedbackServiceImpl ..|> FeedbackService : implements
|
||
TaskServiceImpl ..|> TaskService : implements
|
||
```
|
||
|
||
## 3. 数据库ER图
|
||
|
||
```mermaid
|
||
erDiagram
|
||
USER_ACCOUNT {
|
||
bigint id PK
|
||
varchar name
|
||
varchar phone UK
|
||
varchar email UK
|
||
varchar password
|
||
enum gender
|
||
enum role
|
||
enum status
|
||
enum level
|
||
varchar department
|
||
text skills
|
||
datetime created_at
|
||
datetime updated_at
|
||
}
|
||
|
||
FEEDBACK {
|
||
bigint id PK
|
||
varchar event_id UK
|
||
varchar title
|
||
text description
|
||
enum pollution_type
|
||
enum severity_level
|
||
enum status
|
||
varchar location
|
||
decimal latitude
|
||
decimal longitude
|
||
varchar city_name
|
||
varchar district_name
|
||
bigint submitter_id FK
|
||
datetime created_at
|
||
datetime updated_at
|
||
}
|
||
|
||
TASK {
|
||
bigint id PK
|
||
bigint feedback_id FK
|
||
bigint assignee_id FK
|
||
bigint created_by FK
|
||
enum status
|
||
varchar title
|
||
text description
|
||
varchar location
|
||
decimal latitude
|
||
decimal longitude
|
||
datetime assigned_at
|
||
datetime completed_at
|
||
datetime created_at
|
||
datetime updated_at
|
||
}
|
||
|
||
ASSIGNMENT {
|
||
bigint id PK
|
||
bigint task_id FK
|
||
bigint assigner_id FK
|
||
datetime assignment_time
|
||
datetime deadline
|
||
enum status
|
||
text remarks
|
||
datetime created_at
|
||
datetime updated_at
|
||
}
|
||
|
||
GRID {
|
||
bigint id PK
|
||
int gridx
|
||
int gridy
|
||
varchar city_name
|
||
varchar district_name
|
||
text description
|
||
boolean is_obstacle
|
||
}
|
||
|
||
ATTACHMENT {
|
||
bigint id PK
|
||
bigint feedback_id FK
|
||
varchar file_name
|
||
varchar file_path
|
||
varchar file_type
|
||
bigint file_size
|
||
datetime uploaded_at
|
||
}
|
||
|
||
OPERATION_LOG {
|
||
bigint id PK
|
||
bigint user_id FK
|
||
varchar operation_type
|
||
varchar target_type
|
||
bigint target_id
|
||
text description
|
||
varchar ip_address
|
||
datetime created_at
|
||
}
|
||
|
||
VERIFICATION_CODE {
|
||
bigint id PK
|
||
varchar email
|
||
varchar code
|
||
enum type
|
||
datetime expires_at
|
||
boolean used
|
||
datetime created_at
|
||
}
|
||
|
||
TASK_HISTORY {
|
||
bigint id PK
|
||
bigint task_id FK
|
||
bigint updated_by_id FK
|
||
enum old_status
|
||
enum new_status
|
||
text remarks
|
||
datetime updated_at
|
||
}
|
||
|
||
%% 关系定义
|
||
USER_ACCOUNT ||--o{ FEEDBACK : submits
|
||
USER_ACCOUNT ||--o{ TASK : assigned_to
|
||
USER_ACCOUNT ||--o{ TASK : created_by
|
||
USER_ACCOUNT ||--o{ ASSIGNMENT : assigns
|
||
USER_ACCOUNT ||--o{ OPERATION_LOG : performs
|
||
|
||
FEEDBACK ||--|| TASK : generates
|
||
FEEDBACK ||--o{ ATTACHMENT : has
|
||
|
||
TASK ||--|| ASSIGNMENT : has
|
||
TASK ||--o{ TASK_HISTORY : logs
|
||
|
||
VERIFICATION_CODE }o--|| USER_ACCOUNT : sent_to
|
||
USER_ACCOUNT ||--o{ TASK_HISTORY : updates
|
||
```
|
||
|
||
## 4. 系统架构说明
|
||
|
||
### 4.1 分层架构
|
||
|
||
- **控制器层(Controller)**: 处理HTTP请求，参数验证，响应格式化
|
||
- **服务层(Service)**: 业务逻辑处理，事务管理
|
||
- **仓库层(Repository)**: 数据访问，数据库操作
|
||
- **模型层(Model)**: 实体定义，数据结构
|
||
|
||
### 4.2 核心业务流程
|
||
|
||
1. **用户认证**: JWT令牌生成和验证
|
||
2. **反馈管理**: 环境问题反馈的提交、审核、处理
|
||
3. **任务分配**: 基于反馈创建任务并分配给网格工作人员
|
||
4. **状态跟踪**: 反馈和任务状态的生命周期管理
|
||
|
||
### 4.3 安全机制
|
||
|
||
- 基于角色的访问控制(RBAC)
|
||
- JWT令牌认证
|
||
- 密码加密存储
|
||
- 操作日志记录
|
||
|
||
### 4.4 数据完整性
|
||
|
||
- 外键约束确保数据一致性
|
||
- 唯一约束防止重复数据
|
||
- 枚举类型确保状态值有效性
|
||
- 时间戳记录数据变更历史
|
||
|
||
## 5. 技术栈
|
||
|
||
- **框架**: Spring Boot 3.x
|
||
- **数据库**: MySQL/PostgreSQL
|
||
- **ORM**: Spring Data JPA + Hibernate
|
||
- **安全**: Spring Security + JWT
|
||
- **文档**: Swagger/OpenAPI 3
|
||
- **构建工具**: Maven
|
||
- **Java版本**: JDK 17+
|
||
|
||
---
|
||
|
||
*本文档基于EMS后端项目代码分析生成，包含完整的系统设计图表，可用于系统理解、开发指导和文档维护。* |