From 67cfbeb572eed3ebde71fdda1a21a41f4d1cd447 Mon Sep 17 00:00:00 2001
From: "zhiye.sun" <zhiye.sun@sinitek.com>
Date: Thu, 21 May 2026 13:46:57 +0800
Subject: [PATCH] =?UTF-8?q?docs:=E6=9B=B4=E6=96=B0=E6=9E=B6=E6=9E=84?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3=E4=BB=A5=E5=8F=8D=E6=98=A0=E5=BD=93=E5=89=8D?=
 =?UTF-8?q?=E4=BB=A3=E7=A0=81=E5=AE=9E=E9=99=85=E7=8A=B6=E6=80=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

AGENT.md、README.md、ARCHITECTURE.md、ROADMAP.md 已根据最新代码更新：
- 补充 DTO 层、统一返回体、全局异常处理、审计自动填充等已完成项
- 更新前端控制台架构描述与页面实现状态
- 调整 RAG 模块状态描述（元数据层已完成，业务闭环待建设）
- 移除 docs 目录的 .gitignore 排除规则

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .gitignore                                    |   1 -
 AGENT.md                                      | 121 ++---
 README.md                                     | 116 +++--
 docs/ARCHITECTURE.md                          | 155 +++++++
 docs/ROADMAP.md                               | 122 ++++++
 .../2026-05-18-dto-request-result-refactor.md | 414 ------------------
 .../2026-05-19-vue3-frontend-framework.md     |  92 ++++
 7 files changed, 511 insertions(+), 510 deletions(-)
 create mode 100644 docs/ARCHITECTURE.md
 create mode 100644 docs/ROADMAP.md
 delete mode 100644 docs/superpowers/plans/2026-05-18-dto-request-result-refactor.md
 create mode 100644 docs/superpowers/plans/2026-05-19-vue3-frontend-framework.md

diff --git a/.gitignore b/.gitignore
index 16e5207..05b577b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -31,5 +31,4 @@ build/
 
 ### VS Code ###
 .vscode/
-/docs/
 src/main/resources/application-dev.yaml
diff --git a/AGENT.md b/AGENT.md
index e44f1f7..e16d3ec 100644
--- a/AGENT.md
+++ b/AGENT.md
@@ -11,22 +11,22 @@
 - 文件上传与附件管理
 - 前后端统一的管理控制台
 
-当前阶段以“先搭平台骨架，再逐步补智能能力”为主，优先保证工程结构、接口规范、知识库链路和可扩展性。
+当前阶段以"先搭平台骨架，再逐步补智能能力"为主，优先保证工程结构、接口规范、知识库链路和可扩展性。
 
 ## 2. 总体设计思路
 
-平台整体按“接入层 - 应用层 - 领域层 - 基础设施层”拆分：
+平台整体按"接入层 - 应用层 - 领域层 - 基础设施层"拆分：
 
-- 接入层  
-  提供 REST API、后续可扩展 WebSocket / SSE，用于前端控制台和外部系统接入。
+- **接入层**
+  提供 REST API，后续可扩展 WebSocket / SSE，用于前端控制台和外部系统接入。
 
-- 应用层  
+- **应用层**
   负责请求编排、DTO 转换、统一返回体、会话协调和 Agent 调度入口。
 
-- 领域层  
+- **领域层**
   承载核心业务对象，如系统枚举、附件、知识库、知识文档、Agent 配置、任务执行记录等。
 
-- 基础设施层  
+- **基础设施层**
   负责数据库访问、文件存储、模型调用、向量检索、日志、缓存和第三方工具适配。
 
 ## 3. 核心模块规划
@@ -35,18 +35,22 @@
 
 用于支撑整个平台的通用能力：
 
-- `sys_enum`：系统枚举配置
-- `sys_attachment`：附件与文件上传
-- 统一 DTO / `RequestResult`
-- 通用状态枚举、启用禁用枚举
+- `sys_enum`：系统枚举配置（已完成 CRUD、批量新增、管理端查询）
+- `sys_attachment`：附件与文件上传（已完成本地上传、元数据持久化）
+- 统一 DTO / `RequestResult`（已完成）
+- 通用状态枚举、启用禁用枚举（已完成）
+- 全局异常处理 `GlobalExceptionHandler`（已完成）
+- 公共审计字段自动填充 `EntityAuditMetaObjectHandler`（已完成）
 - 后续可补用户、权限、审计等基础能力
 
 ### 3.2 RAG 知识库模块
 
