在 OpenDashboard 建好流程，接到你的網站

工程師接入路線與憑證

一般管理員先在現有 UI 建流程、設定問題和發佈權限；工程師取得該入口的金鑰後接入，毋須另外用 API 重建同一套表單。單份 API 的 form_id 不能直接代替流程的 node，表單回覆的 expected_version 也不能代替流程的 revision。

新工程師建議順序：先讀流程教學第 1–5 節，完成「讀定義 → 須知確認 → 開始 → 保存／提交 → 繼續 → 讀回」；需要副本才加通知。下載流程後端範例，按教程提供自己的持久化身份對應。此檔不自動建立申請或發佈流程。

既有應用 API 與報表

以下保留既有 /api/apps/v1 表單、資料及報表合約的接入說明。應用管理金鑰的範圍比流程填表金鑰廣，不應交給只需填寫一個流程的網站前端。普通 forms API 也不會自動產生多步報名入口。

新網站可從第一份表單開始直接保存到 OpenDashboard。已有資料的網站可匯入舊資料，之後持續同步或切換為直接保存；一次匯入不代表日後修改會自動同步。

1．取得測試金鑰

請 OpenDashboard 超級管理員在「連接應用」新增你的應用，選擇報表工作區。保存只顯示一次的測試金鑰和正式金鑰。

測試金鑰以 odb_test_ 開頭；正式金鑰以 odb_live_ 開頭。兩邊資料分開，每個應用只可存取自己的資料。把金鑰放在伺服器環境變數，不能放在前端 JavaScript、網址或公開儲存庫。

以下指令在你自己的伺服器／終端執行。將主機改為你獲准使用的 OpenDashboard 部署，先用測試金鑰。

export OPENDASHBOARD_BASE_URL='https://registration.konnec.ai'
# 從秘密管理服務或伺服器環境載入 OPENDASHBOARD_TEST_KEY；不要把金鑰寫入檔案。
curl --fail-with-body "$OPENDASHBOARD_BASE_URL/api/apps/v1/me?capabilities=true" \
  -H "Authorization: Bearer $OPENDASHBOARD_TEST_KEY"

成功會傳回應用資料、test: true，以及選填能力資訊。只有管理員開啟 identified_mode 的應用，才能使用電郵、電話及私人附件。不要把此模式當作公開個人資料的許可。

2．建立表單欄位

這個虛構工作坊讓每位聯絡人登記多位參加者。課程、場次和地點可做統計；匿名參加者編號只用作來源內部區分。

{
  "title": "Synthetic workshop registrations",
  "questions": [
    { "key": "program", "title": "課程", "type": "short_text", "personal": false },
    { "key": "session", "title": "場次", "type": "short_text", "personal": false },
    { "key": "location", "title": "地點", "type": "short_text", "personal": false },
    {
      "key": "participants", "title": "參加者", "type": "repeating_group",
      "min": 0, "max": 100, "personal": false,
      "fields": [
        { "key": "participant_ref", "label": "匿名參加者編號", "type": "text", "personal": false },
        { "key": "category", "label": "類別", "type": "text", "personal": false }
      ]
    }
  ]
}

將 JSON 保存為 form.json，送至 POST /api/apps/v1/forms。

curl --fail-with-body "$OPENDASHBOARD_BASE_URL/api/apps/v1/forms" \
  -H "Authorization: Bearer $OPENDASHBOARD_TEST_KEY" -H 'Content-Type: application/json' \
  --data-binary @form.json

保存回傳的 id 作為 FORM_ID。建立表單不是冪等操作：如果請求逾時而結果未知，先由管理員查核是否已建立，避免直接重送產生重複表單。

文字欄位預設屬個人資料；只對確認適合報表的非識別資料設定 personal: false。姓名、電郵、電話、附件等留在私人欄位。群組只要有一個個人欄位，整個群組就不會進入合集報表；如需人數統計，另建一個只含安全統計欄位的群組。

3．提交及更新回覆

由網站後端根據已核對的使用者身份，選擇穩定匿名編號作 respondent；沒有登入的表單也需安全的回覆識別及存取方法。不要讓瀏覽器任意指定要讀寫另一人的 respondent，也不要每次提交換一個編號，否則 OpenDashboard 會視為另一位回覆者。

{
  "respondent": "demo-contact-a",
  "answers": {
    "program": "合成課程", "session": "Demo A", "location": "Demo Room",
    "participants": [
      { "participant_ref": "demo-a-1", "category": "Demo" },
      { "participant_ref": "demo-a-2", "category": "Demo" },
      { "participant_ref": "demo-a-3", "category": "Demo" }
    ]
  },
  "submitted_at": "2026-01-01T00:00:00Z",
  "replace": true,
  "expected_version": 0
}

將它保存為 response.json，送至 POST /api/apps/v1/forms/$FORM_ID/responses。首次成功為 201，回傳回覆 id 和 version: 1。

curl --fail-with-body "$OPENDASHBOARD_BASE_URL/api/apps/v1/forms/$FORM_ID/responses" \
  -H "Authorization: Bearer $OPENDASHBOARD_TEST_KEY" -H 'Content-Type: application/json' \
  --data-binary @response.json

更新時由網站後端讀 GET /forms/$FORM_ID/responses?respondent=$RESPONDENT，在後端核對目前使用者有權管理這位回覆者，再送完整新答案、replace: true 及 OpenDashboard 目前的 expected_version。省略 respondent 會傳回整份表單的回覆，不可把全體答案直接傳到訪客瀏覽器。更新是整份取代，不是局部合併。

