Environment-Monitoring-System/Report/系统设计_v2.md

系统设计文档

本文档旨在详细阐述环境监督系统（EMS）的系统架构、功能模块和实现细节，为开发、测试和维护提供指导。

1. 总体设计

总体设计旨在从宏观上描述系统的架构、设计原则和核心组成部分，为后续的详细设计奠定基础。

1.1 系统架构设计

1.1.1 架构选型与原则

本系统采用业界成熟的 前后端分离 架构。该架构将用户界面（前端）与业务逻辑处理（后端）彻底分离，二者通过定义良好的 RESTful API 进行通信。这种模式的优势在于：

• 并行开发: 前后端团队可以并行开发、测试和部署，只需遵守统一的API约定，从而显著提升开发效率。
• 技术栈灵活性: 前后端可以独立选择最适合自身场景的技术栈，便于未来对任一端进行技术升级或重构。
• 关注点分离: 前端专注于用户体验和界面呈现，后端专注于业务逻辑、数据处理和系统安全，使得系统各部分职责更清晰，更易于维护。

在架构设计中，我们遵循了以下核心原则：

• 高内聚，低耦合: 将相关功能组织在独立的模块中，并最小化模块间的依赖。
• 可扩展性: 架构设计应能方便地横向扩展（增加更多服务器实例）和纵向扩展（增加新功能模块）。
• 安全性: 从设计之初就考虑认证、授权、数据加密和输入验证等安全问题。
• 可维护性: 采用清晰的代码分层、统一的编码规范和完善的文档，降低长期维护成本。

1.1.2 后端架构

后端服务基于 Spring Boot 3 和 Java 17 构建，这是一个现代化、高性能的组合。其内部采用了经典的三层分层架构模式：

• 表现层 (Controller Layer): 负责接收前端的HTTP请求，使用 @RestController 定义RESTful API。此层负责解析HTTP请求、验证输入参数（使用JSR-303注解），并调用业务逻辑层处理请求，但不包含任何业务逻辑。
• 业务逻辑层 (Service Layer): 系统的核心，使用 @Service 注解。它封装了所有的业务规则、流程控制和复杂计算。它通过调用数据访问层来操作数据，并通过事件发布等机制与其他服务进行解耦交互。
• 数据访问层 (Repository/Persistence Layer): 负责与数据存储进行交互。本项目独创性地采用了一套基于JSON文件的持久化方案。通过自定义的JsonStorageService和一系列Repository类，模拟了类似JPA的接口，实现了对users.json, tasks.json等核心数据文件的增删改查（CRUD）操作。选择JSON文件存储简化了项目的部署和配置，特别适合快速迭代和中小型应用场景。

此架构同时利用了 Spring WebFlux 进行异步处理，具备响应式编程能力，以提升高并发场景下的性能。其清晰的分层和模块化设计也为未来向微服务架构演进奠定了良好基础。

技术选型:

• 核心框架: Spring Boot 3
• 开发语言: Java 17
• 身份认证: Spring Security + JWT (JSON Web Tokens)
• 数据持久化: 自定义JSON文件存储
• 异步处理: Spring Async & Events, Spring WebFlux
• API文档: SpringDoc (OpenAPI 3 / Swagger)

1.1.3 前端架构

前端应用是一个基于 Vue 3 的单页面应用（SPA），使用 Vite 作为构建工具。选择Vue 3是因为其优秀的性能、丰富的生态系统和渐进式的学习曲线。

• UI组件库: Element Plus，提供了一套高质量、符合设计规范的UI组件，加速了界面的开发。
• 状态管理: Pinia，作为Vue 3官方推荐的状态管理库，它提供了极简的API和强大的类型推断支持，能有效管理复杂的应用状态。
• 路由管理: Vue Router，负责管理前端页面的跳转和路由。

1.2 功能模块划分

系统在功能上被划分为一系列高内聚的模块，每个模块负责一块具体的业务领域。这种划分方式便于团队分工和独立开发。