-当前已经有初步表设计与 Java 骨架：
+当前已有完整的元数据管理层：
 
-- `rag_store`：知识库主表
-- `rag_document`：知识库文档表
+- `rag_store`：知识库主表（已完成 CRUD、编码唯一性校验）
+- `rag_document`：知识库文档表（已完成实体、Mapper、Service、条件查询）
+- RAG 解析状态枚举 `RagParseStatusEnum`（已完成）
+- RAG 索引状态枚举 `RagIndexStatusEnum`（已完成）
 
 后续计划继续扩展：
 
@@ -58,7 +62,7 @@
 当前设计原则：
 
 - 文件物理信息放在 `sys_attachment`
-- 业务归属关系通过 `source_type`、`source_id` 或文档关联字段承接
+- 业务归属关系通过 `storeId`、`attachmentId` 关联
 - RAG 领域代码独立放在 `com.bruce.rag`
 
 ### 3.3 Agent 运行模块
@@ -82,52 +86,61 @@
 
 ### 3.4 管理控制台模块
 
-当前已经建立基于 Vue 3、Vite、Element Plus 的前端控制台基础骨架。
+当前已建立基于 Vue 3、Vite、TypeScript、Element Plus 的前端控制台。
 
 已具备的页面与布局：
 
-- 左侧管理菜单与品牌区
-- 工作台入口
-- 系统枚举管理页
-- 附件管理入口
-- 知识库入口
-- 知识文档入口
+- 左侧管理菜单与品牌区（232px 侧边栏）
+- 工作台（占位）
+- 系统枚举管理页（完整 CRUD + 批量新增）
+- 附件管理入口（占位）
+- 知识库管理页（完整 CRUD + 双栏详情）
+- 知识文档入口（占位）
+
+前端技术要点：
+
+- Composition API + `<script setup lang="ts">`
+- Axios 封装，统一 `/api` 前缀，`RequestResult<T>` 信封解包
+- Long 类型安全解析（`json-bigint` 防止 JS 精度丢失）
+- 全局错误拦截与 Element Plus 弹窗提示
+- Vitest + @vue/test-utils 单元测试
 
 当前样式约定：
 
 - 管理控制台定位为后台工具界面，优先保证信息密度、可扫描性和稳定布局。
 - 主内容区域只保留页面自身标题，避免外层布局和页面面板重复展示标题。
 - 页面统一使用 `page-panel` 作为内容容器，侧边栏、页面面板、工具栏和表格使用统一边框、背景和主色变量。
-- 系统枚举页工具栏采用响应式布局，桌面端保持查询项和操作按钮分区，窄屏时纵向排列。
+- 全局样式集中在 `frontend/src/styles/global.css`，页面专属样式在对应 `.vue` 文件的 scoped style 中。
 
 后续控制台至少继续覆盖：
 
-- 枚举管理
-- 附件管理
-- 知识库管理
-- 文档上传与状态查看
+- 附件管理页面前端联调
+- 知识文档管理页面前端联调
 - Agent 调试页
 - 执行日志查看
 
 ## 4. 当前接口设计原则
 
-项目后续统一遵循这些规则：
+项目统一遵循这些规则：
 
-1. `controller` 不直接暴露实体类  
-   所有请求和响应优先走 DTO。
+1. `controller` 不直接暴露实体类
+   所有请求和响应走 DTO。
 
-2. `service` 尽量以 DTO 为边界  
+2. `service` 以 DTO 为边界
    持久化实体只在内部流转，不直接穿透到外层接口。
 
-3. 查询条件不直接使用多个裸参数  
-   尽量改成 `QueryRequest` / `SaveRequest` / `Response` 形式。
+3. 查询条件使用请求 DTO
+   统一使用 `QueryRequest` / `SaveRequest` / `Response` 形式。
 
