SandWorkflow Troubleshooting

SandWorkflow 故障排查

先记录宿主版本、插件版本、发生时间、账号角色、页面和接口错误；截图或日志移除令牌、密码和个人敏感数据。按症状检查，不用重新安装覆盖已有数据。

症状	检查与处理	恢复后验证
无工作流菜单	核对插件安装结果和角色菜单权限；刷新菜单或重新登录。	目标账号能看到对应入口。
菜单存在但组件加载失败	核对发布包、后端、前端三份载荷是否完整、版本是否一致；交由维护者按标准包流程恢复完整载荷。	对应页面加载且接口成功。
设计器没有用户、角色或部门	核对组织查询权限、宿主数据和相关接口错误。	能选择实际用户与分组。
发起页无目标流程	核对已发布、启用状态、发起范围和可发起列表权限。	本人账号能看到流程卡片。
审批人无待办	核对实际当前节点处理人、账号启用状态及待办权限；依次审批后续人需等前一人通过。	当前处理人能打开实例详情。
抄送箱无实例	核对流程是否实际经过抄送节点、本人是否收件人、抄送权限。	收件人能查询该标题。
条件进入默认分支	核对字段真实标识、类型、值与条件顺序。	新实例进入预期分支，旧实例不被修改。
字段不可见或不可编辑	核对当前参与身份及节点表单权限；旧实例兼容提示需单独评估。	仅看到应当可读的字段。
更新定义后旧实例不变	这是版本快照机制；查看实例使用的版本和定义历史。	新实例用新版本、旧实例保持旧规则。
重复处理或不允许撤销	核对任务是否已结束、是否属于本人，定义是否允许撤销。	当前状态符合详情和流转记录。
PostgreSQL / NanoID 结构错误	核对 pgsql 连接、安装版本和正式升级结果；保留错误交维护者诊断。不要手工转整型标识或重跑安装 SQL。	旧数据和新实例均可查询处理。

维护者的只读载荷核对

macOS/Linux 的 Bash，默认在权威源码的 sandworkflow/ 目录执行：

bash tools/check-package-integrity.sh

通过时输出包版本和宿主最低声明。这只检查元数据、SQL 副本和许可证等一致性。

对已通过受控方式同步的演示宿主，可执行：

bash tools/check-sandadmin-host.sh

默认比较 /Users/code/project/sand_demo；检查菜单组件、完整包、后端和前端是否一致，不会安装、修复或启动服务。显式隔离宿主可设置 SANDADMIN_ROOT；权威源码路径可设置 SAND_WORKFLOW_SOURCE。发现差异先查明哪一侧是权威版本，不从宿主反向覆盖源码。

本轮只运行包完整性检查；未运行宿主比对、SQL 或真实页面恢复。