Files
Environment-Monitoring-System/Report/需求定义.md
ChuXun 02a830145e 1
2025-10-25 19:18:43 +08:00

315 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 需求定义文档
## 1. 整体业务流程
下图描述了从公众发现问题、上报、到平台内部流转、处理、并最终反馈结果的完整闭环业务流程。
```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
```
## 2. 功能性需求
### 2.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;
```
### 2.2 需求描述
#### 2.2.1 用户与认证模块
| 功能名称 | 用户与认证模块 |
| :--- | :--- |
| **优先级** | 高 |
| **业务背景** | 作为系统安全的基础,本模块负责管理所有用户的身份验证和访问控制,确保系统资源只能被授权用户访问,同时提供灵活的角色权限管理。 |
| **功能说明** | 1. **用户认证**基于JWT (JSON Web Token) 的安全认证机制,支持账号密码登录,提供令牌刷新功能。<br>2. **权限控制**基于RBAC (基于角色的访问控制) 模型预设管理员、主管、网格员等角色每个角色拥有特定的API访问权限。<br>3. **密码管理**:支持安全的密码重置流程,包括邮箱验证码验证,以及定期密码更新提醒。<br>4. **会话管理**:支持单点登录或多设备登录控制,可配置会话超时策略。 |
| **约束条件** | 1. 密码必须符合复杂度要求至少8位包含大小写字母、数字和特殊字符。<br>2. 敏感操作(如修改权限)需要二次验证。<br>3. 密码在数据库中必须使用BCrypt等强哈希算法加密存储。 |
| **相关查询** | 1. 按用户名、邮箱或手机号查询用户信息。<br>2. 查询特定角色的所有用户列表。<br>3. 查询用户的权限和访问历史。 |
| **其他需求** | 1. 登录失败超过预设次数后,账户应被临时锁定。<br>2. 系统应记录所有关键安全事件(登录、权限变更等)的审计日志。 |
| **裁剪说明** | 不可裁剪,此为系统安全的基础组件。 |
#### 2.2.2 反馈管理模块
| 功能名称 | 反馈管理模块 |
| :--- | :--- |
| **优先级** | 高 |
| **业务背景** | 作为系统的核心输入端口,本模块负责收集、处理和跟踪所有环境问题反馈,是连接公众与管理部门的桥梁,也是后续任务创建的数据源。 |
| **功能说明** | 1. **反馈提交**:提供结构化的表单接口,支持文字描述、污染类型分类、严重程度评估、地理位置标记和多媒体附件上传。<br>2. **AI内容审核**:集成智能审核服务,对反馈内容进行自动分析,识别垃圾信息、重复提交,并进行初步的分类和紧急程度评估。<br>3. **人工审核工作台**:为主管提供高效的反馈审核界面,支持批量处理、快速预览和详情查看。<br>4. **状态追踪**:完整记录反馈从提交到处理完成的全生命周期状态变更,支持多维度的统计和查询。 |
| **约束条件** | 1. 反馈提交必须包含至少一张图片和准确的地理位置信息。<br>2. AI审核结果仅作为参考最终决定权在人工审核者手中。<br>3. 对于紧急程度被标记为"高"的反馈系统应在1小时内完成审核。 |
| **相关查询** | 1. 按状态、时间段、区域、污染类型等多维度查询反馈列表。<br>2. 查看特定反馈的详细信息和处理历史。<br>3. 统计不同类型反馈的数量分布和处理效率。 |
| **其他需求** | 1. 支持反馈的优先级标记和升级处理。<br>2. 对于同一区域短时间内的多个相似反馈,系统应能智能识别并提示可能的重复。 |
| **裁剪说明** | AI审核功能可在初期简化实现但反馈的基本提交和人工审核流程不可裁剪。 |
#### 2.2.3 任务管理模块
| 功能名称 | 任务管理模块 |
| :--- | :--- |
| **优先级** | 高 |
| **业务背景** | 本模块是系统的核心业务处理单元,负责将审核通过的反馈转化为可执行的工作任务,并对任务的分配、执行和完成进行全流程管理。 |
| **功能说明** | 1. **任务创建**:支持从反馈自动生成任务,也支持主管手动创建临时任务,包含任务描述、位置、截止时间、优先级等信息。<br>2. **智能分配**:基于多因素(网格员位置、当前负载、专业技能、历史表现)的任务分配算法,为每个任务推荐最合适的处理人员。<br>3. **任务执行跟踪**:记录任务的每个状态变更(已分配、已接受、进行中、已提交、已审核),支持网格员实时上报处理进度。<br>4. **结果审核**:主管对网格员提交的处理结果进行审核,可以通过或驳回,并提供反馈意见。<br>5. **任务看板**:直观展示不同状态任务的数量和分布,支持拖拽操作进行状态更新。 |
| **约束条件** | 1. 任务必须关联到一个有效的反馈或由授权主管手动创建。<br>2. 任务分配时必须考虑网格员的工作区域和当前任务负载。<br>3. 高优先级任务应在24小时内分配并开始处理。<br>4. 任务提交时必须包含处理过程描述和至少一张结果照片。 |
| **相关查询** | 1. 按状态、负责人、时间段、区域等多维度查询任务列表。<br>2. 查看特定任务的详细信息、处理历史和相关反馈。<br>3. 统计不同网格员的任务完成率、平均处理时长等绩效指标。 |
| **其他需求** | 1. 支持任务的紧急程度升级和重新分配。<br>2. 对于长时间未处理的任务,系统应自动发送提醒通知。<br>3. 支持批量导出任务报告,用于绩效评估和工作汇报。 |
| **裁剪说明** | 智能分配算法可以在初期简化实现,但任务的基本创建、分配和状态管理功能不可裁剪。 |
#### 2.2.4 网格与地图模块
| 功能名称 | 网格与地图模块 |
| :--- | :--- |
| **优先级** | 中 |
| **业务背景** | 本模块负责对地理空间进行网格化管理,将城市区域划分为可管理的网格单元,并为任务执行提供地理位置支持和路径规划。 |
| **功能说明** | 1. **网格定义与管理**:支持管理员定义和维护城市网格系统,包括网格的坐标、属性(如是否为障碍物)和责任人分配。<br>2. **A*寻路算法服务**:基于网格系统和实时路况,为网格员提供从当前位置到任务地点的最优路径规划,考虑距离、交通状况和障碍物。<br>3. **地图可视化**:在地图上直观展示反馈点、任务分布和网格员位置,支持多种筛选条件和图层切换。<br>4. **区域统计**:基于网格系统,生成环境问题热力图,识别高发区域和问题类型分布。 |
| **约束条件** | 1. 网格系统应支持多级划分最小网格单元不应大于500米×500米。<br>2. 路径规划应考虑实际道路情况和障碍物,避免不可通行区域。<br>3. 地图数据应定期更新,确保准确性。 |
| **相关查询** | 1. 查询特定区域内的网格定义和属性。<br>2. 查询特定网格的历史问题记录和统计数据。<br>3. 获取两点间的最优路径规划。 |
| **其他需求** | 1. 支持网格责任人的灵活调整和临时替换。<br>2. 地图界面应支持常见的交互操作(缩放、平移、点选)。<br>3. 支持离线地图数据缓存,保证在网络不稳定情况下的基本功能。 |
| **裁剪说明** | A*寻路算法的高级功能(如考虑实时交通)可以在后期迭代中实现,但基本的网格定义和地图展示功能不应裁剪。 |
#### 2.2.5 决策支持模块
| 功能名称 | 决策支持模块 (管理驾驶舱) |
| :--- | :--- |
| **优先级** | 中 |
| **业务背景** | 本模块旨在将系统中沉淀的大量业务数据转化为有价值的决策洞察,帮助管理层了解环境状况、评估治理效果、优化资源配置。 |
| **功能说明** | 1. **核心指标看板**:实时展示关键业务指标,如待处理反馈数、进行中任务数、平均处理时长、按时完成率等。<br>2. **多维度分析**:支持按时间、区域、污染类型、处理人等多个维度对数据进行交叉分析和趋势展示。<br>3. **热力图可视化**:在地图上以热力图形式展示环境问题的分布密度,直观识别高发区域。<br>4. **绩效评估**:对网格员和区域的工作效率、问题解决质量等进行量化评估,生成排名和对比分析。<br>5. **预警机制**:基于历史数据和趋势分析,对可能出现的环境风险提前预警。 |
| **约束条件** | 1. 数据分析应基于实时或准实时的业务数据,确保决策的时效性。<br>2. 图表和报表应支持多种导出格式PDF、Excel等便于进一步分析和汇报。<br>3. 敏感数据(如个人绩效)的访问应受到严格权限控制。 |
| **相关查询** | 1. 按自定义时间范围查询各类统计指标。<br>2. 查询特定区域或网格员的历史表现数据。<br>3. 生成定制化的数据报表和分析图表。 |
| **其他需求** | 1. 支持数据看板的个性化配置,满足不同管理者的关注点。<br>2. 提供数据异常检测和提醒功能,及时发现数据波动。<br>3. 支持定期自动生成并发送统计报告。 |
| **裁剪说明** | 高级分析功能(如预测模型)可以在后期迭代中实现,但基本的数据统计和可视化功能不应裁剪。 |
## 3. 需求规定
### 3.1 一般性需求
* **数据集中管理与共享**系统应采用统一的数据存储和访问机制确保各模块间的数据一致性和实时共享。所有业务数据应按照标准化格式进行存储并通过规范的API进行访问避免数据孤岛。
* **高可用性与可靠性**系统应保证7x24小时的稳定运行关键业务流程如反馈提交、任务分配的可用性应达到99.9%以上。应实现适当的错误处理和故障恢复机制,确保在出现异常情况时能够快速恢复。
* **安全性与合规性**
* 应用SSL/TLS加密保护所有网络通信。
* 实现严格的认证和授权机制,确保用户只能访问其权限范围内的数据和功能。
* 敏感数据(如用户密码)必须加密存储,并限制访问权限。
* 系统应保留完整的操作日志,支持安全审计和问题追溯。
* 符合相关的数据保护法规和隐私要求。
* **可扩展性与模块化**系统架构应支持水平扩展和功能模块的灵活添加。核心组件应设计为松耦合的便于独立升级和替换。API设计应考虑向后兼容性确保系统可以平滑演进。
* **用户体验优化**
* 界面设计应简洁直观符合现代Web应用的设计标准。
* 关键操作路径应尽量简化,减少用户点击次数。
* 系统响应时间应控制在可接受范围内核心API的平均响应时间不超过500ms。
* 提供适当的操作反馈和状态提示,增强用户对系统的信任感。
* 支持响应式设计确保在不同设备PC、平板、手机上的良好体验。
* **国际化与本地化**:系统应支持多语言界面,初期至少支持中英文切换。日期、时间、数字等格式应根据用户的区域设置进行适当显示。
* **可维护性与可测试性**:系统代码应遵循统一的编码规范和设计模式,保持良好的可读性和可维护性。核心业务逻辑应有充分的单元测试覆盖,便于后续的功能迭代和质量保障。
## 4. 数据描述
### 4.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 | 非负整数 | 否 |
| `createdAt` | 账户创建时间 | DateTime | ISO 8601格式 | 是 |
| `updatedAt` | 账户更新时间 | DateTime | ISO 8601格式 | 是 |
| `lastLoginAt` | 最后登录时间 | DateTime | ISO 8601格式 | 否 |
### 4.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 | 是 |
| `longitude` | 地理位置经度 | Double | 有效范围 | 是 |
| `latitude` | 地理位置纬度 | Double | 有效范围 | 是 |
| `imageUrls` | 图片URL列表 | Array | 至少一张图片 | 是 |
| `status` | 反馈状态 | Enum | PENDING_REVIEW, AI_REJECTED, PROCESSED, CLOSED | 是 |
| `submitterId` | 提交者ID | Long | 外键关联UserAccount | 是 |
| `reviewerId` | 审核者ID | Long | 外键关联UserAccount | 否 |
| `reviewNote` | 审核备注 | String | 最大长度500 | 否 |
| `createdAt` | 提交时间 | DateTime | ISO 8601格式 | 是 |
| `updatedAt` | 更新时间 | DateTime | ISO 8601格式 | 是 |
| `processedAt` | 处理时间 | DateTime | ISO 8601格式 | 否 |
### 4.3 任务 (Task) 数据结构
| 字段名 | 描述 | 数据类型 | 约束条件 | 是否必填 |
| :--- | :--- | :--- | :--- | :--- |
| `id` | 任务唯一标识符 | Long | 主键,自增 | 是 |
| `feedbackId` | 关联的反馈ID | Long | 外键关联Feedback | 否 |
| `title` | 任务标题 | String | 最大长度100 | 是 |
| `description` | 任务描述 | String | 最大长度1000 | 是 |
| `assigneeId` | 被指派的网格员ID | Long | 外键关联UserAccount | 否 |
| `createdBy` | 创建者ID | Long | 外键关联UserAccount | 是 |
| `status` | 任务状态 | Enum | CREATED, ASSIGNED, IN_PROGRESS, SUBMITTED, APPROVED, REJECTED | 是 |
| `priority` | 优先级 | Enum | LOW, MEDIUM, HIGH, URGENT | 是 |
| `longitude` | 任务地点经度 | Double | 有效范围 | 是 |
| `latitude` | 任务地点纬度 | Double | 有效范围 | 是 |
| `deadline` | 截止日期 | DateTime | ISO 8601格式 | 否 |
| `completionReport` | 完成报告 | String | 最大长度2000 | 否 |
| `resultImageUrls` | 结果图片URL列表 | Array | 可为空 | 否 |
| `createdAt` | 创建时间 | DateTime | ISO 8601格式 | 是 |
| `assignedAt` | 分配时间 | DateTime | ISO 8601格式 | 否 |
| `startedAt` | 开始时间 | DateTime | ISO 8601格式 | 否 |
| `submittedAt` | 提交时间 | DateTime | ISO 8601格式 | 否 |
| `approvedAt` | 审核通过时间 | DateTime | ISO 8601格式 | 否 |
| `rejectionReason` | 拒绝原因 | String | 最大长度500 | 否 |
### 4.4 网格 (Grid) 数据结构
| 字段名 | 描述 | 数据类型 | 约束条件 | 是否必填 |
| :--- | :--- | :--- | :--- | :--- |
| `id` | 网格唯一标识符 | Long | 主键,自增 | 是 |
| `gridX` | 网格X坐标 | Integer | 非负整数 | 是 |
| `gridY` | 网格Y坐标 | Integer | 非负整数 | 是 |
| `cityName` | 所属城市 | String | 最大长度50 | 是 |
| `districtName` | 所属区县 | String | 最大长度50 | 是 |
| `description` | 网格描述 | String | 最大长度200 | 否 |
| `isObstacle` | 是否为障碍物 | Boolean | true/false | 是 |
| `responsibleUserId` | 负责人ID | Long | 外键关联UserAccount | 否 |
| `createdAt` | 创建时间 | DateTime | ISO 8601格式 | 是 |
| `updatedAt` | 更新时间 | DateTime | ISO 8601格式 | 是 |