1

2025-10-25 19:18:43 +08:00
parent 4ce487588a
commit 02a830145e
3971 changed files with 1549956 additions and 2 deletions
--- a/Report/ER图.md
+++ b/Report/ER图.md
@@ -0,0 +1,648 @@
+## 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后端项目代码分析生成，包含完整的系统设计图表，可用于系统理解、开发指导和文档维护。*