# 需求定义文档

## 1. 项目介绍

### 1.1 项目背景

环境监测系统（EMS）是为解决城市环境问题而设计的综合性管理平台。随着城市化进程加速，环境污染问题日益凸显，传统的环境问题上报和处理机制存在流程繁琐、响应缓慢、缺乏透明度等问题。本系统旨在通过数字化手段，构建一个连接公众、管理部门和执行人员的环境监测与治理平台，实现环境问题的快速发现、高效处理和全程监督。

### 1.2 项目目标

1. **建立闭环管理机制**：构建从问题发现、上报、审核、分配、处理到结果反馈的完整闭环流程，确保每个环境问题都能得到妥善解决。
2. **提高处理效率**：通过流程优化和智能算法，缩短环境问题从发现到解决的时间，提高环境治理效率。
3. **增强公众参与**：为公众提供便捷的问题上报渠道，增强公众参与环境治理的积极性和获得感。
4. **辅助决策分析**：通过数据可视化和多维度分析，为管理层提供决策支持，优化资源配置和治理策略。
5. **提升治理透明度**：实现环境问题处理全过程可追踪、可监督，增强政府工作透明度和公信力。

## 2. 系统分析

### 2.1 业务痛点分析

1. **信息孤岛**：环境问题信息分散在不同部门和系统中，缺乏统一管理和共享机制。
2. **流程断裂**：传统环境问题处理流程存在多个环节，各环节之间衔接不畅，容易导致问题处理延误或遗漏。
3. **资源分配不均**：缺乏科学的任务分配机制，导致人力资源利用不均衡，部分区域问题积压严重。
4. **监督机制不足**：公众难以了解问题处理进度和结果，缺乏有效的监督渠道。
5. **数据分析不足**：未能充分利用环境问题数据进行趋势分析和预测，难以支持科学决策。

### 2.2 用户角色分析

环境监测系统涉及五类主要用户角色，每个角色在系统中承担不同的职责：

1. **公众用户**：系统的信息输入端，负责发现和上报环境问题，是系统的主要服务对象。
2. **网格员**：系统的执行端，负责接收任务并前往现场处理环境问题，是系统的核心操作人员。
3. **主管**：系统的管理端，负责审核反馈、分配任务、审核结果，是系统的关键决策者。
4. **管理员**：系统的维护端，负责用户管理、权限设置、系统配置等基础支撑工作。
5. **决策者**：系统的战略端，通过分析系统生成的统计数据和趋势图表，制定环境管理策略和资源分配决策，是系统的最终受益者之一。
### 2.3 用例分析

#### 2.3.1 用例图

```mermaid
graph TD
    %% 定义角色
    PublicUser["公众用户"]
    GridWorker["网格员"]
    Supervisor["主管"]
    Admin["管理员"]
    
    %% 定义用例
    UC1["注册与登录"]
    UC2["提交环境问题反馈"]
    UC3["查看反馈处理进度"]
    UC4["接收任务通知"]
    UC5["执行任务"]
    UC6["提交处理结果"]
    UC7["审核反馈内容"]
    UC8["分配任务"]
    UC9["审核处理结果"]
    UC10["查看统计数据"]
    UC11["管理用户账户"]
    UC12["配置系统参数"]
    
    %% 建立关系
    PublicUser --> UC1
    PublicUser --> UC2
    PublicUser --> UC3
    
    GridWorker --> UC1
    GridWorker --> UC4
    GridWorker --> UC5
    GridWorker --> UC6
    
    Supervisor --> UC1
    Supervisor --> UC7
    Supervisor --> UC8
    Supervisor --> UC9
    Supervisor --> UC10
    
    Admin --> UC1
    Admin --> UC10
    Admin --> UC11
    Admin --> UC12
    
    %% 设置样式
    classDef actor fill:#f9f,stroke:#333,stroke-width:2px
    classDef usecase fill:#ccf,stroke:#33f,stroke-width:1px
    
    class PublicUser,GridWorker,Supervisor,Admin actor
    class UC1,UC2,UC3,UC4,UC5,UC6,UC7,UC8,UC9,UC10,UC11,UC12 usecase
```

#### 2.3.2 活动图：反馈提交与处理流程

```mermaid
stateDiagram-v2
    [*] --> 发现环境问题
    发现环境问题 --> 填写反馈表单
    填写反馈表单 --> 上传图片
    上传图片 --> 标记位置
    标记位置 --> 提交反馈
    提交反馈 --> AI自动审核
    
    state AI自动审核 {
        [*] --> 内容分析
        内容分析 --> 垃圾信息检测
        垃圾信息检测 --> 分类与评级
        分类与评级 --> [*]
    }
    
    AI自动审核 --> 判断AI审核结果
    判断AI审核结果 --> 明显无效: AI拒绝
    判断AI审核结果 --> 需人工确认: 需确认
    
    明显无效 --> 标记为AI_REJECTED
    标记为AI_REJECTED --> 通知提交者
    通知提交者 --> [*]
    
    需人工确认 --> 主管人工审核
    主管人工审核 --> 判断审核结果
    
    判断审核结果 --> 驳回: 不通过
    判断审核结果 --> 通过: 通过
    
    驳回 --> 填写驳回理由
    填写驳回理由 --> 更新状态为REJECTED
    更新状态为REJECTED --> 通知提交者反馈被驳回
    通知提交者反馈被驳回 --> [*]
    
    通过 --> 创建任务
    创建任务 --> 更新反馈状态为PROCESSED
    更新反馈状态为PROCESSED --> 任务分配流程
    任务分配流程 --> [*]
```

