feat(knowledge): add create-or-update file workflow

[hanxiantao]

Description

This PR adds POST /api/v1/knowledge-bases/{id}/knowledge/file/create-or-update, a unified multipart API for creating or replacing file knowledge.

The endpoint:

• creates a new file knowledge when no match exists;
• updates an existing file knowledge by explicit knowledge_id or unique file name;
• preserves the knowledge ID and existing references during replacement;
• defaults API-created documents to the api channel;
• supports optimistic concurrency with the current file hash and update version.

High-frequency updates use a durable latest-wins coordinator. Each knowledge has at most one active replacement and one pending replacement. New requests atomically replace the previous pending payload, so obsolete intermediate revisions are not parsed or indexed.

The implementation includes:

• PostgreSQL migration 000084 and SQLite migration 000004, plus MySQL and SQLite bootstrap schemas;
• startup recovery, task retry, dead-letter handling, cancellation, and stale-task reconciliation;
• atomic source-file and metadata replacement followed by re-indexing;
• active, pending, failed, and idle update states in knowledge responses;
• status polling, Swagger documentation, localized UI copy, and focused tests.

This PR intentionally exposes only the create-or-update endpoint. Retry and discard recovery APIs will be submitted separately.

Breaking changes: none. Existing file-create and knowledge APIs remain unchanged.

Type of Change

• New feature
• Documentation update
• Test
• Breaking change

Related Issue

Fixes #2615

Testing

Automated repository, service, handler, router, migration, frontend polling, i18n, type-checking, and Swagger validation passed for the changed workflow.

End-to-end verification covered:

• creating a new API-channel file knowledge;
• updating by explicit knowledge_id while preserving the ID;
• updating by unique file name without knowledge_id;
• concurrent high-frequency updates with one active and only the latest pending payload;
• monotonic update versions and replacement of intermediate pending revisions;
• promotion of the latest pending revision to active and final convergence to idle;
• final stored file hash matching the highest accepted update version;
• HTTP 409 for stale expected version and stale expected file hash;
• HTTP 200 with action=unchanged for identical content without increasing the version;
• deletion removing both the knowledge and its knowledge_file_update_slots row.

The database was inspected during the burst and confirmed that the active version remained stable while the pending slot was repeatedly replaced by the latest accepted version.

Checklist

• Changed source files are formatted
• Targeted backend and frontend tests pass
• High-frequency latest-wins behavior was verified end to end
• Database migrations and slot cleanup were verified
• Documentation and Swagger definitions are updated
• Breaking changes are documented

Screenshots / Recordings

Not included. The user-visible change is limited to transient update-state indicators.

[lyingbug]

是否把本PR拆开，感觉内容有些重，耦合了三个接口，是否有必然联系？

[hanxiantao]

是否把本PR拆开，感觉内容有些重，耦合了三个接口，是否有必然联系？

已拆分，可以再帮忙review下