核心模块	主要职责	关键功能点
认证与授权模块	管理所有用户的身份认证和访问权限	- 用户注册/登录/登出 - JWT令牌生成与验证 - 密码重置 - 基于角色的访问控制(RBAC)
用户与人员管理模块	维护系统中的所有用户账户及其信息	- 用户信息的增、删、改、查 - 用户角色分配与变更 - 用户状态管理（激活/禁用）
反馈管理模块	处理来自外部和内部的环境问题反馈	- 接收公众/认证用户的反馈 - 集成AI进行内容预审核 - 人工审核与处理 - 反馈状态跟踪与统计
任务管理模块	对具体工作任务进行全生命周期管理	- 从反馈创建任务 - 任务分配给网格员 - 任务状态（分配、执行、完成）跟踪 - 任务审核与结果归档
网格与地图模块	对地理空间进行网格化管理，并提供路径支持	- 地理网格的定义与划分 - 网格员与网格的关联 - A*寻路算法服务，优化任务路径
决策支持模块	为管理层提供数据洞察和可视化报告	- 核心业务指标（KPI）统计 - AQI、任务完成率等数据的可视化 - 生成反馈热力图
个人中心模块	为登录用户提供个性化的信息管理和查询功能	- 查看/修改个人资料 - 查询个人提交历史 - 查看个人操作日志

2. 详细设计

2.1 数据持久化设计 (JSON文件)

系统不使用传统数据库，所有数据均以JSON文件的形式存储在服务器的文件系统中。每个核心模型对应一个JSON文件。这种设计简化了部署，但也对数据一致性和并发控制提出了更高的要求。

2.1.1 users.json - 用户账户数据

存储所有系统用户的信息，包括登录凭证、角色和个人资料。

字段名	JSON数据类型	约束/说明	描述
id	Number	唯一标识, 自增	用户的唯一标识符
name	String	非空	用户姓名
phone	String	非空, 唯一	手机号码，可用于登录
email	String	非空, 唯一	电子邮箱，可用于登录
password	String	非空, 长度>=8	加密后的用户密码
gender	String	(ENUM)	性别 (MALE, FEMALE, OTHER)
role	String	(ENUM)	用户角色 (ADMIN, SUPERVISOR, GRID_WORKER等)
status	String	非空, (ENUM)	账户状态 (ACTIVE, INACTIVE, SUSPENDED)
grid_x	Number		关联的网格X坐标 (主要用于网格员)
grid_y	Number		关联的网格Y坐标 (主要用于网格员)
region	String		所属区域或地区
level	String	(ENUM)	用户等级 (JUNIOR, SENIOR, EXPERT)
skills	Array		技能列表 (JSON数组格式的字符串)
enabled	Boolean	非空, 默认 true	账户是否启用
current_latitude	Number		当前纬度坐标 (用于实时定位)
current_longitude	Number		当前经度坐标 (用于实时定位)
failed_login_attempts	Number	默认 0	连续失败登录次数
lockout_end_time	String		账户锁定截止时间
created_at	String	非空	记录创建时间
updated_at	String	非空	记录最后更新时间

2.1.2 feedback.json - 环境问题反馈数据

存储所有由用户（包括公众）提交的环境问题反馈。

字段名	JSON数据类型	约束/说明	描述
id	Number	唯一标识, 自增	反馈的唯一标识符
event_id	String	非空, 唯一	人类可读的事件ID
title	String	非空	反馈标题
description	String		问题详细描述
pollution_type	String	非空, (ENUM)	污染类型 (AIR, WATER, SOIL, NOISE)
severity_level	String	非空, (ENUM)	严重程度 (LOW, MEDIUM, HIGH, CRITICAL)
status	String	非空, (ENUM)	反馈状态 (PENDING_REVIEW, PROCESSED等)
text_address	String		文字描述的地址
grid_x	Number		事发地网格X坐标
grid_y	Number		事发地网格Y坐标
latitude	Number		事发地纬度
longitude	Number		事发地经度
submitter_id	Number	外键 (FK) -> users.id (可为空)	提交者ID (公众提交时可为空)
created_at	String	非空	记录创建时间
updated_at	String	非空	记录最后更新时间

2.1.3 tasks.json - 任务数据

存储由反馈转化而来或手动创建的具体处理任务。