#### 2.3.3 活动图：任务分配与执行流程

```mermaid
stateDiagram-v2
    [*] --> 任务创建完成
    任务创建完成 --> 选择分配方式
    
    state 选择分配方式 {
        [*] --> 手动分配
        [*] --> 智能推荐
        
        智能推荐 --> 运行分配算法
        运行分配算法 --> 推荐最佳人选
        推荐最佳人选 --> 确认人选
        
        手动分配 --> 选择特定网格员
        选择特定网格员 --> 确认人选
        
        确认人选 --> [*]
    }
    
    选择分配方式 --> 创建任务分配记录
    创建任务分配记录 --> 更新任务状态为ASSIGNED
    更新任务状态为ASSIGNED --> 通知网格员
    
    通知网格员 --> 网格员接收通知
    网格员接收通知 --> 判断是否接受
    
    判断是否接受 --> 拒绝: 拒绝
    判断是否接受 --> 接受: 接受
    
    拒绝 --> 选择分配方式
    
    接受 --> 更新状态为IN_PROGRESS
    更新状态为IN_PROGRESS --> 获取路径规划
    获取路径规划 --> 前往现场处理
    前往现场处理 --> 记录处理过程
    记录处理过程 --> 上传处理结果
    上传处理结果 --> 提交处理结果
    提交处理结果 --> 更新状态为SUBMITTED
    
    更新状态为SUBMITTED --> 主管审核结果
    主管审核结果 --> 判断结果是否合格
    
    判断结果是否合格 --> 不合格: 不合格
    判断结果是否合格 --> 合格: 合格
    
    不合格 --> 填写原因要求重新处理
    填写原因要求重新处理 --> 获取路径规划
    
    合格 --> 确认任务完成
    确认任务完成 --> 更新任务状态为APPROVED
    更新任务状态为APPROVED --> 更新反馈状态为CLOSED
    更新反馈状态为CLOSED --> 通知反馈提交者
    通知反馈提交者 --> 更新统计数据
    更新统计数据 --> [*]
```

### 2.4 系统可行性分析

#### 2.4.1 技术可行性

1. **前端技术**：采用Vue 3框架构建用户界面，结合Element Plus组件库，可以快速开发出美观、响应式的Web应用，满足不同设备的访问需求。
2. **后端技术**：基于Spring Boot 3框架和Java 17，具备高性能、高并发处理能力，能够满足系统的稳定性和扩展性需求。
3. **地图服务**：可以集成百度地图、高德地图等成熟的地图API，实现地理位置标记、路径规划等功能。
4. **AI技术**：可以利用现有的自然语言处理和图像识别技术，实现对反馈内容的智能分析和审核。
5. **数据存储**：采用JSON文件存储方案，简化部署和维护，适合中小规模系统的快速实现。

#### 2.4.2 经济可行性

1. **开发成本**：采用主流开源框架和技术栈，降低开发成本和技术门槛。
2. **维护成本**：模块化设计和完善的文档，降低后期维护和升级成本。
3. **投资回报**：通过提高环境问题处理效率，减少人力资源浪费，长期来看具有良好的投资回报。
4. **社会效益**：改善城市环境质量，提升居民生活满意度，产生显著的社会效益。

#### 2.4.3 操作可行性

1. **用户接受度**：系统界面设计简洁直观，操作流程符合用户习惯，易于被各类用户接受和使用。
2. **培训需求**：系统操作简单，只需简单培训即可上手，降低推广和应用门槛。
3. **业务适应性**：系统流程设计符合环境问题处理的实际业务需求，能够无缝融入现有工作流程。

#### 2.4.4 法律可行性

1. **数据隐私**：系统设计符合数据保护法规要求，对用户隐私数据进行加密存储和严格权限控制。
2. **知识产权**：系统开发过程中使用的第三方库和组件均为开源或已获得授权，不存在知识产权风险。
3. **合规性**：系统功能和流程设计符合相关法律法规和行业标准，确保合法合规运营。 

## 3. 功能性需求

### 3.1 功能层次方框图

```mermaid
flowchart TD
    %% 用户交互层
    subgraph "用户交互层"
        direction LR
        C["公众服务模块(问题上报)"]
        H["个人中心模块(我的反馈/资料)"]
        D["管理驾驶舱(数据决策)"]
    end

    %% 核心业务层
    subgraph "核心业务层"
        direction LR
        AI["AI分析模块(内容审核)"]
        E["任务管理模块(分配、流转、执行)"]
    end

    %% 应用支撑层
    subgraph "应用支撑层"
        direction LR
        F["网格与地图模块(LBS & 寻路)"]
        I["文件服务模块(附件存取)"]
    end
    
    %% 基础服务层
    subgraph "基础服务层"
        direction LR
        B["用户与认证模块"]
        G["系统管理模块(用户/权限)"]
        J["日志审计模块"]
    end

    %% 定义关系
    C -- "提交反馈" --> AI
    AI -- "分析结果" --> E
    C -- "附件" --> I
    E -- "调用" --> F
    E -- "任务附件" --> I
    E -- "统计数据" --> D
    
    H -- "查询个人数据" --> E
    
    %% 基础服务支撑所有上层模块 (关系隐含)
    G -- "管理" --> B
    
    classDef userLayer fill:#d4f1f9,stroke:#05a8e5;
    classDef coreLayer fill:#ffe6cc,stroke:#f7a128;
    classDef appSupportLayer fill:#d5e8d4,stroke:#82b366;
    classDef baseLayer fill:#e1d5e7,stroke:#9673a6;

    class C,H,D userLayer;
    class AI,E coreLayer;
    class F,I appSupportLayer;
    class B,G,J baseLayer;
```

