# Common Agent 当前代码架构说明

## 1. 文档目的

本文档描述 `common_agent` 当前已经落地的前后端架构，用于帮助快速理解代码边界、模块职责和扩展点。

## 2. 总体分层

### 后端分层

采用标准 Spring Boot + MyBatis-Plus 分层：

- **controller**：对外暴露 REST API，统一使用 DTO 交互，返回 `RequestResult<T>`。
- **service**：接口 + 实现，继承 MyBatis-Plus `IService` / `ServiceImpl`。
- **mapper**：继承 `BaseMapper<T>`，无 XML，全部使用 `lambdaQuery()` 类型安全查询。
- **entity**：数据库实体模型，继承 `BaseEntity`。
- **dto/request|response**：请求/响应 DTO，响应 DTO 提供 `fromEntity()` 静态转换。
- **config / constant / enums / handler**：模块级配置、常量、枚举和全局异常处理。

### 前端架构

- **入口**：`main.ts` 挂载 Vue App，注册 Pinia、Vue Router、Element Plus。
- **布局**：`AdminLayout.vue` 管理后台壳布局（侧边栏菜单 + 主内容区）。
- **页面**：各业务页面位于 `pages/`，使用 Composition API + `<script setup lang="ts">`。
- **API 层**：`api/request.ts` 封装 Axios，统一 `/api` 前缀，`RequestResult<T>` 信封解包，大整数安全解析。
- **路由**：`router/index.ts` 使用 HTML5 history 模式，所有页面作为 AdminLayout 子路由。
- **状态**：`stores/app.ts` Pinia 状态管理（当前为环境名占位）。
- **样式**：`styles/global.css` 定义全局 CSS 变量和布局，各页面使用 scoped style。

## 3. 已实现模块

### 3.1 公共基础模块

包路径：`com.bruce.common`

职责：

- 提供实体基类 `BaseEntity`（主键、审计字段、乐观锁）。
- 统一 API 返回体 `RequestResult<T>`。
- 全局异常处理 `GlobalExceptionHandler`。
- MyBatis-Plus 审计自动填充 `EntityAuditMetaObjectHandler`。
- 附件本地存储配置 `AttachmentProperties`。
- 文档解析抽象与 Apache Tika 解析实现。
- 系统枚举管理能力（CRUD + 批量新增 + 管理端查询）。
- 附件上传能力（本地磁盘 + 元数据持久化）。

关键类：

| 类 | 路径 |
|----|------|
| BaseEntity | `common/domain/model/BaseEntity.java` |
| RequestResult | `common/domain/model/RequestResult.java` |
| GlobalExceptionHandler | `common/handler/GlobalExceptionHandler.java` |
| EntityAuditMetaObjectHandler | `common/config/EntityAuditMetaObjectHandler.java` |
| AttachmentProperties | `common/config/AttachmentProperties.java` |
| SysEnum | `common/domain/entity/SysEnum.java` |
| SysAttachment | `common/domain/entity/SysAttachment.java` |
| SysEnumController | `common/controller/SysEnumController.java` |
| SysAttachmentController | `common/controller/SysAttachmentController.java` |
| SysEnumServiceImpl | `common/service/impl/SysEnumServiceImpl.java` |
| SysAttachmentServiceImpl | `common/service/impl/SysAttachmentServiceImpl.java` |
| DocumentParserFactory | `common/document/parse/DocumentParserFactory.java` |
| TxtDocumentParser | `common/document/parse/impl/TxtDocumentParser.java` |
| PdfDocumentParser | `common/document/parse/impl/PdfDocumentParser.java` |
| WordDocumentParser | `common/document/parse/impl/WordDocumentParser.java` |
| ExcelDocumentParser | `common/document/parse/impl/ExcelDocumentParser.java` |
| CommonStatusEnum | `common/enums/CommonStatusEnum.java` |
| EnableStatusEnum | `common/enums/EnableStatusEnum.java` |

