67cfbeb572
AGENT.md、README.md、ARCHITECTURE.md、ROADMAP.md 已根据最新代码更新： - 补充 DTO 层、统一返回体、全局异常处理、审计自动填充等已完成项 - 更新前端控制台架构描述与页面实现状态 - 调整 RAG 模块状态描述（元数据层已完成，业务闭环待建设） - 移除 docs 目录的 .gitignore 排除规则 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
155 lines
6.4 KiB
Markdown
155 lines
6.4 KiB
Markdown
# 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. 衔接模型供应商、工作流编排和前端管理台。 |