-4. 统一返回体  
+4. 统一返回体
    使用 `RequestResult<T>` 作为标准响应包装。
 
-5. 基础枚举统一化  
+5. 基础枚举统一化
    通用状态、启用禁用、RAG 解析/索引状态等统一管理。
 
+6. OpenAPI 注解覆盖
+   所有 Controller、DTO 使用 `@Tag`、`@Operation`、`@Schema` 注解。
+
 ## 5. 数据与存储设计
 
 ### 5.1 关系型数据库
@@ -138,7 +151,8 @@
 
 - 业务表采用 PostgreSQL 规范 SQL
 - 主键使用 MyBatis-Plus `ASSIGN_ID`
-- 通用字段沉淀到 `BaseEntity`
+- 通用字段沉淀到 `BaseEntity`（含审计字段 + 乐观锁 `version`）
+- 审计字段通过 `EntityAuditMetaObjectHandler` 自动填充
 
 ### 5.2 向量能力
 
@@ -152,7 +166,7 @@
 
 ### 5.3 文件存储
 
-当前先走本地文件存储，后续可抽象成：
+当前使用本地文件存储（`AttachmentProperties.basePath` 默认 `data/attachments`），后续可抽象成：
 
 - 本地文件系统
 - MinIO / S3
@@ -160,35 +174,28 @@
 
 ## 6. 当前阶段开发优先级
 
-建议优先顺序如下：
-
-1. 统一接口层规范  
-   DTO、返回体、基础校验、通用异常处理
-
-2. 收紧基础模块  
-   `sys_enum`、`sys_attachment`
-
-3. 补全 RAG 基础业务闭环  
-   `rag_store`、`rag_document`、文件归属、文档状态
-
+1. ~~统一接口层规范~~ DTO、返回体、基础校验、通用异常处理（已完成）
+2. ~~收紧基础模块~~ `sys_enum`、`sys_attachment`（已完成）
+3. ~~补全 RAG 基础元数据管理~~ `rag_store`、`rag_document`（已完成）
 4. 接入 Spring AI
-
 5. 建立 Agent 运行时骨架
+6. ~~补前端控制台基础骨架~~（已完成，部分页面待联调）
 
-6. 补前端控制台
+剩余重点：
 
-当前前端控制台已经完成基础骨架和系统枚举页面样式优化，后续重点应转向附件、知识库、知识文档页面的业务闭环。
+- 完善 RAG 文档上传、解析、索引的业务闭环
+- 补齐前端附件管理、知识文档页面的表单与接口联调
+- 接入 Spring AI 并实现模型调用链路
 
 ## 7. 下一步建议
 
 结合当前代码状态，接下来建议重点做：
 
-- 完成现有三块接口 DTO 化改造
-- 建立统一异常处理和错误码规范
-- 完善 `rag_store` / `rag_document` 的增删改查
-- 增加知识库文档上传并自动关联附件
+- 实现知识库文档上传并自动创建 `rag_document` 记录
+- 建立文档解析任务入口与状态流转
 - 为后续切片与向量化预留任务入口
-- 补齐前端附件、知识库、知识文档页面的表单、列表和接口联调
+- 补齐前端附件管理、知识文档页面的联调
+- 接入 Spring AI，实现最小模型调用链路
 
 ## 8. 文档用途说明
 
@@ -203,4 +210,4 @@
 - `agent-runtime.md`
 - `rag-design.md`
 - `api-style.md`
-- `frontend-console.md`
+- `frontend-console.md`
\ No newline at end of file
diff --git a/README.md b/README.md
index 755766b..22737ac 100644
--- a/README.md
+++ b/README.md
@@ -3,8 +3,8 @@
 Common Agent 是一个规划中的通用 Agent 平台，技术路线基于 Java、Spring Boot 和 Spring AI。
 项目目标是建设一套完整的前后端系统，支持 Agent 编排、工具调用、会话管理、RAG 知识库和平台管理能力。
 
