180 lines
5.6 KiB
Markdown
180 lines
5.6 KiB
Markdown
# 文档管理页面开发提案
|
||
|
||
## 1. 目标
|
||
|
||
为 SuperBizAgent 开发一个独立的文档管理页面，用于管理 API 文档的上传、查询、删除和状态监控。
|
||
|
||
## 2. 背景
|
||
|
||
- 后端已完成文档管理功能（DocumentController），包含上传、查询、删除 API
|
||
- 数据库表设计已完成（api_document 表）
|
||
- 项目已有 index.html 聊天界面，使用统一的 styles.css 设计风格
|
||
- 需要一个独立的文档管理界面来操作文档元数据
|
||
|
||
## 3. 核心功能
|
||
|
||
### 3.1 文档列表展示
|
||
- 显示文档元数据：文件名、类别、状态、版本、分块数、上传时间
|
||
- 状态筛选：PENDING / PROCESSING / INDEXED / FAILED
|
||
- 故障源筛选：支持按 fault_source 筛选
|
||
- 分页支持：每页 20 条
|
||
- 默认排序：按上传时间倒序（最新在前）
|
||
|
||
### 3.2 文档上传
|
||
- 文件选择器（支持拖拽上传）
|
||
- 元信息表单：
|
||
- fault_category（文档类别）：下拉选择（EXTERNAL_API / INTERNAL_ERROR 等）
|
||
- fault_source（故障源）：文本输入（如"广东"、"order-service"）
|
||
- api_name（接口名称）：文本输入
|
||
- version（版本）：文本输入（默认 v1.0）
|
||
- 分块配置（可选，有默认值）：
|
||
- chunkSize：默认 500
|
||
- chunkOverlap：默认 50
|
||
- 上传后行为：刷新列表并高亮新文档
|
||
|
||
### 3.3 文档详情查看
|
||
- 点击文档行展开详情面板（右侧滑出或弹窗）
|
||
- 显示完整元数据（包括 docId、fileSize、fileHash、indexedAt 等）
|
||
- 显示索引状态和分块信息
|
||
- 失败文档显示错误信息（error_message）
|
||
|
||
### 3.4 文档删除
|
||
- 删除按钮（每行一个）
|
||
- 确认对话框：警告硬删除（MySQL + Milvus 数据都会删除）
|
||
- 删除成功后刷新列表
|
||
|
||
### 3.5 状态监控
|
||
- 顶部统计卡片：显示各状态文档数量
|
||
- PENDING：待处理
|
||
- PROCESSING：处理中
|
||
- INDEXED：已索引
|
||
- FAILED：失败
|
||
- 点击统计卡片快速筛选对应状态的文档
|
||
|
||
## 4. 技术方案
|
||
|
||
### 4.1 前端技术栈
|
||
- 纯静态页面（HTML + CSS + JavaScript）
|
||
- 复用现有 styles.css 的设计风格
|
||
- 使用原生 Fetch API 调用后端接口
|
||
- 无需引入额外框架
|
||
|
||
### 4.2 页面结构
|
||
```
|
||
documents.html
|
||
├── 顶部导航栏（返回主页按钮）
|
||
├── 状态统计卡片区域
|
||
├── 操作区域（上传按钮 + 筛选器）
|
||
├── 文档列表表格
|
||
└── 详情面板（右侧滑出）
|
||
```
|
||
|
||
### 4.3 样式设计
|
||
- 保持与 index.html 一致的现代简洁风格
|
||
- 使用卡片式布局
|
||
- 状态标签使用颜色区分：
|
||
- PENDING：灰色
|
||
- PROCESSING：蓝色
|
||
- INDEXED：绿色
|
||
- FAILED：红色
|
||
|
||
### 4.4 API 集成
|
||
```javascript
|
||
// 后端 API
|
||
const API_BASE = '/api/documents';
|
||
|
||
// 上传文档
|
||
POST /api/documents/upload (FormData)
|
||
|
||
// 查询文档详情
|
||
GET /api/documents/{docId}
|
||
|
||
// 按状态查询
|
||
GET /api/documents/status/{status}?page=0&size=20
|
||
|
||
// 按故障源查询
|
||
GET /api/documents/faultSource/{faultSource}
|
||
|
||
// 删除文档
|
||
DELETE /api/documents/{docId}
|
||
```
|
||
|
||
### 4.5 状态更新策略
|
||
- 不实现自动轮询（避免复杂性）
|
||
- 提供手动刷新按钮
|
||
- 用户可随时点击刷新查看最新状态
|
||
|
||
## 5. 用户体验
|
||
|
||
### 5.1 上传流程
|
||
1. 用户点击"上传文档"按钮
|
||
2. 弹出上传表单对话框
|
||
3. 选择文件 + 填写元信息
|
||
4. 点击确认上传
|
||
5. 显示上传中状态（禁用按钮，显示加载图标）
|
||
6. 上传成功：关闭对话框，刷新列表，高亮新文档
|
||
7. 上传失败：显示错误信息，保持对话框打开
|
||
|
||
### 5.2 筛选流程
|
||
1. 点击状态统计卡片 → 快速筛选该状态文档
|
||
2. 使用下拉筛选器 → 按状态或故障源筛选
|
||
3. 清除筛选 → 显示全部文档
|
||
|
||
### 5.3 删除流程
|
||
1. 点击删除按钮
|
||
2. 弹出确认对话框："确定删除文档 {fileName}？此操作将删除 MySQL 和 Milvus 中的所有数据，不可恢复。"
|
||
3. 确认 → 调用删除 API → 刷新列表
|
||
4. 取消 → 关闭对话框
|
||
|
||
## 6. 实现优先级
|
||
|
||
### P0（必须实现）
|
||
- 文档列表展示（带状态和故障源筛选）
|
||
- 文档上传（基本表单 + 文件选择）
|
||
- 文档删除（带确认）
|
||
- 状态统计卡片
|
||
|
||
### P1（重要但可后续优化）
|
||
- 文档详情查看（右侧面板）
|
||
- 拖拽上传
|
||
- 列表分页
|
||
|
||
### P2（可选增强）
|
||
- 批量删除
|
||
- 导出文档列表
|
||
- 上传历史记录
|
||
|
||
## 7. 文件清单
|
||
|
||
需要创建的文件：
|
||
- `src/main/resources/static/documents.html` - 文档管理页面主 HTML
|
||
- `src/main/resources/static/documents.js` - 文档管理页面逻辑（可选，也可内联到 HTML）
|
||
- `src/main/resources/static/documents.css` - 文档管理页面专属样式（可选，优先复用 styles.css）
|
||
|
||
需要修改的文件：
|
||
- `src/main/resources/static/index.html` - 添加"文档管理"入口链接（侧边栏）
|
||
|
||
## 8. 约束和风险
|
||
|
||
### 约束
|
||
- 保持与现有页面风格一致
|
||
- 不引入新的前端框架或库
|
||
- 文件上传大小受限于后端配置（Spring Boot multipart.max-file-size）
|
||
|
||
### 风险
|
||
- 大文件上传可能超时（需要后端支持超时配置）
|
||
- 文件 hash 计算在前端（需要 File API 支持）→ 暂时由后端处理
|
||
- 状态监控无实时更新，用户需手动刷新
|
||
|
||
## 9. 验收标准
|
||
|
||
- [ ] 可以通过页面上传文档，填写完整元信息
|
||
- [ ] 可以查看文档列表，显示正确的元数据
|
||
- [ ] 可以按状态筛选文档（PENDING / PROCESSING / INDEXED / FAILED）
|
||
- [ ] 可以按故障源筛选文档
|
||
- [ ] 可以删除文档，删除后列表自动刷新
|
||
- [ ] 状态统计卡片显示正确数量
|
||
- [ ] 页面样式与 index.html 保持一致
|
||
- [ ] 失败文档显示错误信息
|
||
- [ ] 上传失败时显示明确的错误提示
|