知识库动态数据集成技术规范 (Draft V1.0)

1. 集成模式定义

1.1 主动读模式 (Pull Mode)

由系统定时或触发式访问外部 API，获取并更新数据。

• 配置项：

1.2 第三方主动更新模式 (External Push API)

此模式用于第三方系统（如 WMS、ERP）向本系统同步数据（如更新库存）。

• 端点地址：POST /api/v4/external/knowledge/synchronize
• 请求负载 (JSON Payload)：
• 核心逻辑：基于 tenantId 校验租户，基于 auth 校验应用权限，通过 externalId 定位唯一记录并更新 updates 内容。

2. UI 交互设计 (Schema Builder 侧)

在 SchemaBuilderClient.tsx 中计划新增 “数据集成中心” 模块：

• Tab 1: 同步策略选择：切换主动/被动。
• Tab 2: 映射配置器：可视化选择外部 Key 对应内部哪个字段。
• Tab 3: 运行日志与监控：查看最近一次同步的成功/失败情况。

3. 安全与流控 (Security)

• API Key 管理：为每个租户下的每个模板生成独立的加密凭证。
• 限流 (Rate Limiting)：单租户同步频率控制，防止压垮业务数据库。

1.3 后端代理同步接口 (Pull Proxy API)

由于前端存在跨域限制且需要统一鉴权，系统需提供一个中转接口：

• 接口地址：POST /api/v4/external/knowledge/pull
• 逻辑流程：

5. 开发者架构接入指引 (Architecture Guide)

为了让开发者（第三方集成方）明确操作流程，集成中心应提供以下可视化引导：

1. 数据建模：在 Schema Builder 中定义字段，并指定一个字段（如 产品 ID）作为 MatchKey (唯一匹配键)。
2. 凭证获取：在“管理后台 -> 第三方应用”为该对接方创建账号，获取 AppKey 和 AppSecret。
3. 配置映射：在集成中心绑定上述应用方案。
4. 接口对接：按照 1.2 节定义的协议发送 POST 请求。

[!IMPORTANT] MatchKey 的重要性：若不指定匹配键，系统将无法识别更新请求对应哪条记录，导致更新失败或产生冗余数据。

4. 凭证归属与安全 (Credentials & Security)

为了回答“凭证给谁”的问题，我们明确以下逻辑：

• 租户级凭证 (Tenant-Level)：ThirdPartyApp 实例由租助管理员在“应用管理”中统一创建。
• 模板级绑定 (Template-Level)：
• 单向隔离：凭证一旦绑定，该模板的所有同步任务将始终使用该凭证代表的第三方系统身份。