Add customer service API deployment support

docs/API_REFERENCE.md

@@ -31,6 +31,7 @@ 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/admin/super-agent/run` | `POST` | Super Agent 任务 |
 | `/v1/admin/roles` | `GET/POST` | 角色管理 |
 | `/v1/admin/users` | `GET/POST` | 用户管理 |
@@ -73,10 +74,57 @@ curl http://localhost:8102/v1/admin/travel/assistant-query \
   -d '{"question":"黄小西三日游多少钱？"}'
 ```
 
+## 百姓惠智能客服外部接口
+
+该接口用于对接外部客服系统。调用方传入用户自然语言问题，服务端默认选择百姓惠旅行社知识图谱，先召回图谱线路、报价口径、费用、酒店、餐饮、车辆和证据，再用 LLM 融合成客服可直接使用的话术。没有配置 LLM 时会自动退回图谱模板回答。
+
+认证方式使用接口 Key，默认本地开发值来自 `.env` / `docker-compose.yml` 的 `INGEST_API_KEYS`：
+
+```bash
+curl http://localhost:8102/v1/admin/travel/customer-service-query \
+  -H 'Content-Type: application/json' \
+  -H 'X-KG-API-Key: dev-key-1' \
+  -d '{
+    "question": "黄小西三日游多少钱？",
+    "knowledge_graph": "百姓惠",
+    "session_id": "demo-session-001",
+    "use_llm": true,
+    "llm_fusion": true
+  }'
+```
+
+常用入参：
+
+| 字段 | 说明 |
+| --- | --- |
+| `question` / `text` | 用户原始咨询内容，必填 |
+| `knowledge_graph` / `graph_name` | 知识图谱名称，可传 `百姓惠`、`bxh` 或 `baixinghui_travel_agency` |
+| `session_id` | 外部客服会话 ID，可选 |
+| `customer_context` | 外部系统附带的客户上下文，可选 |
+| `use_llm` | 是否启用 LLM 意图解析，默认 `true` |
+| `llm_fusion` | 是否启用 LLM 话术融合，默认 `true` |
+| `return_raw_agent` | 是否返回内部图谱问答原始结果，默认 `false` |
+
+核心返回字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `answer` | 给外部系统展示的完整回答 |
+| `customer_reply` | 可直接发给客户的话术 |
+| `confidence` | 本次回答置信度 |
+| `follow_up_questions` | 建议追问 |
+| `risk_notes` | 不可直接承诺或需二次核实的事项 |
+| `knowledge.plans` | 图谱命中的线路/方案 |
+| `knowledge.evidence` | 图谱证据 |
+| `routing.intent` | 解析出的客户需求 |
+| `trace` | 响应耗时、召回规模、质量检查摘要 |
+
 ## 前端调用
 
 React 管理后台通过 `admin-web/src/api.ts` 访问同源 API。Docker 部署时前端和 API 同在 `http://localhost:8102`，因此无需额外配置跨域代理。
 
+本地问答效果可在 `http://localhost:8102/admin/plaza/user` 验证。当前项目图谱选择 `baixinghui_travel_agency` 时，该页面会走百姓惠旅行社客服问答；选择城市空间图谱时仍为附近地点问答。
+
 ## 外部服务
 
 LLM 和高德地图相关能力默认关闭或留空。启用前需要在 `.env` 或 Docker Compose 环境变量中配置：