{"record":{"id":"c35979619ddbbb64","repo":"jlcodes99/cockpit-tools","slug":"externalimport-app-payload","errorCode":null,"errorMessage":"[ExternalImport][App] payload 归一化失败，已忽略","messagePattern":"\\[ExternalImport\\]\\[App\\] payload 归一化失败，已忽略","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/App.tsx","lineNumber":973,"sourceCode":"            variant: 'secondary',\n          },\n        ],\n      });\n      console.warn('[ExternalImport][App] 当前版本不支持外部导入方式，已终止导入', {\n        currentVersion: currentVersion || null,\n        requiredVersion,\n        providerId: payload.providerId,\n      });\n      return false;\n    },\n    [showModal, t],\n  );\n\n  const handleExternalProviderImportRawPayload = useCallback(async (rawPayload: unknown) => {\n    console.info('[ExternalImport][App] 收到原始 payload:', rawPayload);\n    const normalized = normalizeExternalProviderImportPayload(rawPayload);\n    if (!normalized) {\n      console.warn('[ExternalImport][App] payload 归一化失败，已忽略');\n      return;\n    }\n    if (!(await ensureExternalImportVersionCompatible(normalized))) {\n      return;\n    }\n    const now = Date.now();\n    for (const [key, handledAt] of externalImportHandledAtRef.current) {\n      if (now - handledAt > EXTERNAL_IMPORT_DEDUPE_WINDOW_MS) {\n        externalImportHandledAtRef.current.delete(key);\n      }\n    }\n    const dedupeKey = buildExternalImportDedupeKey(normalized);\n    if (externalImportHandledAtRef.current.has(dedupeKey)) {\n      console.info('[ExternalImport][App] 重复外部导入 payload 已忽略');\n      return;\n    }\n    externalImportHandledAtRef.current.set(dedupeKey, now);\n    console.info('[ExternalImport][App] payload 归一化成功:', {","sourceCodeStart":955,"sourceCodeEnd":991,"githubUrl":"https://github.com/jlcodes99/cockpit-tools/blob/1ed8b77992d62ca81fabf744deb0839ad361d5bf/src/App.tsx#L955-L991","documentation":"handleExternalProviderImportRawPayload logs the raw external import payload and passes it through normalizeExternalProviderImportPayload. If normalization returns null/undefined the payload does not conform to the expected external import schema (missing or wrongly-typed fields such as providerId), so the app logs this warning and drops the payload without importing.","triggerScenarios":"Receiving a raw payload (deep link, clipboard, file drop) whose shape fails validation: missing providerId, wrong types for nested fields, malformed JSON that was partially parsed, or an unknown schema version.","commonSituations":"Hand-edited or truncated shared import files, exports from incompatible third-party tools, copy/paste losing part of the payload, or URL encoding mangling fields.","solutions":["Check the logged '[ExternalImport][App] 收到原始 payload:' line immediately above to see which field failed the schema.","Regenerate the import payload from a valid export rather than editing it by hand.","Validate the payload against the external import schema before sharing (all required fields present, correct types).","If it comes from another tool, confirm the payload matches this app's external import format/version."],"exampleFix":"// before\nconsole.info('[ExternalImport][App] 收到原始 payload:', rawPayload);\nconst normalized = normalizeExternalProviderImportPayload(rawPayload);\nif (!normalized) {\n  console.warn('[ExternalImport][App] payload 归一化失败，已忽略');\n  return;\n}\n// after\nconst parsed = ExternalProviderImportPayloadSchema.safeParse(rawPayload);\nif (!parsed.success) {\n  console.warn('[ExternalImport][App] payload 归一化失败:', parsed.error.issues);\n  return;\n}\nconst normalized = normalizeExternalProviderImportPayload(parsed.data);","handlingStrategy":"type-guard","validationCode":"function isValidExternalImportPayload(p: unknown): boolean {\n  if (typeof p !== 'object' || p === null) return false;\n  const o = p as Record<string, unknown>;\n  return typeof o.providerId === 'string' && o.providerId.length > 0 &&\n    typeof o.requiredVersion === 'string';\n}\nif (!isValidExternalImportPayload(rawPayload)) return;\n","typeGuard":"function isExternalImportPayload(v: unknown): v is ExternalProviderImportPayload {\n  return (\n    typeof v === 'object' && v !== null &&\n    typeof (v as any).providerId === 'string' &&\n    typeof (v as any).config === 'object'\n  );\n}\n","tryCatchPattern":"let rawPayload: unknown;\ntry {\n  rawPayload = JSON.parse(payloadSource);\n} catch {\n  console.warn('[ExternalImport][App] payload JSON 解析失败');\n  return;\n}\nconst normalized = normalizeExternalProviderImportPayload(rawPayload);\nif (!normalized) {\n  console.warn('[ExternalImport][App] payload 归一化失败，已忽略');\n  return;\n}","preventionTips":["Validate payloads with a schema library (zod) at the boundary before normalization","Log which field failed normalization to speed up diagnosis","Regenerate import payloads from the export feature instead of hand-editing","Round-trip test exports/imports when changing the payload schema"],"tags":["validation","import","schema","payload"],"backgroundTag":"schema-validation-failed","analyzedSha":"1ed8b77992d62ca81fabf744deb0839ad361d5bf","analyzedAt":"2026-09-05T09:51:41.178Z","contentChangedAt":"2026-09-05T09:51:41.178Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}