# 公務 AI 認證 WebHR 介接 Q&A

供承辦人、測試與維運人員查閱。這個功能會查詢報名者的公務人員身分，並將符合條件的 AIATCG 取證資料送到人事總處。

整理日期：2026-10-13。以下以兩段對話最後確認的規則為準；PR 已開立不等於已部署，各站仍須確認版本。

## 報名與身分檢核

### Q1：兩支 API 分別做什麼？

**A：** `SendCheckResult` 查詢公務人員身分；`SendOrgReceive` 上傳取證資料。查詢成功不代表證照已上傳。

### Q2：什麼時候查身分？

**A：** 個人報名完成後立刻安排查詢；團體報名匯入後批次查詢。上傳取證資料前，還會再查一次。

### Q3：Y 和 N 是什麼意思？

**A：** Y 表示符合總處這支 API 的在職公務人員條件；N 表示不符合。N 不會說明原因，也不能單憑它判定身分證號填錯。

### Q4：查到 N 會擋報名或自動改價格嗎？

**A：** 不擋報名，只記錄結果。目前沒有定案要自動改價格；有疑問由承辦人確認。

### Q5：查詢失敗或逾時怎麼辦？

**A：** 報名照常完成，結果記為「未檢核」。管理員可在報名記錄頁按「重新檢核」。

### Q6：報名時是 Y，發證後就一定會上傳嗎？

**A：** 不一定。上傳前會重新查詢，當次結果為 Y 才上傳。N 記為「不送（非在職公務人員）」；查詢失敗則留待下次再試。

### Q7：外籍人士也會查嗎？

**A：** 目前只查 AIATCG 報名的本國身分證。外籍模式、居留證記為「不適用」。

### Q8：身分檢核結果在哪裡看？

**A：** 後台個人報名記錄頁的「人事總處身分檢核」卡片，可看最新結果、查詢時間與最近 10 次紀錄。這部分已開 PR #84，需合併並部署後才可使用。

## 證號與取證上傳

### Q9：證號前綴在哪裡設定？可以不填嗎？

**A：** 在後台認證設定填寫。證號由「前綴＋報名編號」組成；不填前綴，就沿用報名編號。

### Q10：前綴有哪些限制？

**A：** 最多 19 字，最後一個字不能是數字。報名編號最長 17 碼，完整證號不能超過總處要求的 36 碼。

### Q11：改前綴後，舊證書還能連回報名資料嗎？

**A：** 可以。排程與後台連結會取出證號末尾的報名編號來比對，不依賴目前設定的前綴。改設定不會改寫已發出的證書。

### Q12：哪些資料會排入取證上傳？

**A：** AIATCG 證書完成發證、且有可用證號的報名。實際新增上傳前，還須通過 Y 的身分檢核。

### Q13：人工發證也能上傳嗎？

**A：** 只有證書 hash 還不夠，還要有可用證號。目前人工發證表單的證號欄位仍是待處理項目，不能假設人工發證都能送。

### Q14：上線後會自動補送以前的證書嗎？

**A：** 不會自動補送全部歷史資料。需要補送時，可指定報名編號執行 `dgpa:send --apply=<報名編號>`。

### Q15：資料什麼時候自動上傳？

**A：** 每天台灣時間 10:00 處理當時所有待送資料。10:00 之後才排入的資料，通常等隔天；要提早送可人工執行。

### Q16：怎麼手動送一筆？怎麼先預覽？

**A：** 在已部署功能的主機執行：

```bash
# 只預覽，不連總處、不改送出狀態；仍會留下 dry-run 紀錄
php artisan dgpa:send --dry-run --apply=<報名編號>

# 真正送出，需輸入 send 確認
php artisan dgpa:send --apply=<報名編號>
```

beta、正式站若透過 `scripts/artisan.php` 載入環境設定，請依 MAINTAIN.md 使用該入口，並以網站服務帳號執行。

### Q17：HTTP 200、result=1、「已送達」是一樣的嗎？

**A：** 不一樣。HTTP 200 只代表收到回應，仍須看 result。取證 API 的 result=1 表示總處已收下這批資料；「已送達」不保證總處後續入檔作業已完成。

