# 文档管理页面开发 - 任务清单
## 任务分解
### Task 1: 创建基础 HTML 结构
**优先级**: P0
**预计时间**: 30 分钟
**依赖**: 无
**描述**:
创建 documents.html 文件，包含完整的页面结构：
- 页面布局（app-layout）
- 顶部导航栏（page-header）
- 状态统计卡片区域（stats-cards）
- 操作工具栏（toolbar）
- 文档列表表格（documents-table）
- 详情面板（detail-panel）
- 上传对话框（uploadModal）
- 删除确认对话框（deleteModal）
**验收标准**:
- [ ] HTML 结构完整，包含所有必要的容器元素
- [ ] 引入 styles.css
- [ ] 表单元素 ID 正确
- [ ] 对话框结构完整
**文件**:
- 创建: `src/main/resources/static/documents.html`
---
### Task 2: 实现样式定制
**优先级**: P0
**预计时间**: 45 分钟
**依赖**: Task 1
**描述**:
创建 documents.css 文件，实现文档管理页面的特定样式：
- 状态统计卡片样式
- 文档表格样式
- 状态徽章样式（4 种颜色）
- 详情面板滑出动画
- 对话框样式
- 响应式布局
**验收标准**:
- [ ] 样式与 index.html 风格一致
- [ ] 状态徽章颜色正确（PENDING 灰色、PROCESSING 蓝色、INDEXED 绿色、FAILED 红色）
- [ ] 表格可读性好，hover 效果流畅
- [ ] 详情面板滑出动画流畅
- [ ] 对话框居中显示，背景遮罩半透明
**文件**:
- 创建: `src/main/resources/static/documents.css`
---
### Task 3: 实现 API 调用层
**优先级**: P0
**预计时间**: 30 分钟
**依赖**: Task 1
**描述**:
在 documents.html 的 script 标签中实现 DocumentAPI 类：
- uploadDocument(formData)
- getDocument(docId)
- getDocumentsByStatus(status, page, size)
- getDocumentsByFaultSource(faultSource)
- deleteDocument(docId)
- handleResponse(response) - 统一处理 Result 格式
**验收标准**:
- [ ] 所有 API 方法实现完整
- [ ] 正确处理 Result 响应格式（code、message、data）
- [ ] 错误处理完善，抛出清晰的错误信息
- [ ] URL 编码正确（faultSource 参数）
**文件**:
- 修改: `src/main/resources/static/documents.html` (script 部分)
---
### Task 4: 实现状态管理器
**优先级**: P0
**预计时间**: 45 分钟
**依赖**: Task 3
**描述**:
实现 DocumentManager 类，管理文档数据和 UI 状态：
- loadDocuments() - 加载文档列表
- updateStats() - 更新状态统计
- renderDocuments() - 渲染文档列表
- renderDetailPanel(docId) - 渲染详情面板
- applyFilter(filter) - 应用筛选条件
- refreshList() - 刷新列表
**验收标准**:
- [ ] 状态管理逻辑清晰
- [ ] 筛选条件正确应用
- [ ] 列表渲染正确
- [ ] 详情面板显示正确
- [ ] 统计数据准确
**文件**:
- 修改: `src/main/resources/static/documents.html` (script 部分)
---
### Task 5: 实现 UI 渲染函数
**优先级**: P0
**预计时间**: 45 分钟
**依赖**: Task 4
**描述**:
实现 UI 渲染相关的辅助函数：
- getStatusBadge(status) - 生成状态徽章 HTML
- renderDocumentRow(doc) - 生成文档表格行
- renderDetailPanel(doc) - 生成详情面板内容
- formatDateTime(dateTime) - 格式化日期时间
- formatFileSize(bytes) - 格式化文件大小
**验收标准**:
- [ ] 状态徽章颜色正确
- [ ] 表格行包含所有必要字段
- [ ] 详情面板信息完整
- [ ] 日期时间格式友好（YYYY-MM-DD HH:mm:ss）
- [ ] 文件大小单位正确（B、KB、MB）
**文件**:
- 修改: `src/main/resources/static/documents.html` (script 部分)
---
### Task 6: 实现文档上传功能
**优先级**: P0
**预计时间**: 60 分钟
**依赖**: Task 3, Task 4
**描述**:
实现文档上传的完整流程：
- 显示/隐藏上传对话框
- 表单验证（文件必填）
- 构建 FormData（包含文件和元信息）
- 调用上传 API
- 显示上传进度（加载状态）
- 处理上传结果（成功刷新列表，失败显示错误）
- 表单重置
**验收标准**:
- [ ] 点击"上传文档"按钮打开对话框
- [ ] 文件必选，其他字段使用默认值
- [ ] FormData 包含所有参数（file、faultCategory、faultSource、apiName、version、chunkSize、chunkOverlap）
- [ ] 上传中按钮禁用，显示加载状态
- [ ] 上传成功：关闭对话框，刷新列表，高亮新文档（可选）
- [ ] 上传失败：显示错误信息，对话框保持打开
- [ ] 取消按钮关闭对话框
**文件**:
- 修改: `src/main/resources/static/documents.html` (script 部分)
---
### Task 7: 实现文档删除功能
**优先级**: P0
**预计时间**: 30 分钟
**依赖**: Task 3, Task 4
**描述**:
实现文档删除的完整流程：
- 显示删除确认对话框
- 显示待删除文档的文件名
- 调用删除 API
- 处理删除结果（成功刷新列表，失败显示错误）
**验收标准**:
- [ ] 点击"删除"按钮打开确认对话框
- [ ] 对话框显示文件名和警告信息
- [ ] 点击"确认删除"调用 API
- [ ] 删除成功：关闭对话框，刷新列表
- [ ] 删除失败：显示错误信息
- [ ] 点击"取消"关闭对话框
**文件**:
- 修改: `src/main/resources/static/documents.html` (script 部分)
---
### Task 8: 实现筛选功能
**优先级**: P0
**预计时间**: 30 分钟
**依赖**: Task 4
**描述**:
实现文档筛选功能：
- 状态下拉框筛选
- 故障源输入框筛选（带防抖）
- 点击状态卡片快速筛选
- 清除筛选
- 筛选时重置分页
**验收标准**:
- [ ] 状态下拉框改变时触发筛选
- [ ] 故障源输入框使用防抖（300ms）
- [ ] 点击状态卡片筛选对应状态的文档
- [ ] 筛选后 currentPage 重置为 0
- [ ] 筛选结果正确显示
**文件**:
- 修改: `src/main/resources/static/documents.html` (script 部分)
---
### Task 9: 实现详情面板
**优先级**: P1
**预计时间**: 30 分钟
**依赖**: Task 4, Task 5
**描述**:
实现文档详情面板功能：
- 点击"查看"按钮打开详情面板
- 加载文档详细信息
- 显示详情面板（滑出动画）
- 关闭详情面板
**验收标准**:
- [ ] 点击"查看"按钮打开详情面板
- [ ] 调用 API 获取文档详情
- [ ] 详情面板从右侧滑出
- [ ] 显示完整的文档信息（基本信息、分类信息、索引信息、时间信息）
- [ ] 失败文档显示错误信息（红色标注）
- [ ] 点击关闭按钮或遮罩关闭面板
**文件**:
- 修改: `src/main/resources/static/documents.html` (script 部分)
---
### Task 10: 实现状态统计
**优先级**: P0
**预计时间**: 20 分钟
**依赖**: Task 3, Task 4
**描述**:
实现状态统计功能：
- 页面加载时查询各状态文档数量
- 更新统计卡片数字
- 点击卡片筛选对应状态
**验收标准**:
- [ ] 页面加载时自动查询统计数据
- [ ] 4 个状态卡片显示正确数量
- [ ] 点击卡片筛选对应状态的文档
- [ ] 刷新列表后自动更新统计
**文件**:
- 修改: `src/main/resources/static/documents.html` (script 部分)
---
### Task 11: 实现刷新功能
**优先级**: P0
**预计时间**: 15 分钟
**依赖**: Task 4
**描述**:
实现手动刷新功能：
- 点击刷新按钮重新加载列表
- 保持当前筛选条件
- 更新状态统计
**验收标准**:
- [ ] 点击"刷新"按钮重新加载数据
- [ ] 保持当前筛选条件不变
- [ ] 同时更新统计数据
- [ ] 显示加载状态
**文件**:
- 修改: `src/main/resources/static/documents.html` (script 部分)
---
### Task 12: 添加页面入口
**优先级**: P1
**预计时间**: 15 分钟
**依赖**: Task 1
**描述**:
在 index.html 的侧边栏添加文档管理页面入口：
- 在"新建对话"按钮下方添加导航按钮
- 按钮文字：文档管理
- 链接到 documents.html
**验收标准**:
- [ ] 侧边栏显示"文档管理"按钮
- [ ] 点击按钮跳转到 documents.html
- [ ] 按钮样式与"新建对话"按钮一致
- [ ] 使用合适的图标（文档图标）
**文件**:
- 修改: `src/main/resources/static/index.html`
---
### Task 13: 错误处理和用户提示
**优先级**: P0
**预计时间**: 30 分钟
**依赖**: 所有功能任务
**描述**:
实现统一的错误处理和用户提示：
- showError(message) - 显示错误通知
- showSuccess(message) - 显示成功通知
- showLoading() / hideLoading() - 显示/隐藏全局加载状态
- 网络错误处理
- API 错误处理
**验收标准**:
- [ ] 通知条在页面顶部显示
- [ ] 错误通知红色背景，成功通知绿色背景
- [ ] 通知 3 秒后自动消失
- [ ] 全局加载状态覆盖整个页面
- [ ] 所有 API 调用都有错误处理
- [ ] 错误信息清晰友好
**文件**:
- 修改: `src/main/resources/static/documents.html` (script 部分)
- 修改: `src/main/resources/static/documents.css`
---
### Task 14: 测试和优化
**优先级**: P1
**预计时间**: 60 分钟
**依赖**: 所有功能任务
**描述**:
进行全面测试和优化：
- 功能测试（所有操作流程）
- 边界测试（空列表、网络错误等）
- 浏览器兼容性测试
- 性能优化（防抖、缓存）
- 代码优化（重构重复代码）
**验收标准**:
- [ ] 所有功能正常工作
- [ ] 边界情况处理正确
- [ ] Chrome、Firefox、Safari 正常运行
- [ ] 无明显性能问题
- [ ] 代码结构清晰，无重复代码
**文件**:
- 修改: `src/main/resources/static/documents.html`
- 修改: `src/main/resources/static/documents.css`
---
## 任务执行顺序
**阶段 1：基础搭建**
1. Task 1: 创建基础 HTML 结构
2. Task 2: 实现样式定制
**阶段 2：核心逻辑**
3. Task 3: 实现 API 调用层
4. Task 4: 实现状态管理器
5. Task 5: 实现 UI 渲染函数
**阶段 3：功能实现**
6. Task 6: 实现文档上传功能
7. Task 7: 实现文档删除功能
8. Task 8: 实现筛选功能
9. Task 10: 实现状态统计
10. Task 11: 实现刷新功能
11. Task 13: 错误处理和用户提示
**阶段 4：增强功能**
12. Task 9: 实现详情面板
13. Task 12: 添加页面入口
**阶段 5：测试和优化**
14. Task 14: 测试和优化
---
## 预计总时间
- P0 任务：约 6 小时
- P1 任务：约 2 小时
- 总计：约 8 小时
---
## 风险和依赖
**技术风险**:
- 文件上传可能受后端配置限制（需确认 max-file-size）
- 大文件上传可能超时
**外部依赖**:
- 后端服务必须运行（localhost:9900）
- 数据库和 Milvus 服务正常
**缓解措施**:
- 在上传前添加文件大小检查（前端限制 10MB）
- 添加详细的错误提示
- 提供重试机制