按「復現現象 → 定位模組 → 查日誌/許可權 → 驗證修復 → 記錄預防」五步排查。每類問題均給出後臺選單路徑與可執行檢查清單，覆蓋實施中最常遇到的 40+ 典型場景。內容依據宜搭官方幫助中心與算數科技專案交付經驗整理。
10 大類
40+ 典型問題
症狀速查矩陣
後臺路徑對照
場景演練 SOP
遇到問題時，建議按此順序排查
1
復現並記錄 — 記錄操作賬號、應用/表單名、時間點、報錯原文或截圖；多人復現可判斷是賬號問題還是配置問題。
2
區分環境 — 區分釘釘客戶端 / 瀏覽器 / 移動端；自建宜搭與 SaaS 版後臺入口不同，避免在錯誤環境查配置。
3
先查許可權與釋出狀態 — 約 60% 的「功能異常」實為許可權不足或流程/自動化未釋出；優先在管理後臺確認成員、角色、釋出狀態。
4
查執行日誌 — 流程例項日誌、智慧助手Pro 執行記錄、OpenAPI 呼叫日誌（開放平臺）是定位根因的關鍵依據。
5
小範圍驗證後推廣 — 修改配置後先用測試賬號驗證，再通知業務方；重大變更前匯出表單結構與許可權快照備查。
症狀速查：先對號入座，再下鑽專題
約 60% 的「功能壞了」實為許可權、釋出狀態或篩選條件問題。下表按使用者可見現象反查最可能模組，避免從 API 或效能方向空耗時間。
| 使用者看到的現象 | 優先懷疑 | 第一步去哪查 | 跳轉 |
|---|---|---|---|
| 打不開應用 / 提示無許可權 | 成員與角色 | 應用設定 → 成員與許可權 | ② |
| 提交了但列表裡找不到 | 資料許可權 / 篩選 / 流程中 | 資料管理 → 重置篩選；查「我發起的」 | ③ |
| 審批一直停在某人 | 審批人失效 / 會籤未齊 | 例項詳情 → 流程圖 / 審批記錄 | ④ |
| 自動化沒跑 / 跑了兩次 | 未釋出 / 觸發條件 / 迴圈觸發 | 智慧助手Pro → 執行日誌 | ⑤ |
| 公式不算數 / 聯動不重新整理 | 欄位型別 / 引用路徑 / 只讀 | 表單設計器 → 公式編輯器 | ⑧ |
| 門戶選單缺頁 / 手機端錯位 | 門戶未釋出 / 角色可見性 | 門戶設計 → 預覽 → 釋出 | ⑨ |
| 改完配置業務方看不到 | 設計態未釋出 | 應用釋出中心 → 對比版本 | ⑩ |
| 介面 401 / 403 | Token / 許可權 / 白名單 | 釘釘開放平臺 → 呼叫日誌 | ⑥ |
| 列表開啟要 10 秒以上 | 資料量 / 無索引 / 大欄位 | 資料管理行數；檢查預設篩選 | ⑦ |
後臺入口速查（實施顧問常用路徑）
組織釘釘工作臺 → 宜搭 → 平臺管理 → 組織管理 → 成員管理
應用許可權我的應用 → 目標應用 → 應用設定 → 成員與許可權 → 角色管理
資料許可權表單/流程 → 資料管理 → 許可權設定 → 資料許可權組
流程運維流程表單 → 資料管理 → 例項詳情 → 流程圖 / 轉交 / 退回
自動化日誌應用內 → 智慧助手Pro → 選擇規則 → 執行日誌
聚合表應用內 → 聚合表 → 重新整理設定 / 手動重新整理
API 除錯open.dingtalk.com → 應用開發 → 宜搭 OpenAPI → 線上除錯
釋出應用編輯態 → 右上角「釋出」→ 釋出記錄 / 版本對比
注意：宜搭「設計態」與「執行態」分離——在設計器裡改完必須點釋出，否則業務使用者仍看到舊版。排查時先確認問題賬號訪問的是否為已釋出版本。
① 登入與釘釘整合
釘釘掃碼登入宜搭無反應或一直轉圈
可能原因
宜搭未安裝到企業、可見範圍不含當前使用者、瀏覽器攔截 Cookie、或自建版域名/CorpId 配置不一致。
排查步驟
- 釘釘管理後臺 → 應用管理 → 確認「宜搭」已啟用，可見範圍包含測試賬號所在部門
- 換 Chrome/Edge 無痕視窗；關閉「阻止第三方 Cookie」後重試
- 優先在釘釘客戶端內開啟工作臺宜搭，排除瀏覽器外掛干擾
- 自建部署：核對宜搭後臺「整合配置」中 CorpId、回撥域名與釘釘開放平臺一致
提示「無許可權訪問」但釘釘賬號正常
宜搭許可權獨立於釘釘通訊錄：需在宜搭「組織管理 → 成員管理」中邀請或同步成員，並分配應用訪問許可權。僅加入釘釘部門不等於自動獲得宜搭應用許可權。
成員已從釘釘離職但仍能登入宜搭
宜搭成員狀態需手動禁用或等待通訊錄同步任務執行（通常 T+1）。管理員應在「成員管理」中及時禁用賬號，並回收應用管理員、開發者等高許可權角色。
多端登入後資料不同步
宜搭以服務端資料為準，客戶端偶發快取延遲。處理方式：下拉重新整理列表；審批類操作優先在發起端完成；避免同時在 PC 與手機編輯同一條記錄。
② 許可權與組織架構
使用者看不到應用或表單入口
按順序排查：應用成員列表 → 應用內角色（管理員/開發者/訪問者）→ 表單級許可權組 → 門戶/選單是否釋出到該角色。新成員預設無許可權，需管理員在「應用設定 → 成員與許可權」中顯式新增。
能看到列表但查不到某些資料行
檢查「資料許可權」配置：全部資料 / 本部門 / 本人 / 自定義條件。列表檢視上的篩選條件也會縮小可見範圍，點選「重置篩選」對比。流程審批中的資料可能只在「待我處理」中可見。
欄位可檢視但無法編輯（按鈕灰色）
原因常見有三：欄位許可權設為只讀；記錄處於流程節點中該欄位被鎖定；欄位由公式/資料聯動賦值導致只讀。在表單設計器中檢查欄位「編輯許可權」與「預設值/公式」配置。
部門架構同步後許可權錯亂
宜搭支援從釘釘同步組織架構，但角色繫結不會自動隨部門變更。部門調整後應審查「按部門授權」的規則，必要時改為「按角色組」管理，降低組織變動帶來的影響。
③ 表單與資料操作
提交成功但在資料管理中找不到記錄
按優先順序排查（約 5 分鐘可定位 80% 案例）
- 資料許可權：資料管理 → 許可權設定 → 確認當前角色為「全部資料」或包含提交人；若僅「本人資料」，管理員賬號看不到他人提交
- 列表篩選：點選「重置篩選」；檢查是否預設篩選了「流程狀態=審批中」導致已結束單被隱藏
- 流程佔用：繫結流程的表單，新記錄在「我發起的」「待我處理」中，未必出現在普通資料檢視
- 自動化誤刪：智慧助手Pro → 執行日誌，篩選提交時間點前後是否有「刪除資料」動作
- 多版本表單：確認檢視的是與提交時相同的表單版本（釋出變更後舊例項仍掛舊版）
欄位校驗不透過但看不出哪一項有問題
必填、格式、唯一性、自定義校驗公式均會攔截提交。移動端錯誤提示較小，建議在 PC 端復現；檢查子表單內是否有隱藏必填行；校驗公式中引用空值時需用 IF 兜底。
附件上傳失敗或一直 0%
單檔案大小受版本限制（免費版通常 ≤ 50MB，企業版可更高）；檢查網路與釘釘/企業防火牆是否攔截上傳域名；圖片欄位與附件欄位限制不同；批次上傳建議分批，單次不超過 20 個檔案。
Excel 批次匯入失敗或部分行丟失
匯入前準備
從資料管理匯出官方模板，勿手改列順序；成員/部門欄位填 userid / 部門編碼，非顯示姓名。
失敗處理
- 下載「錯誤報告」定位行號與欄位；常見：日期非 YYYY-MM-DD、單選值不在選項列表、必填為空
- 單次 ≤ 5000 行；超大檔案按月份拆分匯入
- 匯入不觸發智慧助手Pro——若需補跑，用定時任務或手動批次更新觸發欄位
- 匯入後核對行數：資料管理總行數 − 匯入前行數 ≈ 成功條數
子表單彙總金額計算不正確
主表彙總子表需使用 SUM 等聚合函式，引用路徑應為「子表單.金額」而非主表欄位。子錶行數上限約 200 行（以當前版本文件為準），超出會導致儲存失敗或截斷。
資料匯出 Excel 亂碼或列錯位
使用 UTF-8 開啟；關聯表單欄位匯出為 ID 時需用 VLOOKUP 二次匹配；匯出大量資料建議用「資料管理 → 匯出」而非檢視複製，超限時聯絡管理員分批匯出。
④ 流程審批
提交後流程未發起
確認流程設計已「釋出」且表單已繫結該流程版本；檢查發起條件（如金額閾值）是否滿足；發起人是否在流程允許的發起範圍內；檢視錶單提交日誌是否有流程引擎報錯。
流程卡在某個節點不流轉
診斷路徑
- 開啟該條資料 →「流程圖」：當前節點高亮，檢視「待處理人」是否為空或已離職
- 或籤 / 會籤：或籤需任一透過；會籤需全部透過——確認是否有人未處理
- 條件分支：檢查分支條件欄位型別（金額用數字元件，勿用文字比較）；空值走預設分支
- 審批人規則：「直屬主管」類動態規則在組織不同步時會取不到人，改為固定角色組更穩
- 管理員：流程運維 →「轉交」給在崗人員，或「退回」至可編輯節點
審批人收不到釘釘待辦通知
① 釘釘「設定 → 新訊息通知」中開啟工作通知；② 宜搭應用訊息推送許可權是否開啟；③ 審批人是否使用企業釘釘賬號（非個人版）；④ 在釘釘工作臺進入宜搭手動重新整理待辦；⑤ 檢查是否被「勿擾」或「審批委託」規則轉發走。
退回後資料狀態異常或重複審批
退回目標節點需在設計時明確（上一節點 / 發起人）；退回後欄位可編輯範圍由節點配置決定；避免在退回同時觸發智慧助手Pro 修改同一欄位，防止狀態競爭。
⑤ 高階功能（聚合表 / 智慧助手Pro / 資料工廠）
聚合表資料不更新或數字對不上
聚合表按設定頻率重新整理，非實時；修改源表單後需等待下一次同步或手動觸發重新整理。檢查聚合條件、分組欄位型別是否一致；關聯欄位變更後需重新儲存聚合表配置。
智慧助手Pro 配置了但不執行
五分鐘檢查表
- 規則狀態是否為「已釋出」（草稿不執行）
- 觸發事件與實際操作是否一致：手動改欄位不觸發「僅新增」規則
- 條件裡欄位路徑是否因改版變更（如子表欄位重新命名）
- 執行日誌 → 檢視「跳過 / 失敗」及原因文案
- 批次匯入、OpenAPI 寫入：確認版本是否支援觸發，必要時改定時同步
智慧助手Pro 重複觸發導致資料重複
避免「修改時觸發」監聽會被自身更新再次觸發的欄位；增加條件判斷（如狀態欄位僅變更一次）；使用「僅當欄位從 A 變為 B」類條件；關鍵寫操作建議加唯一性約束或冪等校驗。
資料工廠任務失敗或超時
檢查上游資料來源連通性與欄位對映；單任務資料量過大時拆分為多個節點或縮小時間視窗；檢視任務執行詳情中的失敗行；輸出目標表欄位型別需與加工結果匹配。
⑥ API 與聯結器
宜搭 OpenAPI 基於釘釘開放平臺鑑權，常見 HTTP 狀態碼與處理建議如下（詳見 宜搭 OpenAPI 文件）：
| 狀態碼 | 含義 | 常見原因 | 處理建議 |
|---|---|---|---|
| 401 | 鑑權失敗 | accessToken 過期、AppKey/Secret 錯誤 | 重新獲取 token；核對應用憑證是否輪換 |
| 403 | 無呼叫許可權 | 應用未開通介面、IP 白名單限制 | 開放平臺開通許可權；配置伺服器出口 IP |
| 404 | 資源不存在 | formUuid / instanceId 錯誤或已刪除 | 用最新 ID；刪除操作需冪等處理 |
| 429 | 限流 | 短時間請求過多 | 指數退避重試；合併批次介面 |
| 500 | 服務端錯誤 | 引數格式、欄位型別不匹配 | 對照 API 文件檢查 JSON 結構 |
聯結器呼叫外部系統超時
確認對方介面公網可達且響應 < 30s；宜搭聯結器有超時上限，慢介面應改為非同步回撥或中間層佇列；檢查鑑權頭、Content-Type 是否與對方要求一致。
Webhook 回撥收不到或驗籤失敗
回撥 URL 須 HTTPS 且公網可訪問；核對簽名演算法與金鑰；防火牆放行宜搭/釘釘回撥 IP 段；先用 官方除錯工具模擬推送驗證接收端邏輯。
與 ERP / 資料庫整合資料不一致
明確主資料來源（宜搭為主或 ERP 為主）；用「增量同步 + 對賬報表」而非全量覆蓋；關鍵欄位建立雙向對映表；異常資料進入死信佇列人工複核，避免髒寫。
⑦ 效能與容量
表單開啟慢或列表載入超時
單表資料量超過 10 萬行後查詢明顯變慢；為常用篩選欄位建索引；列表預設不載入大文字/附件欄位；歷史資料歸檔到「歸檔表」或匯出冷儲存；複雜關聯改用聚合表預計算。
儀表盤圖表重新整理卡頓
單圖表資料點建議 < 1 萬；多圖表引用同一資料來源時可合併查詢；避免實時拉取全量明細，改用聚合表或資料工廠預處理；高峰時段避開大批次匯入與定時任務疊加。
版本配額不足（應用數 / 自動化次數）
各版本配額見訂購頁面；清理未使用應用與草稿自動化；合併相似智慧助手Pro；升級套餐或聯絡宜搭商務擴容。算數科技渠道客戶可協助評估版本與採購最佳化。
容量參考（實施建議，非官方 SLA）：
單表單活躍資料建議控制在 5–10 萬行以內；子表單 ≤ 200 行/單；單次匯入 ≤ 5000 行；智慧助手Pro 避免分鐘級高頻觸發。超規模場景應提前規劃歸檔與資料中臺方案。
⑧ 公式與資料聯動
公式類問題佔實施諮詢量約 25%。宜搭公式在儲存時計算，部分聯動在欄位變更時觸發——先分清是「不算」還是「算錯」。
主表彙總子表金額始終為 0
現象：子表已填多行金額，主表「合計」欄位顯示 0 或不更新。
- 公式須用聚合函式：SUM(子表單.金額)，不能直接寫 子表單.金額
- 確認子表欄位元件為「數字」而非「文字」，文字參與 SUM 會得 0
- 子錶行在儲存前未落庫時，公式可能暫不計算——先儲存草稿再檢視
- 子表超過約 200 行時部分行可能被截斷，導致彙總偏小（見容量說明）
IF / DATEDIF 公式報錯或結果為空
現象：提交提示公式錯誤，或日期差、條件判斷無結果。
- 空值兜底：IF(金額, 金額*0.13, 0)，避免 NULL 參與運算
- 日期元件引用直接寫欄位名，格式 YYYY-MM-DD；勿與文字欄位混用 DATEDIF
- 比較運算子兩側型別一致：數字欄位勿加引號
- 在公式編輯器用「除錯」檢視中間變數；複雜邏輯拆為多欄位分步計算
資料聯動 / 關聯表單填充不生效
常見根因
聯動條件欄位未先填寫；關聯表單資料許可權導致取不到目標行；聯動目標欄位為只讀公式欄位。
排查
- 按聯動配置的「觸發順序」依次填欄位，觀察哪一步中斷
- 用管理員賬號測試：若管理員可聯動而普通使用者不行，查關聯表單資料許可權
- 聯動賦值目標改為普通文字/數字欄位，排除公式欄位寫入限制
唯一性校驗「已存在」但列表搜不到
唯一性校驗針對全表資料含無許可權行；當前使用者因資料許可權看不到衝突記錄。管理員用「全部資料」許可權檢索重複值，或匯出全表對賬後清理歷史髒資料。
選項關聯 / 級聯下拉選項不全
檢查選項資料來源表單是否有過濾條件；資料許可權是否限制選項可見範圍；選項超過 500 條時考慮改用關聯表單 + 搜尋選擇元件。
⑨ 門戶與頁面展示
門戶選單缺少某個表單 / 頁面入口
- 門戶設計器 → 檢查選單項是否繫結正確頁面，且狀態為「已釋出」
- 選單「可見角色」是否包含當前使用者所屬角色
- 子應用從主應用拆出後，門戶連結可能仍指向舊路徑，需更新選單 URL
- 移動端與 PC 端可配置不同導航，分別預覽釘釘內 H5 與瀏覽器
自定義頁面圖表 / 列表空白
資料來源表單許可權不足會導致元件無資料；檢查頁面篩選條件是否過嚴（如預設「本月」但無本月資料）；儀表盤元件引用的聚合表是否已重新整理；設計態有資料而執行態無資料時，多為釋出未同步。
手機端佈局錯亂、按鈕點不到
表單設計 → 移動端佈局單獨調整，勿僅依賴 PC 自動適配；避免一行過多列；固定底欄按鈕與釘釘原生欄重疊時，增加底部留白；在真機釘釘內測試，瀏覽器模擬不完全可靠。
列印模板缺欄位 / 分頁斷裂
列印模板需單獨配置欄位對映；子表列印檢查「展開行」設定；圖片/附件欄位列印受許可權與檔案大小影響；流程未結束時部分欄位可能尚未賦值，在「審批完成」節點後再觸發列印更穩。
⑩ 釋出上線與版本管理
釋出檢查清單（上線前 10 項）
- 表單 / 流程 / 智慧助手Pro / 門戶均已點選「釋出」
- 測試角色與生產角色許可權組已區分，測試資料已清理或隔離
- 流程審批人規則在真實組織架構下走通一單
- 關鍵公式、聯動在移動端與 PC 端各測一單
- OpenAPI 呼叫方使用生產環境 AppKey 與白名單
開發改完了，業務方說「還是老樣子」
90% 是未釋出或快取
- 應用編輯態右上角確認「有未釋出變更」提示，執行釋出並填寫變更說明
- 讓業務方完全退出宜搭重新進入，或釘釘端清除應用快取
- 對比「釋出記錄」時間戳與業務反饋時間，確認是否看錯應用（測試應用 vs 生產應用）
釋出後流程例項報錯 / 欄位缺失
刪除欄位或改欄位型別後，進行中例項可能不相容。釋出前評估在途單量；重大結構變更選業務低峰期；必要時保留舊版流程處理在途，新版僅對新單生效（按官方版本策略操作）。
需要回滾到上一版本
在「釋出記錄」檢視歷史版本，按官方支援的範圍回滾表單/流程配置（並非所有元件都支援一鍵回滾）。回滾前匯出當前配置備份；通知業務暫停提交；回滾後迴歸測試核心路徑再開放。
典型場景演練（端到端 SOP）
以下三個場景來自真實交付專案中的高頻工單，按時間順序操作可在 15–30 分鐘內閉環。
場景 A：採購單提交後，採購經理在資料管理裡「搜不到」
第 1 步 · 確認是不是許可權問題（3 分鐘）
用提交人賬號登入 → 資料管理能否看到？若提交人可見、經理不可見 → 資料許可權組問題。
第 2 步 · 查經理角色資料範圍（5 分鐘）
應用設定 → 成員與許可權 → 經理所在角色 → 資料許可權：若設為「本部門」而提交人跨部門，則經理看不到。改為「全部資料」或按「自定義條件」包含相關部門。
第 3 步 · 排除流程與篩選（5 分鐘）
重置列表篩選；查「待我處理」是否卡在審批中；查智慧助手Pro 是否將狀態改為「草稿」導致被預設檢視過濾。
結論判定：提交人可見 + 經理不可見 = 調資料許可權；雙方都不可見 = 查流程狀態或自動化；僅管理員不可見 = 正常，檢查是否用錯賬號。
場景 B：報銷流程卡在「財務稽核」超過 48 小時
第 1 步 · 看流程圖待處理人（2 分鐘）
例項詳情 → 流程圖：財務節點顯示待處理人是誰？若為空 → 審批人規則失效（主管鏈斷裂）。
第 2 步 · 核實審批人釘釘狀態（5 分鐘）
在釘釘通訊錄確認該員工在崗、賬號啟用；是否開啟審批委託把單轉給代理人但未處理。
第 3 步 · 管理員運維（5 分鐘）
流程運維 → 轉交給在崗財務 B；或退回發起人補材料。同步檢查該節點是否誤設為「會籤」導致一人未批全員卡住。
長期修復：財務節點改用「財務角色組」固定審批人 + 配置 24h 超時提醒與轉交規則。
場景 C：OpenAPI 寫入成功，但智慧助手Pro 未同步 ERP
第 1 步 · 確認觸發源（3 分鐘）
智慧助手Pro 若觸發條件為「表單新增」，API 寫入預設可能不觸發（視版本與配置）。查執行日誌該時間點是否有記錄。
第 2 步 · 改觸發策略（10 分鐘）
方案一：API 寫完後由中間服務再調一次「修改標記欄位」觸發自動化；方案二：改為定時任務批次同步未推送記錄；方案三：直接用聯結器 / 自定義 API 節點替代 Pro。
第 3 步 · 對賬與冪等（10 分鐘）
增加「同步狀態」欄位（待同步/已同步/失敗）；失敗寫入日誌表；ERP 側用業務單號做冪等，避免重複推送。
根因歸納：整合問題先畫資料流圖（誰寫主表、誰觸發、誰回撥），再選觸發方式，避免假設「寫了表就會自動跑 Pro」。
問題仍未解決？
官方渠道與算數科技實施團隊均可協助——複雜整合、效能治理建議優先找有專案上下文的實施顧問。
宜搭官方：7×12 線上客服（企業版含專屬客戶經理）· 算數科技：18016313342（微信同號）