From c695125dcec9a1aecc52ca9a0297ec8ae9c17e22 Mon Sep 17 00:00:00 2001 From: nullkey Date: Tue, 21 Jul 2026 00:20:57 +0800 Subject: [PATCH] =?UTF-8?q?fix(feishu):=20resilient=20large-wiki=20sync=20?= =?UTF-8?q?=E2=80=94=20retry,=20streaming=20resume,=20failure=20visibility?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Large Feishu wikis stopped syncing after the first batch (Tencent/WeKnora#2136: 5000+ docs, only ~150 ingested; #1262: a child-list failure aborted the run). Three compounding causes, fixed in layers: 1. Rate-limit / transient failures had no retry. Feishu's wiki/drive/export APIs are aggressively rate limited; a thousand-doc sync issues tens of thousands of calls, and a single 429/5xx burst failed whole swathes of docs. Add exponential backoff honouring Retry-After to doRequest (JSON) and downloadRawBytes (files): 429 up to 3x, 5xx once, transport errors back off. 2. The batch path fetched the entire tree into memory before ingesting, so a sync that hit the 2h task timeout lost all progress and restarted from scratch, and a transient per-document export failure advanced the cursor and skipped that doc permanently. Add an optional StreamingConnector interface, implemented for Feishu: FetchStream interleaves fetch -> ingest -> checkpoint, bounding memory to one item and persisting a per-node edit-time cursor at page boundaries. The service dispatches to it via type assertion; connectors without it fall back to FetchAll / FetchIncremental unchanged (non-breaking). A resumed/incremental run skips nodes already recorded at their current edit time (converges), a failed fetch does not advance the cursor (retried next run instead of dropped), and partial listing failures emit error items and carry prior edit times forward instead of aborting the sync. 3. Failures and skips were invisible. Unsupported node types (mindnote/slides/…) were skipped with no item, error or log ("13 docs synced only 3"). FetchAll now tallies discovered/fetched/failed/skipped per resource with a per-type skip breakdown and a progress line every 100 nodes. The backend already persisted per-item errors in SyncLog.result.errors but the frontend type omitted the field; declare `result` on SyncLog and render up to 50 failed documents in the sync-log drawer (#1262). i18n for zh-CN/en-US/ko-KR/ru-RU. result.errors is a jsonb column shipped in every list response, so it is capped at 100 samples server-side (recordSyncError); the exact failure total comes from the bounded items_failed counter, which the drawer uses for its count and "N more" line so a sync that fails thousands of docs stays bounded. Each sample is a structured, localisable SyncItemError instead of a raw "title: ...api error: status=500 body={json}" dump that repeated the title and leaked status/body/log_id. The connector (feishuFailure) classifies the error into a stable i18n code (+ the feishu code as a param); the service builds {title, code, params, message}; the drawer localises via vue-i18n to the viewer's language (zh/en/ko/ru), falling back to message. A custom UnmarshalJSON keeps old string-form logs readable. The banner is localised from items_failed too. Raw errors stay in the server logs. Follows the two-tier norm of Airbyte/Fivetran/Onyx: human, actionable, localised summaries in the UI; raw detail in logs. Transient errors say "will retry" (the cursor is retained); auth/permission errors point at the fix instead. Tests: client_retry_test (backoff), tally_test (accounting), connector_stream / datasource_stream (streaming dispatch + checkpoint), connector_convergence (timeout + transient-failure resume converges to full coverage; proven to catch #2136 via bug injection), datasource_result_cap (error-sample cap + structured localisable SyncItemError, no raw body), connector_error_reason (error→i18n-code classification), sync_item_error (legacy-string + structured back-compat) — all in the normal suite. connector_realapi / connector_seed are an opt-in real-Feishu harness gated by the feishu_integration build tag AND env vars, never run in CI. --- frontend/src/api/datasource/index.ts | 24 ++ frontend/src/i18n/locales/en-US.ts | 13 + frontend/src/i18n/locales/ko-KR.ts | 13 + frontend/src/i18n/locales/ru-RU.ts | 13 + frontend/src/i18n/locales/zh-CN.ts | 13 + .../knowledge/settings/DataSourceSyncLogs.vue | 81 ++++- .../service/datasource_result_cap_test.go | 67 ++++ .../application/service/datasource_service.go | 309 ++++++++++++++--- .../service/datasource_service_test.go | 4 +- .../service/datasource_stream_test.go | 117 +++++++ internal/datasource/connector.go | 42 +++ .../datasource/connector/feishu/client.go | 270 +++++++++++---- .../connector/feishu/client_retry_test.go | 173 ++++++++++ .../datasource/connector/feishu/connector.go | 319 +++++++++++++++++- .../feishu/connector_convergence_test.go | 274 +++++++++++++++ .../feishu/connector_error_reason_test.go | 108 ++++++ .../feishu/connector_realapi_test.go | 223 ++++++++++++ .../connector/feishu/connector_seed_test.go | 150 ++++++++ .../connector/feishu/connector_stream_test.go | 300 ++++++++++++++++ .../connector/feishu/connector_test.go | 37 +- .../datasource/connector/feishu/tally_test.go | 45 +++ internal/types/datasource.go | 51 ++- internal/types/sync_item_error_test.go | 44 +++ 23 files changed, 2565 insertions(+), 125 deletions(-) create mode 100644 internal/application/service/datasource_result_cap_test.go create mode 100644 internal/application/service/datasource_stream_test.go create mode 100644 internal/datasource/connector/feishu/client_retry_test.go create mode 100644 internal/datasource/connector/feishu/connector_convergence_test.go create mode 100644 internal/datasource/connector/feishu/connector_error_reason_test.go create mode 100644 internal/datasource/connector/feishu/connector_realapi_test.go create mode 100644 internal/datasource/connector/feishu/connector_seed_test.go create mode 100644 internal/datasource/connector/feishu/connector_stream_test.go create mode 100644 internal/datasource/connector/feishu/tally_test.go create mode 100644 internal/types/sync_item_error_test.go diff --git a/frontend/src/api/datasource/index.ts b/frontend/src/api/datasource/index.ts index 2c4caa8e..ee6eb20d 100644 --- a/frontend/src/api/datasource/index.ts +++ b/frontend/src/api/datasource/index.ts @@ -25,6 +25,29 @@ export interface DataSource { latest_sync_log?: SyncLog } +/** + * One user-facing failure sample. The backend sends a stable i18n `code` + * (+ interpolation `params`) so the UI localises it to the viewer's language; + * `message` is a fallback when no i18n key exists (old logs decode into it). + */ +export interface SyncItemError { + title?: string + code?: string + params?: Record + message?: string +} + +export interface SyncResultDetail { + total?: number + created?: number + updated?: number + deleted?: number + skipped?: number + failed?: number + /** Per-item failure samples (capped); localised in the sync-log drawer. */ + errors?: SyncItemError[] +} + export interface SyncLog { id: string data_source_id: string @@ -38,6 +61,7 @@ export interface SyncLog { items_skipped: number items_failed: number error_message: string + result?: SyncResultDetail } export interface ConnectorMeta { diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts index a4d5f761..9e451bbc 100755 --- a/frontend/src/i18n/locales/en-US.ts +++ b/frontend/src/i18n/locales/en-US.ts @@ -6216,6 +6216,19 @@ export default { startTime: 'Started', endTime: 'Finished', duration: 'Duration', + failedItems: 'Failed documents', + failedItemsMore: '{n} more failed documents not shown', + docsFailedSummary: '{n} document(s) failed to sync', + }, + syncError: { + feishu_auth_or_permission: 'Authentication or permission error; check credentials and app permissions', + feishu_rate_limited: 'Feishu API rate limited; will retry on the next sync', + feishu_timeout: 'Export or request timed out; will retry on the next sync', + feishu_server_unavailable: 'Feishu service temporarily unavailable; will retry on the next sync', + feishu_api_error: 'Feishu API error (code={code}); will retry on the next sync', + feishu_api_error_generic: 'Feishu API error; will retry on the next sync', + sync_failed: 'Sync failed; will retry on the next sync', + ingest_failed: 'Ingest failed; see server logs', }, connector: { feishu: 'Feishu', diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.ts index 7cdb5aea..d1b0b25c 100755 --- a/frontend/src/i18n/locales/ko-KR.ts +++ b/frontend/src/i18n/locales/ko-KR.ts @@ -6221,6 +6221,19 @@ export default { startTime: "시작 시간", endTime: "종료 시간", duration: "소요 시간", + failedItems: "실패한 문서", + failedItemsMore: "표시되지 않은 실패 문서 {n}개", + docsFailedSummary: "문서 {n}개 동기화 실패", + }, + syncError: { + feishu_auth_or_permission: "인증 또는 권한 부족: 자격 증명과 앱 권한을 확인하세요", + feishu_rate_limited: "Feishu API 요청 제한, 다음 동기화 시 다시 시도합니다", + feishu_timeout: "문서 내보내기 또는 요청 시간 초과, 다음 동기화 시 다시 시도합니다", + feishu_server_unavailable: "Feishu 서비스가 일시적으로 사용 불가, 다음 동기화 시 다시 시도합니다", + feishu_api_error: "Feishu API 오류(code={code}), 다음 동기화 시 다시 시도합니다", + feishu_api_error_generic: "Feishu API 오류, 다음 동기화 시 다시 시도합니다", + sync_failed: "동기화 실패, 다음 동기화 시 다시 시도합니다", + ingest_failed: "가져오기 실패, 서버 로그를 확인하세요", }, connector: { feishu: "페이슈 (Feishu)", diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts index 562d09f5..8a3c5558 100755 --- a/frontend/src/i18n/locales/ru-RU.ts +++ b/frontend/src/i18n/locales/ru-RU.ts @@ -6042,6 +6042,19 @@ export default { startTime: 'Время начала', endTime: 'Время окончания', duration: 'Длительность', + failedItems: 'Документы с ошибкой', + failedItemsMore: 'Ещё {n} документов с ошибкой не показаны', + docsFailedSummary: 'Не удалось синхронизировать документов: {n}', + }, + syncError: { + feishu_auth_or_permission: 'Ошибка аутентификации или недостаточно прав; проверьте учётные данные и права приложения', + feishu_rate_limited: 'Превышен лимит запросов к API Feishu; повтор при следующей синхронизации', + feishu_timeout: 'Тайм-аут экспорта или запроса; повтор при следующей синхронизации', + feishu_server_unavailable: 'Сервис Feishu временно недоступен; повтор при следующей синхронизации', + feishu_api_error: 'Ошибка API Feishu (code={code}); повтор при следующей синхронизации', + feishu_api_error_generic: 'Ошибка API Feishu; повтор при следующей синхронизации', + sync_failed: 'Ошибка синхронизации; повтор при следующей синхронизации', + ingest_failed: 'Ошибка импорта; смотрите логи сервера', }, connector: { feishu: 'Feishu (Фэйшу)', diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts index 2544faf6..cfa75d5e 100755 --- a/frontend/src/i18n/locales/zh-CN.ts +++ b/frontend/src/i18n/locales/zh-CN.ts @@ -6241,6 +6241,19 @@ export default { startTime: "开始时间", endTime: "结束时间", duration: "耗时", + failedItems: "失败文档", + failedItemsMore: "还有 {n} 个失败文档未显示", + docsFailedSummary: "{n} 个文档同步失败", + }, + syncError: { + feishu_auth_or_permission: "应用鉴权或权限不足,请检查凭证与应用权限", + feishu_rate_limited: "飞书接口限流,下次同步时将重试", + feishu_timeout: "文档导出或请求超时,下次同步时将重试", + feishu_server_unavailable: "飞书服务暂时不可用,下次同步时将重试", + feishu_api_error: "飞书接口错误(code={code}),下次同步时将重试", + feishu_api_error_generic: "飞书接口错误,下次同步时将重试", + sync_failed: "同步失败,下次同步时将重试", + ingest_failed: "入库失败,详情见服务日志", }, connector: { feishu: "飞书", diff --git a/frontend/src/views/knowledge/settings/DataSourceSyncLogs.vue b/frontend/src/views/knowledge/settings/DataSourceSyncLogs.vue index 5167fc6d..b613aa40 100644 --- a/frontend/src/views/knowledge/settings/DataSourceSyncLogs.vue +++ b/frontend/src/views/knowledge/settings/DataSourceSyncLogs.vue @@ -1,7 +1,7 @@