docs:更新架构文档以反映当前代码实际状态
AGENT.md、README.md、ARCHITECTURE.md、ROADMAP.md 已根据最新代码更新： - 补充 DTO 层、统一返回体、全局异常处理、审计自动填充等已完成项 - 更新前端控制台架构描述与页面实现状态 - 调整 RAG 模块状态描述（元数据层已完成，业务闭环待建设） - 移除 docs 目录的 .gitignore 排除规则 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
zhiye.sun
155
docs/ARCHITECTURE.md
Normal file
155
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# 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. 衔接模型供应商、工作流编排和前端管理台。
|
||||
122
docs/ROADMAP.md
Normal file
122
docs/ROADMAP.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# Common Agent 开发路线图
|
||||
|
||||
本文档基于 2026-05-21 当前分支代码整理，用来区分"已经完成""建议优先做""中期建设项"。
|
||||
|
||||
## 已完成
|
||||
|
||||
### 基础工程
|
||||
|
||||
- Spring Boot 4.0.6 后端工程初始化。
|
||||
- PostgreSQL 数据源与多环境配置文件（dev / template）。
|
||||
- MyBatis-Plus 3.5.16、Lombok、Springdoc OpenAPI 2.8.13 已接入。
|
||||
- Maven Wrapper。
|
||||
|
||||
### 公共能力
|
||||
|
||||
- `BaseEntity` 公共字段模型（主键、审计字段、乐观锁）。
|
||||
- `EntityAuditMetaObjectHandler` 审计字段自动填充。
|
||||
- `RequestResult<T>` 统一 API 返回体。
|
||||
- `GlobalExceptionHandler` 全局异常处理。
|
||||
- `AttachmentProperties` 附件本地存储配置。
|
||||
- `sys_enum` 完整能力：实体、Mapper、Service、Controller、DTO 层。
|
||||
- 支持单条增删改查、批量新增、管理端条件查询（含关键词搜索）。
|
||||
- 批量新增内含重复值校验。
|
||||
- `sys_attachment` 完整能力：实体、Mapper、Service、Controller、DTO 层。
|
||||
- 支持本地文件上传、UUID 文件名、日期目录分层、元数据持久化。
|
||||
|
||||
### RAG 基础能力
|
||||
|
||||
- `rag_store`、`rag_document` 表结构与实体定义。
|
||||
- RAG 知识库完整 CRUD（含编码唯一性校验）。
|
||||
- 知识文档条件查询服务。
|
||||
- RAG 解析状态枚举 `RagParseStatusEnum`（UPLOADED / PARSING / PARSED / FAILED）。
|
||||
- RAG 索引状态枚举 `RagIndexStatusEnum`（PENDING / INDEXING / INDEXED / FAILED）。
|
||||
- RAG 来源常量 `RagSystemConstants`。
|
||||
|
||||
### 前端控制台
|
||||
|
||||
- Vue 3 + TypeScript + Vite + Element Plus + Pinia + Vue Router 工程。
|
||||
- `AdminLayout.vue` 管理后台布局（侧边栏菜单 + 主内容区）。
|
||||
- 系统枚举管理页：完整 CRUD + 批量新增对话框 + 关键词搜索 + 响应式布局。
|
||||
- 知识库管理页：完整 CRUD + 概览卡片 + 双栏详情 + 编辑对话框。
|
||||
- API 层：Axios 封装 + Long 类型安全解析 + 统一错误拦截。
|
||||
- 单元测试：Vitest + @vue/test-utils，覆盖路由、布局、页面和 API。
|
||||
|
||||
### 质量保障
|
||||
|
||||
- 后端结构稳定性单元测试。
|
||||
- 前端组件与 API 单元测试。
|
||||
|
||||
## 短期优先级
|
||||
|
||||
建议优先完成下面几项，把 RAG 元数据管理层升级为可用的业务闭环：
|
||||
|
||||
1. 知识库文档上传接口：上传文件后自动创建 `rag_document` 记录。
|
||||
2. 文档解析任务入口与状态流转。
|
||||
3. 向量化任务入口与状态流转。
|
||||
4. 知识库文档新增、详情、启停用、重试等管理接口。
|
||||
5. 前端附件管理页面联调。
|
||||
6. 前端知识文档页面联调。
|
||||
|
||||
## RAG 最小闭环
|
||||
|
||||
在基础规范层补齐后，当前 RAG 元数据层已完成，下一步建设业务闭环：
|
||||
|
||||
1. 附件上传后自动创建 `rag_document` 记录。
|
||||
2. 建立文档解析任务入口（占位解析器）。
|
||||
3. 解析状态、索引状态按流程流转。
|
||||
4. 接入占位向量化接口。
|
||||
5. 提供知识库文档管理完整接口（新增、详情、启停用、重试、删除）。
|
||||
|
||||
## Agent 核心能力
|
||||
|
||||
RAG 数据链路稳定后，再进入 Agent 主线：
|
||||
|
||||
1. Agent 定义管理。
|
||||
2. 会话与消息模型。
|
||||
3. 工具注册与工具调用协议。
|
||||
4. Prompt 模板管理。
|
||||
5. 任务执行与简单编排能力。
|
||||
6. 运行日志与调用追踪。
|
||||
|
||||
## 平台化能力
|
||||
|
||||
中期建议补齐的平台能力：
|
||||
|
||||
- 用户与权限体系。
|
||||
- 知识库管理后台完善（检索配置、索引任务查看）。
|
||||
- Agent 管理后台。
|
||||
- 文件管理与文档预览。
|
||||
- 系统配置中心。
|
||||
- 审计日志与监控告警。
|
||||
|
||||
## 前端协同建议
|
||||
|
||||
当前前端工程已在仓库中落地，后端约定已经冻结：
|
||||
|
||||
- 统一响应体格式：`RequestResult<T>`（`resultcode`, `message`, `data`）。
|
||||
- 上传接口返回模型：`SysAttachmentResponse`。
|
||||
- 枚举查询接口规范：POST `/api/sys-enum/queryForManagement`。
|
||||
- RAG 文档状态字段：`parseStatus` + `indexStatus` + `enabled`。
|
||||
- 大整数 ID 通过 `@JsonSerialize(ToStringSerializer.class)` 输出为字符串。
|
||||
|
||||
## 里程碑
|
||||
|
||||
### 里程碑 1：后端规范化 ~~已完成~~
|
||||
|
||||
- 补齐 DTO、响应体、异常处理、校验。
|
||||
- 接口具备稳定对接能力。
|
||||
|
||||
### 里程碑 2：RAG 可演示
|
||||
|
||||
- 实现知识库文档上传、建档、状态流转。
|
||||
- 预留解析和索引任务接口。
|
||||
- 前端知识库页面完整联调。
|
||||
|
||||
### 里程碑 3：Agent 最小运行时
|
||||
|
||||
- 支持一个可配置 Agent、一个会话、一次模型调用、一次工具调用。
|
||||
|
||||
### 里程碑 4：平台管理化
|
||||
|
||||
- 补齐前端占位页面联调与后台配置能力，形成完整平台雏形。
|
||||
@@ -1,414 +0,0 @@
|
||||
# DTO And RequestResult Refactor Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 将现有枚举、附件、RAG 三块接口统一改造成 DTO 入参与 DTO 返回，并引入 `RequestResult` 作为统一响应包装。
|
||||
|
||||
**Architecture:** `controller`、`service`、`mapper` 三层都尽量以 DTO 作为边界对象，实体类仅用于 MyBatis-Plus 持久化与表映射。控制层统一返回 `RequestResult<T>`，查询条件走 request/query DTO，列表和详情都返回 response DTO，避免继续直接暴露实体和零散参数。
|
||||
|
||||
**Tech Stack:** Java 21、Spring Boot 4、MyBatis-Plus、Spring MVC、JUnit 5
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 建立统一响应体和 DTO 包结构
|
||||
|
||||
**Files:**
|
||||
- Create: `src/main/java/com/bruce/common/dto/RequestResult.java`
|
||||
- Create: `src/main/java/com/bruce/common/dto/request/`
|
||||
- Create: `src/main/java/com/bruce/common/dto/response/`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/request/`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/response/`
|
||||
- Modify: `src/test/java/com/bruce/common/enumconfig/SysEnumComponentStructureTests.java`
|
||||
- Modify: `src/test/java/com/bruce/rag/RagComponentStructureTests.java`
|
||||
|
||||
- [ ] **Step 1: 写失败测试，固定统一返回体存在且控制层不再暴露裸实体**
|
||||
|
||||
在结构测试中增加如下断言思路：
|
||||
|
||||
```java
|
||||
Method saveOrUpdateMethod = SysEnumController.class.getMethod("saveOrUpdate", SysEnumSaveRequest.class);
|
||||
assertEquals(RequestResult.class, saveOrUpdateMethod.getReturnType());
|
||||
```
|
||||
|
||||
```java
|
||||
Method listMethod = RagStoreController.class.getMethod("list", RagStoreQueryRequest.class);
|
||||
assertEquals(RequestResult.class, listMethod.getReturnType());
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行测试并确认失败**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysEnumComponentStructureTests,RagComponentStructureTests" test`
|
||||
|
||||
Expected: FAIL，提示 DTO 或 `RequestResult` 类型不存在，或控制器方法签名不匹配。
|
||||
|
||||
- [ ] **Step 3: 最小化实现统一响应体和基础 DTO 目录**
|
||||
|
||||
`RequestResult.java` 采用如下结构：
|
||||
|
||||
```java
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
public class RequestResult<T> {
|
||||
private boolean success;
|
||||
private String code;
|
||||
private String message;
|
||||
private T data;
|
||||
|
||||
public static <T> RequestResult<T> success(T data) {
|
||||
return new RequestResult<>(true, "SUCCESS", "操作成功", data);
|
||||
}
|
||||
|
||||
public static <T> RequestResult<T> success(String message, T data) {
|
||||
return new RequestResult<>(true, "SUCCESS", message, data);
|
||||
}
|
||||
|
||||
public static <T> RequestResult<T> failure(String code, String message) {
|
||||
return new RequestResult<>(false, code, message, null);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 运行测试并确认通过**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysEnumComponentStructureTests,RagComponentStructureTests" test`
|
||||
|
||||
Expected: PASS 或只剩下后续控制器签名相关失败。
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add src/main/java/com/bruce/common/dto src/main/java/com/bruce/rag/dto src/test/java/com/bruce/common/enumconfig/SysEnumComponentStructureTests.java src/test/java/com/bruce/rag/RagComponentStructureTests.java
|
||||
git commit -m "refactor: 增加统一响应体与DTO结构"
|
||||
```
|
||||
|
||||
### Task 2: 重构 sys_enum 模块为 DTO 入参与 DTO 返回
|
||||
|
||||
**Files:**
|
||||
- Create: `src/main/java/com/bruce/common/dto/request/SysEnumQueryRequest.java`
|
||||
- Create: `src/main/java/com/bruce/common/dto/request/SysEnumSaveRequest.java`
|
||||
- Create: `src/main/java/com/bruce/common/dto/response/SysEnumResponse.java`
|
||||
- Modify: `src/main/java/com/bruce/common/controller/SysEnumController.java`
|
||||
- Modify: `src/main/java/com/bruce/common/service/ISysEnumService.java`
|
||||
- Modify: `src/main/java/com/bruce/common/service/impl/SysEnumServiceImpl.java`
|
||||
- Modify: `src/main/java/com/bruce/common/mapper/SysEnumMapper.java`
|
||||
- Modify: `src/test/java/com/bruce/common/enumconfig/SysEnumComponentStructureTests.java`
|
||||
|
||||
- [ ] **Step 1: 写失败测试，固定 sys_enum 控制器和服务都使用 DTO**
|
||||
|
||||
在 `SysEnumComponentStructureTests` 中增加断言：
|
||||
|
||||
```java
|
||||
Method queryMethod = SysEnumController.class.getMethod("queryByCatalogAndType", SysEnumQueryRequest.class);
|
||||
Method saveMethod = SysEnumController.class.getMethod("saveOrUpdate", SysEnumSaveRequest.class);
|
||||
Method serviceMethod = ISysEnumService.class.getMethod("listByCatalogAndType", SysEnumQueryRequest.class);
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行测试并确认失败**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysEnumComponentStructureTests" test`
|
||||
|
||||
Expected: FAIL，提示方法签名仍然是 `String` 或 `SysEnum`。
|
||||
|
||||
- [ ] **Step 3: 最小化实现 request/response DTO**
|
||||
|
||||
`SysEnumQueryRequest.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class SysEnumQueryRequest {
|
||||
private String catalog;
|
||||
private String type;
|
||||
}
|
||||
```
|
||||
|
||||
`SysEnumSaveRequest.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class SysEnumSaveRequest {
|
||||
private Long id;
|
||||
private String catalog;
|
||||
private String type;
|
||||
private String name;
|
||||
private Integer value;
|
||||
private String strvalue;
|
||||
private Integer sort;
|
||||
private String remark;
|
||||
}
|
||||
```
|
||||
|
||||
`SysEnumResponse.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class SysEnumResponse {
|
||||
private Long id;
|
||||
private String catalog;
|
||||
private String type;
|
||||
private String name;
|
||||
private Integer value;
|
||||
private String strvalue;
|
||||
private Integer sort;
|
||||
private String remark;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 修改 mapper/service/controller**
|
||||
|
||||
- `ISysEnumService` 返回 `List<SysEnumResponse>`，保存返回 `SysEnumResponse`
|
||||
- `SysEnumServiceImpl` 新增 DTO 与实体互转私有方法
|
||||
- `SysEnumMapper` 保留 MP 基础能力；如需自定义查询，新增 DTO 查询方法签名
|
||||
- `SysEnumController` 所有接口返回 `RequestResult<?>`
|
||||
|
||||
控制器目标形态：
|
||||
|
||||
```java
|
||||
@PostMapping("/query")
|
||||
public RequestResult<List<SysEnumResponse>> queryByCatalogAndType(@RequestBody SysEnumQueryRequest request) {
|
||||
return RequestResult.success(sysEnumService.listByCatalogAndType(request));
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 5: 运行测试并确认通过**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysEnumComponentStructureTests" test`
|
||||
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add src/main/java/com/bruce/common/controller/SysEnumController.java src/main/java/com/bruce/common/service/ISysEnumService.java src/main/java/com/bruce/common/service/impl/SysEnumServiceImpl.java src/main/java/com/bruce/common/dto/request/SysEnumQueryRequest.java src/main/java/com/bruce/common/dto/request/SysEnumSaveRequest.java src/main/java/com/bruce/common/dto/response/SysEnumResponse.java src/test/java/com/bruce/common/enumconfig/SysEnumComponentStructureTests.java
|
||||
git commit -m "refactor: 调整sys_enum接口为DTO模式"
|
||||
```
|
||||
|
||||
### Task 3: 重构 sys_attachment 模块为 DTO 入参与 DTO 返回
|
||||
|
||||
**Files:**
|
||||
- Create: `src/main/java/com/bruce/common/dto/request/SysAttachmentUploadRequest.java`
|
||||
- Create: `src/main/java/com/bruce/common/dto/request/SysAttachmentQueryRequest.java`
|
||||
- Create: `src/main/java/com/bruce/common/dto/response/SysAttachmentResponse.java`
|
||||
- Modify: `src/main/java/com/bruce/common/controller/SysAttachmentController.java`
|
||||
- Modify: `src/main/java/com/bruce/common/service/ISysAttachmentService.java`
|
||||
- Modify: `src/main/java/com/bruce/common/service/impl/SysAttachmentServiceImpl.java`
|
||||
- Modify: `src/test/java/com/bruce/common/attachment/SysAttachmentComponentStructureTests.java`
|
||||
|
||||
- [ ] **Step 1: 写失败测试，固定附件接口返回 `RequestResult` 且 service 返回 DTO**
|
||||
|
||||
示例断言：
|
||||
|
||||
```java
|
||||
Method uploadMethod = SysAttachmentController.class.getMethod("upload", MultipartFile.class, SysAttachmentUploadRequest.class);
|
||||
assertEquals(RequestResult.class, uploadMethod.getReturnType());
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行测试并确认失败**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysAttachmentComponentStructureTests" test`
|
||||
|
||||
Expected: FAIL，提示控制器或服务方法签名不匹配。
|
||||
|
||||
- [ ] **Step 3: 新增附件 DTO**
|
||||
|
||||
`SysAttachmentUploadRequest.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class SysAttachmentUploadRequest {
|
||||
private String sourceType;
|
||||
private Long sourceId;
|
||||
}
|
||||
```
|
||||
|
||||
`SysAttachmentQueryRequest.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class SysAttachmentQueryRequest {
|
||||
private String sourceType;
|
||||
private Long sourceId;
|
||||
}
|
||||
```
|
||||
|
||||
`SysAttachmentResponse.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class SysAttachmentResponse {
|
||||
private Long id;
|
||||
private String sourceType;
|
||||
private Long sourceId;
|
||||
private String originalName;
|
||||
private String fileName;
|
||||
private String fileSuffix;
|
||||
private String contentType;
|
||||
private Long fileSize;
|
||||
private String storageType;
|
||||
private String filePath;
|
||||
private String fileUrl;
|
||||
private String remark;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 修改附件控制器和服务**
|
||||
|
||||
- `ISysAttachmentService.upload` 返回 `SysAttachmentResponse`
|
||||
- 控制器上传接口返回 `RequestResult<SysAttachmentResponse>`
|
||||
- 如补充列表查询，也走 `SysAttachmentQueryRequest`
|
||||
|
||||
- [ ] **Step 5: 运行测试并确认通过**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysAttachmentComponentStructureTests" test`
|
||||
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add src/main/java/com/bruce/common/controller/SysAttachmentController.java src/main/java/com/bruce/common/service/ISysAttachmentService.java src/main/java/com/bruce/common/service/impl/SysAttachmentServiceImpl.java src/main/java/com/bruce/common/dto/request/SysAttachmentUploadRequest.java src/main/java/com/bruce/common/dto/request/SysAttachmentQueryRequest.java src/main/java/com/bruce/common/dto/response/SysAttachmentResponse.java src/test/java/com/bruce/common/attachment/SysAttachmentComponentStructureTests.java
|
||||
git commit -m "refactor: 调整附件接口为DTO模式"
|
||||
```
|
||||
|
||||
### Task 4: 重构 rag_store 与 rag_document 模块为 DTO 入参与 DTO 返回
|
||||
|
||||
**Files:**
|
||||
- Create: `src/main/java/com/bruce/rag/dto/request/RagStoreQueryRequest.java`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/request/RagStoreSaveRequest.java`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/request/RagDocumentQueryRequest.java`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/request/RagDocumentSaveRequest.java`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/response/RagStoreResponse.java`
|
||||
- Create: `src/main/java/com/bruce/rag/dto/response/RagDocumentResponse.java`
|
||||
- Modify: `src/main/java/com/bruce/rag/controller/RagStoreController.java`
|
||||
- Modify: `src/main/java/com/bruce/rag/controller/RagDocumentController.java`
|
||||
- Modify: `src/main/java/com/bruce/rag/service/IRagStoreService.java`
|
||||
- Modify: `src/main/java/com/bruce/rag/service/IRagDocumentService.java`
|
||||
- Modify: `src/main/java/com/bruce/rag/service/impl/RagStoreServiceImpl.java`
|
||||
- Modify: `src/main/java/com/bruce/rag/service/impl/RagDocumentServiceImpl.java`
|
||||
- Modify: `src/test/java/com/bruce/rag/RagComponentStructureTests.java`
|
||||
|
||||
- [ ] **Step 1: 写失败测试，固定 RAG 控制器和服务都使用 DTO**
|
||||
|
||||
示例断言：
|
||||
|
||||
```java
|
||||
Method storeListMethod = RagStoreController.class.getMethod("list", RagStoreQueryRequest.class);
|
||||
Method documentListMethod = RagDocumentController.class.getMethod("list", RagDocumentQueryRequest.class);
|
||||
assertEquals(RequestResult.class, storeListMethod.getReturnType());
|
||||
assertEquals(RequestResult.class, documentListMethod.getReturnType());
|
||||
```
|
||||
|
||||
- [ ] **Step 2: 运行测试并确认失败**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=RagComponentStructureTests" test`
|
||||
|
||||
Expected: FAIL，提示控制器和 service 仍然暴露实体或无 DTO。
|
||||
|
||||
- [ ] **Step 3: 新增 RAG DTO**
|
||||
|
||||
`RagStoreQueryRequest.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class RagStoreQueryRequest {
|
||||
private String storeCode;
|
||||
private String storeName;
|
||||
private String status;
|
||||
}
|
||||
```
|
||||
|
||||
`RagStoreResponse.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class RagStoreResponse {
|
||||
private Long id;
|
||||
private String storeCode;
|
||||
private String storeName;
|
||||
private String description;
|
||||
private String status;
|
||||
private String remark;
|
||||
}
|
||||
```
|
||||
|
||||
`RagDocumentQueryRequest.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class RagDocumentQueryRequest {
|
||||
private Long storeId;
|
||||
private Long attachmentId;
|
||||
private String parseStatus;
|
||||
private String indexStatus;
|
||||
private Boolean enabled;
|
||||
}
|
||||
```
|
||||
|
||||
`RagDocumentResponse.java`：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class RagDocumentResponse {
|
||||
private Long id;
|
||||
private Long storeId;
|
||||
private Long attachmentId;
|
||||
private String documentTitle;
|
||||
private String documentSummary;
|
||||
private String parseStatus;
|
||||
private String indexStatus;
|
||||
private Boolean enabled;
|
||||
private String errorMessage;
|
||||
private String remark;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: 修改 RAG service/controller**
|
||||
|
||||
- `IRagStoreService`、`IRagDocumentService` 返回 DTO
|
||||
- `RagStoreController` 和 `RagDocumentController` 返回 `RequestResult`
|
||||
- 查询接口改为 `@PostMapping("/query")` + `@RequestBody QueryRequest`
|
||||
|
||||
- [ ] **Step 5: 运行测试并确认通过**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=RagComponentStructureTests" test`
|
||||
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add src/main/java/com/bruce/rag/controller/RagStoreController.java src/main/java/com/bruce/rag/controller/RagDocumentController.java src/main/java/com/bruce/rag/service/IRagStoreService.java src/main/java/com/bruce/rag/service/IRagDocumentService.java src/main/java/com/bruce/rag/service/impl/RagStoreServiceImpl.java src/main/java/com/bruce/rag/service/impl/RagDocumentServiceImpl.java src/main/java/com/bruce/rag/dto/request src/main/java/com/bruce/rag/dto/response src/test/java/com/bruce/rag/RagComponentStructureTests.java
|
||||
git commit -m "refactor: 调整RAG接口为DTO模式"
|
||||
```
|
||||
|
||||
### Task 5: 全量验证与整理
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/test/java/com/bruce/common/attachment/SysAttachmentComponentStructureTests.java`
|
||||
- Modify: `src/test/java/com/bruce/common/enumconfig/SysEnumComponentStructureTests.java`
|
||||
- Modify: `src/test/java/com/bruce/rag/RagComponentStructureTests.java`
|
||||
|
||||
- [ ] **Step 1: 运行定向测试，确认三块 DTO 改造都覆盖到**
|
||||
|
||||
Run: `.\mvnw.cmd "-Dtest=SysAttachmentComponentStructureTests,SysEnumComponentStructureTests,RagComponentStructureTests" test`
|
||||
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 2: 运行全量测试**
|
||||
|
||||
Run: `.\mvnw.cmd test`
|
||||
|
||||
Expected: `BUILD SUCCESS`
|
||||
|
||||
- [ ] **Step 3: 检查工作区**
|
||||
|
||||
Run: `git status --short`
|
||||
|
||||
Expected: 仅显示本次预期文件，或为空（若已提交）。
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add src/test/java/com/bruce/common/attachment/SysAttachmentComponentStructureTests.java src/test/java/com/bruce/common/enumconfig/SysEnumComponentStructureTests.java src/test/java/com/bruce/rag/RagComponentStructureTests.java
|
||||
git commit -m "test: 校验DTO接口改造结构"
|
||||
```
|
||||
92
docs/superpowers/plans/2026-05-19-vue3-frontend-framework.md
Normal file
92
docs/superpowers/plans/2026-05-19-vue3-frontend-framework.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# Vue3 Frontend Framework Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** 在当前仓库根目录下新增 `frontend/` Vue3 前端工程，形成可独立运行的前后端分离管理台骨架。
|
||||
|
||||
**Architecture:** 前端采用 `Vite + Vue 3 + TypeScript + Vue Router + Pinia + Axios`，以 `frontend/` 作为独立工程目录。页面层按“管理台主布局 + 模块页面”组织，接口请求按模块拆到 `api/`，统一解析后端 `RequestResult<T>` 返回体，并通过开发代理转发到 Spring Boot 后端。
|
||||
|
||||
**Tech Stack:** Vue 3、TypeScript、Vite、Vue Router、Pinia、Axios、CSS Variables
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 初始化前端工程目录和基础依赖
|
||||
|
||||
**Files:**
|
||||
- Create: `frontend/package.json`
|
||||
- Create: `frontend/tsconfig.json`
|
||||
- Create: `frontend/tsconfig.node.json`
|
||||
- Create: `frontend/vite.config.ts`
|
||||
- Create: `frontend/index.html`
|
||||
- Create: `frontend/.gitignore`
|
||||
|
||||
- [ ] 建立前端工程元数据、脚本和 Vite 配置
|
||||
- [ ] 配置开发服务器代理到后端 `/api`
|
||||
- [ ] 固定 TypeScript 和构建入口
|
||||
|
||||
### Task 2: 建立应用入口与全局框架
|
||||
|
||||
**Files:**
|
||||
- Create: `frontend/src/main.ts`
|
||||
- Create: `frontend/src/App.vue`
|
||||
- Create: `frontend/src/styles/reset.css`
|
||||
- Create: `frontend/src/styles/theme.css`
|
||||
- Create: `frontend/src/styles/global.css`
|
||||
|
||||
- [ ] 注册 Router 与 Pinia
|
||||
- [ ] 建立全局样式、主题变量和基础页面容器
|
||||
- [ ] 保证桌面与移动端都能正常加载
|
||||
|
||||
### Task 3: 建立路由、布局和导航骨架
|
||||
|
||||
**Files:**
|
||||
- Create: `frontend/src/router/index.ts`
|
||||
- Create: `frontend/src/layouts/AdminLayout.vue`
|
||||
- Create: `frontend/src/components/app/AppSidebar.vue`
|
||||
- Create: `frontend/src/components/app/AppHeader.vue`
|
||||
- Create: `frontend/src/components/app/AppShellCard.vue`
|
||||
|
||||
- [ ] 建立管理台布局
|
||||
- [ ] 配置仪表盘、系统枚举、附件管理、RAG知识库、RAG文档路由
|
||||
- [ ] 建立侧边导航和顶部栏
|
||||
|
||||
### Task 4: 建立接口层与通用类型
|
||||
|
||||
**Files:**
|
||||
- Create: `frontend/src/types/http.ts`
|
||||
- Create: `frontend/src/types/sys-enum.ts`
|
||||
- Create: `frontend/src/types/attachment.ts`
|
||||
- Create: `frontend/src/types/rag.ts`
|
||||
- Create: `frontend/src/api/http.ts`
|
||||
- Create: `frontend/src/api/sys-enum.ts`
|
||||
- Create: `frontend/src/api/attachment.ts`
|
||||
- Create: `frontend/src/api/rag.ts`
|
||||
|
||||
- [ ] 建立 `RequestResult<T>` 前端类型
|
||||
- [ ] 建立 Axios 实例和统一响应解包
|
||||
- [ ] 按模块拆分 API 请求方法
|
||||
|
||||
### Task 5: 建立页面骨架与基础交互
|
||||
|
||||
**Files:**
|
||||
- Create: `frontend/src/views/dashboard/DashboardView.vue`
|
||||
- Create: `frontend/src/views/sys-enum/SysEnumView.vue`
|
||||
- Create: `frontend/src/views/attachment/AttachmentView.vue`
|
||||
- Create: `frontend/src/views/rag-store/RagStoreView.vue`
|
||||
- Create: `frontend/src/views/rag-document/RagDocumentView.vue`
|
||||
- Create: `frontend/src/components/common/PageSection.vue`
|
||||
- Create: `frontend/src/components/common/EmptyState.vue`
|
||||
|
||||
- [ ] 建立四个业务页面的查询区、状态卡片和表格占位
|
||||
- [ ] 系统枚举、RAG 页面接入真实查询请求
|
||||
- [ ] 附件页面预留上传表单和结果展示
|
||||
|
||||
### Task 6: 补充工程说明与验证
|
||||
|
||||
**Files:**
|
||||
- Modify: `README.md`
|
||||
- Create: `frontend/README.md`
|
||||
|
||||
- [ ] 追加前端启动说明
|
||||
- [ ] 记录 Node 版本、运行命令和代理约定
|
||||
- [ ] 执行 `npm install`、`npm run build` 做基础验证
|
||||
Reference in New Issue
Block a user