### 3.2 模块功能概述

| 模块名称 | 功能概述 |
| :--- | :--- |
| **用户与认证模块** | 管理用户身份验证、权限控制和会话管理，确保系统安全性。提供用户注册、登录、密码重置等功能。 |
| **反馈管理模块** | 处理公众提交的环境问题反馈，包括提交、审核、状态追踪和查询统计等功能。 |
| **任务管理模块** | 将审核通过的反馈转化为工作任务，并管理任务的分配、执行和完成全流程。 |
| **网格与地图模块** | 提供地理空间的网格化管理，支持路径规划和地图可视化，辅助任务执行。 |
| **决策支持模块** | 通过数据分析和可视化，为管理层提供决策支持，帮助优化资源配置和治理策略。 |
| **系统管理模块** | 提供系统配置、用户管理、权限设置等基础功能，保障系统正常运行。 |
| **文件服务模块** | 处理系统中的文件上传、存储和访问，支持反馈和任务的附件管理。 |
| **日志审计模块** | 记录系统操作日志，支持安全审计和问题追溯，确保系统运行的可追溯性。 |

## 4. 整体业务流程

下图描述了从公众发现问题、上报、到平台内部流转、处理、并最终反馈结果的完整闭环业务流程。

```mermaid
flowchart TD
    %% 定义样式
    classDef public fill:#d4f1f9,stroke:#05a8e5,color:#333
    classDef platform fill:#ffe6cc,stroke:#f7a128,color:#333
    classDef worker fill:#d5e8d4,stroke:#82b366,color:#333
    classDef supervisor fill:#e1d5e7,stroke:#9673a6,color:#333
    classDef decision fill:#f8cecc,stroke:#b85450,color:#333
    classDef start_end fill:#f5f5f5,stroke:#666666,color:#333,stroke-width:2px
    
    %% 流程开始
    A([开始]) --> B["[公众端] 发现环境问题"]
    B --> C["[公众端] 提交反馈<br>(标题/描述/图片/位置)"]
    
    %% 平台接收与AI处理
    C --> D["[平台] 接收反馈<br>生成唯一事件ID"]
    D --> E{"[平台] AI自动审核<br>分析内容/分类"}
    
    %% AI审核分支
    E -- "明显无效" --> F1["[平台] 标记为AI_REJECTED"]
    F1 --> F2["[平台] 通知提交者"]
    F2 --> Z1([结束])
    
    E -- "需人工确认" --> G["[主管] 查看反馈详情<br>进行人工审核"]
    
    %% 主管审核分支
    G --> H{"[主管] 审核决定"}
    H -- "驳回" --> I1["[主管] 填写驳回理由"]
    I1 --> I2["[平台] 更新状态为REJECTED"]
    I2 --> I3["[平台] 通知提交者"]
    I3 --> Z2([结束])
    
    %% 审核通过，创建任务
    H -- "通过" --> J1["[主管] 确认反馈有效"]
    J1 --> J2["[平台] 自动创建结构化任务"]
    J2 --> J3["[平台] 更新反馈状态为PROCESSED"]
    
    %% 任务分配
    J3 --> K1{"[主管] 选择分配方式"}
    K1 -- "手动分配" --> K2["[主管] 选择特定网格员"]
    K1 -- "智能推荐" --> K3["[平台] 运行分配算法<br>考虑位置/负载/专长"]
    K3 --> K4["[平台] 推荐最佳人选"]
    K4 --> K2
    K2 --> K5["[平台] 创建任务分配记录<br>更新任务状态为ASSIGNED"]
    K5 --> K6["[平台] 通知网格员"]
    
    %% 网格员处理
    K6 --> L1["[网格员] 接收任务通知"]
    L1 --> L2{"[网格员] 接受任务?"}
    L2 -- "拒绝" --> K1
    L2 -- "接受" --> L3["[网格员] 更新任务状态为IN_PROGRESS"]
    L3 --> L4["[网格员] 查看任务详情<br>获取路径规划"]
    L4 --> L5["[网格员] 前往现场处理"]
    L5 --> L6["[网格员] 记录处理过程<br>上传证明材料"]
    L6 --> L7["[网格员] 提交处理结果<br>更新状态为SUBMITTED"]
    
    %% 主管审核结果
    L7 --> M1["[主管] 审核处理结果"]
    M1 --> M2{"[主管] 结果是否合格?"}
    M2 -- "不合格" --> M3["[主管] 填写原因<br>要求重新处理"]
    M3 --> L4
    
    %% 完成流程
    M2 -- "合格" --> N1["[主管] 确认任务完成"]
    N1 --> N2["[平台] 更新任务状态为APPROVED"]
    N2 --> N3["[平台] 更新反馈状态为CLOSED"]
    N3 --> N4["[平台] 通知反馈提交者"]
    N4 --> N5["[平台] 更新统计数据"]
    N5 --> O["[决策层] 查看数据看板<br>分析环境趋势"]
    O --> Z3([结束])
    
    %% 为节点添加类别
    class A,Z1,Z2,Z3 start_end
    class B,C,F2,I3,N4 public
    class D,E,F1,I2,J2,J3,K3,K4,K5,K6,N2,N3,N5 platform
    class G,H,I1,J1,K1,K2,M1,M2,M3,N1 supervisor
    class L1,L2,L3,L4,L5,L6,L7 worker
    class O decision
``` 

