软件需求规格说明书
1. 引言
本文档旨在明确应急演练系统的功能需求和非功能需求，为系统设计、开发和测试提供依据。
应急演练系统是一个面向企业单位的应急管理信息化平台，覆盖应急演练的计划制定、任务派发、过程执行、评估反馈等核心环节，同时集成AI视频分析能力和飞书即时通讯工具。
2. 系统总体描述
系统提供以下主要功能模块：
- 应急预案管理：支持预案的增删改查，支持Excel批量导入
- 演练计划管理：支持计划的创建、编辑、删除和筛选查询
- 演练任务派发：支持任务创建、分配、状态跟踪和优先级管理
- 演练过程执行：支持演练启动、安全确认、完成和中止
- 演练评估反馈：支持评估创建、评分和问题反馈
- AI视频分析：上传演练视频，调用火山引擎AI智能分析
- 飞书机器人：通过飞书即时通讯进行智能问答和操作
- 用户认证：基于SM2国密算法的安全登录
3. 功能需求
- 用户登录模块：用户通过用户名、密码和验证码登录，密码使用SM2国密算法加密传输和存储。登录失败累计次数，超过阈值锁定账户。
- 应急预案管理：管理预案完整生命周期，包含编号、名称、适用设备类型、响应级别、处置步骤等字段。
- 演练计划管理：支持智能预填上次创建内容。状态管理：
PENDING、IN_PROGRESS、COMPLETED。
- 演练任务派发：自动生成
TASK-YYYY-SEQ 编号。状态包含 PENDING / IN_PROGRESS / COMPLETED / CANCELLED。
- AI视频分析：上传MP4视频（最大200MB），调用火山引擎Doubao分析，自动创建评估记录。
4. 非功能需求
- 密码SM2国密加密传输和存储
- 验证码机制防止暴力破解
- 登录失败锁定（3次临时锁定5分钟，5次永久锁定）
- 智能预填减少重复输入
- 自然语言交互降低使用门槛
软件概要设计说明书
1. 系统架构
系统采用前后端混合架构，整体分为三层：表现层、业务逻辑层和数据访问层。同时集成外部AI服务和即时通讯服务。
- 表现层：JSP页面+JavaScript+CSS，部署于Tomcat服务器
- Web控制器层：Java Servlet，处理HTTP请求和响应
- 业务逻辑层：Java Service类，封装核心业务逻辑
- 数据访问层：通用BaseDao+各模块Dao，基于JDBC+MySQL
- AI服务层：Python Flask应用，提供视频分析和智能对话
- 飞书机器人：Python WebSocket长连接服务
2. 技术栈
| 层次 |
技术/版本 |
| Web服务器 |
Apache Tomcat 9+ |
| Java版本 |
JDK 24 |
| Python版本 |
Python 3.14+ |
| 数据库 |
MySQL 8.0 |
| AI对话 |
DeepSeek Chat API |
| 视频分析 |
火山引擎Doubao |
| 服务框架 |
Flask+Flask-CORS |
| 即时通讯 |
Lark SDK(WebSocket) |
| 国密加密 |
Hutool+Bouncy Castle SM2 |
| Excel处理 |
Alibaba EasyExcel |
3. 模块划分
| 模块名称 |
技术实现 |
| 用户认证 |
LoginServlet+SM2Util+Filter |
| 应急预案管理 |
EmergencyPlanServlet+Dao |
| 演练计划管理 |
DrillPlanServlet+DrillPlanDao |
| 演练任务派发 |
DrillTaskServlet+DrillTaskDao |
| 演练过程执行 |
DrillExecutionServlet+Dao |
| 演练评估反馈 |
DrillEvaluationServlet+Dao |
| AI视频分析 |
VideoAnalyzeServlet+Flask |
| 网站智能助手 |
ChatbotServlet |
| 飞书机器人 |
feishu_bot.py+Flask |
| 飞书通知服务 |
FeishuNotifier.java |
| 编码生成器 |
CodeGenerator |
| 智能预填服务 |
SmartSuggestionService |
4. 接口设计
Java Web接口（基于Servlet）：
| 接口路径 |
功能 |
方式 |
| /login |
用户登录 |
POST |
| /emergencyPlan |
应急预案管理 |
GET/POST |
| /drillPlan |
演练计划管理 |
GET/POST |
| /drillTask |
演练任务管理 |
GET/POST |
| /drillExecution |
演练执行管理 |
GET/POST |
| /drillEvaluation |
演练评估管理 |
GET/POST |
| /aiAnalyze |
AI视频分析 |
POST |
| /chatbot |
智能助手对话 |
POST |
| /uploadPlan |
预案Excel导入 |
POST |
| /captcha |
验证码获取 |
GET |
Flask AI接口（端口5000）：
| 路径 |
功能 |
方式 |
| /analyze |
AI视频分析 |
POST |
| /feishu_callback |
飞书回调 |
POST |
| /api_query |
数据库直连 |
POST |
5. 数据流设计
主要数据流程：
- 登录流程：用户 $\rightarrow$ LoginServlet $\rightarrow$ SM2解密 $\rightarrow$ DB查询 $\rightarrow$ Session $\rightarrow$ 首页
- 预案管理：用户 $\rightarrow$ EmergencyPlanServlet $\rightarrow$ Dao $\rightarrow$ MySQL $\rightarrow$ JSP展示
- 视频分析：用户 $\rightarrow$ VideoAnalyzeServlet $\rightarrow$ Flask $\rightarrow$ 火山引擎AI $\rightarrow$ 生成评估
- 飞书机器人：飞书消息 $\rightarrow$ feishu_bot.py(WebSocket) $\rightarrow$ Function Calling $\rightarrow$ api_query $\rightarrow$ MySQL $\rightarrow$ 回复
软件详细设计说明书
1. 通用工具模块
- DBUtil数据库连接工具：提供
getConnection() 方法返回MySQL连接。URL=jdbc:mysql://localhost:3306/device_management, 驱动=com.mysql.cj.jdbc.Driver。
- SM2Util国密加解密工具：基于Hutool Crypto库实现SM2椭圆曲线公钥密码算法。
encrypt() 公钥加密，decrypt() 私钥解密。前端公钥加密 $\rightarrow$ 网络传输 $\rightarrow$ 后端私钥解密比对。
- LoginCheckFilter登录过滤器：拦截所有请求，白名单放行
/login、/register、/static/*、/captcha、/aiAnalyze、/chatbot、/。
2. 通用数据访问层
BaseDao提供通用增删改查操作，基于JDBC PreparedStatement+反射机制。
executeUpdate(sql, params)：通用增删改，返回影响行数。executeQuery(clazz, sql, params)：通用查询，自动反射映射结果集到实体对象。类型转换处理：LocalDateTime $\rightarrow$ Date，Boolean $\leftrightarrow$ Integer。executeCount(sql, params)：通用COUNT统计查询。- CodeGenerator编码生成器：预案编号
EP-YYYY-SEQ，工单编号 TASK-YYYY-SEQ。实现逻辑：查当前年最大编号 $\rightarrow$ 提取序列号 $\rightarrow$ +1 $\rightarrow$ 格式化三位数。
- SmartSuggestionService智能预填服务：查询各模块最近一条记录提供默认值。
3. 业务模块详细设计
- 登录模块(LoginServlet)：接收参数 $\rightarrow$ 验证码校验 $\rightarrow$ 用户查询 $\rightarrow$ 锁定检查 $\rightarrow$ 密码解密验证。锁定策略：
status=0 禁用，fail_count>=5 永久锁定，fail_count>=3 临时锁定5分钟。
- 应急预案模块(EmergencyPlanServlet)：GET查询列表，POST新增/编辑。Excel导入使用EasyExcel+EmergencyPlanExcelListener逐行校验。校验规则：
plan_code / plan_name / response_level 不能为空，level 只能是 I / II / III / IV。
- 演练计划模块(DrillPlanServlet)：GET加载列表支持筛选，POST新增/编辑。删除后自动飞书通知。支持智能预填。
- AI视频分析模块(VideoAnalyzeServlet)：接收视频 (multipart,最大200MB) $\rightarrow$ 调用Flask AI (
/analyze) $\rightarrow$ Flask转base64调火山引擎Doubao $\rightarrow$ 结果自动创建评估记录 $\rightarrow$ 飞书通知。
- 智能助手模块(ChatbotServlet)：自然语言对话。识别用户意图（查询/新增/修改/删除）和目标模块，执行操作返回HTML格式结果。删除需二次确认（Session缓存
PendingDelete）。
4. AI服务详细设计
- Flask主服务(app.py)：端口5000。路由
/analyze（视频分析）、/feishu_callback（飞书回调）、/api_query（数据库查询）。
- AI配置中心(ai_config.py)：DeepSeek API配置，启动时自动测试API连接可用性。
- 飞书机器人(feishu_bot.py)：基于lark-oapi SDK WebSocket长连接。监听消息事件，文本消息调用Function Calling，文件消息下载后视频分析。
- FeishuNotifier：通过飞书Webhook发卡片消息通知。支持演练计划、任务派发、应急预案、执行完成、评估提交等通知类型。
数据库设计说明书
1. 数据库环境
| 项目 |
说明 |
| DBMS |
MySQL 8.0+ |
| 数据库名 |
device_management |
| 字符集 |
utf8mb4 |
| 存储引擎 |
InnoDB |
| 连接URL |
jdbc:mysql://localhost:3306/device_management |
2. 表结构设计
用户表(users)：存储用户信息，用于登录认证
| 字段 |
类型 |
说明 |
| id |
INT PK AUTO_INCREMENT |
用户ID |
| username |
VARCHAR(50) UNIQUE |
用户名 |
| password |
VARCHAR(256) |
SM2加密密码 |
| status |
TINYINT DEFAULT 1 |
状态(1正常/0禁用) |
| fail_count |
INT DEFAULT 0 |
登录失败次数 |
| lock_time |
DATETIME |
锁定截止时间 |
应急预案表(emergency_plans)：存储预案信息
| 字段 |
类型 |
说明 |
| id |
INT PK AUTO_INCREMENT |
主键 |
| plan_code |
VARCHAR(32) UNIQUE |
预案编号EP-YYYY-SEQ |
| plan_name |
VARCHAR(100) NOT NULL |
预案名称 |
| device_type |
VARCHAR(50) |
适用设备类型 |
| response_level |
VARCHAR(10) |
响应级别I/II/III/IV |
| content |
TEXT |
处置步骤 |
| create_user |
VARCHAR(50) |
创建人 |
演练计划表(drill_plans)：存储演练计划
| 字段 |
类型 |
说明 |
| id |
INT PK |
主键 |
| plan_name |
VARCHAR(100) |
计划名称 |
| drill_unit |
VARCHAR(100) |
演练单位 |
| drill_project |
VARCHAR(100) |
演练项目 |
| drill_time |
DATETIME |
演练时间 |
| status |
VARCHAR(20) |
PENDING/IN_PROGRESS/COMPLETED |
演练任务表(drill_tasks)：存储任务派发信息
| 字段 |
类型 |
说明 |
| id |
INT PK |
主键 |
| task_code |
VARCHAR(32) UNIQUE |
工单编号 |
| plan_id |
INT |
关联计划ID |
| assignee |
VARCHAR(100) |
执行人 |
| priority |
VARCHAR(10) |
优先级 |
| status |
VARCHAR(20) |
PENDING/IN_PROGRESS/COMPLETED/CANCELLED |
演练执行表(drill_executions)：存储执行过程
| 字段 |
类型 |
说明 |
| id |
INT PK |
主键 |
| plan_id |
INT |
关联计划ID |
| safety_read |
TINYINT(1) |
是否已读安全须知 |
| start_time |
DATETIME |
开始时间 |
| end_time |
DATETIME |
结束时间 |
| duration_minutes |
INT |
持续时长 |
| status |
VARCHAR(20) |
NOT_STARTED/IN_PROGRESS/COMPLETED/ABORTED |
演练评估表(drill_evaluations)：存储评估反馈
| 字段 |
类型 |
说明 |
| id |
INT PK |
主键 |
| execution_id |
INT |
关联执行ID |
| plan_id |
INT |
关联计划ID |
| feedback_type |
VARCHAR(20) |
类型 |
| score |
INT |
评分1-100 |
| issues_exist |
TEXT |
存在问题 |
| improvement |
TEXT |
改进建议 |
| evaluator |
VARCHAR(50) |
评估人 |
3. 表间关系
drill_tasks.plan_id $\rightarrow$ drill_plans.iddrill_executions.plan_id $\rightarrow$ drill_plans.iddrill_executions.task_id $\rightarrow$ drill_tasks.iddrill_evaluations.plan_id $\rightarrow$ drill_plans.iddrill_evaluations.execution_id $\rightarrow$ drill_executions.id
4. 存储脚本
数据库建表脚本位于项目根目录的 drill_system_tables.sql 文件中。执行前需 USE device_management;
项目开发计划
1. 项目概述
应急演练系统旨在通过信息化手段提升企业应急演练的效率和规范化水平。采用Java Web + Python AI + 飞书集成的技术路线。
2. 技术选型
| 技术领域 |
选型 |
| Web服务器 |
Apache Tomcat |
| 编程语言 |
Java 24 + Python 3 |
| 数据库 |
MySQL 8.0 |
| AI对话 |
DeepSeek Chat API |
| 视频分析 |
火山引擎Doubao |
| 即时通讯 |
飞书开放平台 |
| 国密加密 |
SM2(Hutool) |
| Excel处理 |
EasyExcel |
3. 质量保证计划
- 代码审查：关键模块代码走查
- 单元测试：每个DAO类和方法测试
- 集成测试：各模块接口联调
- 安全测试：SQL注入/XSS/CSRF测试
4. 风险管理
| 风险 |
应对措施 |
| AI API配额不足 |
多备API Key，监控配额 |
| 飞书API变更 |
关注公告，及时更新SDK |
| MySQL连接故障 |
配置连接池，添加重试 |
| SM2密钥泄露 |
定期轮换密钥 |
测试计划
1. 测试范围
本次测试覆盖应急演练系统的所有功能模块。
2. 测试类型
- 功能测试：对各功能模块黑盒测试，验证需求规格中定义的功能是否完整实现。
- 接口测试：对HTTP接口进行请求-响应验证，包括Servlet接口和Flask接口。
- 安全测试：登录认证测试、权限测试、SQL注入测试、SM2加密验证、账户锁定测试。
- 集成测试：验证Java后端 $\leftrightarrow$ MySQL、Java后端 $\leftrightarrow$ Flask、Flask $\leftrightarrow$ DeepSeek/火山引擎、飞书机器人 $\leftrightarrow$ 数据库的协作。
3. 测试用例
登录测试用例：
| 编号 |
测试项 |
预期结果 |
| TC-LOGIN-001 |
正确登录 |
登录成功跳转首页 |
| TC-LOGIN-002 |
验证码错误 |
提示验证码错误 |
| TC-LOGIN-003 |
连续3次密码错误 |
提示临时锁定5分钟 |
| TC-LOGIN-004 |
连续5次密码错误 |
提示账户已锁定 |
| TC-LOGIN-005 |
未登录访问 |
重定向到登录页 |
预案管理测试用例：
| 编号 |
测试项 |
预期结果 |
| TC-EP-001 |
新增预案 |
保存成功列表可见 |
| TC-EP-002 |
编辑预案 |
修改成功数据更新 |
| TC-EP-003 |
删除预案 |
删除成功列表减少 |
| TC-EP-004 |
Excel导入正常 |
导入成功数据入库 |
| TC-EP-005 |
Excel导入空项 |
提示错误信息 |
AI视频分析测试用例：
| 编号 |
测试项 |
预期结果 |
| TC-AI-001 |
上传视频分析 |
Flask返回分析结果 |
| TC-AI-002 |
自动创建评估 |
自动生成评估记录 |
| TC-AI-003 |
AI服务不可用 |
返回友好错误提示 |
飞书机器人测试用例：
| 编号 |
测试项 |
预期结果 |
| TC-FEISHU-001 |
发送文本消息 |
机器人回复列表 |
| TC-FEISHU-002 |
发送视频文件 |
机器人回复分析结果 |
| TC-FEISHU-003 |
Function Calling |
正确调用工具函数 |
4. 测试环境
| 环境 |
配置 |
| 操作系统 |
Windows 10/11 |
| Web服务器 |
Tomcat 9+ 端口8080 |
| 数据库 |
MySQL 8.0 |
| Java环境 |
JDK 24 |
| Python环境 |
Python 3.14+ |
| 浏览器 |
Chrome/Firefox/Edge |
5. 完成标准
- 所有功能测试用例通过率100%
- 无严重级别Bug
- 所有接口响应正常
- 安全测试无高危漏洞
浙公网安备 33010602011771号