Add Cloud Tour Libo knowledge graph platform

docs/API_REFERENCE.md

@@ -6,12 +6,18 @@ FastAPI 会自动生成交互式 API 文档。启动服务后访问：
 http://localhost:8102/docs
 ```
 
-所有后台接口统一挂载在：
+后台管理接口统一挂载在：
 
 ```text
 /v1/admin
 ```
 
+第三方系统对接接口统一挂载在：
+
+```text
+/v1/openapi
+```
+
 ## 常用接口
 
 | 接口 | 方法 | 说明 |
@@ -31,7 +37,8 @@ http://localhost:8102/docs
 | `/v1/admin/plaza/overview` | `GET` | 图谱广场概览 |
 | `/v1/admin/manual-ingest/extract` | `POST` | 手动抽取 |
 | `/v1/admin/travel/assistant-query` | `POST` | 旅行客服问答 |
-| `/v1/admin/travel/customer-service-query` | `POST` | 百姓惠智能客服外部问答接口 |
+| `/v1/openapi/knowledge-qa/query` | `POST` | 百姓惠智能客服第三方问答接口 |
+| `/v1/admin/travel/customer-service-query` | `POST` | 兼容旧版外部问答接口 |
 | `/v1/admin/super-agent/run` | `POST` | Super Agent 任务 |
 | `/v1/admin/roles` | `GET/POST` | 角色管理 |
 | `/v1/admin/users` | `GET/POST` | 用户管理 |
@@ -76,30 +83,38 @@ curl http://localhost:8102/v1/admin/travel/assistant-query \
 
 ## 百姓惠智能客服外部接口
 
-该接口用于对接外部客服系统。调用方传入用户自然语言问题，服务端默认选择百姓惠旅行社知识图谱，先召回图谱线路、报价口径、费用、酒店、餐饮、车辆和证据，再用 LLM 融合成客服可直接使用的话术。没有配置 LLM 时会自动退回图谱模板回答。
+该接口用于对接外部客服系统。调用方传入用户自然语言问题，服务端默认选择百姓惠旅行社知识图谱，按“LLM 生成只读 Cypher -> FalkorDB 图查询 -> LLM 基于证据组织答案”的链路返回客服话术和图谱证据。生产环境需要配置问答环节 LLM。
 
-认证方式使用接口 Key，默认本地开发值来自 `.env` / `docker-compose.yml` 的 `INGEST_API_KEYS`：
+认证方式使用接口 Key。Key 可以在后台 `系统 -> Agent 设置 -> 外部图谱问答 API` 维护；同时兼容 `.env` / `docker-compose.yml` 的 `INGEST_API_KEYS`。同一模块底部可以配置“问答环节 LLM 模型”，外部客服话术融合会优先使用该模型，未填写时继承全局 LLM：
 
 ```bash
-curl http://localhost:8102/v1/admin/travel/customer-service-query \
+curl http://localhost:8102/v1/openapi/knowledge-qa/query \
   -H 'Content-Type: application/json' \
   -H 'X-KG-API-Key: dev-key-1' \
   -d '{
+    "request_id": "crm-msg-20260610-0001",
     "question": "黄小西三日游多少钱？",
-    "knowledge_graph": "百姓惠",
+    "graph_name": "baixinghui_travel_agency",
     "session_id": "demo-session-001",
+    "channel": "online_service",
+    "customer_id": "customer-001",
     "use_llm": true,
     "llm_fusion": true
   }'
 ```
 
+新系统请优先使用 `/v1/openapi/knowledge-qa/query`；`/v1/admin/travel/customer-service-query` 仅用于兼容已经接入的内部/旧系统。
+
 常用入参：
 
 | 字段 | 说明 |
 | --- | --- |
+| `request_id` / `message_id` | 外部系统请求或消息 ID，可选；不传时服务端生成 |
 | `question` / `text` | 用户原始咨询内容，必填 |
-| `knowledge_graph` / `graph_name` | 知识图谱名称，可传 `百姓惠`、`bxh` 或 `baixinghui_travel_agency` |
+| `graph_name` / `knowledge_graph` | 知识图谱名称；不传时使用后台默认图谱。百姓惠可传 `百姓惠`、`bxh` 或 `baixinghui_travel_agency` |
 | `session_id` | 外部客服会话 ID，可选 |
+| `channel` | 来源渠道，如 `web`、`wechat`、`online_service`，可选 |
+| `customer_id` / `external_user_id` | 外部客户 ID，可选 |
 | `customer_context` | 外部系统附带的客户上下文，可选 |
 | `use_llm` | 是否启用 LLM 意图解析，默认 `true` |
 | `llm_fusion` | 是否启用 LLM 话术融合，默认 `true` |
@@ -109,6 +124,8 @@ curl http://localhost:8102/v1/admin/travel/customer-service-query \
 
 | 字段 | 说明 |
 | --- | --- |
+| `request_id` | 外部请求 ID，原样回传或由服务端生成 |
+| `trace_id` | 服务端链路追踪 ID，排查问题时使用 |
 | `answer` | 给外部系统展示的完整回答 |
 | `customer_reply` | 可直接发给客户的话术 |
 | `confidence` | 本次回答置信度 |
@@ -119,6 +136,26 @@ curl http://localhost:8102/v1/admin/travel/customer-service-query \
 | `routing.intent` | 解析出的客户需求 |
 | `trace` | 响应耗时、召回规模、质量检查摘要 |
 
+认证请求头支持三种写法，推荐第一种：
+
+```text
+X-KG-API-Key: <api-key>
+X-API-Key: <api-key>
+Authorization: Bearer <api-key>
+```
+
+生产环境必须至少配置一个 API Key；未配置时，对外问答接口会返回 `503`，表示接口尚未启用。
+不要使用 `dev-key-1` 这类弱密钥作为生产 Key；建议使用高强度随机字符串，按周期轮换，并优先通过环境变量 `INGEST_API_KEYS` 或后台配置统一管理。
+
+常见错误码：
+
+| 状态码 | 说明 |
+| --- | --- |
+| `400` | 请求体缺少 `question` |
+| `401` | API Key 缺失或无效 |
+| `502` | 图查询、LLM 生成 Cypher 或答案合成失败 |
+| `503` | 后台未配置接口 API Key |
+
 ## 前端调用
 
 React 管理后台通过 `admin-web/src/api.ts` 访问同源 API。Docker 部署时前端和 API 同在 `http://localhost:8102`，因此无需额外配置跨域代理。