[thekfjie]

Summary

Fixes #903.

A successfully extracted PDF can show a failure reason in More information even though the database has no processing error. Keep error-free file responses empty instead of manufacturing an extraction failure.

• Apply the same response error resolution to file objects and processing-status responses.
• Preserve safe failure messages for actual failures, including legacy failed rows without an error code.
• Keep embedding errors separate and leave the existing failure-message sanitizer intact.

Reproduction

1. Use v0.4.6 with a PDF record containing processing_status=ready, processing_ready=true, extract_status=ready, extract_engine=mineru, extract_chars=638, extract_pages=1, and embed_status=none.
2. Leave processing_error_code and processing_error_message empty.
3. Map the record to the file-object or processing-status API response.

Actual behavior

The API returns a PDF extraction-failure message despite the successful state and empty stored error fields. More information renders that message as the failure reason.

Expected behavior

Files without processing errors retain an empty error message. Genuine failures continue to receive the existing safe explanation.

Root cause and approach

HumanizeFileProcessingError is a failure formatter: an empty code defaults to extract_failed. Response mapping called it unconditionally, including for successful, queued and empty files.

Add ResolveFileProcessingErrorMessage at the response boundary. It returns an empty message when the status is not failed and both error fields are empty after trimming. Otherwise it delegates to the existing formatter. Use it in the application status mapper and both HTTP response mappers.

The extraction pipeline and persisted records are unchanged. This also fixes existing successful records when they are read again.

Change type

• Bug fix

Affected areas

• Backend / API
• Files / RAG / extraction
• Frontend / UI behavior through corrected API data

Verification

All Go commands ran in backend with Go 1.26.10 and SQLite development headers.

• The new regression tests fail on unmodified v0.4.6 with the PDF failure message and pass with the fix.
• go test ./internal/application/processing ./internal/transport/http/conversation -count=1
• go test ./... -count=1
• go vet ./...
• make lint
• go test -race ./internal/application/processing ./internal/transport/http/conversation -count=1
• go test -tags nopostgres,noredis,nos3,noswagger,nomsgpack,nootlp ./internal/application/processing ./internal/transport/http/conversation -count=1
• git diff --check

Regression coverage includes PDF, document and image states; queued/extracting/embedding/ready states; whitespace-only fields; empty documents; independent embedding failures; legacy failures; coded failures; and safe handling of raw diagnostics.

Screenshots, API examples, or logs

Synthetic ready-PDF response before the fix:

processingStatus: ready
extractStatus: ready
processingErrorCode: ""
processingErrorMessage: "PDF 未提取到可读文本。该文件可能是扫描件、图片型 PDF、加密 PDF，或文档内容本身不可复制。"

After the fix, processingErrorMessage is empty. Processing-status responses likewise keep errorMessage empty.

The original Windows/MinerU upload was not replayed. This fixes the response inconsistency; it does not establish why the report's first PDF failed extraction.

Configuration, migration, and compatibility notes

No configuration change, database migration or data rewrite. No response fields are added or removed. Files with actual errors retain their safe failure messages.

Documentation

• No separate user documentation is required for this response-mapping fix.

Security and privacy

• Tests use synthetic metadata and contain no PDF contents or credentials.
• Existing user-scoped file lookup remains unchanged.
• Raw upstream diagnostics are still handled by the existing sanitizer.

Checklist

• Existing issues, related PRs and the current dev code were checked.
• The change is limited to error-message mapping and regression coverage.
• Repository quality checks and relevant tests passed.
• Build output, local settings and storage data are excluded.