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。
• 系统枚举管理能力（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
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
RagStoreController	rag/controller/RagStoreController.java
RagDocumentController	rag/controller/RagDocumentController.java
RagStoreServiceImpl	rag/service/impl/RagStoreServiceImpl.java
RagDocumentServiceImpl	rag/service/impl/RagDocumentServiceImpl.java
RagParseStatusEnum	rag/enums/RagParseStatusEnum.java
RagIndexStatusEnum	rag/enums/RagIndexStatusEnum.java
RagSystemConstants	rag/constant/RagSystemConstants.java

接口列表：

方法	路径	说明
POST	/api/rag/store/query	知识库条件查询
GET	/api/rag/store/detail	获取知识库详情
POST	/api/rag/store/save	新增/更新知识库
POST	/api/rag/store/delete	删除知识库
POST	/api/rag/documents/query	知识文档条件查询

当前边界：

• 元数据管理层已完成（知识库 CRUD、文档查询）。
• 尚未实现"文档上传后自动建档"、"解析入库"、"切片向量化"、"检索问答"等业务流程。

4. 数据模型关系

当前核心表关系如下：

表名	说明	关联
sys_enum	系统枚举配置	独立
sys_attachment	附件元数据	独立，被 rag_document 引用
rag_store	知识库主表	独立
rag_document	知识库文档表	关联 rag_store.id 和 sys_attachment.id

rag_document 是 RAG 模块与附件模块的连接点。

5. 配置与运行

关键配置文件：

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

6. 测试策略

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

7. 当前不足

• RAG 尚未进入"可用链路"，只有元数据管理层。
• Agent 运行时相关模型与服务尚未开始建设。
• 前端部分页面（工作台、附件管理、知识文档）为占位状态。
• 缺少鉴权、租户、操作日志。

8. 建议演进方向

1. 补 RAG 最小闭环：上传附件 → 建立文档 → 状态流转 → 解析占位。
2. 接入 Spring AI，实现最小模型调用链路。
3. 建设 Agent 域模型：Agent、Session、Message、Tool、Task。
4. 补齐前端占位页面的表单与联调。
5. 衔接模型供应商、工作流编排和前端管理台。