## 5. 详细需求描述

### 5.1 用户与认证模块

| 功能名称 | 用户与认证模块 |
| :--- | :--- |
| **优先级** | 高 |
| **业务背景** | 作为系统安全的基础，本模块负责管理所有用户的身份验证和访问控制，确保系统资源只能被授权用户访问，同时提供灵活的角色权限管理。 |
| **功能说明** | 1. **用户认证**：基于JWT (JSON Web Token) 的安全认证机制，支持账号密码登录，提供令牌刷新功能。<br>2. **权限控制**：基于RBAC (基于角色的访问控制) 模型，预设管理员、主管、网格员等角色，每个角色拥有特定的API访问权限。<br>3. **密码管理**：支持安全的密码重置流程，包括邮箱验证码验证，以及定期密码更新提醒。<br>4. **会话管理**：支持单点登录或多设备登录控制，可配置会话超时策略。 |
| **约束条件** | 1. 密码必须符合复杂度要求（至少8位，包含大小写字母、数字和特殊字符）。<br>2. 敏感操作（如修改权限）需要二次验证。<br>3. 密码在数据库中必须使用BCrypt等强哈希算法加密存储。<br>4. 登录失败超过预设次数后，账户应被临时锁定。 |
| **相关查询** | 1. 按用户名、邮箱或手机号查询用户信息。<br>2. 查询特定角色的所有用户列表。<br>3. 查询用户的权限和访问历史。 |
| **其他需求** | 1. 系统应记录所有关键安全事件（登录、权限变更等）的审计日志。<br>2. 支持用户个人资料的维护和更新。 |

**用户认证流程图**：

```mermaid
sequenceDiagram
    participant User as 用户
    participant AuthController as 认证控制器
    participant AuthService as 认证服务
    participant UserRepository as 用户仓库
    participant JwtUtil as JWT工具
    participant Database as JSON持久化存储

    User->>AuthController: POST /api/auth/login
    AuthController->>AuthService: signIn(LoginRequest)
    AuthService->>UserRepository: findByEmailOrPhone()
    UserRepository->>Database: 查询用户信息
    Database-->>UserRepository: 返回用户数据
    UserRepository-->>AuthService: 返回UserAccount
    AuthService->>AuthService: 验证密码
    AuthService->>JwtUtil: 生成JWT令牌
    JwtUtil-->>AuthService: 返回JWT
    AuthService-->>AuthController: JwtAuthenticationResponse
    AuthController-->>User: 返回JWT令牌
```

### 5.2 反馈管理模块

| 功能名称 | 反馈管理模块 |
| :--- | :--- |
| **优先级** | 高 |
| **业务背景** | 作为系统的核心输入端口，本模块负责收集、处理和跟踪所有环境问题反馈，是连接公众与管理部门的桥梁，也是后续任务创建的数据源。 |
| **功能说明** | 1. **反馈提交**：提供结构化的表单接口，支持文字描述、污染类型分类、严重程度评估、地理位置标记和多媒体附件上传。<br>2. **AI内容审核**：集成智能审核服务，对反馈内容进行自动分析，识别垃圾信息、重复提交，并进行初步的分类和紧急程度评估。<br>3. **人工审核工作台**：为主管提供高效的反馈审核界面，支持批量处理、快速预览和详情查看。<br>4. **状态追踪**：完整记录反馈从提交到处理完成的全生命周期状态变更，支持多维度的统计和查询。 |
| **约束条件** | 1. 反馈提交必须包含至少一张图片和准确的地理位置信息。<br>2. AI审核结果仅作为参考，最终决定权在人工审核者手中。<br>3. 对于紧急程度被标记为"高"的反馈，系统应在1小时内完成审核。<br>4. 同一用户在短时间内（如5分钟）不能重复提交内容高度相似的反馈。 |
| **相关查询** | 1. 按状态、时间段、区域、污染类型等多维度查询反馈列表。<br>2. 查看特定反馈的详细信息和处理历史。<br>3. 统计不同类型反馈的数量分布和处理效率。 |
| **其他需求** | 1. 支持反馈的优先级标记和升级处理。<br>2. 对于同一区域短时间内的多个相似反馈，系统应能智能识别并提示可能的重复。<br>3. 支持反馈附件的预览和下载。 |

**反馈提交处理流程图**：