接口列表：

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/sys-enum/queryForManagement` | 管理端枚举查询（支持关键词搜索） |
| GET | `/api/sys-enum/detail` | 获取单个枚举 |
| POST | `/api/sys-enum/save` | 新增/更新枚举 |
| POST | `/api/sys-enum/batchSave` | 批量新增枚举 |
| POST | `/api/sys-enum/delete` | 删除枚举 |
| POST | `/api/attachments/upload` | 上传附件 |

### 3.2 RAG 知识库模块

包路径：`com.bruce.rag`

职责：

- 维护 RAG 知识库主数据（CRUD + 编码唯一性校验）。
- 维护知识库文档与附件的关联关系。
- 支持知识文档批量上传、解析入口、解析快照、手动切片入口和状态流转。
- 定义切片、向量、解析状态、索引状态和 RAG 相关来源常量。

关键类：

| 类 | 路径 |
|----|------|
| RagStore | `rag/entity/RagStore.java` |
| RagDocument | `rag/entity/RagDocument.java` |
| RagChunk | `rag/entity/RagChunk.java` |
| RagChunkEmbedding | `rag/entity/RagChunkEmbedding.java` |
| RagStoreController | `rag/controller/RagStoreController.java` |
| RagDocumentController | `rag/controller/RagDocumentController.java` |
| RagStoreServiceImpl | `rag/service/impl/RagStoreServiceImpl.java` |
| RagDocumentServiceImpl | `rag/service/impl/RagDocumentServiceImpl.java` |
| RagDocumentParseServiceImpl | `rag/service/impl/RagDocumentParseServiceImpl.java` |
| RagDocumentChunkServiceImpl | `rag/service/impl/RagDocumentChunkServiceImpl.java` |
| ChunkerFactory | `rag/parse/ChunkerFactory.java` |
| FixedLengthChunker | `rag/parse/impl/FixedLengthChunker.java` |
| DelimiterChunker | `rag/parse/impl/DelimiterChunker.java` |
| RagParseStatusEnum | `rag/enums/RagParseStatusEnum.java` |
| RagIndexStatusEnum | `rag/enums/RagIndexStatusEnum.java` |
| RagChunkStrategyEnum | `rag/enums/RagChunkStrategyEnum.java` |
| RagSystemConstants | `rag/constant/RagSystemConstants.java` |

接口列表：

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/rag/store/list` | 查询全部知识库 |
| POST | `/api/rag/store/query` | 知识库条件查询 |
| GET | `/api/rag/store/detail` | 获取知识库详情 |
| GET | `/api/rag/store/overview` | 获取知识库总览 |
| GET | `/api/rag/store/documentOverview` | 获取单个知识库文档概览 |
| POST | `/api/rag/store/save` | 新增/更新知识库 |
| POST | `/api/rag/store/delete` | 删除知识库 |
| POST | `/api/rag/documents/list` | 查询全部知识文档 |
| POST | `/api/rag/documents/query` | 知识文档条件查询 |
| GET | `/api/rag/documents/detail` | 获取知识文档详情 |
| POST | `/api/rag/documents/save` | 新增/更新知识文档 |
| POST | `/api/rag/documents/delete` | 删除知识文档 |
| POST | `/api/rag/documents/batchUpload` | 批量上传文档并创建 `rag_document` |
| POST | `/api/rag/documents/parse` | 批量解析知识文档 |
| POST | `/api/rag/documents/chunk` | 按策略异步生成文档切片 |

当前边界：

- 知识库 CRUD、文档 CRUD、批量上传、Tika 文本解析、解析快照和状态流转已完成。
- `rag_chunk` 已支持基于解析快照的手动异步切片，当前已落地定长切片和分隔符切片。
- `rag_chunk_embedding` 已支持按知识库向量相似度召回 TopK，用于 Agent 调试链路引用回显。
- RAG 对外检索问答接口、索引任务化和重排序能力仍在后续建设中。

### 3.3 Agent 模块

包路径：`com.bruce.agent`

职责：

- 维护 Agent 定义主数据（CRUD + 编码唯一性 + 绑定知识库校验）。
- 提供 Agent 调试对话接口，支持普通对话与 RAG 对话模式切换。
- 在 RAG 对话模式下，完成“问题向量化 -> 切片召回 -> 上下文组装 -> Chat 模型回答”的最小链路。
- 返回引用切片和请求 ID，便于前端调试与调用追踪。

关键类：

| 类 | 路径 |
|----|------|
| AgentDefinition | `agent/entity/AgentDefinition.java` |
| AgentDefinitionController | `agent/controller/AgentDefinitionController.java` |
| AgentDefinitionServiceImpl | `agent/service/impl/AgentDefinitionServiceImpl.java` |
| AgentDefinitionResponse | `agent/dto/response/AgentDefinitionResponse.java` |
| AgentChatResponse | `agent/dto/response/AgentChatResponse.java` |
| ChatModelGateway | `modelprovider/gateway/ChatModelGateway.java` |
| ChatModelGatewayImpl | `modelprovider/gateway/ChatModelGatewayImpl.java` |
| ChatRequest | `modelprovider/gateway/ChatRequest.java` |
| ChatResult | `modelprovider/gateway/ChatResult.java` |

