diff --git a/backend/main.py b/backend/main.py index 2909753f..2611e996 100755 --- a/backend/main.py +++ b/backend/main.py @@ -85,6 +85,7 @@ def custom_generate_unique_id(route: APIRoute) -> str: # cache docs for different text _openapi_cache: Dict[str, Dict[str, Any]] = {} + # replace placeholder def replace_placeholders_in_schema(schema: Dict[str, Any], trans: Dict[str, str]) -> None: """ @@ -102,7 +103,6 @@ def replace_placeholders_in_schema(schema: Dict[str, Any], trans: Dict[str, str] replace_placeholders_in_schema(item, trans) - # OpenAPI build def get_language_from_request(request: Request) -> str: # get param from query ?lang=zh @@ -155,7 +155,6 @@ def generate_openapi_for_lang(lang: str) -> Dict[str, Any]: return openapi_schema - # custom /openapi.json and /docs @app.get("/openapi.json", include_in_schema=False) async def custom_openapi(request: Request): diff --git a/example/README.md b/example/README.md new file mode 100644 index 00000000..7606943f --- /dev/null +++ b/example/README.md @@ -0,0 +1,99 @@ +# 小助手嵌入示例 + +本目录提供四个示例页面，演示如何在第三方页面中嵌入 SQLBot 小助手：**基础应用 / 高级应用** × **浮窗模式 / 全屏模式**。 + +## 前置条件 + +- **Node.js**：用于运行示例静态服务（建议 14+） +- **SQLBot 服务**：已部署并可访问（如 `http://localhost:5173`） +- **小助手应用**：在 SQLBot「小助手应用」中已创建至少一个**基础应用**和一个**高级应用**，并记下对应的应用 ID + +## 配置 + +1. 打开 `config.js`，按实际环境修改： + - **SQLBOT_BASE_URL**：SQLBot 前端访问地址（末尾不要加 `/`），例如 `http://localhost:5173` + - **BASIC_ASSISTANT_ID**：基础应用的小助手 ID + - **ADVANCED_ASSISTANT_ID**：高级应用的小助手 ID + +2. 在 SQLBot 管理后台，为上述两个小助手应用的「跨域设置」中增加示例服务地址，例如： + - 若示例运行在 3000 端口：`http://localhost:3000` + +## 一键启动 + +- **Linux / macOS**：在终端执行 + `./start.sh` + 或指定端口：`PORT=8080 ./start.sh` + +- **Windows**：双击 `start.bat`，或在 cmd 中执行 + `start.bat` + 修改端口可在执行前设置环境变量：`set PORT=8080` 后执行 `node server.js` + +启动后终端会输出访问地址（默认 `http://localhost:3000`），在浏览器打开即可从导航页进入四个示例。 + +## 四种模式说明 + +| 模式 | 说明 | +|------------|------| +| 基础 · 浮窗 | 通过 `assistant.js` 加载，页面右下角出现浮窗按钮，点击打开对话。数据源来自 SQLBot 中为该基础应用配置的数据源列表。 | +| 基础 · 全屏 | 通过 `sqlbot-embedded-dynamic.umd.js` 在页面内挂载全屏对话区域。数据源同上。 | +| 高级 · 浮窗 | 同上浮窗交互，但使用「高级应用」ID。数据源由第三方接口动态返回，需在 SQLBot 中配置接口 URL 与凭证。 | +| 高级 · 全屏 | 同上全屏挂载，但使用「高级应用」ID。 | + +--- + +## 详细测试方案 + +### 测试环境 + +- **浏览器**：Chrome、Edge 或 Safari（建议使用最新版） +- **示例服务**：本目录通过 `start.sh` / `start.bat` 或 `node server.js` 启动后的地址（如 `http://localhost:3000`） +- **SQLBot**：已配置的 `SQLBOT_BASE_URL` 对应服务可正常访问 + +### 测试前准备 + +1. 在 SQLBot「小助手应用」中，为将要使用的**基础应用**和**高级应用**在「跨域设置」中填入示例服务地址（如 `http://localhost:3000`），并保存。 +2. 确认 `config.js` 中 `SQLBOT_BASE_URL`、`BASIC_ASSISTANT_ID`、`ADVANCED_ASSISTANT_ID` 已正确填写。 +3. 启动示例服务并打开导航页 `http://localhost:3000`（或你设置的端口），确认页面底部「当前配置」显示正确。 + +### 用例 1：基础应用 · 浮窗模式 + +1. 在导航页点击「基础应用 · 浮窗」进入示例页。 +2. **预期**：页面右下角出现小助手浮窗按钮（图标或配置的 Logo）。 +3. 点击浮窗按钮，**预期**：弹出对话窗口，可输入内容。 +4. 发送一条简单问句（如「你好」或一个与已配置数据源相关的问题），**预期**：能收到回复或至少无控制台报错（若未配置数据源则可能提示无数据源，属正常）。 +5. **失败排查**：若未出现浮窗，检查浏览器控制台是否有跨域或脚本加载错误；确认跨域设置包含当前示例页的 origin（如 `http://localhost:3000`）。 + +### 用例 2：基础应用 · 全屏模式 + +1. 在导航页点击「基础应用 · 全屏」进入示例页。 +2. **预期**：页面主体为小助手对话界面（可能需等待 1～2 秒加载 UMD）。 +3. 在输入框中输入问题并发送，**预期**：能正常对话或看到加载/错误提示（与 SQLBot 及数据源配置一致）。 +4. **失败排查**：若白屏或一直加载，打开控制台查看是否 404（如 `sqlbot-embedded-dynamic.umd.js` 不存在）或跨域错误；确认 SQLBot 已部署包含该 UMD 的包（如 xpack）。 + +### 用例 3：高级应用 · 浮窗模式 + +1. 在导航页点击「高级应用 · 浮窗」进入示例页。 +2. **预期**：同样出现右下角浮窗按钮，点击后打开对话。 +3. 发送问题，**预期**：若已配置数据源接口且凭证正确，则与基础应用类似可正常对话；若未配置或接口不可用，可能提示无数据源或接口错误，属预期行为。 +4. **失败排查**：与用例 1 相同，另需在 SQLBot 中确认该高级应用的「配置接口」与「接口凭证」已正确填写。 + +### 用例 4：高级应用 · 全屏模式 + +1. 在导航页点击「高级应用 · 全屏」进入示例页。 +2. **预期**：全屏展示小助手对话界面，行为与用例 2 类似，但使用高级应用的数据源逻辑。 +3. 发送问题，**预期**：与用例 3 一致，取决于第三方数据源接口是否配置并可用。 +4. **失败排查**：同用例 2 与用例 3。 + +### 常见问题与排查 + +| 现象 | 可能原因 | 处理建议 | +|------|----------|----------| +| **浮窗/全屏完全没有效果** | 未配置 config.js 或 ID 为空 | 编辑 `example/config.js`，填写 `SQLBOT_BASE_URL`（如 `http://localhost:5173`）和 `BASIC_ASSISTANT_ID` / `ADVANCED_ASSISTANT_ID`（在「小助手应用」列表或编辑页可看到应用 ID），保存后刷新示例页。示例页在未配置时会显示黄色提示框。 | +| 浮窗不出现或控制台跨域报错 | 小助手跨域设置未包含当前页面 origin | 在 SQLBot「小助手应用」中编辑对应小助手，在「跨域设置」中增加示例地址（如 `http://localhost:3000`），保存。 | +| assistant.js 加载失败 / 404 | SQLBot 前端未启动或地址填错 | 确认 SQLBot 前端已启动（与 config 中 `SQLBOT_BASE_URL` 一致），浏览器可直接访问该地址。 | +| 嵌入失败 / 接口报错 | 跨域未包含示例地址，或小助手不存在 | 同上「跨域设置」；并确认填写的 assistant ID 在「小助手应用」中存在。 | +| 全屏页白屏或一直加载 | UMD 未部署或路径错误 | 确认 SQLBot 前端存在 `/xpack_static/sqlbot-embedded-dynamic.umd.js`；若项目无 xpack，全屏模式可能不可用，仅验证浮窗即可。 | +| 对话提示无数据源 / 接口错误 | 基础应用未选数据源，或高级应用未配置/不可用接口 | 基础应用：在 SQLBot 中为该应用配置数据源；高级应用：配置接口 URL 与凭证，并确保接口返回约定格式。 | +| 配置已改但页面仍显示旧 ID | 浏览器缓存 | 硬刷新（Ctrl+F5）或清缓存后重试。 | + +完成上述四个用例且行为符合预期，即可认为示例与当前 SQLBot 环境集成正常。 diff --git a/example/advanced-floating.html b/example/advanced-floating.html new file mode 100644 index 00000000..134554bc --- /dev/null +++ b/example/advanced-floating.html @@ -0,0 +1,51 @@ + + + + + + 高级应用 - 浮窗模式 + + + + +
← 返回示例首页
+
+

