SuperBizAgent-java/openspec/changes/doc-management-ui/tasks.md

文档管理页面开发 - 任务清单

任务分解

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）
• 添加详细的错误提示
• 提供重试机制