# 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/` 中补充任务记录