407 lines
10 KiB
Markdown
407 lines
10 KiB
Markdown
# 文档管理页面开发 - 任务清单
|
||
|
||
## 任务分解
|
||
|
||
### 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）
|
||
- 添加详细的错误提示
|
||
- 提供重试机制
|