```mermaid
sequenceDiagram
    participant User as 用户
    participant FeedbackController as 反馈控制器
    participant FeedbackService as 反馈服务
    participant FeedbackRepository as 反馈仓库
    participant AIService as AI服务
    participant EventPublisher as 事件发布器
    participant Database as JSON持久化存储

    User->>FeedbackController: POST /api/feedback/submit
    FeedbackController->>FeedbackService: submitFeedback(request, files)
    FeedbackService->>FeedbackService: 生成事件ID
    FeedbackService->>FeedbackRepository: save(feedback)
    FeedbackRepository->>Database: 保存反馈数据
    Database-->>FeedbackRepository: 返回保存结果
    FeedbackRepository-->>FeedbackService: 返回Feedback实体
    FeedbackService->>EventPublisher: 发布反馈创建事件
    EventPublisher->>AIService: 触发AI处理
    AIService->>AIService: 分析反馈内容
    FeedbackService-->>FeedbackController: 返回Feedback
    FeedbackController-->>User: 201 Created
```

### 5.3 任务管理模块

| 功能名称 | 任务管理模块 |
| :--- | :--- |
| **优先级** | 高 |
| **业务背景** | 本模块是系统的核心业务处理单元，负责将审核通过的反馈转化为可执行的工作任务，并对任务的分配、执行和完成进行全流程管理。 |
| **功能说明** | 1. **任务创建**：支持从反馈自动生成任务，也支持主管手动创建临时任务，包含任务描述、位置、截止时间、优先级等信息。<br>2. **智能分配**：基于多因素（网格员位置、当前负载、专业技能、历史表现）的任务分配算法，为每个任务推荐最合适的处理人员。<br>3. **任务执行跟踪**：记录任务的每个状态变更（已分配、已接受、进行中、已提交、已审核），支持网格员实时上报处理进度。<br>4. **结果审核**：主管对网格员提交的处理结果进行审核，可以通过或驳回，并提供反馈意见。<br>5. **任务看板**：直观展示不同状态任务的数量和分布，支持拖拽操作进行状态更新。 |
| **约束条件** | 1. 任务必须关联到一个有效的反馈或由授权主管手动创建。<br>2. 任务分配时必须考虑网格员的工作区域和当前任务负载。<br>3. 高优先级任务应在24小时内分配并开始处理。<br>4. 任务提交时必须包含处理过程描述和至少一张结果照片。<br>5. 已完成的任务不能重新分配或修改。 |
| **相关查询** | 1. 按状态、负责人、时间段、区域等多维度查询任务列表。<br>2. 查看特定任务的详细信息、处理历史和相关反馈。<br>3. 统计不同网格员的任务完成率、平均处理时长等绩效指标。 |
| **其他需求** | 1. 支持任务的紧急程度升级和重新分配。<br>2. 对于长时间未处理的任务，系统应自动发送提醒通知。<br>3. 支持批量导出任务报告，用于绩效评估和工作汇报。 |

**任务分配流程图**：

```mermaid
sequenceDiagram
    participant Supervisor as 主管
    participant TaskController as 任务控制器
    participant TaskService as 任务服务
    participant AssignmentService as 分配服务
    participant UserRepository as 用户仓库
    participant TaskRepository as 任务仓库
    participant GridWorker as 网格工作人员

    Supervisor->>TaskController: POST /api/tasks/assign
    TaskController->>TaskService: assignTask(taskId, workerId)
    TaskService->>UserRepository: findById(workerId)
    UserRepository-->>TaskService: 返回GridWorker
    TaskService->>AssignmentService: createAssignment()
    AssignmentService->>TaskRepository: updateTaskStatus()
    TaskRepository-->>AssignmentService: 更新成功
    AssignmentService-->>TaskService: Assignment创建成功
    TaskService->>TaskService: 发送通知给工作人员
    TaskService-->>TaskController: 分配成功
    TaskController-->>Supervisor: 200 OK
    Note over GridWorker: 接收任务通知
```

### 5.4 网格与地图模块

| 功能名称 | 网格与地图模块 |
| :--- | :--- |
| **优先级** | 中 |
| **业务背景** | 本模块负责对地理空间进行网格化管理，将城市区域划分为可管理的网格单元，并为任务执行提供地理位置支持和路径规划。 |
| **功能说明** | 1. **网格定义与管理**：支持管理员定义和维护城市网格系统，包括网格的坐标、属性（如是否为障碍物）和责任人分配。<br>2. **A*寻路算法服务**：基于网格系统和实时路况，为网格员提供从当前位置到任务地点的最优路径规划，考虑距离、交通状况和障碍物。<br>3. **地图可视化**：在地图上直观展示反馈点、任务分布和网格员位置，支持多种筛选条件和图层切换。<br>4. **区域统计**：基于网格系统，生成环境问题热力图，识别高发区域和问题类型分布。 |
| **约束条件** | 1. 网格系统应支持多级划分，最小网格单元不应大于500米×500米。<br>2. 路径规划应考虑实际道路情况和障碍物，避免不可通行区域。<br>3. 地图数据应定期更新，确保准确性。<br>4. 网格坐标系统必须与地理坐标系统（经纬度）有明确的转换关系。 |
| **相关查询** | 1. 查询特定区域内的网格定义和属性。<br>2. 查询特定网格的历史问题记录和统计数据。<br>3. 获取两点间的最优路径规划。<br>4. 查询特定区域内的网格员分布情况。 |
| **其他需求** | 1. 支持网格责任人的灵活调整和临时替换。<br>2. 地图界面应支持常见的交互操作（缩放、平移、点选）。<br>3. 支持离线地图数据缓存，保证在网络不稳定情况下的基本功能。 |

