# 东软环保公众监督系统 - 总体设计文档

## 1. 项目背景与目标

### 1.1 项目背景
随着公众环保意识的增强和环境问题的日益复杂化，传统单一的环境监督模式已难以满足现代社会的需求。为提升环境治理的效率、透明度和公众参与度，我们提出构建一个创新的、多端协同的环保监督平台——"东软环保公众监督系统"。

### 1.2 需求背景
本项目的核心需求源于对现有环保监督流程的优化渴望。当前流程存在信息传递链条长、问题响应慢、数据孤岛效应明显、公众参与感不强等痛点。系统旨在通过整合公众、一线网格员、系统管理者和宏观决策者的力量，打通从问题发现、数据上报、任务分配、现场核实到数据分析和决策支持的全流程闭环。

### 1.3 项目目标
- **提升监督效率**：通过AI预审和智能化任务分配，缩短问题响应时间。
- **强化公众参与**：提供便捷、透明的反馈渠道，激励公众成为环保监督的"眼睛"。
- **实现数据驱动**：将零散的反馈数据转化为结构化的、可供分析决策的宝贵资产。
- **构建管理闭环**：打造一个覆盖"公众-执行-管理-决策"四位一体的协同工作平台。

## 2. 功能总体描述
系统整体上由四个功能明确、相互独立的客户端构成，共同协作完成环保监督任务。

- **NEPS端 (公众监督员端)**: 系统的公众入口，允许用户注册、提交污染反馈、追踪反馈处理进度，并查看个人统计数据。
- **NEPG端 (AQI检测网格员端)**: 一线执行人员的操作平台，用于接收任务、在简化的网格地图上进行路径指引、提交现场勘查的AQI数据报告。
- **NEPM端 (系统管理端)**: 系统的"大脑"，供**主管(Supervisor)**审核反馈、通过手动或智能模式分配任务；同时供**系统管理员(Admin)**管理系统用户、角色及权限。
- **NEPV端 (可视化大屏端)**: 决策支持中心，以数据可视化的方式向决策者展示区域环境态势、污染热力图、治理成效等宏观指标，并提供AI生成的年度报告。

## 3. 技术架构选型

为保证系统的稳定性、可扩展性和开发效率，我们选择以下主流且成熟的技术栈：

### 3.1 开发语言
- **后端**: Java 21 (充分利用其新特性，如虚拟线程、Record类等)
- **前端**: TypeScript (为JavaScript提供类型安全，提升代码质量)

### 3.2 开发框架
- **后端**: Spring Boot 3.x
    - **核心优势**: 自动化配置、强大的社区生态、内嵌Web服务器，能快速构建稳定、高效的RESTful API。
    - **关键组件**:
        - `Spring Web`: 构建Web应用和API。
        - `Spring Data JPA`: 简化数据库持久化操作。
        - `Spring Security`: 提供强大而灵活的认证和授权功能，保障系统安全。
        - `Spring Validation`: 进行数据校验。
- **前端**: Vue 3.x
    - **核心优势**: 采用组合式API (Composition API)，逻辑组织更清晰；基于Vite的构建工具，开发体验极佳；响应式系统性能优越。
    - **关键组件**:
        - `Vue Router`: 管理前端路由。
        - `Pinia`: 进行应用的状态管理。
        - `Axios`: 用于与后端API进行HTTP通信。
        - `Element Plus / Ant Design Vue`: 作为基础UI组件库，快速构建美观的界面。

### 3.3 数据库
- **数据库**: MySQL 8.x
    - **核心优势**: 作为全球最受欢迎的开源关系型数据库，MySQL具有性能稳定、社区支持广泛、与Java及Spring Boot生态完美集成的优点。其成熟的事务处理和数据一致性保障能力，完全满足本项目对核心业务数据的存储需求。

### 3.4 关键第三方服务
- **邮箱服务**: 调用163邮箱的SMTP API，实现注册、忘记密码等场景的动态验证码发送。
- **AI大模型服务**: 调用火山引擎的`deepseek-v3-250324`模型API，实现对用户反馈的自动审核与关键信息提取。 

## 4. 系统架构设计

### 4.1 总体架构图

