20 KiB
20 KiB
需求定义文档
1. 整体业务流程
下图描述了从公众发现问题、上报、到平台内部流转、处理、并最终反馈结果的完整闭环业务流程。
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 功能层次方框图
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) 的安全认证机制，支持账号密码登录，提供令牌刷新功能。 2. 权限控制：基于RBAC (基于角色的访问控制) 模型，预设管理员、主管、网格员等角色，每个角色拥有特定的API访问权限。 3. 密码管理：支持安全的密码重置流程，包括邮箱验证码验证，以及定期密码更新提醒。 4. 会话管理：支持单点登录或多设备登录控制，可配置会话超时策略。 |
| 约束条件 | 1. 密码必须符合复杂度要求（至少8位，包含大小写字母、数字和特殊字符）。 2. 敏感操作（如修改权限）需要二次验证。 3. 密码在数据库中必须使用BCrypt等强哈希算法加密存储。 |
| 相关查询 | 1. 按用户名、邮箱或手机号查询用户信息。 2. 查询特定角色的所有用户列表。 3. 查询用户的权限和访问历史。 |
| 其他需求 | 1. 登录失败超过预设次数后，账户应被临时锁定。 2. 系统应记录所有关键安全事件（登录、权限变更等）的审计日志。 |
| 裁剪说明 | 不可裁剪，此为系统安全的基础组件。 |
2.2.2 反馈管理模块
| 功能名称 | 反馈管理模块 |
|---|---|
| 优先级 | 高 |
| 业务背景 | 作为系统的核心输入端口，本模块负责收集、处理和跟踪所有环境问题反馈，是连接公众与管理部门的桥梁，也是后续任务创建的数据源。 |
| 功能说明 | 1. 反馈提交：提供结构化的表单接口，支持文字描述、污染类型分类、严重程度评估、地理位置标记和多媒体附件上传。 2. AI内容审核：集成智能审核服务，对反馈内容进行自动分析，识别垃圾信息、重复提交，并进行初步的分类和紧急程度评估。 3. 人工审核工作台：为主管提供高效的反馈审核界面，支持批量处理、快速预览和详情查看。 4. 状态追踪：完整记录反馈从提交到处理完成的全生命周期状态变更，支持多维度的统计和查询。 |
| 约束条件 | 1. 反馈提交必须包含至少一张图片和准确的地理位置信息。 2. AI审核结果仅作为参考，最终决定权在人工审核者手中。 3. 对于紧急程度被标记为"高"的反馈，系统应在1小时内完成审核。 |
| 相关查询 | 1. 按状态、时间段、区域、污染类型等多维度查询反馈列表。 2. 查看特定反馈的详细信息和处理历史。 3. 统计不同类型反馈的数量分布和处理效率。 |
| 其他需求 | 1. 支持反馈的优先级标记和升级处理。 2. 对于同一区域短时间内的多个相似反馈，系统应能智能识别并提示可能的重复。 |
| 裁剪说明 | AI审核功能可在初期简化实现，但反馈的基本提交和人工审核流程不可裁剪。 |
2.2.3 任务管理模块
| 功能名称 | 任务管理模块 |
|---|---|
| 优先级 | 高 |
| 业务背景 | 本模块是系统的核心业务处理单元，负责将审核通过的反馈转化为可执行的工作任务，并对任务的分配、执行和完成进行全流程管理。 |
| 功能说明 | 1. 任务创建：支持从反馈自动生成任务，也支持主管手动创建临时任务，包含任务描述、位置、截止时间、优先级等信息。 2. 智能分配：基于多因素（网格员位置、当前负载、专业技能、历史表现）的任务分配算法，为每个任务推荐最合适的处理人员。 3. 任务执行跟踪：记录任务的每个状态变更（已分配、已接受、进行中、已提交、已审核），支持网格员实时上报处理进度。 4. 结果审核：主管对网格员提交的处理结果进行审核，可以通过或驳回，并提供反馈意见。 5. 任务看板：直观展示不同状态任务的数量和分布，支持拖拽操作进行状态更新。 |
| 约束条件 | 1. 任务必须关联到一个有效的反馈或由授权主管手动创建。 2. 任务分配时必须考虑网格员的工作区域和当前任务负载。 3. 高优先级任务应在24小时内分配并开始处理。 4. 任务提交时必须包含处理过程描述和至少一张结果照片。 |
| 相关查询 | 1. 按状态、负责人、时间段、区域等多维度查询任务列表。 2. 查看特定任务的详细信息、处理历史和相关反馈。 3. 统计不同网格员的任务完成率、平均处理时长等绩效指标。 |
| 其他需求 | 1. 支持任务的紧急程度升级和重新分配。 2. 对于长时间未处理的任务，系统应自动发送提醒通知。 3. 支持批量导出任务报告，用于绩效评估和工作汇报。 |
| 裁剪说明 | 智能分配算法可以在初期简化实现，但任务的基本创建、分配和状态管理功能不可裁剪。 |
2.2.4 网格与地图模块
| 功能名称 | 网格与地图模块 |
|---|---|
| 优先级 | 中 |
| 业务背景 | 本模块负责对地理空间进行网格化管理，将城市区域划分为可管理的网格单元，并为任务执行提供地理位置支持和路径规划。 |
| 功能说明 | 1. 网格定义与管理：支持管理员定义和维护城市网格系统，包括网格的坐标、属性（如是否为障碍物）和责任人分配。 2. A*寻路算法服务：基于网格系统和实时路况，为网格员提供从当前位置到任务地点的最优路径规划，考虑距离、交通状况和障碍物。 3. 地图可视化：在地图上直观展示反馈点、任务分布和网格员位置，支持多种筛选条件和图层切换。 4. 区域统计：基于网格系统，生成环境问题热力图，识别高发区域和问题类型分布。 |
| 约束条件 | 1. 网格系统应支持多级划分，最小网格单元不应大于500米×500米。 2. 路径规划应考虑实际道路情况和障碍物，避免不可通行区域。 3. 地图数据应定期更新，确保准确性。 |
| 相关查询 | 1. 查询特定区域内的网格定义和属性。 2. 查询特定网格的历史问题记录和统计数据。 3. 获取两点间的最优路径规划。 |
| 其他需求 | 1. 支持网格责任人的灵活调整和临时替换。 2. 地图界面应支持常见的交互操作（缩放、平移、点选）。 3. 支持离线地图数据缓存，保证在网络不稳定情况下的基本功能。 |
| 裁剪说明 | A*寻路算法的高级功能（如考虑实时交通）可以在后期迭代中实现，但基本的网格定义和地图展示功能不应裁剪。 |
2.2.5 决策支持模块
| 功能名称 | 决策支持模块 (管理驾驶舱) |
|---|---|
| 优先级 | 中 |
| 业务背景 | 本模块旨在将系统中沉淀的大量业务数据转化为有价值的决策洞察，帮助管理层了解环境状况、评估治理效果、优化资源配置。 |
| 功能说明 | 1. 核心指标看板：实时展示关键业务指标，如待处理反馈数、进行中任务数、平均处理时长、按时完成率等。 2. 多维度分析：支持按时间、区域、污染类型、处理人等多个维度对数据进行交叉分析和趋势展示。 3. 热力图可视化：在地图上以热力图形式展示环境问题的分布密度，直观识别高发区域。 4. 绩效评估：对网格员和区域的工作效率、问题解决质量等进行量化评估，生成排名和对比分析。 5. 预警机制：基于历史数据和趋势分析，对可能出现的环境风险提前预警。 |
| 约束条件 | 1. 数据分析应基于实时或准实时的业务数据，确保决策的时效性。 2. 图表和报表应支持多种导出格式（PDF、Excel等），便于进一步分析和汇报。 3. 敏感数据（如个人绩效）的访问应受到严格权限控制。 |
| 相关查询 | 1. 按自定义时间范围查询各类统计指标。 2. 查询特定区域或网格员的历史表现数据。 3. 生成定制化的数据报表和分析图表。 |
| 其他需求 | 1. 支持数据看板的个性化配置，满足不同管理者的关注点。 2. 提供数据异常检测和提醒功能，及时发现数据波动。 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格式 | 是 |