common_agent/docs/ARCHITECTURE.md

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 适配层、工作流编排和前端管理台。