项目文档 · 设备运维工单平台
工单项目需求与开发计划
业务规则、已实现功能、待办事项与开发里程碑。
项目文档目录 · 4 篇
本篇目录
核对日期：2026-10-13。当前：v0.1 开发中。
1. 项目背景 #
以园区或实验室的设备故障为场景：报修人提交故障，管理员派给工程师，工程师处理后交给报修人验收。使用模拟数据，不接入真实硬件。
最终希望能够追踪“谁提交了问题、谁负责处理、当前处理到哪一步、为什么发生状态变化”。
2. 目标用户（后续 Web 阶段） #
| 角色 | 计划权限 |
|---|---|
| 报修人 REPORTER | 提交工单、查看自己的工单、评论、验收通过或驳回 |
| 工程师 ENGINEER | 查看分给自己的工单、评论、提交处理结果 |
| 管理员 ADMIN | 管理设备、查看工单、派单 |
当前没有用户实体、登录或权限检查。assign 接受正整数工程师编号，不会验证这个人是否存在或具有工程师角色。
3. 当前需求及验收口径 #
| 编号 | 需求 | 当前状态与验收口径 |
|---|---|---|
| R01 | 创建工单 | 已实现；编号 > 0；标题非 null，trim 后非空且 length ≤ 50；初始 OPEN、处理人 null |
| R02 | 修改标题 | 已实现；沿用创建时的标题规则；失败保留原标题 |
| R03 | 管理工单 | 已实现；拒绝 null 和重复编号；重复添加不能覆盖旧工单 |
| R04 | 编号查询 | 已实现；找到返回工单引用，找不到返回 null |
| R05 | 状态筛选 | 已实现；拒绝 null 状态；无匹配返回空列表；结果按插入顺序排列 |
| R06 | 派单 | 已实现；工程师编号 > 0，仅 OPEN 可派单；成功更新处理人和状态；失败保留原值 |
| R07 | 单张工单写文件 | Demo 已实现；UTF-8 保存编号、标题、状态、处理人及 count |
| R08 | 文件读回字段 | Demo 已实现；UTF-8 读回字符串，检查必要字段并解析编号、枚举与处理人 |
| R09 | 校验并恢复工单 | 已实现；Ticket.restore 复用构造器校验，检查状态与处理人一致性，并保留原编号、状态及处理人 |
| R10 | 服务集合存取 | 待实现；保存多张工单，完整加载后恢复服务；坏记录不得被静默忽略 |
标题长度当前按 Java String.length() 计算，即 UTF-16 代码单元数量；没有按用户感知字符数计数。
4. 状态规则 #
| 操作 | 前置状态 | 成功后的状态 | 实现状态 |
|---|---|---|---|
| 创建 | 无 | OPEN | 已实现 |
| 派单 | OPEN | IN_PROGRESS | 已实现 |
| 提交处理结果 | IN_PROGRESS | RESOLVED | 待实现 |
| 验收通过 | RESOLVED | CLOSED | 待实现 |
| 验收驳回 | RESOLVED | IN_PROGRESS | 待实现 |
RESOLVED、CLOSED 已定义为枚举值，恢复入口可以重建这两种状态，但相应的业务流转方法尚未实现。后续关闭后的工单不再进行业务变更；当前 rename 只有标题校验，完整的关闭限制尚未实现。
业务状态通过具有明确含义的方法修改，避免开放任意 setStatus 绕过规则。后续 Web 阶段同时检查操作者权限，并记录操作日志。
5. 开发里程碑 #
| 阶段 | 工作内容 | 完成标准 |
|---|---|---|
| v0.1 Java 基础业务 | 对象封装、集合、文件持久化、异常处理 | 多张工单能够保存并恢复，异常数据有明确反馈，业务校验不会被恢复入口绕过 |
| v0.5 Web 核心 | Maven、MySQL、Spring Boot、MyBatis、完整状态流、分页、评论、操作日志 | 本地接口能跑通报修到验收，数据库持久化，状态变更和日志具有事务一致性 |
| v1.0 实习展示 | 三角色登录权限、并发派单防护、自动化测试、简单页面、部署说明 | 从干净环境按文档启动，权限与核心异常场景通过验证，可演示完整流程 |
后续依赖版本在进入对应阶段时核对并固定。当前没有数据库表和 REST 接口实现，因此这里的阶段规划不能作为现有功能演示说明。
不纳入当前范围：微服务、Kubernetes、支付、真实设备通信。可选扩展在核心流程完成后安排。
6. 下一步任务 #
字段解析和受约束的对象恢复入口已完成，接下来：
- 将文件操作抽取到持久化类，逐步接入 TicketService。
- 读取并校验 count，支持多张工单及重复编号检查。
- 明确首次启动缺文件和存档损坏的不同处理方式；加载失败不以空集合覆盖原存档。
- 增加可重复运行的自动化测试，再进入构建工具、数据库与 Web 阶段。
以上四项尚未完成，按教学进度逐项实现。
7. 文档演进 #
当前需求、设计、运行验收文档随源码维护。进入数据库阶段补表结构、约束与迁移说明；进入 Web 阶段补请求响应、错误码与权限矩阵；进入部署阶段补环境变量、启动方式和数据备份恢复步骤。