系统采用微服务思想指导下的单体架构，前后端分离，四端统一调用后端API。这种设计在项目初期能保证快速迭代，同时为未来向微服务演进预留了空间。

```mermaid
graph TD
    subgraph 用户端
        A[NEPS 公众监督员端<br>(Vue3/H5)]
        B[NEPG 网格员端<br>(Vue3/H5)]
        C[NEPM 系统管理端<br>(Vue3/Web)]
        D[NEPV 可视化大屏端<br>(Vue3/Web)]
    end

    subgraph "后端服务 (Spring Boot)"
        E(API网关<br>Spring Cloud Gateway)
        F[用户认证服务<br>Spring Security]
        G[反馈管理模块]
        H[任务管理模块]
        I[智能分配模块<br>A*算法]
        J[数据可视化模块]
        K[文件存储模块]
    end

    subgraph "数据与服务"
        L[MySQL 8.x<br>主数据库]
        M[火山引擎<br>AI大模型]
        N[163邮箱<br>SMTP服务]
    end

    A -->|HTTPS/REST API| E
    B -->|HTTPS/REST API| E
    C -->|HTTPS/REST API| E
    D -->|HTTPS/REST API| E

    E --> F
    E --> G
    E --> H
    E --> I
    E --> J
    E --> K

    F --> L
    G --> L
    H --> L
    I --> L
    J --> L
    K --> L

    G -->|异步调用| M
    F -->|SMTP| N

```

### 4.2 核心数据流（问题处理流程）

1.  **提交**: 公众监督员通过NEPS端提交环境问题反馈，数据进入后端`反馈管理模块`，初始状态为`AI审核中`。
2.  **审核**: `反馈管理模块`异步调用`火山引擎AI服务`进行内容审核与信息提取。审核通过后，状态更新为`待处理`。
3.  **分配**: 主管在NEPM端查看`待处理`的反馈。`任务管理模块`调用`智能分配模块`的A*算法，推荐最优网格员。主管确认后，生成任务并分配。
4.  **处理**: 网格员在NEPG端接收任务，前往现场处理，并提交包含AQI数据的报告。
5.  **审核与闭环**: 主管在NEPM端审核任务报告。审核通过则任务完成，状态更新为`已完成`；不通过则打回给网格员。
6.  **可视化**: 所有处理完成的数据，由`数据可视化模块`进行聚合与分析，最终在NEPV大屏端展示。

## 5. 非功能性需求设计

### 5.1 性能需求
- **核心API响应时间**: 95%的核心API请求（如登录、任务查询）应在500ms内响应。
- **AI处理时间**: AI审核与信息提取的异步处理过程应在30秒内完成。
- **并发用户数**: 系统应支持至少500个并发用户在线，核心功能稳定运行。
- **大屏刷新率**: NEPV端数据应支持分钟级刷新。

### 5.2 安全性需求
- **认证与授权**: 所有API均需通过Spring Security进行认证和授权检查，防止未授权访问。
- **数据传输**: 全站强制使用HTTPS，确保数据在传输过程中的加密。
- **数据存储**: 用户密码、API密钥等敏感信息必须加密存储。
- **防SQL注入**: 采用JPA和参数化查询，从根本上防止SQL注入攻击。
- **防XSS攻击**: 前端对用户输入进行严格过滤和转义，防止跨站脚本攻击。

### 5.3 可扩展性需求
- **模块化设计**: 后端业务逻辑严格按照模块划分，降低耦合度，便于未来将单个模块拆分为微服务。
- **无状态服务**: 后端核心业务服务设计为无状态，便于水平扩展和负载均衡。
- **消息队列**: （未来规划）引入RabbitMQ或Kafka，实现服务间的异步解耦，提升系统的削峰填谷和弹性能力。

### 5.4 可维护性需求
- **统一编码规范**: 全项目遵循统一的Java和TypeScript编码规范。
- **日志记录**: 对关键业务流程和异常情况进行详细的结构化日志记录，便于问题排查。
- **API文档**: 使用Swagger/OpenAPI自动生成并维护最新的API文档。
- **模块化前端**: 前端代码按四端和功能模块组织，提高代码的可读性和复用性。