From f583d77fa05aef760da379f681afd5a6f9ad672a Mon Sep 17 00:00:00 2001 From: wizardchen Date: Tue, 14 Jul 2026 16:48:30 +0800 Subject: [PATCH] feat(knowledge): enhance error handling in knowledge spans Refactor the error handling logic in the GetKnowledgeSpans function to utilize a new helper function, knowledgeSpansLastError, which consolidates the logic for determining the last error from span failures and knowledge row failures. This improves clarity and maintainability of the code. Additionally, update test cases to cover new scenarios for last error handling. --- frontend/package-lock.json | 19 ++++++ frontend/package.json | 3 +- .../knowledge-processing-timeline.vue | 3 +- internal/handler/knowledge.go | 67 ++++++++++++------- internal/handler/knowledge_spans_test.go | 39 +++++++++++ 5 files changed, 105 insertions(+), 26 deletions(-) diff --git a/frontend/package-lock.json b/frontend/package-lock.json index 98f125e7..a4de98a6 100644 --- a/frontend/package-lock.json +++ b/frontend/package-lock.json @@ -43,6 +43,7 @@ "less": "^4.6.4", "less-loader": "^12.3.2", "npm-run-all2": "^8.0.4", + "tsx": "^4.23.1", "typescript": "~6.0.3", "vite": "^7.3.5", "vue-tsc": "^3.2.8" @@ -4859,6 +4860,24 @@ "node": ">=6.10" } }, + "node_modules/tsx": { + "version": "4.23.1", + "resolved": "https://mirrors.tencent.com/npm/tsx/-/tsx-4.23.1.tgz", + "integrity": "sha512-GQHnkIfxyx1wYCOS/wonik5MVRZU9hi1TEZmzGZSCJB1y9YgoZ8H6itNE/u4suE+yLmOzuE4E5S4TZ/ZX2wcWQ==", + "dev": true, + "dependencies": { + "esbuild": "~0.28.0" + }, + "bin": { + "tsx": "dist/cli.mjs" + }, + "engines": { + "node": ">=18.0.0" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + } + }, "node_modules/typescript": { "version": "6.0.3", "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz", diff --git a/frontend/package.json b/frontend/package.json index a68380ba..8b52a67c 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -10,7 +10,7 @@ "preview": "vite preview", "build-only": "vite build", "type-check": "vue-tsc --build", - "test": "node --test" + "test": "tsx --test" }, "dependencies": { "@microsoft/fetch-event-source": "^2.0.1", @@ -48,6 +48,7 @@ "less": "^4.6.4", "less-loader": "^12.3.2", "npm-run-all2": "^8.0.4", + "tsx": "^4.23.1", "typescript": "~6.0.3", "vite": "^7.3.5", "vue-tsc": "^3.2.8" diff --git a/frontend/src/components/knowledge-processing-timeline.vue b/frontend/src/components/knowledge-processing-timeline.vue index b6bb5d91..85486bf8 100644 --- a/frontend/src/components/knowledge-processing-timeline.vue +++ b/frontend/src/components/knowledge-processing-timeline.vue @@ -1224,9 +1224,10 @@ const primaryHeadTitle = computed(() => props.docTitle || t('knowledgeStages.tit watch( [ () => totalMs.value, - () => data.value?.parse_status, + () => headerStatus.value, () => currentStageIndex.value, () => currentStageLabel.value, + () => stages.value.length, ], () => { emit('update:summary', { diff --git a/internal/handler/knowledge.go b/internal/handler/knowledge.go index 55ccd933..15cbbf8b 100644 --- a/internal/handler/knowledge.go +++ b/internal/handler/knowledge.go @@ -722,30 +722,15 @@ func (h *KnowledgeHandler) GetKnowledgeSpans(c *gin.Context) { "current_stage": currentStageName, "trace": tree, } - if lastErr != nil { - resp["last_error"] = gin.H{ - "stage": lastErr.Name, - "code": lastErr.ErrorCode, - "message": lastErr.ErrorMessage, - "name": lastErr.Name, - "error_code": lastErr.ErrorCode, - "error_message": lastErr.ErrorMessage, - "finished_at": lastErr.FinishedAt, - } - } else if currentAttempt == latestAttempt && knowledge.ParseStatus == types.ParseStatusFailed && knowledge.ErrorMessage != "" { - // The knowledge row can be failed by recovery/dead-letter paths after - // the main root span has already closed. Surface that authoritative - // failure reason instead of leaving the detail drawer with a red status - // but no explanation. - resp["last_error"] = gin.H{ - "stage": "knowledge_processing", - "code": "UNKNOWN", - "message": knowledge.ErrorMessage, - "name": "knowledge_processing", - "error_code": "UNKNOWN", - "error_message": knowledge.ErrorMessage, - "finished_at": knowledge.UpdatedAt, - } + if lastError := knowledgeSpansLastError( + currentAttempt, + latestAttempt, + knowledge.ParseStatus, + knowledge.ErrorMessage, + knowledge.UpdatedAt, + lastErr, + ); lastError != nil { + resp["last_error"] = lastError } c.JSON(http.StatusOK, gin.H{ "success": true, @@ -753,6 +738,40 @@ func (h *KnowledgeHandler) GetKnowledgeSpans(c *gin.Context) { }) } +// knowledgeSpansLastError builds the last_error payload for GetKnowledgeSpans. +// Span failures win when present; otherwise a failed knowledge row without a +// matching span error (recovery / dead-letter paths) surfaces ErrorMessage. +func knowledgeSpansLastError( + currentAttempt, latestAttempt int, + parseStatus, knowledgeErrorMessage string, + knowledgeUpdatedAt time.Time, + spanFailure *types.KnowledgeProcessingSpan, +) gin.H { + if spanFailure != nil { + return gin.H{ + "stage": spanFailure.Name, + "code": spanFailure.ErrorCode, + "message": spanFailure.ErrorMessage, + "name": spanFailure.Name, + "error_code": spanFailure.ErrorCode, + "error_message": spanFailure.ErrorMessage, + "finished_at": spanFailure.FinishedAt, + } + } + if currentAttempt != latestAttempt || parseStatus != types.ParseStatusFailed || knowledgeErrorMessage == "" { + return nil + } + return gin.H{ + "stage": "knowledge_processing", + "code": "UNKNOWN", + "message": knowledgeErrorMessage, + "name": "knowledge_processing", + "error_code": "UNKNOWN", + "error_message": knowledgeErrorMessage, + "finished_at": knowledgeUpdatedAt, + } +} + // buildSpanTree assembles a flat list of span rows into a parent-child // tree rooted at the (knowledge, attempt)'s root span. Missing canonical // stages are filled in with pending placeholders so the UI always renders diff --git a/internal/handler/knowledge_spans_test.go b/internal/handler/knowledge_spans_test.go index 1f9c4191..be31d985 100644 --- a/internal/handler/knowledge_spans_test.go +++ b/internal/handler/knowledge_spans_test.go @@ -122,3 +122,42 @@ func TestBuildSpanTree_LastFailureSurfaces(t *testing.T) { "last_error must point at the actually-failed span, not the cascade-cancelled downstream") a.Equal("DOCREADER_TIMEOUT", lastFail.ErrorCode) } + +func TestKnowledgeSpansLastError_PrefersSpanFailure(t *testing.T) { + now := time.Now() + spanFail := &types.KnowledgeProcessingSpan{ + Name: types.StageDocReader, + ErrorCode: "DOCREADER_TIMEOUT", + ErrorMessage: "slow", + FinishedAt: &now, + } + + got := knowledgeSpansLastError(2, 2, types.ParseStatusFailed, "recovery blew up", now, spanFail) + a := assert.New(t) + a.Equal(types.StageDocReader, got["name"]) + a.Equal("DOCREADER_TIMEOUT", got["error_code"]) + a.Equal("slow", got["error_message"]) +} + +func TestKnowledgeSpansLastError_RecoveryFallbackUsesKnowledgeMessage(t *testing.T) { + now := time.Now() + got := knowledgeSpansLastError(2, 2, types.ParseStatusFailed, "wiki ingest timed out", now, nil) + a := assert.New(t) + a.NotNil(got) + a.Equal("knowledge_processing", got["name"]) + a.Equal("UNKNOWN", got["error_code"]) + a.Equal("wiki ingest timed out", got["error_message"]) + a.Equal(now, got["finished_at"]) +} + +func TestKnowledgeSpansLastError_SkipsRecoveryFallbackForHistoricalAttempt(t *testing.T) { + now := time.Now() + got := knowledgeSpansLastError(1, 2, types.ParseStatusFailed, "wiki ingest timed out", now, nil) + assert.Nil(t, got) +} + +func TestKnowledgeSpansLastError_SkipsRecoveryFallbackWithoutMessage(t *testing.T) { + now := time.Now() + got := knowledgeSpansLastError(2, 2, types.ParseStatusFailed, "", now, nil) + assert.Nil(t, got) +}