**路径规划流程图**：

```mermaid
sequenceDiagram
    participant User as 用户
    participant PathfindingController as 寻路控制器
    participant AStarService as A*服务
    participant MapData as 地图数据

    User->>+PathfindingController: POST /api/pathfinding/find (起点, 终点)
    PathfindingController->>+AStarService: findPath(start, end)
    AStarService->>+MapData: getObstacles()
    MapData-->>-AStarService: 返回障碍物信息
    AStarService->>AStarService: 执行A*算法计算路径
    AStarService-->>-PathfindingController: 返回计算出的路径
    PathfindingController-->>-User: 200 OK (路径坐标列表)
```

### 5.5 决策支持模块

| 功能名称 | 决策支持模块 (管理驾驶舱) |
| :--- | :--- |
| **优先级** | 中 |
| **业务背景** | 本模块旨在将系统中沉淀的大量业务数据转化为有价值的决策洞察，帮助管理层了解环境状况、评估治理效果、优化资源配置。 |
| **功能说明** | 1. **核心指标看板**：实时展示关键业务指标，如待处理反馈数、进行中任务数、平均处理时长、按时完成率等。<br>2. **多维度分析**：支持按时间、区域、污染类型、处理人等多个维度对数据进行交叉分析和趋势展示。<br>3. **热力图可视化**：在地图上以热力图形式展示环境问题的分布密度，直观识别高发区域。<br>4. **绩效评估**：对网格员和区域的工作效率、问题解决质量等进行量化评估，生成排名和对比分析。<br>5. **预警机制**：基于历史数据和趋势分析，对可能出现的环境风险提前预警。 |
| **约束条件** | 1. 数据分析应基于实时或准实时的业务数据，确保决策的时效性。<br>2. 图表和报表应支持多种导出格式（PDF、Excel等），便于进一步分析和汇报。<br>3. 敏感数据（如个人绩效）的访问应受到严格权限控制。<br>4. 系统应能处理和分析至少一年的历史数据。 |
| **相关查询** | 1. 按自定义时间范围查询各类统计指标。<br>2. 查询特定区域或网格员的历史表现数据。<br>3. 生成定制化的数据报表和分析图表。<br>4. 查询环境问题的时间分布和地理分布。 |
| **其他需求** | 1. 支持数据看板的个性化配置，满足不同管理者的关注点。<br>2. 提供数据异常检测和提醒功能，及时发现数据波动。<br>3. 支持定期自动生成并发送统计报告。 |

**决策者获取仪表盘数据流程图**：

```mermaid
sequenceDiagram
    participant DecisionMaker as 决策者
    participant DashboardController as 仪表盘控制器
    participant DashboardService as 仪表盘服务
    participant variousRepositories as 各类仓库
    participant Database as JSON持久化存储

    DecisionMaker->>DashboardController: GET /api/dashboard/stats
    DashboardController->>DashboardService: getDashboardStats()
    DashboardService->>variousRepositories: (并行)调用多个仓库方法获取数据
    variousRepositories->>Database: 查询统计数据
    Database-->>variousRepositories: 返回数据
    variousRepositories-->>DashboardService: 返回统计结果
    DashboardService->>DashboardService: 聚合数据为DashboardStatsDTO
    DashboardService-->>DashboardController: 返回DashboardStatsDTO
    DashboardController-->>DecisionMaker: 返回核心统计数据
``` 

### 5.6 决策者角色需求

| 功能名称 | 决策者角色需求 |
| :--- | :--- |
| **优先级** | 中 |
| **业务背景** | 决策者是环境监测系统的战略用户，负责根据系统提供的数据分析结果制定环境管理策略和资源分配决策。他们需要全局视角的数据展示和深度分析功能，以支持科学决策。 |
| **功能说明** | 1. **综合仪表盘**：提供环境状况、处理效率、资源利用等多维度的综合数据视图，支持按时间、区域进行筛选。<br>2. **趋势分析**：展示关键指标的历史变化趋势，支持多指标对比和季节性分析。<br>3. **资源分配建议**：基于历史数据和预测模型，为人力资源调配和预算分配提供决策建议。<br>4. **绩效评估报告**：生成网格员、区域、团队的绩效评估报告，支持多维度比较。<br>5. **预警监控**：实时监控环境问题高发区域和异常情况，支持预警规则配置。 |
| **约束条件** | 1. 决策者界面应简洁明了，突出关键指标和异常情况。<br>2. 复杂分析应提供直观的可视化展示，避免过多的数字和表格。<br>3. 报表生成不应影响系统的整体性能。<br>4. 敏感数据的访问应受到严格的权限控制。 |
| **相关查询** | 1. 按时间段、区域、问题类型等维度查询统计数据。<br>2. 查询资源利用效率和投入产出比。<br>3. 查询环境问题的地理分布和时间分布热点。<br>4. 查询预测模型生成的趋势预测结果。 |
| **其他需求** | 1. 支持报表的导出和分享功能。<br>2. 提供决策建议的解释性说明，增强决策透明度。<br>3. 支持自定义关注指标和提醒阈值。<br>4. 提供移动端访问能力，满足随时随地查看关键数据的需求。 |

