diff --git a/pocket-base/bai_chat_alm_hooks/README.md b/pocket-base/bai_chat_alm_hooks/README.md new file mode 100644 index 0000000..ff943a3 --- /dev/null +++ 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/*` 系列接口工作 +- 响应内容支持解析 `...` 片段并分离展示 + +### 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/` 中补充任务记录 \ No newline at end of file diff --git a/pocket-base/bai_chat_alm_hooks/task.md b/pocket-base/bai_chat_alm_hooks/task.md new file mode 100644 index 0000000..102f971 --- /dev/null +++ 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）增加返回首页按钮 diff --git a/pocket-base/bai_chat_alm_hooks/task_record/Task_1_理解目录结构并形成文档，便于后期持续维护.md b/pocket-base/bai_chat_alm_hooks/task_record/Task_1_理解目录结构并形成文档，便于后期持续维护.md new file mode 100644 index 0000000..dedcb26 --- /dev/null +++ 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) \ No newline at end of file diff --git a/pocket-base/bai_chat_alm_hooks/task_record/Task_2_在现有三个页面中，增加返回首页按钮.md b/pocket-base/bai_chat_alm_hooks/task_record/Task_2_在现有三个页面中，增加返回首页按钮.md new file mode 100644 index 0000000..45d6509 --- /dev/null +++ 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) \ No newline at end of file diff --git a/pocket-base/bai_chat_alm_hooks/views/ai-manage-index.html b/pocket-base/bai_chat_alm_hooks/views/ai-manage-index.html index 3b9beb5..94e9dc4 100644 --- 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,9 +57,12 @@ - -
+
+ 返回首页
diff --git a/pocket-base/bai_chat_alm_hooks/views/sql-lab-index.html b/pocket-base/bai_chat_alm_hooks/views/sql-lab-index.html index d42c53e..763c89e 100644 --- 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 @@
-
+
+ 返回首页 +
+