# 文档管理页面开发提案

## 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 保持一致
- [ ] 失败文档显示错误信息
- [ ] 上传失败时显示明确的错误提示