06 — 知识库文档推送（HMAC）

第三方将知识文档写入门户知识库（本系统空间）；publish=true 或 status=PUBLISHED 时同步写入 Dify 共享库。
代码锚点：OpenKbDocumentController、OpenKbHmacFilter、OpenKb*Request、KbDifyDocumentSyncService。

基路径：/api/open/kb/documents
方法：全部为 POST（含删除语义的 /delete）。

---

1. 鉴权头

与 02-事项推送-HMAC.md 完全一致：

Header	必填	说明
X-Client-Id	是	SSO client_id
X-Timestamp	是	Unix 秒（epoch seconds）
X-Signature	是	HMAC-SHA256 的 Hex（大小写不敏感比对）
X-Idempotency-Key	否	可选对账键

时间窗：±300 秒。Client 须存在、启用、绑定 system_code、CONFIDENTIAL 且可解析 client_secret。

签名串：

{clientId}\n{timestamp}\n{rawBody}

system_code 始终取自 Client 绑定，不要在 body 里依赖自带 systemCode。

---

2. 接口清单

方法	路径	语义
POST	/api/open/kb/documents/upsert	按 system_code + externalId 创建或更新；publish=true 时同步发布到 Dify
POST	/api/open/kb/documents/status	PUBLISHED 同步发布到 Dify；OFFLINE 下线并从 Dify 删除
POST	/api/open/kb/documents/delete	按绑定 system_code + externalId 软删，并同步从 Dify 删除

成功响应 data：

字段	说明
docCode	门户文档业务编码
externalId	对方业务主键
status	DRAFT / PUBLISHED / OFFLINE
ingestStatus	草稿多为 PENDING；发布成功为 READY
jobCode	若触发发布/下线则返回成功审计任务编码，否则空串

禁止：OPEN 客户端覆写 source_type=PLATFORM 文档；禁止跨 system_code。

文档写入 Client 对应的 SYSTEM 知识空间（不存在则自动创建）。

---

3. UPSERT — POST /api/open/kb/documents/upsert

字段	必填	说明
externalId	是	对方业务主键
title	是	标题
content	否	正文（md/txt/html 直存 content_text）
fileCode	否	已上传平台文件编码（一期解析 md/txt/html）
contentType	否	默认 md
summary	否	短摘要
publish	否	true 时立即同步发布到 Dify；失败直接返回业务错误（正文已落库）

建议 content 与 fileCode 至少提供其一，否则发布会失败。

curl 示例

CLIENT_ID="demo-client"
SECRET="your-client-secret"
TS=$(date +%s)
BODY='{"externalId":"DOC-1001","title":"请假流程说明","content":"# 请假\n提交后等待审批。","contentType":"md","publish":true}'
SIG=$(node -e "const c=require('crypto');const b=process.argv[1],id=process.argv[2],ts=process.argv[3],s=process.argv[4];console.log(c.createHmac('sha256',s).update(id+'\n'+ts+'\n'+b).digest('hex'))" "$BODY" "$CLIENT_ID" "$TS" "$SECRET")

curl -sS -X POST "https://portal.example.com/api/open/kb/documents/upsert" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: $CLIENT_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -d "$BODY"

---

4. STATUS — POST /api/open/kb/documents/status

字段	必填	说明
externalId	是	对方业务主键
status	是	PUBLISHED 或 OFFLINE

---

5. DELETE — POST /api/open/kb/documents/delete

字段	必填	说明
externalId	是	对方业务主键

使用 POST（非 HTTP DELETE 方法），与事项开放 API 一致。

---

6. 发布说明

publish=true / status=PUBLISHED 在同一请求内调用 Dify Knowledge API 写入共享库，回填 dify_document_id，ingest_status=READY。
失败（未配置 Dataset、无正文、Dify HTTP 错误）直接返回业务错误（常见 code=400/502），不再写入 PENDING 队列。
OFFLINE / delete 按 dify_document_id 从 Dify 删除。个人/团队库不走本接口。
jobCode 仅为成功审计记录（kb_ingest_job.status=SUCCESS），无异步 Worker。