-当前项目处于基础工程阶段。后端骨架、PostgreSQL 配置、MyBatis-Plus、Lombok、多环境配置文件和前端控制台基础页面已经完成；
-Agent 运行时、RAG 索引和更多管理功能会在后续阶段逐步实现。
+当前项目处于基础工程阶段。后端骨架（含 DTO、统一返回体、全局异常处理、审计自动填充）、PostgreSQL 配置、MyBatis-Plus、Lombok、多环境配置文件和前端控制台基础页面已经完成；
+Agent 运行时、RAG 文档解析与向量化和更多管理功能会在后续阶段逐步实现。
 
 ## 项目愿景
 
@@ -18,33 +18,63 @@ Common Agent 希望成为一个可复用的企业级 AI 应用基础平台：
 
 ## 当前技术栈
 
-- Java 21
-- Spring Boot 4.0.6
-- Spring AI，规划接入
-- MyBatis-Plus 3.5.16
-- PostgreSQL JDBC Driver
-- Lombok
-- Maven Wrapper
-- PostgreSQL 数据库：`common_agent`
+| 类别 | 技术 |
+|------|------|
+| 后端 | Java 21, Spring Boot 4.0.6, MyBatis-Plus 3.5.16 |
+| 数据库 | PostgreSQL |
+| 工具库 | Lombok, Springdoc OpenAPI 2.8.13, Jackson |
+| 构建 | Maven Wrapper |
+| 前端 | Vue 3, TypeScript 5.9, Vite, Element Plus, Pinia, Vue Router 4 |
+| 前端测试 | Vitest, @vue/test-utils |
+| 后端测试 | Spring Boot Test |
 
 ## 项目结构
 
 ```text
 common_agent
-├── frontend
-│   ├── src/layouts
-│   ├── src/pages
-│   ├── src/router
-│   └── src/styles
-├── src/main/java/com/bruce
-│   └── CommonAgentApplication.java
-├── src/main/resources
-│   ├── application.yaml
-│   ├── application-dev.yaml
-│   └── application-template.yaml
-├── docs
-│   ├── ARCHITECTURE.md
-│   └── ROADMAP.md
+├── frontend/                          # Vue 3 前端控制台
+│   ├── src/
+│   │   ├── api/                       # Axios 封装与各模块 API
+│   │   ├── layouts/                   # AdminLayout 管理后台布局
+│   │   ├── pages/                     # 业务页面（工作台、枚举、附件、知识库、文档）
+│   │   ├── router/                    # Vue Router 配置
+│   │   ├── stores/                    # Pinia 状态管理
+│   │   ├── styles/                    # 全局样式
+│   │   └── types/                     # TypeScript 类型声明
+│   └── package.json
+├── src/
+│   ├── main/java/com/bruce/
+│   │   ├── CommonAgentApplication.java
+│   │   ├── common/                    # 公共模块
+│   │   │   ├── config/                # AttachmentProperties, EntityAuditMetaObjectHandler
+│   │   │   ├── controller/            # SysAttachmentController, SysEnumController
+│   │   │   ├── domain/
+│   │   │   │   ├── entity/            # SysAttachment, SysEnum
+│   │   │   │   └── model/             # BaseEntity, RequestResult
+│   │   │   ├── dto/
+│   │   │   │   ├── request/           # 各模块请求 DTO
+│   │   │   │   └── response/          # 各模块响应 DTO
+│   │   │   ├── enums/                 # CommonStatusEnum, EnableStatusEnum
+│   │   │   ├── handler/               # GlobalExceptionHandler
+│   │   │   ├── mapper/                # SysAttachmentMapper, SysEnumMapper
+│   │   │   └── service/               # 接口与实现
+│   │   └── rag/                       # RAG 知识库模块
+│   │       ├── constant/              # RagSystemConstants
+│   │       ├── controller/            # RagStoreController, RagDocumentController
+│   │       ├── dto/                   # 请求/响应 DTO
+│   │       ├── entity/                # RagStore, RagDocument
+│   │       ├── enums/                 # RagParseStatusEnum, RagIndexStatusEnum
+│   │       ├── mapper/                # RagDocumentMapper, RagStoreMapper
+│   │       └── service/               # 接口与实现
+│   ├── main/resources/
+│   │   ├── application.yaml           # 环境选择
+│   │   ├── application-dev.yaml       # 开发环境配置
+│   │   └── application-template.yaml  # 配置模板
+│   └── test/java/                     # 单元测试（结构稳定性测试 + 前端 API 测试）
+├── docs/
+│   ├── ARCHITECTURE.md                # 架构说明
+│   └── ROADMAP.md                     # 开发路线图
+├── AGENT.md                           # 平台设计草案
 ├── pom.xml
 └── README.md
 ```
