提交歷程追蹤
一份提交自建立至覆核的完整時序，用於回答分數的產生經過
要回答「這份作答為什麼是這個分數」或「這筆提交停在哪個階段」，逐一查詢各端點再行拼湊相當耗時。歷程（Trace）端點直接提供組合好的完整時序：
GET /v1/submissions/{submission_id}/trace需要 submissions:read。
歷程的定義與範圍
歷程是平台持久事件紀錄的唯讀投影，該紀錄以追加方式記載生命週期轉換與批閱事件。
它不是由現況即時拼湊而成。兩者的差異在於事後檢視：資源的目前狀態只說明現況，歷程則說明經過，包含已被後續版本取代的中間狀態。
它也不是內部可觀測性資料。OpenTelemetry span 與 LLM 追蹤等資料僅留存於維運端，不會出現於此。
結構
{
"submission_id": "sub_9Xw2Lp",
"source": "direct",
"status": "completed",
"events": [
{
"at": "2026-03-02T09:30:00Z",
"stage": "submission",
"type": "submission.created",
"visibility": "customer"
},
{
"at": "2026-03-02T09:31:02Z",
"stage": "grading",
"type": "response.grading_started",
"response_id": "resp_5Kc3Yv",
"question_ref": "q_7g2NkP:2",
"visibility": "customer"
},
{
"at": "2026-03-02T09:33:15Z",
"stage": "grading",
"type": "response.grading_completed",
"outcome": "graded",
"response_id": "resp_5Kc3Yv",
"question_ref": "q_7g2NkP:2",
"evidence": [{ "kind": "score", "earned": 7, "max": 10 }],
"visibility": "customer"
},
{
"at": "2026-03-02T09:33:15Z",
"stage": "submission",
"type": "submission.completed",
"status": "completed",
"visibility": "customer"
},
{
"at": "2026-03-02T14:10:00Z",
"stage": "revision",
"type": "response.evaluation_revised",
"response_id": "resp_5Kc3Yv",
"reason_code": "manual_regrade",
"message": "學生以替代論證方式作答，原評分低估其正確性。",
"evidence": [{ "kind": "score", "earned": 8.5, "max": 10 }],
"visibility": "customer"
}
]
}事件依時間排序，最早的在前。時間相同時以事件紀錄的流水序號作為穩定的次要排序，因此順序具確定性，同一份歷程讀取兩次的順序一致。
| 階段 | type |
|---|---|
submission | submission.created、submission.completed、submission.failed |
grading | response.grading_started、response.grading_completed（帶 outcome）、response.grading_failed（帶 reason_code） |
revision | response.evaluation_revised |
type 的值就是 Webhook 事件的名稱，一字不差。 歷程是同一批事件的持久投影，因此不會為同一件事取第二個名字；要把收到的送達對回歷程，直接比對字串即可。stage 是另一個軸，只用於分組顯示，不參與名稱。response.grading_completed 帶有評分的 outcome，因此一筆零分作答會顯示其原因（blank、content_irrelevant 或 sensitive_content），而非與一般的零分無從區分。
證據為指標而非內容
evidence 陣列帶的是指標，永遠不會內嵌內容。目前只有一種：
kind | 內容 |
|---|---|
score | earned / max |
kind 是可增加的列舉值，日後可能新增，請忽略無法辨識的值。
批閱的信心值不會出現在這裡，也不會出現在合約的任何位置。
它是平台內部用於工程與
研究的數值，對客戶端沒有可靠的意義。分流用途請改用評分結果上的
review_suggested 布林值。
可見性
每個事件標記為 customer 或 admin，端點依呼叫者過濾。租戶金鑰只會收到 customer 事件，過濾於伺服器端執行，admin 的內部診斷事件永遠不會回傳給租戶金鑰。
適用情境
客訴處理。 家長質疑分數時，歷程可一次提供完整脈絡：批閱時間、判定結果，以及何人在何時基於何種理由作出修改。
排查停滯的提交。 可逐項查看每一筆停在哪個階段，較反覆讀取提交物件更為直接。
稽核。 response.evaluation_revised 事件帶有理由與前後分數，附於紀錄中即構成一份可讀的異動軌跡。
若僅需覆核紀錄，GET /submissions/{id}/evaluation-revisions 更為精簡，它只回傳覆核，並帶有 delta 與前一次分數。