# 常見問題

給接入網站的開發者和管理員。這裡的例子全部是合成資料；沒有任何來源網站或真人資料。

## 怎樣選兩邊填表及查看的方式？

先看[三種接入方式](integration-modes.md)。新流程由 OpenDashboard 保存正式答案，連結／iframe／自訂 UI 共用規則；外站只需查看自己的申請時用流程填表 API，需要資料庫副本時加[流程通知與同步](workflow-sync.md)。原站主導的回寫僅維護既有整合。

## 需要把現有網站重寫嗎？

不用。現有網站繼續顯示表單及處理登入；由你自己的伺服器將欄位及答案送到 OpenDashboard。每個網站有自己的應用、金鑰及報表工作區，使用同一套通用 API。

## OpenDashboard 會自動提供填表頁嗎？

流程已有公開報名連結、iframe 及每宗申請的私人續填頁，在「流程 → 網站接入」取得；只有一份表單也可建立一個填表步驟。普通 `/api/apps/v1/forms` 只建立連接應用的定義，不回傳公開填表頁。獨立活動／問卷的原有入口仍保持原樣，不能混用這三種表單的網址。

## 我們想自己設計填表頁，如何知道欄位及答案格式？

新流程先讀[流程接入教學](workflow-ui.md)，使用 `/api/workflow-ui?action=definition` 取得問題，並按 application 的 current_actions 操作同一申請。

以下才是普通單份連接應用表單的方式：由網站後端 GET /forms/:id 取得 questions。UI 按 type 顯示控制，答案按 key 保存，選項原樣送回，重複群組使用物件陣列。後端核對使用者身份、加入 respondent，再 POST /forms/:id/responses。閱讀[自己的填表介面教程](custom-ui.md)，下載表單／答案 JSON，參考讀回版本、驗證錯誤及完整更新。這些普通端點只適用於同一連接應用擁有的表單；競賽報名及作品另用 entry／submission 端點，教程也列出差別。

## 金鑰放在哪裡？

放在伺服器秘密管理服務或環境變數。前端只呼叫你自己的後端。OpenDashboard 只保存金鑰雜湊，無法重新顯示原金鑰；遺失時請管理員輪換。舊金鑰會立即失效。

## 怎樣區分測試和正式資料？

應用金鑰 `odb_test_` 只看到測試資料，`odb_live_` 只看到正式資料；流程金鑰則為 `odb_flow_test_`／`odb_flow_live_`，只操作綁定的流程入口。日常流程 UI 不需要選資料環境；驗收另用隔離流程，勿在收取真實報名的入口試填。錯用金鑰讀取表單／合集得到 404。用測試金鑰完成驗收後，在正式環境另建自己的定義。

## 一份表單有多人，怎樣計算？

把多人資料放在 `repeating_group`。`submissions` 計提交份數，群組項目表計群組內項目數，多選表計選項次數。兩份合成回覆含 3＋4 位參加者，應為 2 份提交和 7 個項目，不能用兩者代替對方。

## 多選會把人數算多嗎？

選項表中一個項目可以有多行。計人／項目數用項目表，或在選項表對 `item_key` 做 `countDistinct`；後者只包括有選任何選項的項目。按 `choice` 分組的 count 是各選項次數，總和可以大於項目數。

## 在 OpenDashboard 管理介面可以查看外站表單嗎？

有上述個人資料查看權限的平台職員，可在「表單管理」或回覆選單找到正式外站表單；來源網站名稱及「只供查看」會顯示在列表。回覆頁支援分頁、完整欄位、重複群組及私人附件。預設列表略過已封存的外站表單，測試表單及 OpenDashboard 代理表單 不會出現在這個入口。表單定義、回覆修改、刪除和通知仍由來源網站維護。

## 為甚麼群組沒有出現在儀表板？

先讀合集 tables，核對回傳字典和 `unit`。群組預設個人，只要其任何巢狀欄位屬個人，整個群組就被排除。只對經確認的非識別欄位設定 `personal: false`；電郵、電話及附件不能改成非個人。若需統計而原群組含身份欄位，另建只含安全統計欄位的群組。

## 重複群組可以有小表格嗎？

可以。群組可包含一層巢狀群組，最多兩層群組。每層最多 50 個欄位、每個群組最多 100 個項目。子項目以 `parent_item_key` 連到父項目；資料表名稱不應由客戶端解析或拼接。報表每個指標仍只讀一張資料表。

## 為甚麼表格中沒有姓名和附件？

合集資料表及公開報告排除個人欄位，因為報表可能分享。私人答案仍保存在回覆中，可由該應用的伺服器，或具備應用共用工作區 `read_personal` 權限的平台職員讀取。超級管理員沿用共用工作區的存取權限。`personal: false` 是安全分類聲明，不會替你去識別；也不要把個人資料寫進表單標題、欄位標籤、respondent 或報表註解。

