# 系统设计文档

本文档旨在详细阐述环境监督系统（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** 进行异步处理，具备响应式编程能力，以提升高并发场景下的性能。其清晰的分层和模块化设计也为未来向微服务架构演进奠定了良好基础。

```plantuml
@startuml 后端分层架构图
package "EMS后端架构" {
  [前端应用] --> [Controller层]
  [Controller层] --> [Service层]
  [Service层] --> [Repository层]
  [Repository层] --> [JSON文件存储]
  
  note right of [Controller层]
    负责接收HTTP请求
    参数验证
    权限检查
  end note
  
  note right of [Service层]
    业务逻辑核心
    事务管理
    事件发布
  end note
  
  note right of [Repository层]
    数据访问
    查询构建
    持久化逻辑
  end note
}
@enduml
```

#### 1.1.3 前端架构

前端应用是一个基于 **Vue 3** 的单页面应用（SPA），使用 **Vite** 作为构建工具。选择Vue 3是因为其优秀的性能、丰富的生态系统和渐进式的学习曲线。
- **UI组件库**: **Element Plus**，提供了一套高质量、符合设计规范的UI组件，加速了界面的开发。
- **状态管理**: **Pinia**，作为Vue 3官方推荐的状态管理库，它提供了极简的API和强大的类型推断支持，能有效管理复杂的应用状态。
- **路由管理**: **Vue Router**，负责管理前端页面的跳转和路由。

### 1.2 功能模块划分

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

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

```plantuml
@startuml 功能模块图
!define RECTANGLE class

RECTANGLE "认证与授权模块" as auth #LightBlue
RECTANGLE "用户与人员管理模块" as user #LightGreen
RECTANGLE "反馈管理模块" as feedback #LightYellow
RECTANGLE "任务管理模块" as task #LightPink
RECTANGLE "网格与地图模块" as grid #LightCyan
RECTANGLE "决策支持模块" as decision #LightGray
RECTANGLE "个人中心模块" as profile #LightSalmon

auth -- user : 提供身份信息
feedback -- task : 生成任务
task -- grid : 使用地理信息
user -- task : 分配任务
task -- decision : 提供数据
feedback -- decision : 提供数据
user -- profile : 个人信息
@enduml
```