字段名	JSON数据类型	约束/说明	描述
id	Number	唯一标识, 自增	任务的唯一标识符
feedback_id	Number	外键 (FK) -> feedback.id (可为空)	关联的原始反馈ID
assignee_id	Number	外键 (FK) -> users.id (可为空)	任务执行人（网格员）ID
created_by	Number	外键 (FK) -> users.id	任务创建人（主管）ID
status	String	非空, (ENUM)	任务状态 (PENDING, IN_PROGRESS, COMPLETED)
title	String		任务标题
description	String		任务详细描述
pollution_type	String	(ENUM)	污染类型
severity_level	String	(ENUM)	严重程度
text_address	String		任务地点文字描述
grid_x	Number		任务地点网格X坐标
grid_y	Number		任务地点网格Y坐标
latitude	Number		任务地点纬度
longitude	Number		任务地点经度
assigned_at	String		任务分配时间
completed_at	String		任务完成时间
created_at	String	非空	记录创建时间
updated_at	String	非空	记录最后更新时间
deadline	String		任务截止日期

2.1.4 grids.json - 业务网格数据

存储业务逻辑上的地理网格信息。

字段名	JSON数据类型	约束/说明	描述
id	Number	唯一标识, 自增	网格的唯一标识符
gridx	Number		网格X坐标
gridy	Number		网格Y坐标
city_name	String		所属城市
district_name	String		所属区县
description	String		网格描述信息
is_obstacle	Boolean	默认 false	是否为障碍物（如禁区）

2.1.5 assignments.json - 任务分配记录数据

记录任务分配的详细信息，连接任务、分配者和执行者。

字段名	JSON数据类型	约束/说明	描述
id	Number	唯一标识, 自增	分配记录的唯一标识符
task_id	Number	非空, 外键 (FK) -> tasks.id	关联的任务ID
assigner_id	Number	非空, 外键 (FK) -> users.id	分配者（主管）ID
status	String	非空, (ENUM)	分配状态
remarks	String		分配备注
assignment_time	String	非空	分配时间
deadline	String		任务截止日期

---

(其他辅助表如 attachment.json, operation_log.json, map_grid.json 等的设计将遵循类似结构)

2.2 核心业务流程

本章节将结合时序图和业务规则，详细描述系统的主要业务工作流。

2.2.1 反馈处理与任务生成流程

这是系统的核心业务闭环，涵盖了从问题发现到任务完成的全过程。其状态流转严格遵循预设的规则。

反馈处理流程:

1. 提交反馈: 公众用户或认证用户通过API提交环境问题反馈。
2. 进入AI审核: 新提交的反馈初始状态为 PENDING，系统发布 FeedbackSubmittedForAiReviewEvent 事件，触发AI服务进行异步审核。反馈状态变为 AI_REVIEWING。
3. 主管人工审核: AI审核后，无论结果如何，反馈都将进入人工审核阶段。主管（Supervisor）在系统中查看待处理的反馈。
4. 决策与流转:
   • 批准 (APPROVED): 如果反馈有效，主管将其批准。系统据此发布 TaskReadyForAssignmentEvent 事件，表明可以基于此反馈创建任务。原反馈的状态更新为 TASK_CREATED。
   • 拒绝 (REJECTED): 如果反馈无效或重复，主管可以拒绝该反馈，并填写原因。

任务处理流程:

1. 创建任务: 基于已批准的反馈，系统创建一条新任务，初始状态为 CREATED。
2. 分配任务: 主管根据网格区域、网格员负载等规则，将任务指派给特定的网格员（Grid Worker）。任务状态更新为 ASSIGNED。
3. 执行任务: 网格员接收到任务通知，接受任务后，状态变为 IN_PROGRESS。网格员前往现场处理。
4. 提交结果: 网格员完成任务后，在系统中提交工作报告。任务状态更新为 SUBMITTED（待审核）。
5. 审核任务: 主管审核已完成的任务。
   • 批准 (APPROVED): 任务审核通过，流程结束。
   • 拒绝 (REJECTED): 任务不符合要求，可将任务打回给网格员重新处理。

2.2.2 用户认证与授权流程

1. 用户登录: 用户使用邮箱/手机号和密码请求登录。
2. 凭证验证: 系统验证用户信息和密码的正确性。
3. 令牌生成: 验证通过后，系统使用JWT生成一个有时效性的 access_token。
4. 访问授权: 用户在后续的请求中，需在请求头携带此 token。后端通过一个安全过滤器（Filter）来解析和验证 token，确认用户的身份和权限，从而决定是否能访问受保护的API资源。

2.2.3 密码重置流程