### Q18：上傳錯誤在哪裡看？

**A：** 個人報名頁的「人事總處 WebHR 送出狀態」卡片可看狀態、錯誤與呼叫紀錄。批次管理在後台「其他 → WebHR 取證上傳」，路徑為 `/admin/dgpaapi`。

### Q19：送達後改姓名、身分證號，或退回證書怎麼辦？

**A：** 已納入上傳流程的資料，修改姓名、證號或日期會排入重送。改身分證號會先刪除舊號資料，再新增新號資料；已送達的證書退回時，會排入刪除。刪除使用 `actiontype=2`，不再做 Y/N 檢核。

## 失敗與通知

### Q20：10:00 送失敗，當天會自動補送嗎？

**A：** 目前沒有當天補送排程。可等隔天 10:00，或人工重送。對話最後提出的 14:00 補送只是建議，尚未定案。

### Q21：哪些錯誤會自動重試？

**A：** 依原因處理：

| 情況 | 處理方式 |
|---|---|
| 連線失敗、逾時、result=3 或 9 | 留待隔天重試；累計達上限後需人工處理，預設上限 3 次 |
| result=8，批號重複 | 當場換批號，最多重送 3 次 |
| result=2，筆數不符 | 當場換批號重送 1 次；仍失敗則交人工處理 |
| result=B，逐筆資料錯誤 | 有錯的資料需人工確認、修正後重送 |
| result=4、5、6、7、A，或回應無法解析 | 保留待送、不計重試次數；先修正程式或設定，否則隔天仍可能失敗 |
| 上傳前身分檢核失敗 | 本輪先不送，隔天再查；不耗用取證上傳的重試次數 |

### Q22：查到 N，之後變成 Y 還能送嗎？

**A：** 可以。管理員從取證上傳頁重送，系統會再次檢核；當次查到 Y 才送。

### Q23：會發 Google Chat 通知嗎？

**A：** 會。取證上傳執行後會發結果摘要；身分查詢失敗也會通知。使用與發證完成相同的 `CHAT_WEBHOOK_OPS`。

### Q24：每次查到 Y 或 N 都會通知嗎？

**A：** 不會。成功的身分查詢只留在後台，避免訊息太多。dry-run 和 probe 也不發通知。通知不含姓名、身分證號，詳細資料請看後台。

## 呼叫紀錄與個資

### Q25：後台 log 的網址是什麼？

**A：** 各站網址後面加 `/admin/dgpaapilogs`，用管理員帳號登入。選單在「其他 → WebHR API 呼叫紀錄」。dry-run 預設隱藏，需勾選才會顯示。

### Q26：呼叫紀錄能連回報名頁嗎？

**A：** 明細頁可看相關報名。PR #84 另在列表加入「報名編號」欄：最多 3 筆直接顯示連結，更多則到明細頁查看。純 probe 測試沒有對應報名。

### Q27：`personId_hmac` 是什麼？會送給總處嗎？

**A：** 它是身分證號的比對指紋，方便查同一個人曾被送過哪些次。只存在紀錄中，不會送給總處。

### Q28：HMAC 能還原身分證號嗎？換 APP_KEY 有影響嗎？

**A：** HMAC 不能直接解密還原，但持有 APP_KEY 的人仍可能透過猜測比對找出原號碼，因此不能當成完全匿名資料。換 APP_KEY 後，新算的指紋也無法直接對上舊紀錄。

### Q29：log 存哪些內容？保存多久？

**A：** 保存呼叫時間、狀態、結果與遮罩摘要，身分證號另存 HMAC，密文只存雜湊。資料庫呼叫紀錄保存 3 年；檔案備份在 `storage/logs/dgpa-probe/`，檔案的清理需另外確認。

### Q30：送出的完整資料完全不留存嗎？

**A：** 呼叫 log 不留完整個資。但業務資料表 `dgpa_report.data_enc` 會用 APP_KEY 加密保存送出明細，供之後刪除或更正使用，需一併保護資料庫與金鑰。

## 辦公室通道與憑證

### Q31：為什麼 beta、正式站要經過辦公室？

**A：** 總處已確認會擋境外 IP。網站透過辦公室的台灣出口 IP 連線，讓總處看到已在白名單內的來源。