## 更新答案會產生重複嗎？

流程：沿用同一私人憑證及申請，修改項目帶 item；每個新動作產生 operation_id，結果未知重送原請求。詳見[流程重試](workflow-ui.md#retry)。

普通表單：同一表單及 respondent 只有一份回覆。使用穩定 respondent，送完整答案、`replace: true`、目前 `expected_version` 和明確時間。成功後保存 id／version。精確重試保留相同內容、時間及原 expected_version，會傳回原結果；建立表單及合集則沒有這個保障。

## 收到 response_changed 應怎樣處理？

用 `GET /forms/:id/responses?respondent=固定匿名編號` 重新讀取該回覆者的最新回覆，核對來源哪份資料較新，再決定下一次更新。不要自動只提高 expected_version 然後覆寫。未使用 expected_version 的舊式 replace 不具相同重試保障。

## 請求逾時可以直接重送嗎？

GET 可重讀；有 expected_version 的回覆可精確重試；record 依固定 record_id 重試；附件保留 external_id 和檔案摘要。建立表單／合集結果不明時先查核，不能盲目重送。報告連結在仍有效時會回用同一個，但停用或過期後重新建立會產生新連結。

## 原始長文、歷史和檔案怎樣保存？

最新表單答案用 responses；歷史用 append-only records。`data` 可存私人原文但每筆 compact JSON 最多 65,536 bytes，不進報表；較大內容需要你按來源設計分段及清單。identified mode 應用可使用 uploads 保存 1 byte 至 50 MiB 的私人檔案，提交大小及 SHA-256，完成後由伺服器驗證。

## 刪除 records 會刪掉全部個人資料嗎？

不會。`DELETE /records?respondent=...` 只清除該回覆者的記錄 payload，保留 tombstone 防止重送復活；表單答案、私人附件及已凍結的分享／快照要另行處理。現有 uploads API 沒有刪除端點，附件保留／抹除需由營運管理員處理。

## API 是否自動建立儀表板？

API 準備好資料。管理員在應用工作區加入合集，再建立及核對儀表板。新指標預設未核實。個人報告需先在 OpenDashboard 設定範本名稱，再由 API 取得連結；API 不會自動發布或核實管理報告。

## 個人報告會看到其他人的資料嗎？

OpenDashboard 對合集和應用記錄按 respondent 重新查詢，只送該回覆者的行。手動匯入的資料表、固定文字及圖像可能對所有人相同；管理員不要把全體資料放在這類範本中。報告 URL 本身就是存取憑證，請私下提供，必要時停用。

## 表單或合集欄位想改怎樣做？

現有定義不能任意修改。PATCH fields 只改個人分類；欄位、型別或合集成員改動時建新表單／合集，保存新舊版本對應。歷史 record kind 使用新 schema 字串，不改舊聲明。既有指標、快照及分享不會被偷偷重寫。

## 哪些錯誤值得重試？

400 按 `fields`／`errors` 修正內容；401 檢查金鑰或應用停用狀態；404 檢查應用和測試／正式模式；409 按該端點處理衝突；413 拆分請求或縮減資料；429 按 Retry-After；5xx／逾時有限次重試，遵守端點的冪等規則。完整代碼見 API 參考。

## 新網站接入前要驗收甚麼？

驗證只有自己的應用可讀資料，測試／正式隔離，個人欄位被排除，兩份回覆及多人數分開計算，空群組保留字典，更新和重試不重複，以及個人報告只讀對應回覆者。可執行範例會驗證提交數、項目數、更新及精確重試。

## 新網站可以只用 OpenDashboard 保存表單資料嗎？

可以。新流程固定由 OpenDashboard 管理答案，外站只需保存身份／私人憑證對應。以下是普通連接應用表單的接法：網站顯示表單並核對使用者，後端直接呼叫 OpenDashboard 保存答案；答案、私人附件及歷史可由 OpenDashboard 的 responses／uploads／records 保存。你的網站不用另外建立表單答案資料庫，也可按需要選擇雙份保存。網站仍需伺服器端入口保護應用金鑰及回覆存取權，表單和合集 id 可保留在設定中。直接保存模式只有 OpenDashboard 確認保存成功才顯示提交成功；未成功時保留頁面答案並讓使用者重試。

## 直接保存後，資料和儀表板會即時更新嗎？

每次成功的 API 提交已保存在 OpenDashboard，不必等待匯入或同步排程。合集及個人報告在下次讀取時使用最新答案；儀表板在重新開啟或重新整理時刷新，目前沒有自動推送畫面更新。已有網站的批次匯入／同步是另外一種接入方式，不會限制新網站直接保存。

## 不保存本地答案，怎樣讓使用者修改自己的回覆？

從 OpenDashboard 讀取目前答案和版本，再以 expected_version 提交完整更新。應用金鑰只限該應用，但不會替網站辨認目前登入的訪客；網站後端需用自己的身份／存取憑證核對 respondent，不能信任瀏覽器任意傳來的編號。可用 `GET /forms/:id/responses?respondent=<ref>` 精確讀回該隊，不存在時為空陣列；不加參數才讀全體。後端仍須先核對身份，不能把全體私人答案送到瀏覽器。

## 可以在自己的網站顯示 OpenDashboard 的資料列表或圖表嗎？

可以由自己的後端讀取所屬應用資料，再交給自己的介面。答案列表使用 responses；排除個人欄位的報表資料使用合集 tables。管理員和一般訪客可看的資料不同，網站後端必須核對。現有個人報告可用按鈕連結開啟；可直接嵌入的通用列表／圖表元件尚未提供。

## 可否保留自己的資料庫並自動同步給 OpenDashboard？

可以用同一套提交／更新 API 接入。建議由網站在同一資料庫交易保存答案及待同步工作，背景工作依來源版本順序送出，成功後保存 OpenDashboard id／version。失敗保留待同步狀態並重試；OpenDashboard 接收成功前只可顯示本地保存成功。這個背景流程要由網站實作，建立連接應用不會自動接通任意資料庫。

## 兩邊都保存時，修改哪一份才算數？

先選定主要寫入端。網站為主時，所有修改先存網站，再同步 OpenDashboard；OpenDashboard 為主時，先確認 OpenDashboard 成功，再更新本地副本。每份回覆保留來源版本及 OpenDashboard 版本，衝突時核對內容，不可單靠時間較晚便覆寫。流程支援 workflow.application.changed 變更通知及處理回報；普通 responses 沒有通用回覆變更 webhook。兩者都沒有自動雙向合併或跨資料庫交易保證。原站回寫 intake 有專用的待處理指令通知；以 OpenDashboard 為主時，兩個 UI 共用中央版本檢查，不需要兩份答案互相覆寫。

## 資料保存及介面選項要綁在一起嗎？

不用。網站可以不保存本地答案，仍用自己的填表及資料列表；也可保留本地答案，使用 OpenDashboard 報告。同一套 API 支援這些組合。流程目前已提供完整頁面的 iframe，與連結共用問題和規則；普通 forms API 沒有可直接嵌入的通用元件。

## 只限職員或含個人資料的儀表板可以分享嗎？

可以由有 edit_boards 權限的人，在分享介面檢查接收者預覽及全部數據欄位，再確認公開分享警告。即時數據會變成當次的固定版本，來源 API 和工作區權限不會公開；每次更新分享都要重新確認。只有顯示、計算、分組或篩選用到的欄位會包含在分享中。任何取得分享連結的人都可以查看及轉傳。這個可選分享流程不改變合集、個人報告範本及匯出原有的個人欄位保護。

## 可否在 OpenDashboard 免登入填表並送回原站？

可以選用[免登入填表與原站回寫](intakes.md)。公開入口只建立新隊伍，再以私人連結修改；既有資料不會按姓名或電郵被認領。需要配置原站回寫程序及通知，單純匯入或建立表單不會自動啟用。

## 只在 OpenDashboard 看管理資料，外站是否完全不能讀答案？

管理畫面放在哪裡與金鑰權限不同。外站可以不提供名單／統計，但仍按權限讓參加者載入本隊草稿。現有應用金鑰可讀寫該應用資源，沒有自動變成僅寫入金鑰。要在服務端禁止任何答案讀取，需額外的受限存取層。

## 兩份表單是否要串成流程？報名網址在哪裡？

需要報名後交作品、補件或審核時，把步驟放在流程管理；普通獨立問卷仍用本身的填表網址。在流程管理選擇流程，再到「網站接入 → 報名連結」開啟或複製公開連結。原站同步的表單資料在同一流程的表單分頁查看。每隊繼續填寫用自己的私人連結，不是重新走公開入口。

## 接另一個網站是否要重寫 OpenDashboard？

一般不需要：新活動在流程管理完成設定，網站使用流程填表 API 或連結／iframe；需要副本時加流程通知。較廣的 workflows／runs／links 管理 API 及既有 intakes／commands／ack 合約繼續保留。每站仍需自己的欄位、身份、權限與附件對應。兩邊填表不代表兩邊各保存一套可任意覆蓋的正式答案，詳見[接入方式](integration-modes.md)。