osiman/SuperBizAgent-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
refactor/mvp1.0
SuperBizAgent-java/openspec/changes/archive/2026-07-05-doc-management-ui/tasks.md
T

10 KiB
Raw Permalink Blame History

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

任务分解

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）
  • 添加详细的错误提示
  • 提供重试机制
Reference in New Issue View Git Blame Copy Permalink