高级应用 · 浮窗模式

+

本页嵌入的是「高级应用」小助手，右下角为浮窗入口。高级应用的数据源由第三方接口动态返回，需在 SQLBot 中配置接口 URL 与凭证后方可正常使用。

+ + +
+ + + diff --git a/example/advanced-fullscreen.html b/example/advanced-fullscreen.html new file mode 100644 index 00000000..c2c5a6a1 --- /dev/null +++ b/example/advanced-fullscreen.html @@ -0,0 +1,47 @@ + + + + + + 高级应用 - 全屏模式 + + + + +
+
← 返回示例首页
+
+
+ + + diff --git a/example/basic-floating.html b/example/basic-floating.html new file mode 100644 index 00000000..addd1921 --- /dev/null +++ b/example/basic-floating.html @@ -0,0 +1,53 @@ + + + + + + 基础应用 - 浮窗模式 + + + + +
← 返回示例首页
+
+

基础应用 · 浮窗模式

+

本页通过 assistant.js 嵌入小助手，右下角会出现浮窗按钮，点击即可打开对话。数据源由 SQLBot 中配置的「基础应用」数据源列表决定。

+ + +
+ + + diff --git a/example/basic-fullscreen.html b/example/basic-fullscreen.html new file mode 100644 index 00000000..80f42f4b --- /dev/null +++ b/example/basic-fullscreen.html @@ -0,0 +1,47 @@ + + + + + + 基础应用 - 全屏模式 + + + + +
+
← 返回示例首页
+
+
+ + + diff --git a/example/config.js b/example/config.js new file mode 100644 index 00000000..1bc275b0 --- /dev/null +++ b/example/config.js @@ -0,0 +1,12 @@ +/** + * 小助手示例配置（浏览器端） + * 请在运行示例前修改 SQLBOT_BASE_URL 与两个 ID。 + */ +window.SQLBOT_EXAMPLE_CONFIG = { + /** SQLBot 服务地址，末尾不要加 /，例如 http://localhost:8000 */ + SQLBOT_BASE_URL: 'http://localhost:8000', + /** 基础应用的小助手 ID（在「小助手应用」中创建基础应用后获得） */ + BASIC_ASSISTANT_ID: '7437401056310464512', + /** 高级应用的小助手 ID（在「小助手应用」中创建高级应用后获得） */ + ADVANCED_ASSISTANT_ID: '7437401056310464512', +}; diff --git a/example/index.html b/example/index.html new file mode 100644 index 00000000..1e44ccde --- /dev/null +++ b/example/index.html @@ -0,0 +1,107 @@ + + + + + + 小助手嵌入示例 - 导航 + + + +
+

