01 认识项目与拆需求：先说明要做什么
01 认识项目与拆需求：先说明要做什么
本章你会做出什么
你还不会写页面也没关系。本章先将一个模糊的“做个后台系统”拆成明确的角色、状态、页面和接口。以后每写一个功能，都能知道它服务于哪一步业务。
先理解三个概念
1. 业务场景
业务场景是现实中为什么需要系统。公司员工的电脑连不上网络时，如果只在群里留言，问题容易遗漏。工单系统让每个问题拥有编号、负责人、处理进度和历史记录。
2. 角色与权限
角色表示一类用户，权限表示他们能执行的动作。主管可以分配任务，但普通提单用户不应该分配别人的工单。
3. 状态流转
一张工单从创建到结束会经历固定状态。状态流转不能任意跳转，否则“未处理就关闭”会导致统计和责任追踪失真。
本章最终目录变化
本章先在纸上或笔记文件中完成需求，不创建源代码：
servicedesk-practice/
notes/
requirements.md # 可选：保存本章表格和流程图
一步一步操作
第 1 步：写出核心流程
将系统最重要的成功路径固定下来：
flowchart LR
A["用户提交工单<br/>PENDING 待受理"] --> B["主管分配处理人<br/>PROCESSING 处理中"]
B --> C["处理人提交解决结果<br/>WAITING_CONFIRM 待确认"]
C --> D["用户确认完成<br/>CLOSED 已关闭"]
A --> E["创建人取消<br/>CANCELLED 已取消"]
C --> B
退回箭头表示：用户认为问题没有解决时，可把“待确认”退回“处理中”。
第 2 步：确定四种角色
| 角色代码 | 页面上显示的名字 | 主要任务 |
|---|---|---|
USER |
提单用户 | 新建工单、查看本人提交的工单、确认或退回结果 |
AGENT |
处理人员 | 查看分配给自己的工单、提交解决结果 |
SUPERVISOR |
服务主管 | 查看全部工单、分配处理人、查看看板 |
ADMIN |
系统管理员 | 管理账号、角色权限和分类，也可查看全部工单 |
第 3 步：做权限表
| 能力 | USER |
AGENT |
SUPERVISOR |
ADMIN |
|---|---|---|---|---|
| 创建工单 | 是 | 是 | 是 | 是 |
| 查看本人创建工单 | 是 | 是 | 是 | 是 |
| 查看本人负责工单 | 否 | 是 | 是 | 是 |
| 查看全部工单 | 否 | 否 | 是 | 是 |
| 分配工单 | 否 | 否 | 是 | 是 |
| 处理工单 | 否 | 是 | 是 | 是 |
| 查看运营看板 | 否 | 是 | 是 | 是 |
| 管理用户、角色、分类 | 否 | 否 | 否 | 是 |
后来代码中会将这些能力保存为权限码，例如：
ticket:view_own
ticket:view_assigned
ticket:view_all
ticket:assign
ticket:handle
dashboard:view
system:manage
第 4 步：固定工单状态和动作
| 当前状态 | 谁可操作 | 动作代码 | 新状态 |
|---|---|---|---|
PENDING 待受理 |
主管/管理员 | 分配负责人 | PROCESSING |
PENDING 待受理 |
创建人 | CANCEL |
CANCELLED |
PROCESSING 处理中 |
处理人或有权主管 | SUBMIT_RESOLUTION |
WAITING_CONFIRM |
WAITING_CONFIRM 待确认 |
创建人 | CONFIRM_CLOSE |
CLOSED |
WAITING_CONFIRM 待确认 |
创建人 | REOPEN |
PROCESSING |
第 5 步：列出页面
| 页面 | 面向角色 | 主要作用 |
|---|---|---|
| 登录页 | 所有人 | 使用账号密码登录 |
| 工作台看板 | 处理人员、主管、管理员 | 查看总量、状态、分类、趋势与 SLA |
| 我的工单 | 所有人 | 查看本人创建的工单并新建 |
| 工单中心 | 处理人员、主管、管理员 | 查看负责或全部工单 |
| 新建工单 | 所有人 | 填写标题、分类、优先级、描述 |
| 工单详情 | 有数据访问权的人 | 查看时间线、评论并执行当前可用动作 |
| 用户/角色/分类管理 | 管理员 | 管理系统基础配置 |
| 403 / 404 | 所有人 | 提示无权限或地址不存在 |
第 6 步：列出首版接口
所有路径统一以 /api/v1 开始：
| 目的 | 方法和路径 |
|---|---|
| 登录、恢复身份 | POST /auth/login、GET /auth/profile |
| 获取分类 | GET /categories |
| 工单列表、新建 | GET /tickets、POST /tickets |
| 详情、编辑待受理工单 | GET /tickets/:id、PATCH /tickets/:id |
| 分配与状态动作 | POST /tickets/:id/assign、POST /tickets/:id/transition |
| 评论 | POST /tickets/:id/comments |
| 看板 | GET /dashboard/overview |
| 管理配置 | /admin/users、/admin/roles、/admin/categories |
第 7 步：明确不做什么
个人求职项目最怕范围不断扩大。首版不实现：
- 附件上传、实时聊天、短信或邮件通知。
- 多租户、审批流、微服务、移动端。
- WebSocket 和部署平台配置。
你只额外实现一个有业务意义的亮点：按优先级计算 SLA 截止时间，并提示即将超时或已超时。
关键文件完整代码：你的需求笔记
你可以新建 notes/requirements.md，复制以下内容作为开发合同：
# ServiceDesk 需求基线
## 主流程
用户创建 PENDING -> 主管分配 PROCESSING -> 处理人提交结果 WAITING_CONFIRM -> 用户确认 CLOSED
补充分支：创建人在 PENDING 可取消；创建人在 WAITING_CONFIRM 可退回 PROCESSING。
## 角色
USER、AGENT、SUPERVISOR、ADMIN。
## 首版功能
- 登录鉴权、按权限码显示页面和按钮，并由后端再次拦截。
- 工单创建、待受理编辑、列表分页筛选、详情评论和状态时间线。
- 用户、角色权限和分类管理。
- 运营看板与 SLA 标签。
## 不在首版范围
附件、通知、导出、实时通信、部署上线。
启动并验证
本章无需运行程序。请尝试不看文档，回答这四个问题：
- 谁创建工单？
- 谁分配工单？
- 工单什么时候处于
WAITING_CONFIRM？ - 为什么用户页面不显示“分配负责人”按钮，同时后端仍需校验？
如果你能讲出 创建 -> 分配 -> 处理 -> 确认关闭 并说出四个角色，本章通过。
常见报错与原因
| 误区 | 后果 | 修正方式 |
|---|---|---|
| 一开始就加入十多个功能 | 功能做不完，无法演示 | 先固定主流程和 SLA |
| 只考虑页面，不考虑谁能访问数据 | 接口出现越权读取 | 同时设计查看权限和操作权限 |
| 前端直接传任意目标状态 | 流程容易乱跳 | 前端提交动作，后端决定下一状态 |
本章完成清单
- 我写下了四种角色和权限表。
- 我确定了五种状态和允许的流转动作。
- 我列出了首版页面与接口。
- 我明确首版不做的功能。
- 我能用自己的语言讲清核心闭环。
面试时这一章能怎么讲
我没有选择只有增删改查的博客，而是选择工单业务，因为它能体现角色权限、状态流转、列表筛选和统计分析。我先限定五种状态和四类角色，让每个页面和接口都围绕可演示的业务闭环建设。