1. 请求重置: 用户在登录页面点击"忘记密码"，输入注册时使用的邮箱地址。
2. 发送验证码: 系统向该邮箱发送一封包含随机验证码的邮件。
3. 验证与重置: 用户在指定时间内输入收到的验证码和新密码。系统校验验证码的正确性后，更新用户在 users.json 文件中的密码。

2.2.4 主要业务规则

• 权限控制规则:

  1. ADMIN: 拥有全系统所有权限，是系统的最高管理员。
  2. SUPERVISOR: 负责管理网格员、审核反馈和任务，是区域的管理者。
  3. DECISION_MAKER: 拥有数据查看和分析权限，通常是决策层用户。
  4. GRID_WORKER: 负责执行被分配的任务，是系统的主要执行者。
  5. PUBLIC: 只能提交反馈，是系统的外部参与者。

• 任务分配规则:

  1. 优先基于网格区域进行自动分配。
  2. 分配时会综合考虑网格员的当前工作负载，避免分配不均。
  3. 标记为"紧急"的反馈所生成的任务，拥有更高的分配优先级。
  4. 主管可以对已分配的任务进行手动干预和重新分配。

• 反馈处理规则:

  1. 所有反馈提交后，首先由AI服务进行预审核和内容分析。
  2. 系统会检测可能重复的反馈，并提示审核人员进行合并处理。
  3. 紧急反馈（如严重等级为CRITICAL）会被优先展示给审核人员。

2.3 API接口设计

本章节详细定义了系统各模块的API接口，包括认证、任务管理、数据上报等。

2.3.1 认证接口 (/api/auth)

处理用户注册、登录、登出和密码管理等功能。

序号	接口路径	HTTP方法	功能描述	请求参数 (Body/Query)	成功响应 (Body)
1	/api/auth/signup	POST	用户注册	SignUpRequest (name, phone, email, password, role, etc.)	201 CREATED
2	/api/auth/login	POST	用户登录	LoginRequest (email/phone, password)	JwtAuthenticationResponse (token)
3	/api/auth/logout	POST	用户登出	无	200 OK
4	/api/auth/send-verification-code	POST	发送注册验证码	email (Query Param)	200 OK
5	/api/auth/send-password-reset-code	POST	发送密码重置验证码	email (Query Param)	200 OK
6	/api/auth/reset-password-with-code	POST	使用验证码重置密码	PasswordResetWithCodeDto (email, code, newPassword)	200 OK

2.3.2 公共接口 (/api/public)

提供给外部系统或公众使用的无需认证的接口。

序号	接口路径	HTTP方法	功能描述	请求参数 (Body/Form-Data)	成功响应 (Body)
1	/api/public/feedback	POST	提交公众反馈(带文件)	feedback: PublicFeedbackRequest (JSON), files: MultipartFile[]	201 CREATED (返回 Feedback 对象)

2.3.3 反馈管理接口 (/api/feedback)

认证用户（如主管、管理员）对环境问题反馈进行查询、统计和处理。

序号	接口路径	HTTP方法	功能描述	权限	请求参数 (Body/Query)	成功响应 (Body)
1	/api/feedback/submit	POST	认证用户提交反馈(带文件)	isAuthenticated()	feedback: FeedbackSubmissionRequest (JSON), files: MultipartFile[]	201 CREATED (返回 Feedback 对象)
2	/api/feedback	GET	获取所有反馈(分页+多条件过滤)	isAuthenticated()	status, pollutionType, severityLevel, cityName, districtName, startDate, endDate, keyword, pageable	Page<FeedbackResponseDTO>
3	/api/feedback/{id}	GET	根据ID获取反馈详情	ADMIN, SUPERVISOR, DECISION_MAKER	id (Path Var)	FeedbackResponseDTO
4	/api/feedback/stats	GET	获取反馈统计数据	isAuthenticated()	无	FeedbackStatsResponse
5	/api/feedback/{id}/process	POST	处理反馈(如审核通过)	ADMIN, SUPERVISOR	id (Path Var), ProcessFeedbackRequest (Body)	FeedbackResponseDTO

2.3.4 任务管理接口 (/api/management/tasks)

主管和管理员用于任务的全生命周期管理，包括创建、分配、查询和审批。

