09 故障排除手冊

主要讀者：平台維護者、系統維運、值班工程師。

1 共用唯讀診斷

夜間採固定時間強制關閉，包含初始化失敗、中斷及卡住情境。值班時先在剩餘時間內保存線索，不能為除錯、寄報告或等待上傳延後關閉；早晨環境重新啟用後再追查。確切關閉時間與資源清單由環境設定提供。

先取得 triggerNum、planNum、envNum、runNum 及事件時間。以平台查詢結果或核准的唯讀資料庫連線診斷，不直接重新初始化資料、不修改 Run 為成功、不清除未知的 cache。

1-1 執行紀錄查詢

下列 SQL 使用 psql 變數 run_num。狀態值因層級不同而不同：Run 的 3 是完成，Case 的 3 是通過，Step 的 3 是錯誤。

BEGIN READ ONLY;
SET LOCAL statement_timeout = '10s';
SELECT run_num, plan_num, trigger_num, env_num, run_status,
       expected_suite_count, expected_case_count,
       run_start_time, run_end_time
FROM qa.qa_c008
WHERE run_num = :'run_num'::bigint;

SELECT s.run_suite_num, s.suite_num, c.run_case_num, c.case_num,
       c.case_status, c.case_start_time, c.case_end_time
FROM qa.qa_c009 s
JOIN qa.qa_c010 c ON c.run_suite_num = s.run_suite_num
WHERE s.run_num = :'run_num'::bigint
ORDER BY s.run_suite_num, c.run_case_num;

SELECT c.run_case_num, d.run_step_num, d.step_num,
       d.step_order, d.step_type, d.step_status,
       d.step_start_time, d.step_end_time
FROM qa.qa_c009 s
JOIN qa.qa_c010 c ON c.run_suite_num = s.run_suite_num
JOIN qa.qa_c011 d ON d.run_case_num = c.run_case_num
WHERE s.run_num = :'run_num'::bigint
ORDER BY c.run_case_num, d.step_order, d.run_step_num;
ROLLBACK;

錯誤詳情可進一步查 runLog、stepError、stepResult 與 postProcResp。請求、回應及設定可能含敏感資訊，交班前遮罩。不要整份貼上 Environment 設定或認證日誌。

1-2 觸發器及環境重疊查詢

trigger_num 與 env_num 由事件紀錄提供。

BEGIN READ ONLY;
SET LOCAL statement_timeout = '10s';
SELECT trigger_num, plan_num, env_num, is_enabled,
       cron, last_run_time, next_run_time, notice_group_code
FROM qa.qa_c007
WHERE trigger_num = :'trigger_num'::bigint;

SELECT run_num, trigger_num, plan_num, run_status,
       run_start_time, run_end_time
FROM qa.qa_c008
WHERE env_num = :'env_num'::bigint
ORDER BY run_start_time DESC
LIMIT 30;
ROLLBACK;

只看到不同的 envNum 不代表實際資料來源隔離；須由維護者核對真正共用的服務與資料。資料模型與欄位定義見資料模型及資料字典。

1-3 日誌搜尋

LOG_FILE 是本次事件已取得的日誌檔。先按時間及 Run 範圍縮小，再查以下訊息。

rg -n 'launchScheduledPlan|asyncExecuteTaskHandle triggerNum|作業打架|排程失敗|cronText不得為空' "$LOG_FILE"
rg -n 'truncateAndInitDataByInTable|truncateTable start|initDataFromInTable start|test plan execute fail' "$LOG_FILE"
rg -n 'compareResultReportWorker|uploadJacoco|sendReport start|sendReport end|sendReportAsync error' "$LOG_FILE"

sendReport end 不能證明 Email 已送達，因管理端寄信流程仍可能捕捉錯誤。初始化的結束訊息也不能證明每張表成功，須檢查其間的錯誤與實際資料。

1-4 夜間保存與早晨核對

下列「5 分鐘」是診斷時間上限；若距固定關閉時間不足 5 分鐘，以關閉截止為準。

2 沒有新 Run、執行停滯或 EKS 狀態不明

2-1 現況限制

3 初始化不完整、案例錯誤或相依跳過異常

3-1 不可只依結束狀態判斷

4 報告未寄送、通過率可疑或結果缺漏

4-1 報告解讀規則

5 復原交班

依驗收文件重驗受影響案例。固定強制關閉政策已確認；實際截止時間、資源清單及線索保存機制仍須核對部署設定。本手冊提供診斷與交班步驟，不以臨時手動命令替代環境既有關閉控制。