Appearance
常见问题与排查
本手册用于排查 OA 审批中的表单可见性、发起提交、待办生成、节点流转、多人处理、分支、加签、附件、数据管理和报表异常。排查目标不是临时绕过问题，而是使用审批编号、接口响应、流程轨迹和任务状态定位真实责任层。
不要通过硬编码审批人、默认部门、强制完成、吞掉接口错误或无证据重复提交来掩盖问题。所有修复都应保留可复现证据，并验证真实业务场景。
1. 排查前先做什么
1.1 固定问题现场
第一时间记录：
- 审批编号；
- 审批表单名称和表单 ID；
- 出问题的账号、用户 ID 和角色；
- 当前企业、租户和工作空间；
- 问题发生的精确时间；
- 当前审批状态和当前节点；
- 预期结果与实际结果；
- 页面截图、接口状态和错误信息。
不要在刷新、重新提交或切换账号之后才开始记录，否则可能丢失原始状态。
1.2 确认工作空间
同一账号可能加入多个工作空间。审批表单、人员关系、待办和数据权限都可能按工作空间隔离。
先确认页面左侧当前工作空间与审批发起环境一致。不要因为另一个空间存在同名表单就认为数据应当互通。
1.3 先清除页面条件
在判断“没有数据”前：
- 清空搜索词；
- 重置组合筛选；
- 选择“全部审批单”；
- 刷新当前页面；
- 再按审批编号精确查询。
2. 五分钟快速定位表
| 现象 | 第一检查点 | 常见责任层 |
|---|---|---|
| 发起人看不到表单 | 发布、启用、谁可以发起、工作空间 | 表单配置或权限 |
| 提示选择部门但无组件 | 多部门设置、成员部门、页面加载 | 配置、组织数据或前端 |
| 点击提交无反应 | 必填校验、重复提交、接口响应 | 表单、前端或接口 |
| 通知有审批但待办没有 | 当前节点、任务生成、账号环境 | 消息、流程或任务 |
| 下一审批人没有待办 | 人员解析、多人方式、分支命中 | 流程引擎或任务 |
| 已处理没有记录 | 操作账号、任务完成、列表筛选 | 任务或查询 |
| 办理成功但仍在待处理 | 办理接口、会签任务、节点聚合 | 任务或流程 |
| 会签只显示一个人 | 节点方式、人员列表、任务数 | 配置或任务生成 |
| 并行分支提前结束 | 分支命中、汇聚规则、完成事件 | 流程引擎 |
| 加签顺序或展示混乱 | 前/后加签类型、原节点关联 | 流程和轨迹展示 |
| 附件上传失败 | 预签名接口、对象存储、文件限制 | 存储或权限 |
| 数据查看查不到 | 表单、时间、状态、数据权限 | 查询或权限 |
| 报表数量不一致 | 时间口径、状态口径、分页 | 报表统计 |
3. 证据链怎么建立
排查同一问题时，建议按四层收集证据：
| 层级 | 需要查看什么 | 可以证明什么 |
|---|---|---|
| 页面层 | 列表、详情、按钮、筛选、提示 | 用户看到的实际现象 |
| 请求层 | URL、方法、请求时间、响应码、错误体 | 接口是否被调用及返回结果 |
| 业务层 | 审批状态、当前节点、流程轨迹、任务状态 | 流程实际运行结果 |
| 数据/日志层 | 实例、节点、任务、事件和日志关联 ID | 根因与责任模块 |
仅凭消息卡片、流程设计图或某个列表状态不足以定性。至少要用审批编号把页面、接口和流程轨迹串联起来。
4. 发起人看不到审批表单
4.1 核查表单管理
进入 管理审批表单，确认表单存在于预期分组，并检查“谁可以发起”和最后更新时间。
核查顺序：
- 表单是否已创建并保存；
- 表单是否已经发布；
- 表单是否处于启用状态，而不是“已停用”；
- “谁可以发起”是否包含当前账号、部门或全部成员；
- 当前账号是否属于配置时选择的企业和部门；
- 表单是否移动到了其他分组；
- 发起页是否保留了搜索词或旧缓存。
4.2 常见结论
- 管理员能看到、普通成员看不到：优先检查发起范围；
- 所有人都看不到：优先检查发布和启用状态；
- 只有某个工作空间看不到：检查表单归属和空间切换；
- 搜索不到但分组中存在：检查名称、分组和搜索条件。
5. 提示“请选择所在部门”，但页面没有组件
发起页是否展示“所在部门”通常由高级设置和发起人的部门关系共同决定。
排查步骤：
- 检查高级设置中的多部门选项，是自动选择还是发起人手动选择；
- 确认发起人是否属于多个有效部门；
- 确认成员部门关系属于当前企业和工作空间；
- 检查发起页是否成功加载部门选择组件；
- 检查组件是否因表单滚动位置、响应式布局或前端异常被隐藏；
- 检查提交请求中的部门字段是否为空或使用了失效部门 ID；
- 对比前端校验规则和后端必填规则是否一致。
不要直接给所有人硬编码同一个默认部门。正确修复应让配置、组织数据、页面组件和提交字段保持一致。
6. 表单提交失败或按钮无反应
6.1 页面校验
先检查：
- 必填字段是否全部填写；
- 数字、日期、范围和选项是否符合规则；
- 必填附件是否上传成功；
- 所在部门、动态审批人或抄送人是否已选择；
- 页面是否滚动到未展示的错误字段；
- 提交按钮是否处于加载或禁用状态。
6.2 接口判断
| 响应情况 | 常见含义 | 下一步 |
|---|---|---|
| 未发出请求 | 前端校验、按钮状态或运行时异常 | 查看页面错误和控制台 |
| 400 / 422 | 字段格式或业务校验失败 | 保留错误体并核对提交数据 |
| 401 | 登录态或令牌失效 | 重新登录并确认环境 |
| 403 | 无发起权限或数据权限 | 核对角色和发起范围 |
| 404 | 表单、版本或接口路径不存在 | 核对发布版本和请求地址 |
| 409 | 重复提交或状态冲突 | 刷新并检查是否已生成审批 |
| 500 | 服务端未处理异常 | 使用时间和关联 ID查日志 |
6.3 避免重复提交
请求超时不等于提交失败。再次点击前先到“我发起的”或历史记录按标题、时间和审批编号检查是否已经生成审批。
7. 消息通知有审批，待办中心没有
消息通知和待办任务是两个相关但不同的数据对象。消息到达只能证明通知记录存在，不能证明个人任务仍处于可处理状态。
排查顺序：
- 确认通知中的审批编号；
- 核对通知接收账号与当前登录账号；
- 核对当前企业和工作空间；
- 清空待办搜索、表单筛选和组合筛选；
- 查看审批详情的整体状态和当前节点；
- 检查任务是否已被本人或其他或签人员处理；
- 检查审批是否被撤回、退回、拒绝或删除；
- 检查消息时间是否早于最新流程变更；
- 用用户 ID和节点实例检查个人任务是否生成。
7.1 常见结论
- 通知存在、任务从未生成：任务生成异常；
- 通知和任务都生成，但任务已结束：通知未随状态变化消失属于正常历史消息；
- 任务属于另一用户 ID：人员解析或账号映射问题；
- 任务在另一工作空间：环境切换问题；
- 或签中他人先处理：当前账号待办被正常关闭。
8. 下一审批人明确是本人，但没有待办
打开审批详情，核对审批编号、当前节点、节点状态和完整轨迹。
重点检查：
- 流程是否已经真正到达该节点；
- 节点配置的是当前用户、角色、部门负责人还是动态人员；
- 人员解析结果是否包含当前用户 ID；
- 节点是依次处理、会签还是或签；
- 依次处理时是否仍有前序人员未完成；
- 条件分支是否真正命中当前路径；
- 并行分支是否启动当前路径；
- 是否触发空审批人策略、自动通过或自动转交；
- 任务记录的租户、工作空间和处理人是否正确；
- 消息发送和任务写入是否处于同一事务结果。
流程图上配置了某人不等于本次实例一定会解析到该人。应以本次节点实例和任务记录为准。
9. 审批或办理成功后，已处理没有记录
进入 待办中心 → 已处理的，清空搜索和筛选后按审批编号核对。
排查步骤：
- 确认提交接口真实返回成功；
- 确认操作人与当前登录账号一致；
- 检查原任务是否从待处理变为完成；
- 检查流程轨迹是否写入操作人、意见和时间；
- 检查“已处理的”查询是否按任务处理人过滤；
- 清除表单、时间和搜索条件；
- 到数据管理按审批编号打开详情；
- 检查是否存在状态已变更但个人历史未写入的事务不一致。
个人“已处理”与整体“已完成”不是同一状态。会签或并行分支尚未结束时，个人任务应进入已处理，但整张审批仍可显示审批中。
10. 办理人提交成功，但节点仍显示办理中
办理节点可能是单人、依次处理、会签或或签。先确认当前办理方式。
核查：
- 本人的办理任务是否完成；
- 是否还有其他会签办理人未完成；
- 依次办理是否已经轮到下一人；
- 或签中是否正确关闭其他任务；
- 办理结果和附件是否成功保存；
- 节点完成事件是否触发流程继续；
- 下一个节点任务是否已经创建；
- 页面是否仍显示旧缓存。
如果接口成功、轨迹已写入、任务完成，但节点仍未聚合，应重点排查多人节点完成条件和流程事件。
11. 会签、或签和依次处理异常
| 方式 | 正确行为 | 常见异常 |
|---|---|---|
| 依次处理 | 只给当前顺位人员待办 | 后一顺位提前收到或前一人完成后未流转 |
| 会签 | 所有人同时收到，全部完成才结束 | 只生成一人任务或一人完成后节点提前结束 |
| 或签 | 所有人同时可处理，任一人完成后结束 | 他人完成后旧任务仍可提交 |
11.1 会签只有一个人收到
- 检查节点保存的人员列表是否完整；
- 检查是否误设为依次处理；
- 核对每个成员的用户 ID、企业和工作空间；
- 检查是否有重复人员去重；
- 检查任务表是否为每位参与人生成记录；
- 检查消息发送是否只处理了第一位人员。
11.2 或签重复提交
或签必须在服务端以任务和节点状态做并发控制。第一个人完成后，其他任务应关闭；后续请求应返回清晰的状态冲突，而不是重复推进流程。
12. 条件分支走错或未命中
条件分支按优先级命中一条路径，未命中普通条件时进入默认分支。
排查所需数据：
- 发起时保存的表单字段值；
- 发起人所属部门和组织信息；
- 条件表达式、操作符和值；
- 多个条件之间是“且”还是“或”；
- 分支优先级；
- 默认分支；
- 本次实例记录的实际命中结果。
常见根因：
- 数字以文本比较；
- 单选值使用显示名称而条件使用内部值；
- 多选“包含任一”和“包含全部”混淆；
- 部门 ID与部门名称混用；
- 高优先级条件先命中，后续条件不再执行；
- 表单改版后条件仍引用旧字段；
- 重新提交时仍错误使用旧快照。
修复后应使用边界值、默认分支和多选组合建立回归用例。
13. 并行分支未启动或审批提前完成
并行分支可以同时启动多条符合条件的路径，之后由聚合规则决定何时继续。
排查步骤：
- 列出设计时的全部并行分支；
- 记录每条分支的条件和本次判断结果；
- 确认应启动的每条分支都创建了节点实例；
- 确认每条分支都创建了对应人员任务；
- 核对分支完成、拒绝或跳过状态；
- 核对聚合规则是全部、数量、比例还是其他条件；
- 检查流程完成事件是否早于聚合完成；
- 检查未命中分支是否被错误计入已完成；
- 检查或签节点是否被误当成分支汇聚完成。
在所有分支条件尚未计算完、应启动分支尚未满足聚合规则时，流程不应提前显示已完成。
14. 加签顺序、人员或轨迹展示异常
14.1 正确顺序
| 类型 | 正确顺序 |
|---|---|
| 前加签 | 加签人先处理，完成后返回原审批人 |
| 后加签 | 原审批人先完成，再由后加签人处理 |
14.2 排查重点
- 加签记录保存的是前加签还是后加签；
- 原审批节点与新增节点的关联关系；
- 加签人的用户 ID和任务是否生成；
- 原审批任务在前加签期间是否正确暂停；
- 后加签是否在原审批完成后才激活；
- 流程轨迹是否把加签节点独立展示；
- 展示是否明确标注前加签或后加签；
- 加签完成事件是否只推进一次。
“设置加签”是操作记录，“前加签人/后加签人”是实际任务节点，两者不应混在同一位置造成顺序歧义。
15. 退回、拒绝或撤回后状态不正确
15.1 退回
检查退回目标、允许退回范围、原节点任务关闭、目标节点任务重建和重新提交后的路径。
15.2 拒绝
检查拒绝动作是否按配置终止流程、是否关闭全部未处理任务、是否保留拒绝意见和时间。
15.3 撤回
检查发起人是否具备撤回条件、撤回后未处理任务是否关闭、详情和列表是否更新为已撤回。
三种动作语义不同，不能通过统一设置“结束状态”掩盖具体轨迹。
16. 审批按钮缺失、无权限或状态冲突
看不到同意、拒绝、退回、加签或提交按钮时，按顺序判断：
- 当前账号是否是任务处理人；
- 当前节点是审批人还是办理人；
- 任务是否已由本人或他人处理；
- 审批是否被撤回、拒绝或删除；
- 当前节点是否允许退回或加签；
- 页面是否使用过期状态；
- 权限接口是否返回 403；
- 前端是否因接口错误直接隐藏按钮。
正确做法是显示明确的不可操作原因，而不是静默隐藏所有入口。
17. 附件上传或预览失败
审批意见和办理意见支持上传图片与附件。
17.1 上传链路
通常包含：
- 前端请求生成预签名地址；
- 平台校验租户、用户、工作空间和文件信息；
- 对象存储返回上传地址；
- 浏览器直接上传文件；
- 前端保存文件元数据；
- 提交审批意见时关联附件。
17.2 排查清单
- 文件名、类型、大小是否符合限制；
- 预签名接口是否成功；
- 请求中的项目、作用域、租户、用户和工作空间是否正确；
- 对象存储地址是否可达；
- 上传请求是否被 CORS、权限或时钟偏差拒绝；
- 上传成功后是否返回文件键或访问地址；
- 提交意见时是否携带附件元数据；
- 预览地址是否过期；
- 附件记录与审批编号是否正确关联。
反馈时只提供去敏后的请求信息，禁止粘贴访问令牌、预签名密钥或对象存储密钥。
18. 评论、附件或审批意见没有显示
- 确认评论或审批接口返回成功；
- 检查操作记录是否写入正确节点；
- 检查意见类型是否被映射成评论、审批同意、拒绝或办理提交；
- 检查附件关联是否在意见写入后提交失败；
- 刷新详情并滚动到对应节点；
- 检查轨迹排序使用操作时间还是节点时间；
- 检查前后加签意见是否被错误归入原节点。
不要把评论当作审批完成动作。评论成功后当前任务仍应保持可处理。
19. 数据查看查不到审批或状态不一致
排查顺序：
- 选择正确表单；
- 清除完成时间和状态；
- 输入完整审批编号；
- 核对数据管理员权限；
- 核对企业、租户和工作空间；
- 打开详情查看服务端最新状态；
- 将列表状态、详情状态和最后轨迹时间比较；
- 检查表单版本和历史数据是否使用不同字段结构。
如果详情正确而列表错误，优先检查查询索引、缓存或列表状态映射；如果轨迹和整体状态都错误，检查流程状态事件。
20. 操作记录、导出或删除异常
20.1 导出未生成
- 检查勾选数量；
- 检查导出接口和异步任务；
- 检查操作记录是否生成文件；
- 检查对象存储和下载权限；
- 不要连续点击生成重复文件。
20.2 删除后仍能查到
- 确认删除接口是否成功；
- 检查删除记录是否写入；
- 刷新并清空筛选；
- 检查是否只是软删除或延迟更新；
- 检查报表和查询是否使用不同数据源。
删除是不可恢复操作。排查过程中只打开确认窗口，不应为了复现而删除真实业务数据。
21. 报表与数据查看数量不一致
统一以下口径后再比较：
- 审批表单；
- 企业和工作空间；
- 日期范围；
- 使用发起时间还是完成时间；
- 是否包含审批中、拒绝、驳回和撤回；
- 完成率分子和分母；
- 分页和每页条数；
- 删除数据和统计刷新时间。
使用审批编号逐条比对明细，不要只比较页面第一屏的数量。
22. 页面一直加载、显示空白或偶发失败
22.1 页面层检查
- 是否只有当前浏览器异常；
- 是否刷新后恢复；
- 是否存在运行时错误；
- 是否有接口长期 pending；
- 是否是窗口尺寸或滚动位置导致内容不可见；
- 是否被浏览器插件、代理或网络策略拦截。
22.2 服务层检查
- 接口服务是否健康；
- 当前环境地址是否正确；
- 认证、租户和工作空间上下文是否完整；
- 查询是否超时；
- 数据库、Redis或对象存储是否可用；
- 同一时间是否有大量相同错误。
不要用无限重试或静默空状态代替错误提示。页面应让用户知道是“没有数据”还是“加载失败”。
23. 安全的临时恢复动作
在不改变业务数据的前提下，可以：
- 刷新页面；
- 清空搜索和筛选；
- 切换到正确工作空间；
- 重新登录以更新过期会话；
- 用审批编号从其他只读入口核对；
- 等待已经提交的请求返回；
- 保存错误信息后重新打开详情。
未经确认不要：
- 重复提交审批；
- 手工修改流程状态；
- 删除并重新创建真实审批；
- 跳过未完成节点；
- 直接修改数据库任务状态；
- 用另一个人的账号代为处理；
- 将访问令牌粘贴到聊天或工单。
24. 修复后的回归验证
修复不能只验证出问题的一张单据。至少覆盖：
24.1 基础流程
- 正常发起、同意、拒绝、退回；
- 办理节点提交；
- 评论和附件；
- 已处理和数据详情记录。
24.2 多人和分支
- 依次处理顺序；
- 会签全部完成；
- 或签一人完成后关闭其他任务；
- 条件分支边界值和默认分支；
- 多条并行分支和聚合完成；
- 前加签和后加签。
24.3 权限和数据
- 不同企业与工作空间隔离；
- 发起范围与数据管理员权限；
- 导出、删除审计；
- 报表和数据查看口径一致。
真实页面、接口、任务状态和轨迹都验证通过后，才能确认问题解决。
25. 升级给研发的证据模板
可以按下面格式提交：
text
问题标题：
审批编号：
表单名称 / 表单 ID：
环境：开发 / 测试 / 生产
企业 / 租户 / 工作空间：
问题账号 / 用户 ID / 角色：
发生时间：
预期结果：
实际结果：
当前审批状态：
当前节点：
已完成的排查步骤：
相关请求 URL（不含令牌）：
HTTP 状态码和错误信息：
服务端关联 ID / 日志时间：
页面、详情和轨迹截图：
是否可以稳定复现：25.1 必须脱敏
不要提交：
- Authorization 访问令牌；
- Cookie 和会话 ID；
- 数据库、Redis和对象存储密码；
- 预签名地址中的敏感查询参数；
- 未脱敏的身份证、银行卡、薪资或合同内容。
26. 关联操作手册
- 表单、流程与发布问题：OA 审批管理员手册
- 发起与提交问题：OA 审批发起人手册
- 审批、办理与待办问题：OA 审批操作人手册
- 查询、导出、删除与报表问题：OA 审批数据管理员手册