序号	接口路径	HTTP方法	功能描述	权限	请求参数 (Body/Query)	成功响应 (Body)
1	/api/management/tasks	GET	获取任务列表(分页+多条件过滤)	ADMIN, SUPERVISOR, DECISION_MAKER	status, assigneeId, severity, pollutionType, startDate, endDate, pageable	List<TaskSummaryDTO>
2	/api/management/tasks/{taskId}	GET	获取任务详情	SUPERVISOR	taskId (Path Var)	TaskDetailDTO
3	/api/management/tasks	POST	手动创建新任务	SUPERVISOR	TaskCreationRequest (Body)	201 CREATED (返回 TaskDetailDTO)
4	/api/management/tasks/{taskId}/assign	POST	分配任务给网格员	SUPERVISOR	taskId (Path Var), TaskAssignmentRequest (Body)	TaskSummaryDTO
5	/api/management/tasks/{taskId}/review	POST	审核任务	SUPERVISOR	taskId (Path Var), TaskApprovalRequest (Body)	TaskDetailDTO
6	/api/management/tasks/{taskId}/cancel	POST	取消任务	SUPERVISOR	taskId (Path Var)	TaskDetailDTO
7	/api/management/tasks/feedback	GET	获取待处理的反馈列表	SUPERVISOR, ADMIN	无	List<Feedback>
8	/api/management/tasks/feedback/{feedbackId}/create-task	POST	从反馈创建任务	SUPERVISOR	feedbackId (Path Var), TaskFromFeedbackRequest (Body)	201 CREATED (返回 TaskDetailDTO)
9	/api/management/tasks/{taskId}/approve	POST	批准任务(完成)	ADMIN	taskId (Path Var)	TaskDetailDTO
10	/api/management/tasks/{taskId}/reject	POST	拒绝任务(打回)	ADMIN	taskId (Path Var), TaskRejectionRequest (Body)	TaskDetailDTO

2.3.5 网格员任务接口 (/api/worker)

网格员用于查看和处理自己被分配的任务。

序号	接口路径	HTTP方法	功能描述	权限	请求参数 (Body/Query)	成功响应 (Body)
1	/api/worker	GET	获取我被分配的任务列表	GRID_WORKER	status (Query Param), pageable	Page<TaskSummaryDTO>
2	/api/worker/{taskId}	GET	获取任务详情	GRID_WORKER	taskId (Path Var)	TaskDetailDTO
3	/api/worker/{taskId}/accept	POST	接受任务	GRID_WORKER	taskId (Path Var)	TaskSummaryDTO
4	/api/worker/{taskId}/submit	POST	提交任务完成情况(带文件)	GRID_WORKER	taskId (Path Var), comments (Form Part), files (Form Part)	TaskSummaryDTO

2.3.6 人员管理接口 (/api/personnel)

管理员用于管理系统中的所有用户账户。

序号	接口路径	HTTP方法	功能描述	权限	请求参数 (Body/Query)	成功响应 (Body)
1	/api/personnel/users	POST	创建新用户	ADMIN	UserCreationRequest (Body)	201 CREATED (返回 UserAccount 对象)
2	/api/personnel/users	GET	获取用户列表(分页+过滤)	ADMIN, GRID_WORKER	role, name (Query Params), pageable	PageDTO<UserAccount>
3	/api/personnel/users/{userId}	GET	根据ID获取用户详情	ADMIN	userId (Path Var)	UserAccount
4	/api/personnel/users/{userId}	PATCH	更新用户信息(部分更新)	ADMIN	userId (Path Var), UserUpdateRequest (Body)	UserAccount
5	/api/personnel/users/{userId}/role	PUT	更新用户角色	ADMIN	userId (Path Var), UserRoleUpdateRequest (Body)	UserAccount
6	/api/personnel/users/{userId}	DELETE	删除用户	ADMIN	userId (Path Var)	204 NO_CONTENT

2.3.7 网格管理接口 (/api/grids)

管理员用于管理地理网格、分配网格员和查看统计数据。