**决策者使用流程图**：

```mermaid
sequenceDiagram
    participant DecisionMaker as 决策者
    participant Dashboard as 综合仪表盘
    participant ReportGenerator as 报表生成器
    participant AnalyticsEngine as 分析引擎
    participant Database as 数据存储

    DecisionMaker->>Dashboard: 登录系统
    Dashboard->>AnalyticsEngine: 请求核心指标数据
    AnalyticsEngine->>Database: 查询原始数据
    Database-->>AnalyticsEngine: 返回数据
    AnalyticsEngine->>AnalyticsEngine: 计算指标和趋势
    AnalyticsEngine-->>Dashboard: 返回处理后的数据
    Dashboard-->>DecisionMaker: 展示综合仪表盘
    
    DecisionMaker->>Dashboard: 调整筛选条件(时间/区域)
    Dashboard->>AnalyticsEngine: 请求筛选后的数据
    AnalyticsEngine->>Database: 查询筛选数据
    Database-->>AnalyticsEngine: 返回筛选结果
    AnalyticsEngine-->>Dashboard: 返回处理后的数据
    Dashboard-->>DecisionMaker: 更新仪表盘显示
    
    DecisionMaker->>ReportGenerator: 请求生成绩效报告
    ReportGenerator->>AnalyticsEngine: 获取绩效数据
    AnalyticsEngine->>Database: 查询绩效相关数据
    Database-->>AnalyticsEngine: 返回数据
    AnalyticsEngine-->>ReportGenerator: 提供分析结果
    ReportGenerator-->>DecisionMaker: 生成并下载报告
    
    DecisionMaker->>Dashboard: 查看资源分配建议
    Dashboard->>AnalyticsEngine: 请求优化建议
    AnalyticsEngine->>AnalyticsEngine: 运行资源优化算法
    AnalyticsEngine-->>Dashboard: 返回建议结果
    Dashboard-->>DecisionMaker: 展示资源分配建议
``` 

## 6. 需求规定

### 6.2 技术规格需求

*   **前端技术栈**：
    * 核心框架：Vue.js 3.x
    * 构建工具：Vite
    * UI组件库：Element Plus
    * 状态管理：Pinia
    * 路由管理：Vue Router
    * HTTP客户端：Axios

*   **后端技术栈**：
    * 核心框架：Spring Boot 3.x
    * 编程语言：Java 17
    * 安全框架：Spring Security 6.x
    * API文档：SpringDoc (OpenAPI)
    * 数据验证：Jakarta Bean Validation (Hibernate Validator)
    * 日志系统：SLF4J & Logback

*   **数据存储**：
    * 采用JSON文件存储方案
    * 实现自定义的泛型JSON仓储层
    * 确保数据操作的线程安全性

*   **部署环境**：
    * 支持Docker容器化部署
    * 支持常见的Web服务器（如Nginx、Apache）
    * 最低硬件要求：4核CPU、8GB内存、50GB存储空间

## 7. 数据描述

### 7.1 用户账户 (UserAccount) 数据结构

| 字段名 | 描述 | 数据类型 | 约束条件 | 是否必填 |
| :--- | :--- | :--- | :--- | :--- |
| `id` | 用户唯一标识符 | Long | 主键，自增 | 是 |
| `name` | 用户姓名 | String | 最大长度50 | 是 |
| `phone` | 手机号码 | String | 符合手机号格式 | 是 |
| `email` | 电子邮箱 | String | 符合邮箱格式 | 是 |
| `password` | 密码（加密存储） | String | 最小长度8，包含字母、数字和特殊字符 | 是 |
| `gender` | 性别 | Enum | MALE, FEMALE, OTHER | 否 |
| `role` | 用户角色 | Enum | ADMIN, SUPERVISOR, GRID_WORKER, PUBLIC_USER | 是 |
| `status` | 账户状态 | Enum | ACTIVE, INACTIVE, LOCKED | 是 |
| `gridX` | 网格X坐标（仅网格员） | Integer | 非负整数 | 否 |
| `gridY` | 网格Y坐标（仅网格员） | Integer | 非负整数 | 否 |
| `region` | 地理区域或区县 | String | 最大长度255 | 否 |
| `level` | 熟练度级别（仅网格员） | Enum | JUNIOR, INTERMEDIATE, SENIOR, EXPERT | 否 |
| `skills` | 技能列表（JSON格式） | List<String> | - | 否 |
| `createdAt` | 账户创建时间 | DateTime | ISO 8601格式 | 是 |
| `updatedAt` | 账户更新时间 | DateTime | ISO 8601格式 | 是 |
| `enabled` | 账户是否启用 | Boolean | true/false | 是 |
| `currentLatitude` | 当前纬度（仅网格员） | Double | 有效范围 | 否 |
| `currentLongitude` | 当前经度（仅网格员） | Double | 有效范围 | 否 |
| `failedLoginAttempts` | 连续登录失败次数 | Integer | 非负整数 | 是 |
| `lockoutEndTime` | 锁定结束时间 | DateTime | ISO 8601格式 | 否 |

### 7.2 反馈 (Feedback) 数据结构