### Q32：NAS 要每天拉資料、送出、再回傳嗎？

**A：** 不用。已選定 SSH 反向通道搭配 tinyproxy。網站仍負責 10:00 排程、加密、送出與處理回應；NAS 只轉送連線。

### Q33：beta 和正式站共用一條通道嗎？開發機也要走嗎？

**A：** beta、正式站各有一條通道，避免互相影響。開發機維持直連，不設定 `DGPA_PROXY`。

### Q34：通道設定、金鑰應該放哪裡？

**A：** 範本與說明放在 `ops/dgpa-relay/`，實際設定與私鑰放在辦公室主機指定的部署目錄。真實 IP、金鑰不要放進版本庫。`storage/` 不適合放這套維運範本。

### Q35：NAS 看得到身分證號或需要總處 Key 嗎？

**A：** 不需要。TLS 連線由網站一路加密到總處，NAS 只轉送。總處 Key 留在網站端；NAS 仍需保護自己的 SSH 私鑰。

### Q36：NAS 關機或通道斷線會怎樣？

**A：** 網站會記錄連線錯誤，再依重試規則處理。autossh 會嘗試重連；恢復後可人工補送，或等下一次排程。

### Q37：有通道了，為什麼還要 TWCA 憑證？

**A：** 通道只解決網路路徑；網站仍要驗證總處的 HTTPS 憑證。缺中繼憑證時會出現 `unable to get local issuer certificate`，需補齊憑證鏈。

### Q38：部署會帶走憑證和本機 log 嗎？

**A：** 不會。`deploy.sh` 排除整個 `storage/`，本機資料庫紀錄也不會跟著部署。beta、正式站須各自安裝憑證鏈；`storage/logs/dgpa-probe/` 放的是 JSON 紀錄，不是憑證。

### Q39：TWCA 憑證要怎麼裝？

**A：** 依 MAINTAIN.md 的步驟匯入系統信任庫，或用 `DGPA_CA_BUNDLE` 指定完整憑證鏈。透過通道仍須保留 HTTPS 憑證驗證，不要關閉它。

## 測試與常見錯誤

### Q40：probe 各階段測什麼？

**A：**

| 階段 | 測試用途 | 對話中的結果 |
|---|---|---|
| 1-1 | 查詢測試號碼，確認身分 API 的加密與封裝 | result=1，身分結果 N |
| 2-1 | 取證 API 送空請求，確認可連線 | result=4，符合預期 |
| 2-2 | 送 0 筆，確認標頭與加密可解析 | result=A，傳送筆數不可為 0 |
| 3，不送 desc | 送測試明細，檢查各欄位 | result=B；另有「查無證號代碼」待解決 |

2-2 的成功不能單獨證明 `senddata` 的拼法正確；後來不送 `desc` 的階段 3，才成功進入明細檢查。

### Q41：省略 desc 要怎麼測？

**A：** 先預覽，再決定是否真的送：

```bash
php artisan dgpa:probe 3 --no-desc
php artisan dgpa:probe 3 --no-desc --send
```

真正送出時需輸入 `3` 確認。這是測試 API，不能用來上傳真實考生的證書。

### Q42：probe 3 的「日期格式錯誤」要修嗎？

**A：** 不用。預設生效日期刻意只送 6 碼，搭配測試身分證號，避免測試資料被收下。正式資料使用合法的 7 碼民國日期。

### Q43：`--valid-date` 是什麼？

**A：** 把測試生效日期改成合法的 7 碼，用來排除日期問題。這會拿掉日期錯誤這層保護，只靠測試身分證號，不能保證一定不會入檔。若取證 probe 回 result=1，應停止並聯絡總處確認、清理。

### Q44：為什麼之前一直回 result=7？

**A：** 總處確認程式把 `desc` 誤寫成 `B51desc`。省略 `desc` 後已回 B，成功進入明細檢查；不是已證實要改成 `personId` 或 `sendData`。

### Q45：現在正式流程還送 desc 嗎？

**A：** PR #83 改成省略這個非必填欄位，不是送空字串。總處預告 2026-10-16 可使用修正版，但目前尚未驗證修正；正式流程仍可先不送 desc。