序号	接口路径	HTTP方法	功能描述	权限	请求参数 (Body/Query)	成功响应 (Body)
1	/api/grids	GET	获取所有网格列表	ADMIN, DECISION_MAKER, GRID_WORKER	无	List<Grid>
2	/api/grids/{id}	PATCH	更新网格信息(如设为障碍物)	ADMIN	id (Path Var), GridUpdateRequest (Body)	Grid
3	/api/grids/coverage	GET	获取网格覆盖率统计	ADMIN	无	List<GridCoverageDTO>
4	/api/grids/{gridId}/assign	POST	分配网格员到指定网格(通过ID)	ADMIN	gridId (Path Var), userId (Body)	200 OK
5	/api/grids/{gridId}/unassign	POST	从网格中移除网格员(通过ID)	ADMIN	gridId (Path Var)	200 OK
6	/api/grids/coordinates/{gridX}/{gridY}/assign	POST	分配网格员到指定网格(通过坐标)	ADMIN, GRID_WORKER	gridX, gridY (Path Vars), userId (Body)	200 OK
7	/api/grids/coordinates/{gridX}/{gridY}/unassign	POST	从网格中移除网格员(通过坐标)	ADMIN, GRID_WORKER	gridX, gridY (Path Vars)	200 OK

2.3.8 仪表盘数据接口 (/api/dashboard)

为前端仪表盘提供各种聚合和统计数据，用于决策支持和系统状态监控。

序号	接口路径	HTTP方法	功能描述	权限	请求参数 (Body/Query)	成功响应 (Body)
1	/api/dashboard/stats	GET	获取仪表盘核心统计数据	DECISION_MAKER, ADMIN	无	DashboardStatsDTO
2	/api/dashboard/reports/aqi-distribution	GET	获取AQI等级分布数据	DECISION_MAKER, ADMIN	无	List<AqiDistributionDTO>
3	/api/dashboard/reports/monthly-exceedance-trend	GET	获取月度超标趋势数据	DECISION_MAKER, ADMIN	无	List<TrendDataPointDTO>
4	/api/dashboard/reports/grid-coverage	GET	获取网格覆盖情况数据	DECISION_MAKER, ADMIN	无	List<GridCoverageDTO>
5	/api/dashboard/map/heatmap	GET	获取反馈热力图数据	DECISION_MAKER, ADMIN	无	List<HeatmapPointDTO>
6	/api/dashboard/reports/pollution-stats	GET	获取污染物统计报告数据	DECISION_MAKER, ADMIN	无	List<PollutionStatsDTO>
7	/api/dashboard/reports/task-completion-stats	GET	获取任务完成情况统计数据	DECISION_MAKER, ADMIN	无	TaskStatsDTO
8	/api/dashboard/map/aqi-heatmap	GET	获取AQI热力图数据	DECISION_MAKER, ADMIN	无	List<AqiHeatmapPointDTO>
9	/api/dashboard/thresholds	GET	获取所有污染物阈值设置	DECISION_MAKER, ADMIN	无	List<PollutantThresholdDTO>
10	/api/dashboard/thresholds/{pollutantName}	GET	获取指定污染物的阈值设置	DECISION_MAKER, ADMIN	pollutantName (Path Var)	PollutantThresholdDTO
11	/api/dashboard/thresholds	POST	保存污染物阈值设置	ADMIN	PollutantThresholdDTO (Body)	PollutantThresholdDTO
12	/api/dashboard/reports/pollutant-monthly-trends	GET	获取各污染物月度趋势数据	DECISION_MAKER, ADMIN	无	Map<String, List<TrendDataPointDTO>>

2.3.9 其他接口

包含文件处理、操作日志、个人资料等辅助功能的接口。

序号	接口路径	HTTP方法	功能描述	权限	请求参数 (Body/Query)	成功响应 (Body)
1	/api/files/{filename}	GET	下载/预览文件(下载)	isAuthenticated()	filename (Path Var)	Resource (文件流)
2	/api/view/{filename}	GET	下载/预览文件(内联预览)	isAuthenticated()	filename (Path Var)	Resource (文件流)
3	/api/logs/my-logs	GET	获取当前用户的操作日志	isAuthenticated()	无	List<OperationLogDTO>
4	/api/logs	GET	获取所有操作日志(可过滤)	ADMIN	operationType, userId, startTime, endTime	List<OperationLogDTO>
5	/api/me/feedback	GET	获取当前用户的反馈历史	isAuthenticated()	pageable	List<UserFeedbackSummaryDTO>
6	/api/supervisor/reviews	GET	获取待审核的反馈列表	SUPERVISOR, ADMIN	无	List<Feedback>
7	/api/supervisor/reviews/{feedbackId}/approve	POST	审核通过反馈	SUPERVISOR, ADMIN	feedbackId (Path Var)	200 OK
8	/api/supervisor/reviews/{feedbackId}/reject	POST	审核拒绝反馈	SUPERVISOR, ADMIN	feedbackId (Path Var), RejectFeedbackRequest (Body)	200 OK
9	/api/map/grid	GET	获取完整地图网格数据	isAuthenticated()	无	List<MapGrid>
10	/api/map/grid	POST	创建/更新单个网格单元	ADMIN	MapGrid (Body)	MapGrid
11	/api/map/initialize	POST	初始化地图网格	ADMIN	width, height (Query)	String (Message)
12	/api/pathfinding/find	POST	A*寻路算法查找路径	isAuthenticated()	PathfindingRequest (Body)	List<Point>
13	/api/tasks/unassigned	GET	获取未分配的任务列表	ADMIN, SUPERVISOR	无	List<Feedback>
14	/api/tasks/grid-workers	GET	获取可用的网格员列表	ADMIN, SUPERVISOR	无	List<UserAccount>
15	/api/tasks/assign	POST	分配任务给网格员	ADMIN, SUPERVISOR	AssignmentRequest (Body)	Assignment

