设备运维工单平台项目说明
设备运维工单平台的业务、角色、状态流转、技术选择和交付标准。
完整学习目录 · 14 篇
本篇目录
这是为 Java 实习准备设计的原创教学项目。一个园区或实验室需要记录设备故障：使用者报修，管理员分派工程师，工程师填写处理结果，报修人验收，负责人查询处理记录与统计。设备数据采用模拟记录，不需要硬件开发经验或真实设备接入。
项目的完整性来自可用的业务流程、权限、数据一致性、测试和部署。前期从少量普通 Java 类开始，最终完成可演示的 Web 应用；每一版延续同一套业务规则。
为什么选择这个项目 #
Java 实习常见能力可以映射为具体项目练习：需求与设计对应角色和业务规则，编码与缺陷修复对应完整工单闭环，数据库能力对应关联查询与聚合，工程交付对应测试、打包和部署。故障知识库可在主线完成后作为选做扩展。
教学实现由我们逐步设计，不把现成项目更名后当作独立作品。联网参考采用 Spring REST 官方示例 的最小接口学习方式；Spring Petclinic 留作后期阅读参考，用于观察一个完整 Spring 示例的组织方式。它们不替代本项目的业务设计和自己写代码的过程。
角色和完整业务 #
| 角色 | 能做什么 | 关键边界 |
|---|---|---|
| 报修人 REPORTER | 查看设备；提交、查看自己的工单；评论；验收或退回处理结果 | 不能查看或修改别人的工单；不能自行指定处理人 |
| 工程师 ENGINEER | 查看分配给自己的工单；评论；填写处理结果 | 不能处理未分配给自己的工单，也不能替报修人验收 |
| 管理员 ADMIN | 维护设备；查看全量工单；给待派单工单分配工程师；查看统计 | 第一版不代替报修人验收，不支持任意修改状态 |
三个角色采用固定枚举和明确规则。第一版不提供公开注册、动态权限配置或复杂组织关系；演示账号通过初始化数据生成。进入数据库阶段再加入用户和角色，不在第一课一次写完。
工单状态约定为：
OPEN 待派单 → IN_PROGRESS 处理中 → RESOLVED 待验收 → CLOSED 已关闭
↑ │
└──── 验收退回 ────┘管理员只能对 OPEN 工单派单；分配成功后进入 IN_PROGRESS。工程师提交非空处理说明后进入 RESOLVED。报修人可以确认关闭，或填写退回原因返回 IN_PROGRESS。CLOSED 在第一版中不再变更。评论不会自动改变状态。
状态迁移通过 assign、resolve、accept、reject 等业务方法表达，不提供任意设置状态的公共接口。关键操作写入操作记录，并与工单更新处于同一个数据库事务。
三个交付版本 #
| 版本 | 必须完成 | 能展示的能力 |
|---|---|---|
| v0.1 Java 练习版 | 工单对象、创建与查询、状态筛选、简单存档、按职责拆类 | 面向对象、集合、异常、IO、接口；确认能自己写 |
| v0.5 Web 开发版 | MySQL 持久化、Spring MVC 接口、MyBatis、完整流转、分页筛选、评论与操作记录 | HTTP、SQL、分层、事务、接口联调；仅在本地学习环境运行 |
| v1.0 可投递版 | 登录与三角色权限、并发派单保护、核心测试、简单页面、运行与部署说明、演示数据 | 一套能运行、能解释、能独立修改和交付的 Java 后端项目 |
简单页面包括登录、工单列表与创建、工单详情与操作、设备管理四类页面。页面可以提供骨架，学习重点是请求参数、接口结果、权限和错误处理。图表美化不作为完成主线的前提。
技术选择 #
| 用途 | 计划采用 | 选择理由与实施边界 |
|---|---|---|
| Java | Java 21 | 统一学习和运行环境；先学对象与业务逻辑，再按需要认识较新语法 |
| 构建 | Maven 与 Maven Wrapper | 让依赖与构建命令可复现；在第 3 周学习包结构和构建 |
| Web | Spring Boot 4.1.x、Spring MVC | 使用注解、JSON 和可执行应用；按正式版本的文档教学 |
| 数据访问 | MyBatis Spring Boot Starter 4.0.x | 保留手写 SQL 的训练，先学 JDBC 再理解框架省去了什么 |
| 数据库 | MySQL；独立部署环境计划 8.4 系列 | 现有 8.0 环境可先做 SQL 练习；项目数据库单独建立，不迁移其他数据 |
| 登录与权限 | Spring Security，Session Cookie | 先做同源应用的认证授权；保留 CSRF 防护，使用框架密码编码器 |
| 测试 | JUnit Jupiter 与 Spring 配套测试组件 | 具体依赖跟随所选 Boot 版本，验证业务行为与数据库一致性 |
| 交付 | Git、日志、Linux、Docker Compose | 形成可复现的开发和部署过程，容器化放在业务完成之后 |
2026 年 10 月 12 日访问的 Spring Boot 系统要求 页面显示 4.1.1，要求 Java 至少 17；Java 21 在该兼容范围内。MyBatis 官方兼容表 将 Starter 4.0 对应到 Spring Boot 4.0 及以上。正式开建 Web 版时重新核对并固定补丁版本，不选 milestone 或 snapshot，也不把旧 Boot 2/3 教程的依赖直接混入。
开始前分别检查终端 JDK、IDEA 项目 SDK 和 Maven 使用的 Java。第3周统一为 Java 21；数据库阶段用 SELECT VERSION() 核对实际服务端版本。命令不在 PATH 中时先查安装位置，不据此断定工具未安装。
数据和接口设计 #
开始时只有 Ticket 的编号和标题，后续随课程逐步扩充。Web 版预计包含以下六张主要表：
| 表 | 主要内容 |
|---|---|
| app_user | 用户编号、唯一用户名、密码哈希、固定角色、启用状态 |
| device | 设备编号、唯一设备编码、名称、位置、是否启用 |
| ticket | 工单编号、标题、描述、设备、报修人、处理人、状态、版本号、创建/更新时间 |
| ticket_comment | 工单、评论作者、内容、时间 |
| ticket_action_log | 工单、操作者、动作、前后状态、说明、时间 |
| ticket_resolution | 工单、工程师、每次处理说明、时间；退回后可再次提交 |
保留设备停用状态，不直接删除被历史工单引用的设备。用户停用也保留历史记录。展示时间与数据库时间的转换在接口设计时明确约定，列表使用固定排序并加编号作为同时间下的排序依据。
核心接口草案：
| 请求 | 功能 |
|---|---|
| POST /api/tickets | 创建自己的报修单 |
| GET /api/tickets | 在当前用户可见范围内分页、筛选 |
| GET /api/tickets/{id} | 查看有权限访问的工单详情 |
| POST /api/tickets/{id}/assign | 管理员派单，携带期望版本与工程师编号 |
| POST /api/tickets/{id}/resolve | 当前处理工程师提交处理说明 |
| POST /api/tickets/{id}/accept | 报修人验收关闭 |
| POST /api/tickets/{id}/reject | 报修人说明原因并退回 |
| POST /api/tickets/{id}/comments | 有访问权限的用户发表评论 |
身份来自登录会话，不接受请求体中伪造的报修人或操作人编号。分页限制单页大小；不存在、参数错误、未登录、无权操作、版本冲突分别返回清楚的结果。设备、用户与登录接口在相应课程补齐，不在第一课背整张接口表。
最重要的工程练习 #
避免重复派单。 两名管理员同时看到 OPEN 工单时，不能后一次静默覆盖前一次。用包含编号、OPEN 状态和期望版本的数据库条件更新，并检查受影响行数；成功时版本递增并写日志，失败时返回冲突。状态更新和日志写入共用事务。用两个从相同初始版本发起的请求验证结果。这个问题不需要先引入分布式锁。
测试业务边界。 核心用例包括有效创建、空标题、无效设备、越权查询、错误处理人、非法状态迁移、重复验收、并发派单以及日志写入失败后的事务回滚。单元测试验证规则，接口测试验证请求行为，真实 MySQL 集成测试验证数据库约束与事务；不能只靠模拟对象证明事务和锁正确。
定位和修复问题。 至少保留一个真实开发错误的复现步骤、预期与实际结果、原因、修复和回归测试。日志应能定位请求与业务异常；数据库账号和密钥不进入源码。
交付给另一个使用者。 README 应包含版本、启动命令、配置示例、初始化数据、测试、演示流程和已知限制。演示使用虚构账号与设备；部署练习包括启动、停止、查看日志、健康检查、备份与恢复。
扩展只选有用的部分 #
| 扩展 | 加入条件 | 可验证的结果 |
|---|---|---|
| SQL 统计看板 | 核心接口与权限完成 | 按设备/状态统计，处理时长口径清楚，关联和聚合结果可核对 |
| Redis 缓存 | 能解释查询成本与一致性需求 | 只缓存一个统计查询，验证过期、失效和缓存不可用时的处理 |
| 有界线程池任务 | 已理解线程、共享状态和异常 | 用小型任务演示并行、失败和队列容量，解释后台任务与同步请求的差别 |
| 故障知识库 | v1.0 验收通过 | 先做文章维护和关键词检索，再考虑模型辅助 |
| AI 故障建议 | 知识库可用且不挤占投递 | 只根据有权限读取的资料给建议与出处；无依据或调用失败时明确提示，不自动执行派单和验收 |
AI 阶段如接入外部模型，会在选择服务时确认费用与数据范围；用模拟资料开发。用一组预先整理的故障问题检查命中、无答案和超时处理，再决定是否需要 RAG。它是求职项目的可选扩展，不等同于算法训练经验。
第一版不加入微服务拆分、Kubernetes、消息队列、复杂工作流、真实硬件通信或支付。若后续目标岗位明确要求某项，再通过有业务理由的小实验补充。
完成标准 #
- 三种账号能演示报修、派单、处理、验收及退回，权限检查在服务端生效。
- 工单重启后不丢失，操作记录完整，并发派单不会互相覆盖。
- 核心异常场景有验证，自动测试可重复运行。
- 能按说明在另一环境启动、查看日志并恢复测试数据库备份。
- 能独立修改一个业务规则，解释 SQL、事务、接口、权限和一次排错过程。
- 简历只描述实际实现和实际测得的结果，不编造用户规模、吞吐量或企业上线经历。