接口列表：

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/agents/list` | 查询全部 Agent |
| POST | `/api/agents/query` | Agent 条件查询 |
| GET | `/api/agents/detail` | 获取 Agent 详情 |
| POST | `/api/agents/save` | 新增/更新 Agent |
| POST | `/api/agents/delete` | 删除 Agent |
| POST | `/api/agents/{agentId}/chat` | Agent 调试对话 |

当前边界：

- `agent_definition` 与前端 Agent 管理页已完成联调。
- 对话入口已支持 `ragEnabled` 开关，`true` 走 RAG 召回，`false` 走普通对话。
- 尚未落地会话持久化（`agent_session` / `agent_message`）和工具调用编排。

## 4. 数据模型关系

当前核心表关系如下：

| 表名 | 说明 | 关联 |
|------|------|------|
| `sys_enum` | 系统枚举配置 | 独立 |
| `sys_attachment` | 附件元数据 | 独立，被 rag_document 引用 |
| `rag_store` | 知识库主表 | 独立 |
| `rag_document` | 知识库文档表 | 关联 `rag_store.id` 和 `sys_attachment.id` |
| `rag_chunk` | 知识切片表 | 关联 `rag_store.id` 和 `rag_document.id` |
| `rag_chunk_embedding` | 切片向量表 | 关联 `rag_store.id`、`rag_document.id` 和 `rag_chunk.id` |
| `agent_definition` | Agent 定义表 | 关联 `rag_store.id` |

`rag_document` 是 RAG 模块与附件模块的连接点，`rag_chunk` 和 `rag_chunk_embedding` 是检索链路核心落点，`agent_definition` 负责把 Agent 与知识库绑定到同一调用链路。

## 5. 配置与运行

关键配置文件：

| 文件 | 说明 |
|------|------|
| `application.yaml` | 环境选择（当前 `active: dev`） |
| `application-dev.yaml` | 开发环境配置（PostgreSQL 数据源、MyBatis-Plus、附件目录） |
| `application-template.yaml` | 配置模板 |

## 6. 测试策略

- **后端测试**：围绕结构约束的单元测试（Mapper/Service/Controller 继承体系、实体字段注解、方法签名验证）。
- **前端测试**：Vitest + @vue/test-utils，覆盖路由定义、布局组件、页面渲染、API 调用和 Long 类型解析。

## 6.1 注释规范

- 新增或修改核心业务代码时，需补充中文注释，优先说明类职责、方法目的、关键判断和扩展边界。
- 每次提交代码时，需要同步检查本次改动是否已经补齐对应中文注释，避免后续阅读只能靠反推代码语义。
- 注释应聚焦设计意图和边界，不建议堆砌“变量赋值”“循环遍历”这类低价值说明。

## 6.2 结构化枚举规范

- 长期固定的结构化文本字段，统一采用整型枚举值作为前后端传输协议，不再直接传递字符串名称。
- 后端 Java 枚举类是这类结构化枚举的单一事实来源，前端常量和 `sys_enum` 数据都基于它同步。
- 新增或修改结构化枚举时，需要通过统一的枚举初始化测试按 `catalog + type` 先删后全量重建写入 `sys_enum`。
- 不同枚举组之间的 `catalog + type` 必须唯一，否则会破坏枚举组重建的确定性。

## 7. 当前不足

- RAG 尚未形成独立检索问答接口，当前召回能力主要用于 Agent 调试链路。
- Agent 运行时尚未持久化会话，工具调用与任务编排仍未落地。
- 前端部分页面（附件管理、检索配置、最近任务）为占位或后续能力提示。
- 缺少鉴权、租户、操作日志。

## 8. 建议演进方向

1. 补 RAG 最小检索闭环：解析文本 → 生成切片 → 生成向量 → 检索召回。
2. 把当前 Agent 调试链路升级为会话化运行：沉淀 Session、Message 和上下文裁剪策略。
3. 建设 Agent 工具注册与调用协议，补齐任务状态与执行日志。
4. 补齐索引任务、重试、重建索引和前端任务视图。
5. 衔接模型供应商、Spring AI 适配层、工作流编排和前端管理台。