同一次寫入重試時，保留完全相同的答案、版本及 submitted_at。精確重送回傳 200 和原來的 id／版本。收到 409 response_changed 時，重新讀取並處理衝突；不要把舊資料強行覆蓋較新的版本。

4．建立合集及核對人數

用剛才回傳的表單 id 建立合集：

{ "title": "Synthetic workshops", "form_ids": ["<FORM_ID>"] }

送至 POST /collections，保存回傳的 COLLECTION_ID，再讀資料表。

curl --fail-with-body "$OPENDASHBOARD_BASE_URL/api/apps/v1/collections/$COLLECTION_ID/tables" \
  -H "Authorization: Bearer $OPENDASHBOARD_TEST_KEY"

submissions 每位回覆者每份表單一行。安全重複群組另外產生 unit: "項目" 的資料表；多選欄位另外產生 unit: "選項" 的資料表。表鍵以 groups: 開頭，應視為不透明識別，依回傳的 label、unit 和欄位字典選擇，不要解析或自行拼接。

空群組仍有欄位字典及 0 行資料。父層安全文字可出現在 parent:<key> 維度，方便分類；父層數值不會複製到每個子項目，避免重複加總。

5．在 OpenDashboard 建立儀表板

用管理員帳號打開應用所屬的工作區，在「數據來源」加入該應用的合集。合集會帶入回覆、題目、標籤，以及已宣告安全的群組資料表。

初始報告會分開顯示已提交表單、群組項目數、選項次數及有選項的項目數。設定區塊時先選對資料表，再選計數、平均或分類。所有新指標都未經核實，請由負責人核對後再標記；應用 API 不會自動發布或核實管理報告。

資料會在工作區重新開啟時刷新，保留已有指標和排版。安全分類改動會移除被撤回群組的舊快取。快照及已凍結的分享內容維持原值，需要另外更新分享。

6．提供個人報告連結

在工作區建立只使用適當合集資料的儀表板，設定穩定的「個人報告範本」名稱，例如 workshop_report。這與可重用的版面範本不同。

{
  "respondent": "demo-contact-a",
  "template": "workshop_report",
  "expires_in_days": 30
}

送至 POST /collections/$COLLECTION_ID/report-links，保存回傳的 url，放在你網站的「查看報告」按鈕。沒有對應範本會回傳 template_not_found，應先在 OpenDashboard 完成設定。

連結持有者不需要登入。OpenDashboard 每次開啟只讀取該回覆者的合集／應用記錄，不能把包含全體資料的手動資料表放進個人報告。不要公開轉貼個人連結。需要停用時送 DELETE /report-links/$REPORT_LINK_ID。

7．執行完整虛構範例

下載伺服器端範例。需要 Node.js 22.13 或更新版本，只接受測試金鑰。它建立一份表單和合集，提交 3＋4 個參加者，驗證重試不重複，再更新為 2＋4。它不寄信、不建立真人資料、不自動發布儀表板。

export OPENDASHBOARD_BASE_URL='https://registration.konnec.ai'
export OPENDASHBOARD_EXAMPLE_STATE='./opendashboard-example-state.json'
# 先在伺服器環境提供 OPENDASHBOARD_TEST_KEY。
node example.mjs

預期結果：submissions: 2、participantsBefore: 7、participantsAfter: 6，附表單和合集 id。範例將合成答案直接送到 OpenDashboard；本地狀態檔只保存資源 id 和操作狀態，不保存答案、附件或金鑰。重新執行會使用本地狀態檔的 id，不會重建定義。狀態檔屬私人操作記錄，不能提交到公開儲存庫；若出現 pending，先確認前次建立操作結果。

個人報告需由管理員先建立範本；按上一步再取得連結。不要把測試 id 搬去正式環境：正式金鑰要建立自己的表單及合集。

8．正式接入及日常維護

先完成測試環境驗收：欄位及型別一致、空群組、多人群組、更新和重試、人數、個人報告隔離，以及個人欄位不進報表。通過後由負責人切換正式金鑰，保存來源編號與 OpenDashboard id／版本的對應。

同步器應記錄不含秘密和個人答案的結果，採有限次重試及告警。429 按 Retry-After 等待；5xx／逾時依各端點的冪等規則重試。表單或合集結構變了就建新定義；金鑰輪換後更新伺服器設定。

私人原文或歷史資料可用 Records API 的 data；它不進入報表。檔案需要 identified mode 的私人 uploads API，不能只貼一個網址便當作已備份附件。完整 API 參考及常見問題列出限制、錯誤和操作方法。

資料變更通知與自動同步

同步由外部網站的後端觸發。資料儲存與待送事件應放在同一交易；提交成功後喚醒背景 worker，只處理變動的穩定 respondent。用單回覆查詢取得目前版本，再送完整答案及 expected_version。失敗保留待辦、延遲重試；重啟先補送待辦。通知本身不是耐久佇列，不應在瀏覽器保存應用 key 或只依賴一次網絡呼叫。低頻全量對帳可補漏；OpenDashboard 不會因建立表單而自動監看外部資料庫。

流程資料副本

外站需要接收 OpenDashboard 報名與作品資料時，使用流程資料同步：核對表單與步驟對應、沿用固定申請編號，並在「網站接入」設定資料變更通知。