| 字段名 | 描述 | 数据类型 | 约束条件 | 是否必填 |
| :--- | :--- | :--- | :--- | :--- |
| `id` | 反馈唯一标识符 | Long | 主键，自增 | 是 |
| `eventId` | 事件ID（业务编号） | String | UUID格式 | 是 |
| `title` | 反馈标题 | String | 最大长度100 | 是 |
| `description` | 问题详细描述 | String | 最大长度1000 | 是 |
| `pollutionType` | 污染类型 | Enum | AIR, WATER, SOIL, NOISE, OTHER | 是 |
| `severityLevel` | 严重程度 | Enum | LOW, MEDIUM, HIGH, CRITICAL | 是 |
| `status` | 反馈状态 | Enum | PENDING_REVIEW, AI_REJECTED, PROCESSED, CLOSED | 是 |
| `textAddress` | 文本地址描述 | String | 最大长度200 | 否 |
| `gridX` | 网格X坐标 | Integer | 非负整数 | 否 |
| `gridY` | 网格Y坐标 | Integer | 非负整数 | 否 |
| `submitterId` | 提交者ID | Long | 外键关联UserAccount | 是 |
| `latitude` | 地理位置纬度 | Double | 有效范围 | 是 |
| `longitude` | 地理位置经度 | Double | 有效范围 | 是 |
| `user` | 提交者用户对象 | UserAccount | 外键关联 | 是 |
| `attachments` | 附件列表 | List<Attachment> | 至少一张图片 | 是 |
| `task` | 关联的任务 | Task | 一对一关联 | 否 |
| `createdAt` | 提交时间 | DateTime | ISO 8601格式 | 是 |
| `updatedAt` | 更新时间 | DateTime | ISO 8601格式 | 是 |

### 7.3 任务 (Task) 数据结构

| 字段名 | 描述 | 数据类型 | 约束条件 | 是否必填 |
| :--- | :--- | :--- | :--- | :--- |
| `id` | 任务唯一标识符 | Long | 主键，自增 | 是 |
| `feedback` | 关联的反馈 | Feedback | 外键关联Feedback | 否 |
| `assignee` | 被指派的网格员 | UserAccount | 外键关联UserAccount | 否 |
| `createdBy` | 创建者 | UserAccount | 外键关联UserAccount | 是 |
| `status` | 任务状态 | Enum | CREATED, ASSIGNED, IN_PROGRESS, SUBMITTED, APPROVED, REJECTED | 是 |
| `assignedAt` | 分配时间 | DateTime | ISO 8601格式 | 否 |
| `completedAt` | 完成时间 | DateTime | ISO 8601格式 | 否 |
| `createdAt` | 创建时间 | DateTime | ISO 8601格式 | 是 |
| `updatedAt` | 更新时间 | DateTime | ISO 8601格式 | 是 |
| `title` | 任务标题 | String | 最大长度100 | 是 |
| `description` | 任务描述 | String | 最大长度1000 | 是 |
| `pollutionType` | 污染类型 | Enum | AIR, WATER, SOIL, NOISE, OTHER | 是 |
| `severityLevel` | 严重程度 | Enum | LOW, MEDIUM, HIGH, CRITICAL | 是 |
| `textAddress` | 文本地址描述 | String | 最大长度200 | 否 |
| `gridX` | 网格X坐标 | Integer | 非负整数 | 否 |
| `gridY` | 网格Y坐标 | Integer | 非负整数 | 否 |
| `latitude` | 地理位置纬度 | Double | 有效范围 | 是 |
| `longitude` | 地理位置经度 | Double | 有效范围 | 是 |
| `history` | 任务历史记录 | List<TaskHistory> | - | 否 |
| `assignment` | 任务分配信息 | Assignment | 一对一关联 | 否 |
| `submissions` | 任务提交记录 | List<TaskSubmission> | - | 否 |

### 7.4 网格 (Grid) 数据结构

| 字段名 | 描述 | 数据类型 | 约束条件 | 是否必填 |
| :--- | :--- | :--- | :--- | :--- |
| `id` | 网格唯一标识符 | Long | 主键，自增 | 是 |
| `gridX` | 网格X坐标 | Integer | 非负整数 | 是 |
| `gridY` | 网格Y坐标 | Integer | 非负整数 | 是 |
| `cityName` | 所属城市 | String | 最大长度50 | 是 |
| `districtName` | 所属区县 | String | 最大长度50 | 是 |
| `description` | 网格描述 | String | 最大长度200 | 否 |
| `isObstacle` | 是否为障碍物 | Boolean | true/false | 是 |

### 7.5 任务分配 (Assignment) 数据结构

| 字段名 | 描述 | 数据类型 | 约束条件 | 是否必填 |
| :--- | :--- | :--- | :--- | :--- |
| `id` | 分配唯一标识符 | Long | 主键，自增 | 是 |
| `task` | 关联的任务 | Task | 外键关联Task | 是 |
| `assigner` | 分配人 | UserAccount | 外键关联UserAccount | 是 |
| `assignmentTime` | 分配时间 | DateTime | ISO 8601格式 | 是 |
| `deadline` | 截止日期 | DateTime | ISO 8601格式 | 否 |
| `status` | 分配状态 | Enum | PENDING, ACCEPTED, REJECTED, COMPLETED | 是 |
| `remarks` | 备注说明 | String | 最大长度500 | 否 |