Merge branch 'main' of http://blv-rd.tech:3001/Boonlive_RD_Web/Web_BAI_Manage_ApiServer

2026-04-01 19:05:19 +08:00
parent 94811b52e2 eb4765cd10
commit c8a1f72bde
7 changed files with 362 additions and 5 deletions
--- a/pocket-base/bai_chat_alm_hooks/README.md
+++ b/pocket-base/bai_chat_alm_hooks/README.md
@@ -0,0 +1,212 @@
+# bai_chat_alm_hooks 维护说明
+
+## 1. 目录定位
+
+`bai_chat_alm_hooks` 是 PocketBase Hook 体系中的一个独立业务子目录，当前承载 3 类能力：
+
+- AI 对话测试页
+- SQL 实验室
+- 业务审计控制台
+
+本目录不是纯前端目录，也不是纯接口目录，而是一个“页面模板 + PocketBase 路由 + 外部服务转发”的组合模块。
+
+## 2. 当前目录结构
+
+```text
+bai_chat_alm_hooks/
+├─ bai-ai-manage-main.pb.js
+├─ bai-chat.pb.js
+├─ bai-sql-lab.pb.js
+├─ task.md
+├─ task_record/
+└─ views/
+   ├─ ai-manage-index.html
+   ├─ bai-chat-index.html
+   └─ sql-lab-index.html
+```
+
+各文件职责如下：
+
+| 路径 | 职责 |
+| --- | --- |
+| `bai-ai-manage-main.pb.js` | 业务审计控制台页面与审计 API |
+| `bai-chat.pb.js` | AI 对话测试页面与聊天转发 API |
+| `bai-sql-lab.pb.js` | SQL 实验室页面、诊断接口、SQL 透传接口 |
+| `views/ai-manage-index.html` | 审计控制台页面模板 |
+| `views/bai-chat-index.html` | 对话测试页面模板 |
+| `views/sql-lab-index.html` | SQL 实验室页面模板 |
+| `task.md` | 当前协作任务入口 |
+| `task_record/` | 每个任务的落地记录 |
+
+## 3. 路由管理规则
+
+### 3.1 总入口规则
+
+本目录的路由不会自动生效，统一由 [pocket-base/bai-web-main.pb.js](../bai-web-main.pb.js) 通过 `require(...)` 显式装载：
+
+- `require(${__hooks}/bai_chat_alm_hooks/bai-ai-manage-main.pb.js)`
+- `require(${__hooks}/bai_chat_alm_hooks/bai-chat.pb.js)`
+- `require(${__hooks}/bai_chat_alm_hooks/bai-sql-lab.pb.js)`
+
+因此，后续如果本目录新增新的 `.pb.js` 路由文件，必须同步在总入口中追加 `require`，否则 PocketBase 不会注册这些路由。
+
+### 3.2 本目录内部约定
+
+每个 `.pb.js` 文件通常同时定义两类路由：
+
+- 页面路由：返回 HTML 模板
+- API 路由：为页面提供数据，或转发请求到外部服务
+
+统一模式如下：
+
+1. 用 `routerAdd(method, path, handler)` 注册路由。
+2. 页面路由通过 `$template.loadFiles(__hooks + "/bai_chat_alm_hooks/views/xxx.html").render({})` 加载模板。
+3. 页面返回前统一注入登录守卫脚本，依赖浏览器本地存储中的 `pb_manage_token` 和 `pb_manage_logged_in`。
+4. API 路由内部通过 `$http.send(...)` 调用外部服务，或通过 `$app.findAllRecords(...)` 读取 PocketBase 数据。
+5. 前端页面通过 `/pb-api-v1/...` 访问本目录 API；当系统部署在 `/pb` 前缀下时，页面会自动拼接 `/pb/pb-api-v1/...`。
+
+### 3.3 页面与接口对照
+
+| 模块文件 | 页面路由 | API 路由 |
+| --- | --- | --- |
+| `bai-ai-manage-main.pb.js` | `GET /bai-ai-manage` | `GET /pb-api-v1/audit/users`、`GET /pb-api-v1/audit/chat-list`、`GET /pb-api-v1/audit/export-all` |
+| `bai-chat.pb.js` | `GET /bai-chat` | `POST /pb-api-v1/chat/send` |
+| `bai-sql-lab.pb.js` | `GET /bai-ai-sql-lab` | `GET /pb-api-v1/diagnostics`、`POST /pb-api-v1/sql-ops` |
+
+## 4. 模块职责说明
+
+### 4.1 审计控制台
+
+入口文件：`bai-ai-manage-main.pb.js`
+
+作用：
+
+- 提供业务审计页面 `ai-manage-index.html`
+- 查询审计 API，拉取用户维度会话统计
+- 查询指定用户的聊天流水
+- 支持导出当前用户的全量聊天数据
+- 额外通过 `tbl_auth_users` 建立手机号到姓名的映射
+
+外部依赖：
+
+- 审计 API 服务 `http://bai-alm-audit-api:3010`
+- PocketBase 内部表 `tbl_auth_users`
+
+前端行为：
+
+- 页面内 `apiBase` 会自动识别是否运行在 `/pb` 前缀下
+- 用户列表、聊天列表、导出按钮都通过 `/pb-api-v1/audit/*` 系列接口工作
+- 响应内容支持解析 `<think>...</think>` 片段并分离展示
+
+### 4.2 AI 对话测试页
+
+入口文件：`bai-chat.pb.js`
+
+作用：
+
+- 提供一个微信风格的测试聊天页面
+- 接收前端消息后转发到 AnythingLLM
+- 将返回值统一整理为 `{ code, reply }` 给前端使用
+
+外部依赖：
+
+- AnythingLLM `http://bai-anythingllm:3001/api/v1/workspace/ai/chat`
+
+实现特征：
+
+- 固定使用 `workspace/ai`
+- 固定 `mode = chat`
+- 固定 `sessionId = 8888`
+- 前端调用地址写死为 `/pb/pb-api-v1/chat/send`，说明该页面主要面向带 `/pb` 前缀的部署环境
+
+### 4.3 SQL 实验室
+
+入口文件：`bai-sql-lab.pb.js`
+
+作用：
+
+- 提供数据库探勘页面
+- 提供依赖连通性检查接口
+- 提供 SQL 透传执行接口
+
+外部依赖：
+
+- 审计 API 服务 `http://bai-alm-audit-api:3010`
+
+实现特征：
+
+- `/pb-api-v1/diagnostics` 用于检查 Python 探针与 SQLite 读能力
+- `/pb-api-v1/sql-ops` 负责把前端 SQL 请求转发给审计 API
+- 页面初始化时会自动体检并查询表列表
+- 文件头部明确强调：不要引入 `dynamic_model`，避免引擎崩溃
+
+## 5. 页面模板约定
+
+`views/` 下的 HTML 文件不是静态展示页，而是“可直接运行的单文件页面模板”，页面逻辑包含：
+
+- 页面结构与样式
+- 前端状态管理
+- 直接调用本目录 API 的脚本
+
+当前模板与接口关系：
+
+| 模板 | 依赖接口 |
+| --- | --- |
+| `views/ai-manage-index.html` | `/pb-api-v1/audit/users`、`/pb-api-v1/audit/chat-list`、`/pb-api-v1/audit/export-all` |
+| `views/bai-chat-index.html` | `/pb-api-v1/chat/send` |
+| `views/sql-lab-index.html` | `/pb-api-v1/diagnostics`、`/pb-api-v1/sql-ops` |
+
+这意味着修改接口路径时，必须同步检查对应模板中的 `fetch(...)` 调用。
+
+## 6. 外部依赖关系
+
+| 依赖项 | 用途 |
+| --- | --- |
+| PocketBase | 当前 Hook 运行宿主，提供 `routerAdd`、`$template`、`$http`、`$app` 等能力 |
+| bai-anythingllm:3001 | AI 对话转发目标 |
+| bai-alm-audit-api:3010 | 审计查询、SQL 透传、诊断探针服务 |
+
+简化调用链如下：
+
+1. 浏览器访问页面路由。
+2. PocketBase 加载 `views/*.html` 并返回页面。
+3. 页面脚本调用 `/pb-api-v1/*`。
+4. PocketBase Hook 根据业务转发到 AnythingLLM 或审计 API。
+5. 结果回到页面展示。
+
+## 7. 后续维护建议
+
+### 7.1 新增模块时
+
+建议按以下结构新增：
+
+1. 新建一个独立 `.pb.js` 文件，负责该模块页面和 API。
+2. 如需页面，再在 `views/` 下增加对应 HTML。
+3. 在总入口 [pocket-base/bai-web-main.pb.js](../bai-web-main.pb.js) 中追加 `require(...)`。
+4. 如果接口路径变更，同步更新对应页面内的 `fetch(...)`。
+5. 在 `task_record/` 中补充变更记录。
+
+### 7.2 修改现有模块时
+
+优先检查以下几点：
+
+- 页面路由是否仍然能正确加载模板
+- 登录守卫脚本是否被保留
+- `/pb` 前缀兼容逻辑是否被破坏
+- 外部服务地址和返回结构是否发生变化
+- HTML 页面里的接口地址是否与 Hook 路由一致
+
+### 7.3 风险点
+
+- 当前部分 SQL 语句采用字符串拼接方式构造，后续如引入用户可控参数，需要额外关注注入风险
+- `bai-chat.pb.js` 中使用固定 `sessionId` 与固定鉴权头，后续若要支持多用户隔离，需要先调整转发协议
+- `bai-chat-index.html` 当前请求路径直接写为 `/pb/pb-api-v1/chat/send`，比其他页面更依赖部署前缀
+
+## 8. 本次 Task_1 产出
+
+Task_1 已完成以下交付：
+
+- 梳理本目录结构
+- 梳理路由总入口规则与本目录内部约定
+- 建立可持续维护的目录说明文档
+- 在 `task_record/` 中补充任务记录
--- a/pocket-base/bai_chat_alm_hooks/task.md
+++ b/pocket-base/bai_chat_alm_hooks/task.md
@@ -0,0 +1,22 @@
+# 项目简介
+    - BAI API 服务是一个基于 PocketBase 的后端服务，集成了 AI 对话、SQL 实验室和业务审计功能，为企业提供智能客服和数据分析能力。
+    - 本项目是一个团队协作项目，我们的任务集中在 pocket-base\bai_chat_alm_hooks，*** 未经允许不能在目录以外修改任何内容 ***
+    - 服务依赖
+        - PocketBase 服务
+        - AnythingLLM 服务 (bai-anythingllm:3001)
+        - 审计 API 服务 (bai-alm-audit-api:3010)
+    - 路由统一在 pocket-base\bai-web-main.pb.js 管理
+
+# 项目协作模式
+    - 我将会在本文档添加任务，以 “Task_1：xxxx”的形式发布任务
+    - AI 理解任务并实施
+    - 项目验收后，在 pocket-base\bai_chat_alm_hooks\task_record 中为每个任务创建一个md格式的任务记录，以任务名称为文件名
+
+# Taks_1: 理解目录结构并形成文档，便于后期持续维护
+    - 理解本目录项目内容
+    - 理解路由管理规则
+    - 生成本目录项目说明文档，并记载在任务记录中
+
+# Taks_2: 在现有三个页面中，增加“返回首页”按钮
+    - 首页页面是 /bai_web_pb_hooks/pages/index.js
+    - 当前已经实现的三个页面（ai-manage-index.html，bai-chat-index.html，sql-lab-index.html）增加返回首页按钮
--- a/pocket-base/bai_chat_alm_hooks/task_record/Task_1_理解目录结构并形成文档，便于后期持续维护.md
+++ b/pocket-base/bai_chat_alm_hooks/task_record/Task_1_理解目录结构并形成文档，便于后期持续维护.md
@@ -0,0 +1,80 @@
+# Task_1 任务记录：理解目录结构并形成文档，便于后期持续维护
+
+## 1. 任务目标
+
+根据 [pocket-base/bai_chat_alm_hooks/task.md](../task.md) 中的 Task_1 要求，完成以下事项：
+
+- 理解 `bai_chat_alm_hooks` 目录项目内容
+- 理解路由管理规则
+- 生成本目录项目说明文档，并形成任务记录
+
+## 2. 目录理解结果
+
+`bai_chat_alm_hooks` 目前由 3 个 PocketBase Hook 文件和 3 个 HTML 页面模板组成，对应 3 个业务模块：
+
+| 模块 | 入口文件 | 页面模板 | 主要能力 |
+| --- | --- | --- | --- |
+| 审计控制台 | `bai-ai-manage-main.pb.js` | `views/ai-manage-index.html` | 审计用户列表、聊天流水查询、导出 |
+| 对话测试页 | `bai-chat.pb.js` | `views/bai-chat-index.html` | 聊天消息转发到 AnythingLLM |
+| SQL 实验室 | `bai-sql-lab.pb.js` | `views/sql-lab-index.html` | 依赖体检、SQL 透传、数据探勘 |
+
+目录核心特点：
+
+- 后端路由和前端页面模板都在同一目录内维护
+- 页面不是单独打包产物，而是由 PocketBase 直接加载 HTML 模板返回
+- 多数接口本质上是对外部服务的转发或包装
+
+## 3. 路由管理规则理解结果
+
+路由管理分两层：
+
+### 3.1 总入口层
+
+本目录中的 Hook 文件由 [pocket-base/bai-web-main.pb.js](../bai-web-main.pb.js) 统一 `require(...)`：
+
+- `bai-ai-manage-main.pb.js`
+- `bai-chat.pb.js`
+- `bai-sql-lab.pb.js`
+
+结论：
+
+- 新增 `.pb.js` 文件后，如果不在总入口追加 `require(...)`，路由不会生效
+- 本次任务按要求未修改目录外文件，只做规则理解和文档化
+
+### 3.2 模块实现层
+
+每个 Hook 文件内部都通过 `routerAdd(...)` 同时注册：
+
+- 页面路由
+- API 路由
+
+共同约定如下：
+
+1. 页面模板从 `views/` 目录加载。
+2. 页面返回前会注入登录守卫脚本。
+3. 页面侧通过 `/pb-api-v1/*` 调用 API。
+4. API 再调用外部服务 `bai-anythingllm:3001` 或 `bai-alm-audit-api:3010`。
+
+## 4. 本次新增文档
+
+本次在本目录新增了维护说明文档：
+
+- [pocket-base/bai_chat_alm_hooks/README.md](../README.md)
+
+文档内容包含：
+
+- 当前目录结构
+- 页面/API 对照关系
+- 路由接入规则
+- 外部依赖关系
+- 模块职责说明
+- 后续维护建议与风险点
+
+## 5. 验收结论
+
+Task_1 已完成，且满足“未经允许不能在目录以外修改任何内容”的限制。
+
+本次实际变更仅位于：
+
+- [pocket-base/bai_chat_alm_hooks/README.md](../README.md)
+- [pocket-base/bai_chat_alm_hooks/task_record/Task_1_理解目录结构并形成文档，便于后期持续维护.md](./Task_1_理解目录结构并形成文档，便于后期持续维护.md)
--- a/pocket-base/bai_chat_alm_hooks/task_record/Task_2_在现有三个页面中，增加返回首页按钮.md
+++ b/pocket-base/bai_chat_alm_hooks/task_record/Task_2_在现有三个页面中，增加返回首页按钮.md
@@ -0,0 +1,36 @@
+# Task_2 任务记录：在现有三个页面中，增加返回首页按钮
+
+## 1. 任务目标
+
+根据 [pocket-base/bai_chat_alm_hooks/task.md](../task.md) 中的 Task_2 要求，为当前已经实现的三个页面增加“返回首页”按钮。
+
+首页页面对应路由定义位于 [pocket-base/bai_web_pb_hooks/pages/index.js](../../bai_web_pb_hooks/pages/index.js#L1)，实际访问路径为 `/pb/manage`。
+
+## 2. 本次修改内容
+
+本次仅修改 `bai_chat_alm_hooks` 目录内的页面模板，在以下 3 个页面头部增加了“返回首页”按钮：
+
+- [pocket-base/bai_chat_alm_hooks/views/ai-manage-index.html](../views/ai-manage-index.html)
+- [pocket-base/bai_chat_alm_hooks/views/bai-chat-index.html](../views/bai-chat-index.html)
+- [pocket-base/bai_chat_alm_hooks/views/sql-lab-index.html](../views/sql-lab-index.html)
+
+按钮统一跳转到：
+
+- `/pb/manage`
+
+## 3. 实现说明
+
+- 审计控制台页面：在头部右侧操作区新增返回首页入口，并保留原有统计与 TERMINAL 按钮。
+- 对话测试页面：在头部右侧新增文字按钮，保留原有返回上一页图标。
+- SQL 实验室页面：在头部右侧状态信息前新增返回首页按钮，不影响诊断状态展示。
+
+## 4. 验收结果
+
+Task_2 已完成。
+
+本次修改范围仅限：
+
+- [pocket-base/bai_chat_alm_hooks/views/ai-manage-index.html](../views/ai-manage-index.html)
+- [pocket-base/bai_chat_alm_hooks/views/bai-chat-index.html](../views/bai-chat-index.html)
+- [pocket-base/bai_chat_alm_hooks/views/sql-lab-index.html](../views/sql-lab-index.html)
+- [pocket-base/bai_chat_alm_hooks/task_record/Task_2_在现有三个页面中，增加返回首页按钮.md](./Task_2_在现有三个页面中，增加返回首页按钮.md)
--- a/pocket-base/bai_chat_alm_hooks/views/ai-manage-index.html
+++ b/pocket-base/bai_chat_alm_hooks/views/ai-manage-index.html
@@ -57,10 +57,13 @@
                </template>
            </div>
        </div>
-        <div class="hidden lg:flex items-center space-x-4 text-[11px] font-medium">
+        <div class="flex items-center space-x-2 lg:space-x-4 text-[11px] font-medium">
+            <a href="/pb/manage" class="text-slate-300 hover:text-white border border-white/10 px-3 py-1 rounded transition-all">返回首页</a>
+            <div class="hidden lg:flex items-center space-x-4">
                <span class="text-emerald-500 font-mono" x-text="users.length"></span>
                <a href="/pb/bai-ai-sql-lab" target="_blank" class="text-slate-500 hover:text-emerald-400 border border-white/10 px-3 py-1 rounded transition-all">TERMINAL</a>
            </div>
+        </div>
    </header>

    <div class="flex-1 flex overflow-hidden relative">
--- a/pocket-base/bai_chat_alm_hooks/views/bai-chat-index.html
+++ b/pocket-base/bai_chat_alm_hooks/views/bai-chat-index.html
@@ -60,7 +60,8 @@
            <svg @click="window.history.back()" class="w-6 h-6 text-[#191919] cursor-pointer" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path d="M15 19l-7-7 7-7" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"></path></svg>
            <span class="ml-2 text-[17px] font-bold text-[#191919]">对话测试</span>
        </div>
-        <div class="flex items-center">
+        <div class="flex items-center space-x-3">
+            <a href="/pb/manage" class="text-[13px] font-semibold text-[#576b95] hover:text-[#3e5175] transition-colors">返回首页</a>
            <svg class="w-6 h-6 text-[#191919]" fill="currentColor" viewBox="0 0 24 24"><path d="M12 8c1.1 0 2-.9 2-2s-.9-2-2-2-2 .9-2 2 .9 2 2 2zm0 2c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2zm0 6c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2z"></path></svg>
        </div>
    </header>
--- a/pocket-base/bai_chat_alm_hooks/views/sql-lab-index.html
+++ b/pocket-base/bai_chat_alm_hooks/views/sql-lab-index.html
@@ -38,7 +38,10 @@
                </button>
            </div>
        </div>
+        <div class="flex items-center space-x-3">
+            <a href="/pb/manage" class="text-xs text-slate-300 hover:text-white border border-slate-700 px-3 py-1 rounded transition-colors">返回首页</a>
            <div class="text-[10px] text-slate-500 max-w-xs truncate" :title="diag.sqlite_detail" x-text="diag.sqlite_detail"></div>
+        </div>
    </header>

    <div class="flex-1 flex overflow-hidden">