@@ -80,21 +110,19 @@ spring:
 
 运行测试：
 
-```powershell
-.\mvnw.cmd test
+```bash
+./mvnw test
 ```
 
 启动应用：
 
-```powershell
-.\mvnw.cmd spring-boot:run
+```bash
+./mvnw spring-boot:run
 ```
 
-当前阶段还没有加入 Web 服务依赖或常驻任务，所以应用可能启动成功后立即退出。
-
 启动前端：
 
-```powershell
+```bash
 cd frontend
 npm install
 npm run dev
@@ -102,7 +130,7 @@ npm run dev
 
 前端检查：
 
-```powershell
+```bash
 cd frontend
 npm run test:unit
 npm run type-check
@@ -115,11 +143,13 @@ npm run build
 
 当前已有页面：
 
-- 工作台
-- 系统枚举
-- 附件管理
-- 知识库
-- 知识文档
+| 页面 | 状态 |
+|------|------|
+| 工作台 | 占位 |
+| 系统枚举 | 完整 CRUD + 批量新增 |
+| 附件管理 | 占位 |
+| 知识库 | 完整 CRUD + 双栏详情 |
+| 知识文档 | 占位 |
 
 当前 UI 规范：
 
@@ -128,6 +158,15 @@ npm run build
 - 全局样式集中在 `frontend/src/styles/global.css`，页面专属样式优先放在对应 `.vue` 文件的 scoped style 中。
 - 后台页面以清晰、克制、便于扫描为优先目标，避免营销式大面积装饰。
 
+## 接口规范
+
+- 统一返回体：`RequestResult<T>`（`resultcode`, `message`, `data`）
+- 所有接口通过 DTO 交互，不直接暴露实体
+- 查询条件封装为 `XxxQueryRequest`
+- 响应 DTO 提供 `fromEntity()` 静态转换
+- 大整数 ID 通过 `@JsonSerialize(ToStringSerializer.class)` 防止前端精度丢失
+- 全局异常处理返回 HTTP 400/500 状态码
+
 ## 规划模块
 
 - `agent-core`：Agent 执行模型、工具注册、记忆和编排能力。
@@ -141,9 +180,10 @@ npm run build
 
 - [架构说明](docs/ARCHITECTURE.md)
 - [开发路线图](docs/ROADMAP.md)
+- [平台设计草案](AGENT.md)
 
 ## 参考资料
 
 - [Spring AI Reference](https://docs.spring.io/spring-ai/reference/)
 - [Spring AI RAG Reference](https://docs.spring.io/spring-ai/reference/api/retrieval-augmented-generation.html)
-- [MyBatis-Plus](https://baomidou.com/)
+- [MyBatis-Plus](https://baomidou.com/)
\ No newline at end of file
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..9be2604
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -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. 衔接模型供应商、工作流编排和前端管理台。
\ No newline at end of file
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
new file mode 100644
index 0000000..a33ff15
--- /dev/null
+++ b/docs/ROADMAP.md
@@ -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：平台管理化
+
+- 补齐前端占位页面联调与后台配置能力，形成完整平台雏形。
\ No newline at end of file
diff --git a/docs/superpowers/plans/2026-05-18-dto-request-result-refactor.md b/docs/superpowers/plans/2026-05-18-dto-request-result-refactor.md
deleted file mode 100644
index 3465d4c..0000000
--- a/docs/superpowers/plans/2026-05-18-dto-request-result-refactor.md
+++ /dev/null
@@ -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接口改造结构"
-  ```
diff --git a/docs/superpowers/plans/2026-05-19-vue3-frontend-framework.md b/docs/superpowers/plans/2026-05-19-vue3-frontend-framework.md
new file mode 100644
index 0000000..4a1fbd6
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-19-vue3-frontend-framework.md
@@ -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` 做基础验证