# 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)