2.3.10 API 设计原则与最佳实践

为保证API的规范性、安全性和易用性，系统在设计和实现中遵循了以下原则：

1. 统一响应格式: 所有API响应都封装在一个标准结构中，包含成功/失败状态、数据负载、消息和时间戳，便于前端统一处理。分页查询则返回包含分页信息（总数、总页数等）的标准化分页对象。
2. 细粒度权限控制: 系统利用Spring Security的 @PreAuthorize 注解在方法级别上实现了细粒度的权限控制，确保即使用户通过了认证，也只能访问其角色被授权的特定资源和操作。
3. 严格的参数验证: 所有接收输入的API端点（特别是写操作）都使用了JSR-303验证注解（如 @Valid, @NotBlank, @Email）对请求体和参数进行严格校验，从入口处保证了数据的合法性和完整性。
4. 清晰的API文档: 通过集成SpringDoc，为所有公共API生成了遵循OpenAPI 3.0规范的交互式文档（Swagger UI），包含了清晰的描述、参数说明和响应示例。
5. 全面的日志记录: 使用 @Slf4j 在关键业务流程、成功操作及异常情况处记录了详细日志，便于系统监控、问题排查和安全审计。

---

2.4 架构特性与外部集成

除了核心的业务功能，系统在架构层面采用了一些现代化的设计来实现高性能和高可扩展性，并集成了一些外部服务来增强功能。

2.4.1 事件驱动架构 (EDA)

系统内部采用轻量级的事件驱动模型（基于Spring Events）来实现关键业务逻辑的解耦。

• 核心事件:

  1. FeedbackSubmittedForAiReviewEvent: 当一个新反馈被提交后发布，用于触发AI服务的异步分析。
  2. TaskReadyForAssignmentEvent: 当一个反馈被批准并可以转化为任务时发布。
  3. AuthenticationSuccessEvent: 用户成功登录时发布，可用于记录日志或更新用户状态。
  4. AuthenticationFailureEvent: 用户登录失败时发布，用于监控恶意尝试。

• 优势:

  • 解耦: 事件的发布者和消费者之间没有直接依赖，易于扩展新功能。
  • 异步化: 许多耗时的操作（如AI分析、邮件发送）可以通过异步监听事件来完成，避免阻塞主线程，提升用户体验。

2.4.2 外部服务集成

• AI服务:

  • 服务商: 火山引擎 (Volcano Engine)
  • 核心功能: 用于反馈内容的智能分析，包括自动提取关键词、评估严重等级和进行初步分类，为人工审核提供决策支持。

• 邮件服务:

  • 服务商: 163 SMTP
  • 核心功能: 用于发送系统通知类邮件，如用户注册、密码重置验证码、任务分配通知等。

2.4.3 性能与缓存

为了提升系统响应速度和处理高并发请求的能力，系统内置了基于内存的缓存机制。

• 缓存技术: Google Guava Cache
• 缓存内容:
  • 用户数据: 缓存频繁访问的用户信息。
  • 配置数据: 如污染物阈值等不经常变动的系统配置。
  • 热点数据: 如热门网格的统计信息。
• 策略: 缓存设置了合理的过期时间和大小限制，以保证数据的一致性和内存的有效利用。