任务描述

设备运维管理系统——第一阶段任务分析

一、典型用户模板
（1）名字：小周
（2）年龄：21岁
（3）收入：在校大学生，暂无固定收入，项目为课程设计作业
（4）代表的用户在市场上的比例和重要性：代表了团队中负责后端核心模块与第三方集成的开发人员。在软件项目开发团队中，这类角色约占开发人员总数的 30%，他们是系统核心功能的实现者，直接决定了项目的技术架构和功能完整性，重要性极高。
（5）使用这个软件的典型场景
编写飞书机器人核心服务代码，实现工单通知的自动推送
在本地 IDE 中调试自然语言解析模块，测试"创建工单"等指令的识别准确率
通过浏览器访问系统配置页面，测试飞书 Webhook 消息的接收与响应
查看服务器日志，排查飞书消息发送失败的原因
（6）使用本软件/服务的环境：
笔记本电脑：在宿舍/实验室使用 IntelliJ IDEA 编写 Java 代码
浏览器：通过 Chrome 访问本地 Tomcat 服务进行功能测试
飞书桌面端/手机端：在飞书中与机器人对话，测试消息解析和卡片推送
手机移动网络：外出时通过手机测试飞书消息的实时接收
（7）生活/工作情况：软件工程专业大三学生，课程设计项目团队成员之一。平时有专业课学习任务，课余时间投入项目开发。每周固定时间与团队成员开会沟通进度，遇到问题通过线上协作解决。开发环境为 Windows + JDK 8 + Tomcat + MySQL。

（8）知识层次和能力：

教育程度：本科在读，软件工程专业
对电脑熟悉程度：熟练使用开发工具和命令行，能独立搭建开发环境
对万维网熟悉程度：熟悉 HTTP 协议和 Web 开发基础，了解 RESTful API 设计
技术栈：Java、Servlet、JSP、MySQL、飞书开放平台 API、基础的自然语言处理

（9）用户的动机、目的和困难：

动机：完成课程设计任务，锻炼工程实践能力，通过团队协作构建一个有实际价值的系统
目的：在第一阶段冲刺中高质量完成飞书集成、工单管理和自然语言解析三个核心模块
困难：
飞书开放平台 API 文档较多，需要时间理解各个接口的调用方式和参数格式
长连接 WebSocket 模式与 HTTP 回调模式的切换和兼容处理较复杂
中文自然语言指令的解析存在歧义，规则匹配需要不断调试优化
open_id 映射表需要手动维护，新增工程师时代码需要重新部署

（10）用户的偏好：
偏好清晰的代码结构和详细的注释，便于团队成员阅读和维护
喜欢通过日志输出调试信息，方便定位问题
希望配置信息与代码分离，修改参数不需要重新编译
对中文界面和中文注释更习惯，便于团队协作交流

二、用户场景/故事（Story）
场景一：实现飞书机器人推送工单通知（成功场景）
目标：当系统中产生新的维修工单时，自动通过飞书机器人将工单详情以交互式卡片的形式推送给被指派的工程师。
过程：

1. 需求分析：小周阅读团队整理的需求文档，明确工单通知的触发时机和推送内容要求——包含工单编号、设备名称、位置、优先级、描述等字段。
2. 接口调研：查阅飞书开放平台文档，找到"发送交互式卡片"接口 im.message.create，了解 receive_id_type 和卡片 JSON 的格式规范。
3. 代码编写：在 [FeishuService.java](file:///C:/Users/xxhht/IdeaProjects/yunwei/src/main/java/com/yunwei/util/FeishuService.java) 中编写 sendInteractiveCard() 方法，实现 HTTP POST 请求调用飞书 API，并添加 buildSimpleCard() 方法用于构造卡片 JSON。
4. 工程师映射：在代码中定义 ENGINEER_OPEN_ID 映射表，将"赵工程师"等中文姓名与对应的飞书 open_id 关联起来，通过 resolveAssignToOpenId() 方法实现姓名到 ID 的解析。
5. 本地测试：小周在飞书中向机器人发送测试消息，观察控制台日志输出，确认 senderId 被正确解析。随后手动触发工单创建流程，验证飞书卡片是否成功推送到指定工程师。
6. 功能验证：经过多次调试，飞书卡片成功推送，工程师在手机端可以直接看到工单详情，点击"接单"按钮还能触发后续操作，功能达到预期。
   场景二：自然语言指令解析失败（失败场景）
   目标：让用户通过飞书自然语言对话（如"帮我创建一个维修工单"）来操作系统，而不需要记忆复杂的命令格式。
   过程：
7. 编写解析规则：小周在 [FeishuNLParser.java](file:///C:/Users/xxhht/IdeaProjects/yunwei/src/main/java/com/yunwei/util/FeishuNLParser.java) 中编写关键词匹配规则，尝试识别"创建工单"、"派给"、"设备"等关键词。
8. 初步测试成功：测试标准句式"创建维修工单，设备：空压机，位置：A区，派给赵工程师"，解析器成功提取了类型、设备、位置和指派人。
9. 发现问题：当用户输入"帮我整个工单呗，就那个空压机有点问题，让老赵去看看"这种口语化表达时，解析器无法正确识别——"整个"没有被匹配为"创建"，"老赵"也没有映射到"赵工程师"。
10. 规则扩展：小周添加了更多同义词匹配规则（"整个"→"创建"，"老赵"→"赵工程师"），并引入模糊匹配逻辑。
11. 新问题出现：然而，更多的规则反而引入了歧义——当用户说"查询一下上周的工单"时，解析器误判为"创建工单"，因为包含了"工单"关键词。
12. 暂时方案：小周调整了解析优先级，先检查是否包含查询类关键词，再判断创建类指令。同时在系统日志中增加了 NLParser 的详细输出，便于后续优化。目前支持标准格式的指令解析，口语化表达的准确率仍需在后续迭代中提升。

总结
第一阶段的三个核心任务——飞书机器人集成、工单管理系统、自然语言指令解析——已基本完成核心功能。飞书集成实现了消息的双向通信和交互式卡片推送；工单管理系统提供了从创建、派单到完成的全流程管理；自然语言解析支持标准指令的识别。
后续改进方向包括：将工程师 open_id 映射从硬编码改为数据库表管理，以支持动态增删；进一步优化自然语言解析，引入 LLM 大模型提升口语化指令的理解能力；完善异常处理和日志记录，提升系统的稳定性和可维护性。
通过第一阶段的开发实践，我对飞书开放平台 API、Java Web 开发模式以及团队协作流程都有了更深的理解，为后续阶段打下了良好的基础。