小助手嵌入示例

+

选择下方任一示例，在页面中体验基础应用 / 高级应用的浮窗或全屏嵌入。使用前请在 config.js 中填写 SQLBot 地址与小助手 ID，并在 SQLBot 中配置跨域。

+
+
+
+
+

基础应用 · 浮窗

+

右下角浮窗按钮，点击后打开对话。

+ 打开示例 +
+
+

基础应用 · 全屏

+

整页展示小助手对话界面。

+ 打开示例 +
+
+

高级应用 · 浮窗

+

浮窗模式，数据源由第三方接口提供。

+ 打开示例 +
+
+

高级应用 · 全屏

+

全屏模式，数据源由第三方接口提供。

+ 打开示例 +
+
+
+ 当前配置（来自 config.js）：
+ SQLBOT_BASE_URL: -
+ BASIC_ASSISTANT_ID: -
+ ADVANCED_ASSISTANT_ID: - +
+
+ + + + diff --git a/example/server.js b/example/server.js new file mode 100644 index 00000000..aff8fd45 --- /dev/null +++ b/example/server.js @@ -0,0 +1,58 @@ +#!/usr/bin/env node +/** + * 静态文件服务，用于运行小助手嵌入示例 + * 使用方式：node server.js 或 PORT=8080 node server.js + */ +const http = require('http'); +const fs = require('fs'); +const path = require('path'); + +const PORT = parseInt(process.env.PORT, 10) || 3000; +const ROOT = path.join(__dirname); + +const MIME = { + '.html': 'text/html; charset=utf-8', + '.js': 'application/javascript; charset=utf-8', + '.json': 'application/json', + '.css': 'text/css', + '.ico': 'image/x-icon', + '.svg': 'image/svg+xml', + '.png': 'image/png', + '.jpg': 'image/jpeg', + '.woff2': 'font/woff2', +}; + +const server = http.createServer((req, res) => { + let filePath = path.join(ROOT, req.url === '/' ? 'index.html' : req.url); + filePath = path.normalize(filePath); + if (!filePath.startsWith(ROOT)) { + res.writeHead(403); + res.end('Forbidden'); + return; + } + fs.readFile(filePath, (err, data) => { + if (err) { + if (err.code === 'ENOENT') { + res.writeHead(404); + res.end('Not Found'); + } else { + res.writeHead(500); + res.end('Server Error'); + } + return; + } + const ext = path.extname(filePath); + res.setHeader('Content-Type', MIME[ext] || 'application/octet-stream'); + res.end(data); + }); +}); + +server.listen(PORT, () => { + const url = `http://localhost:${PORT}`; + console.log(''); + console.log(' 小助手嵌入示例服务已启动'); + console.log(' 访问地址: ' + url); + console.log(''); + console.log(' 请在 SQLBot「小助手应用」中将跨域设置包含: ' + url); + console.log(''); +}); diff --git a/example/start.bat b/example/start.bat new file mode 100644 index 00000000..fafdade2 --- /dev/null +++ b/example/start.bat @@ -0,0 +1,16 @@ +@echo off +chcp 65001 >nul +cd /d "%~dp0" +where node >nul 2>nul +if %errorlevel% neq 0 ( + echo 未检测到 Node.js，请先安装: https://nodejs.org/ + pause + exit /b 1 +) +if not defined PORT set PORT=3000 +echo. +echo 启动示例服务 (端口: %PORT%) +echo 启动后请将 SQLBot 小助手跨域设置包含: http://localhost:%PORT% +echo. +node server.js +pause diff --git a/example/start.sh b/example/start.sh new file mode 100755 index 00000000..c8c69db2 --- /dev/null +++ b/example/start.sh @@ -0,0 +1,13 @@ +#!/usr/bin/env sh +# 一键启动小助手嵌入示例服务（Linux / macOS） +cd "$(dirname "$0")" +if ! command -v node >/dev/null 2>&1; then + echo "未检测到 Node.js，请先安装: https://nodejs.org/" + exit 1 +fi +export PORT="${PORT:-3000}" +echo "" +echo " 启动示例服务 (端口: $PORT)" +echo " 启动后请将 SQLBot 小助手跨域设置包含: http://localhost:$PORT" +echo "" +exec node server.js