356 lines
15 KiB
Markdown
356 lines
15 KiB
Markdown
# 工单需求规格说明
|
||
|
||
日期：2026-05-22
|
||
|
||
## 1. 背景
|
||
|
||
`rdms-project` 当前承载项目、产品、需求、执行、任务等核心交付对象。现有代码中产品需求、项目需求已经具备 `sourceType` / `sourceBizId` 来源字段，可以承接来自工单的需求派生关系；执行和任务也已经形成“项目需求 -> 执行 -> 任务”的后续交付链路。
|
||
|
||
本需求新增内部工单能力。工单作为独立业务对象存在，不复用需求、执行或任务主表。工单用于记录内部用户提交的诉求，经工单负责人受理后，可按归属类型派生产品需求或项目需求，并通过现有需求链路继续流转到执行、任务。
|
||
|
||
## 2. 目标
|
||
|
||
1. 支持内部用户创建普通工单或父工单。
|
||
2. 支持父工单逐步拆分子工单，父工单只汇总，不直接处理。
|
||
3. 支持普通工单、子工单作为最小处理单位，由指定工单负责人受理、拒绝、处理和关闭。
|
||
4. 支持工单单归属到一个产品或一个项目。
|
||
5. 支持产品工单派生产品需求、项目工单派生项目需求。
|
||
6. 支持有派生需求的工单在全部需求完成后自动关闭。
|
||
7. 支持无派生需求的工单由工单负责人手动关闭。
|
||
|
||
## 3. 非目标
|
||
|
||
1. 本期不做外部客户工单，不保留 `sourceChannel`、`externalCustomerName`、`externalContact` 等外部来源字段。
|
||
2. 本期不做工单编号 `ticketNo`。
|
||
3. 工单不能直接派生执行或任务。
|
||
4. 父工单不能受理、拒绝、派生需求或手动关闭。
|
||
5. 本期不引入流程引擎，不做可配置审批流。
|
||
6. 本期不自动判断工单是否涉及多个产品/项目，也不自动判断归属产品或项目；这些由录入人员人工选择。
|
||
|
||
## 4. 核心概念
|
||
|
||
### 4.1 工单形态
|
||
|
||
使用 `ticketMode` 表达工单形态：
|
||
|
||
| 值 | 含义 | 是否可处理 | 说明 |
|
||
|---|---|---|---|
|
||
| `single` | 普通工单 | 是 | 单归属工单，不挂父工单 |
|
||
| `parent` | 父工单 | 否 | 原始诉求汇总单，可持续拆分子工单 |
|
||
| `child` | 子工单 | 是 | 挂在父工单下的最小处理单位 |
|
||
|
||
不使用 `isParent`。`ticketMode` 比布尔字段更准确，可以区分普通工单、父工单和子工单，避免在父工单尚未创建子工单时无法识别其形态。
|
||
|
||
### 4.2 归属类型
|
||
|
||
普通工单和子工单必须单归属：
|
||
|
||
| `belongType` | 归属对象 | 可派生对象 | 后续链路 |
|
||
|---|---|---|---|
|
||
| `product` | 一个产品 | 产品需求 | 产品需求 -> 指派项目 -> 项目需求 -> 执行 -> 任务 |
|
||
| `project` | 一个项目 | 项目需求 | 项目需求 -> 执行 -> 任务 |
|
||
|
||
父工单不填写 `belongType`、`productId`、`projectId`。
|
||
|
||
## 5. 业务流程
|
||
|
||
### 5.1 总流程图
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A([开始]) --> B[录入人员创建工单]
|
||
B --> C{ticketMode}
|
||
|
||
C -->|parent| P1[父工单: splitting]
|
||
P1 --> P2[列表操作列拆分子工单]
|
||
P2 --> C1[创建子工单: pending_accept]
|
||
P1 --> P3{是否存在子工单且全部为终态}
|
||
P3 -->|否| P1
|
||
P3 -->|是| P4[父工单: closed]
|
||
P4 --> Z([结束])
|
||
|
||
C -->|single| S1[普通工单: pending_accept]
|
||
C1 --> S2[工单负责人待处理]
|
||
S1 --> S2
|
||
S2 --> D{是否受理}
|
||
D -->|否| R[工单: rejected]
|
||
R --> Z
|
||
D -->|是| E[工单: processing]
|
||
|
||
E --> F{是否派生需求}
|
||
F -->|否| G[负责人填写处理结论并手动关闭]
|
||
G --> H[工单: closed]
|
||
H --> I[触发父工单汇总检查]
|
||
I --> Z
|
||
|
||
F -->|是| J{归属类型}
|
||
J -->|product| K[派生一个或多个产品需求]
|
||
J -->|project| L[派生一个或多个项目需求]
|
||
K --> M[等待派生需求全部完成]
|
||
L --> M
|
||
M --> N{全部派生需求完成}
|
||
N -->|否| E
|
||
N -->|是| O[系统自动关闭工单: closed]
|
||
O --> I
|
||
```
|
||
|
||
### 5.2 父工单流程
|
||
|
||
1. 录入人员创建父工单，状态为 `splitting`。
|
||
2. 父工单只记录原始诉求和附件，不进入处理队列。
|
||
3. 工单列表查询的操作列为父工单提供“拆分子工单”入口。
|
||
4. 录入人员可以持续新增子工单。
|
||
5. 父工单至少存在一个子工单，且所有子工单均进入终态后，系统自动关闭父工单。
|
||
6. 父工单关闭后不再作为处理对象，但可继续作为历史汇总查看。
|
||
|
||
### 5.3 普通工单 / 子工单流程
|
||
|
||
1. 创建后进入 `pending_accept`。
|
||
2. 工单负责人判断是否受理。
|
||
3. 不受理则进入 `rejected`，需要填写拒绝原因。
|
||
4. 受理后进入 `processing`。
|
||
5. 处理中可以派生需求，也可以在无派生需求时填写处理结论并手动关闭。
|
||
6. 一旦存在派生需求，工单不能手动关闭，必须等待全部派生需求完成后自动关闭。
|
||
|
||
## 6. 状态模型
|
||
|
||
### 6.1 父工单状态
|
||
|
||
| 状态 | 含义 | 进入方式 | 退出方式 |
|
||
|---|---|---|---|
|
||
| `splitting` | 拆分中 / 汇总中 | 创建父工单 | 所有子工单终态后自动关闭 |
|
||
| `closed` | 已关闭 | 系统自动关闭 | 终态 |
|
||
|
||
父工单不允许进入 `pending_accept`、`rejected`、`processing`。
|
||
|
||
### 6.2 普通工单 / 子工单状态
|
||
|
||
| 状态 | 含义 | 进入方式 | 退出方式 |
|
||
|---|---|---|---|
|
||
| `pending_accept` | 待受理 | 创建普通工单或子工单 | 受理或拒绝 |
|
||
| `rejected` | 已拒绝 | 工单负责人拒绝 | 终态 |
|
||
| `processing` | 处理中 | 工单负责人受理 | 手动关闭或自动关闭 |
|
||
| `closed` | 已关闭 | 手动关闭或派生需求全部完成后自动关闭 | 终态 |
|
||
|
||
终态包括 `rejected`、`closed`。
|
||
|
||
### 6.3 自动关闭规则
|
||
|
||
1. 普通工单 / 子工单存在派生需求时，只有全部派生需求完成后才自动关闭。
|
||
2. 普通工单 / 子工单不存在派生需求时，允许工单负责人手动关闭，必须填写 `closeResult`。
|
||
3. 父工单至少存在一个子工单，且所有子工单均为 `rejected` 或 `closed` 后，自动关闭。
|
||
4. 父工单不直接检查需求完成情况，只汇总子工单终态。
|
||
|
||
## 7. 数据模型
|
||
|
||
### 7.1 工单主表
|
||
|
||
建议表名：`rdms_ticket`
|
||
|
||
| 字段 | 类型建议 | 必填规则 | 说明 |
|
||
|---|---|---|---|
|
||
| `id` | `bigint` | 是 | 主键 |
|
||
| `parent_id` | `bigint` | 否 | 父工单 ID；`child` 必填 |
|
||
| `ticket_mode` | `varchar(32)` | 是 | `single` / `parent` / `child` |
|
||
| `title` | `varchar(255)` | 是 | 工单标题 |
|
||
| `description` | `text` | 否 | 工单描述，支持富文本 |
|
||
| `ticket_type` | `varchar(32)` | 是 | 工单类型，字典 |
|
||
| `priority` | `varchar(32)` | 否 | 优先级，建议复用需求优先级字典 |
|
||
| `status_code` | `varchar(32)` | 是 | 工单状态 |
|
||
| `submitter_id` | `bigint` | 是 | 提交人用户 ID |
|
||
| `submitter_nickname` | `varchar(64)` | 否 | 提交人昵称快照 |
|
||
| `owner_id` | `bigint` | `single` / `child` 必填 | 工单负责人用户 ID |
|
||
| `owner_nickname` | `varchar(64)` | 否 | 工单负责人昵称快照 |
|
||
| `belong_type` | `varchar(32)` | `single` / `child` 必填 | `product` / `project` |
|
||
| `product_id` | `bigint` | 产品工单必填 | 归属产品 ID |
|
||
| `project_id` | `bigint` | 项目工单必填 | 归属项目 ID |
|
||
| `accept_time` | `datetime` | 否 | 受理时间 |
|
||
| `reject_reason` | `varchar(500)` | 拒绝时必填 | 拒绝原因 |
|
||
| `close_time` | `datetime` | 否 | 关闭时间 |
|
||
| `close_result` | `varchar(1000)` | 手动关闭时必填 | 处理结论 |
|
||
| `attachments` | `json` | 否 | 附件列表，沿用 `AttachmentItem` |
|
||
|
||
审计字段、逻辑删除字段复用现有 `BaseDO` 风格。
|
||
|
||
### 7.2 工单需求关联表
|
||
|
||
建议表名：`rdms_ticket_requirement_link`
|
||
|
||
| 字段 | 类型建议 | 必填规则 | 说明 |
|
||
|---|---|---|---|
|
||
| `id` | `bigint` | 是 | 主键 |
|
||
| `ticket_id` | `bigint` | 是 | 工单 ID |
|
||
| `target_type` | `varchar(32)` | 是 | `product_requirement` / `project_requirement` |
|
||
| `target_id` | `bigint` | 是 | 需求 ID |
|
||
|
||
不设置 `relationType`。本期关联表只表达“该工单派生了哪些需求”。
|
||
|
||
建议唯一约束：`ticket_id + target_type + target_id`。
|
||
|
||
## 8. 需求派生规则
|
||
|
||
### 8.1 产品工单派生产品需求
|
||
|
||
适用条件：
|
||
|
||
1. `ticketMode` 为 `single` 或 `child`。
|
||
2. `belongType = product`。
|
||
3. 工单状态为 `processing`。
|
||
|
||
派生结果：
|
||
|
||
1. 创建 `ProductRequirementDO`。
|
||
2. `productId` 使用工单 `productId`。
|
||
3. `sourceType = "work_order"`。
|
||
4. `sourceBizId = ticketId`。
|
||
5. 标题、描述、优先级、附件、提出人等字段可从工单带入，并允许派生表单二次编辑。
|
||
6. 写入 `rdms_ticket_requirement_link`，`targetType = product_requirement`。
|
||
|
||
后续链路沿用现有产品需求分发到项目的能力。
|
||
|
||
### 8.2 项目工单派生项目需求
|
||
|
||
适用条件：
|
||
|
||
1. `ticketMode` 为 `single` 或 `child`。
|
||
2. `belongType = project`。
|
||
3. 工单状态为 `processing`。
|
||
|
||
派生结果：
|
||
|
||
1. 创建 `ProjectRequirementDO`。
|
||
2. `projectId` 使用工单 `projectId`。
|
||
3. `sourceType = "work_order"`。
|
||
4. `sourceBizId = ticketId`。
|
||
5. 标题、描述、优先级、附件、提出人等字段可从工单带入，并允许派生表单二次编辑。
|
||
6. 写入 `rdms_ticket_requirement_link`，`targetType = project_requirement`。
|
||
|
||
后续执行和任务沿用现有项目需求、执行、任务链路。
|
||
|
||
### 8.3 完成判定
|
||
|
||
1. 产品工单只检查由该工单派生的产品需求。
|
||
2. 项目工单只检查由该工单派生的项目需求。
|
||
3. 需求完成态应复用现有需求状态模型的终态配置，不在工单逻辑中写死具体状态码。
|
||
4. 派生需求数量大于 0 且全部完成时，系统自动关闭对应工单。
|
||
|
||
## 9. 页面与待办
|
||
|
||
### 9.1 我的提交
|
||
|
||
展示当前用户提交的工单，包括：
|
||
|
||
1. 父工单。
|
||
2. 普通工单。
|
||
3. 子工单。
|
||
|
||
建议支持按状态、工单类型、归属类型、归属对象、创建时间筛选。
|
||
|
||
### 9.2 我的待处理
|
||
|
||
展示当前用户负责的普通工单和子工单，不展示父工单。
|
||
|
||
筛选条件：
|
||
|
||
1. `ownerId = 当前用户`。
|
||
2. `ticketMode in (single, child)`。
|
||
3. `statusCode in (pending_accept, processing)`。
|
||
|
||
### 9.3 父工单列表操作
|
||
|
||
工单列表查询中，父工单行需要在操作列展示“拆分子工单”入口。该入口只对父工单提交人或具备工单管理权限的用户可见。
|
||
|
||
点击后进入新增子工单表单，表单需要携带父工单上下文，并要求录入人员填写子工单的归属类型、归属产品/项目、工单负责人、工单类型等处理字段。
|
||
|
||
### 9.4 父工单汇总展示
|
||
|
||
父工单汇总展示需要包含：
|
||
|
||
1. 原始诉求信息。
|
||
2. 子工单列表。
|
||
3. 子工单归属产品/项目。
|
||
4. 子工单负责人。
|
||
5. 子工单状态。
|
||
6. 子工单派生需求数量与完成数量。
|
||
7. 父工单自动关闭结果。
|
||
|
||
## 10. 权限规则
|
||
|
||
1. 创建工单走全域权限。
|
||
2. 父工单新增子工单：父工单提交人或具备工单管理权限的用户可操作。
|
||
3. 普通工单 / 子工单受理、拒绝、手动关闭：工单负责人或具备工单管理权限的用户可操作。
|
||
4. 派生产品需求时，需要满足产品对象权限。
|
||
5. 派生项目需求时，需要满足项目对象权限。
|
||
6. 父工单不能执行受理、拒绝、派生需求、手动关闭动作。
|
||
|
||
## 11. 接口建议
|
||
|
||
接口路径建议落在 `rdms-project` 模块：
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| `POST` | `/project/tickets` | 创建普通工单或父工单 |
|
||
| `POST` | `/project/tickets/{parentId}/children` | 父工单新增子工单 |
|
||
| `GET` | `/project/tickets/my-submitted/page` | 我的提交 |
|
||
| `GET` | `/project/tickets/my-pending/page` | 我的待处理 |
|
||
| `GET` | `/project/tickets/{id}` | 工单详情 |
|
||
| `POST` | `/project/tickets/{id}/accept` | 受理 |
|
||
| `POST` | `/project/tickets/{id}/reject` | 拒绝 |
|
||
| `POST` | `/project/tickets/{id}/close` | 无派生需求时手动关闭 |
|
||
| `POST` | `/project/tickets/{id}/derive-product-requirement` | 派生产品需求 |
|
||
| `POST` | `/project/tickets/{id}/derive-project-requirement` | 派生项目需求 |
|
||
|
||
创建、更新类接口需要继续遵守仓库 HTTP 动词语义约定。部分动作使用语义化 `POST` 子动作接口，不引入 `PATCH`。
|
||
|
||
## 12. 校验规则
|
||
|
||
1. `ticketMode = parent` 时，`ownerId`、`belongType`、`productId`、`projectId` 必须为空。
|
||
2. `ticketMode = single` 时，`ownerId`、`belongType` 必填，且 `productId` / `projectId` 按归属类型二选一。
|
||
3. `ticketMode = child` 时，`parentId`、`ownerId`、`belongType` 必填，且父工单必须存在且 `ticketMode = parent`。
|
||
4. 产品工单必须填写 `productId`，不能填写 `projectId`。
|
||
5. 项目工单必须填写 `projectId`，不能填写 `productId`。
|
||
6. 只有 `pending_accept` 状态的普通工单 / 子工单可以受理或拒绝。
|
||
7. 只有 `processing` 状态的普通工单 / 子工单可以派生需求。
|
||
8. 有派生需求的工单不能手动关闭。
|
||
9. 无派生需求的 `processing` 工单可以手动关闭，必须填写 `closeResult`。
|
||
10. 父工单不能手动关闭。
|
||
11. 父工单至少有一个子工单，且全部子工单终态后才能自动关闭。
|
||
|
||
## 13. 错误处理
|
||
|
||
建议新增明确错误码覆盖以下场景：
|
||
|
||
1. 工单不存在。
|
||
2. 工单形态非法。
|
||
3. 父工单不能处理。
|
||
4. 子工单父级非法。
|
||
5. 工单归属类型非法。
|
||
6. 产品工单不能派生项目需求。
|
||
7. 项目工单不能派生产品需求。
|
||
8. 工单状态不允许当前动作。
|
||
9. 有派生需求的工单不能手动关闭。
|
||
10. 派生需求未全部完成，工单不能自动关闭。
|
||
|
||
## 14. 测试重点
|
||
|
||
1. 创建父工单后状态为 `splitting`，且不能受理、拒绝、派生需求、手动关闭。
|
||
2. 父工单可以持续新增多个子工单。
|
||
3. 子工单必须单归属产品或项目。
|
||
4. 普通工单 / 子工单创建后进入 `pending_accept`。
|
||
5. 工单负责人拒绝后进入 `rejected`。
|
||
6. 工单负责人受理后进入 `processing`。
|
||
7. 无派生需求的 `processing` 工单可手动关闭。
|
||
8. 有派生需求的工单不能手动关闭。
|
||
9. 产品工单只能派生产品需求。
|
||
10. 项目工单只能派生项目需求。
|
||
11. 派生需求全部完成后自动关闭工单。
|
||
12. 所有子工单终态后自动关闭父工单。
|
||
|
||
## 15. 风险与约束
|
||
|
||
1. 自动关闭依赖需求完成态判定，实施时必须和现有需求状态模型对齐。
|
||
2. 产品需求分发到项目后的项目需求、执行、任务链路不属于工单直接职责，工单只追踪自己直接派生的需求。
|
||
3. 父工单允许持续补子工单，会带来“父工单已关闭后是否允许继续补子单”的边界。本规格默认父工单关闭后不再补子单；如需重开父工单，需要单独设计重开动作。
|
||
4. 现有前端已有 `/ticket/my-submitted`、`/ticket/my-pending` 资源入口，后端接口落地时需要与前端路由和菜单权限同步。
|
||
|