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

第三方将知识文档写入门户知识库（本系统空间），并可触发入库流水线。
代码锚点：OpenKbDocumentController、OpenKbHmacFilter、OpenKb*Request。

基路径：/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 时发布并写入 PENDING 入库任务
POST	/api/open/kb/documents/status	PUBLISHED 发布入库；OFFLINE 下线并清向量
POST	/api/open/kb/documents/delete	按绑定 system_code + externalId 软删，并触发 OFFLINE 清理任务

成功响应 data：

字段	说明
docCode	门户文档业务编码
externalId	对方业务主键
status	DRAFT / PUBLISHED / OFFLINE
ingestStatus	PENDING / RUNNING / READY / FAILED
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 时立即发布并入 PENDING 任务

建议 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. 入库说明

发布后由 KbIngestWorker 异步消费：切块 → AiEmbeddingPort（场景 EMBEDDING）→ Redis Stack 向量索引 → ingest_status=READY|FAILED。
需在管理端为场景 EMBEDDING 绑定可用 Provider / Embedding 模型，并配置 API Key（禁止明文入库）。