### Q46：「外部證照代碼 查無證號代碼」怎麼處理？

**A：** 請總處確認系統設定的 `certcode`、`certnm` 與比對規則，並附測試批號與時間。大小寫兩種測試都出現同樣錯誤，不能只靠改大小寫解決。

### Q47：`scp` 出現 `subsystem request failed` 怎麼辦？

**A：** 若傳到 NAS，先確認 SFTP 是否啟用；也可用 `scp -O` 改走舊協定，或用 File Station 上傳。伺服器的專用通道帳號本來就不能傳檔，請用管理帳號。

### Q48：`REMOTE HOST IDENTIFICATION HAS CHANGED` 怎麼辦？

**A：** 先用管理帳號確認伺服器真正的主機金鑰指紋，再比對 NAS 的 `known_hosts`。確認是記錄過期或寫錯後才更新，並重啟通道容器；不要關掉主機驗證。

### Q49：自己產的 SSH 金鑰和 known_hosts 有什麼差別？

**A：** 自己產的金鑰證明「NAS 有權建立通道」；`known_hosts` 證明「連到的是正確伺服器」。修正 known_hosts 通常不用重產 NAS 金鑰。

### Q50：「無法寫入 dgpa_api_log」一定是沒跑 migration 嗎？

**A：** 不一定。先看 migration，再看 SQLSTATE。對話中曾因部署版本文字太長而失敗，PR #82 已改成只記 commit hash。真正送出前若寫不進稽核紀錄，probe 會拒絕送出。

### Q51：部署後會自動建立新資料表嗎？

**A：** 主機上的 `deploy.sh` 不會自動跑 migration，需依 MAINTAIN.md 手動執行。身分檢核另有 `dgpa_identity_check` 新表，不要只確認前兩張表。

### Q52：`config:cache` 找不到 storage/bootstrap/app.php，和 API 有關嗎？

**A：** 這是原有 bootstrap 路徑設定問題，與總處回應無關。需修正快取路徑設定；不要因此把 API 的資料庫錯誤也當成同一件事。

### Q53：連線 timeout 就代表缺憑證嗎？

**A：** 不是。TCP timeout 先查網路、白名單和通道；憑證錯誤表示已連上，但驗證未通過。總處首頁走不同網路，首頁能開不代表 WebHR API 能連。

## 正式上線

### Q54：現在可以直接開啟正式取證上傳嗎？

**A：** 依 2026-10-13 對話結尾，還不行。證照代碼與名稱尚待總處確認，`ORG_RECEIVE_KEYS_CONFIRMED` 仍為 false。beta 能跑 probe，不代表正式取證上傳已驗收。

### Q55：開 DGPA_ENABLED 就會全部開始送嗎？

**A：** 它會啟用相關身分查詢與排程，但取證送出還有確認開關與 Y/N 篩選。開啟前應先確認版本、migration、queue、cron、憑證、通道及通知設定。

### Q56：上線驗收要測哪些事？

**A：** 依序確認：

1. AIATCG 報名後能查到 Y/N，N 不擋報名，失敗顯示未檢核。
2. 團體匯入能批次檢核，後台可重新檢核。
3. 發證號碼含設定的前綴，仍能連回報名資料。
4. 真實合格考生上傳前會再查一次，Y 才送、N 不送。
5. 手動送出與每天 10:00 排程都能處理結果、顯示錯誤並發通知。
6. 呼叫紀錄能連回報名頁；通道中斷時留下錯誤，恢復後可補送。

真實取證測試應使用真正通過的考生資料，並與總處確認接收結果。

## 參考資料

- [功能規格](webhr-dgpa-integration-spec.md)
- [總處聯繫信件草稿](webhr-dgpa-email-draft.md)
- 主程式庫的 `MAINTAIN.md` 與 `ops/dgpa-relay/README.md`：主機與通道的逐步操作。
- 整理來源：Claude 對話 `session_0162SaNcuTbmCS6bZULbRXgg`、`session_01NDBxVXvq1bLuUWLPZu93xq`。
- PR #83、#84 在對話結尾為已開立待 review，本文未另查目前合併或部署狀態。