osiman/SuperBizAgent-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
93764488047362fbac246ee031e1ea082298e5d5
SuperBizAgent-java/openspec/changes/doc-management-ui/proposal.md
T
zhuyongxin 92ab8d27ee feat(doc-management): 添加文档管理前端页面 
- 新增 documents.html 文档管理页面
  - 文档列表展示（支持筛选和分页）
  - 文档上传功能（带元信息表单）
  - 文档详情查看（右侧滑出面板）
  - 文档删除功能
  - 状态统计卡片（待处理/处理中/已索引/失败）

- 新增 documents.css 和 documents.js
  - 纯静态页面实现，无需额外框架
  - 与现有 index.html 保持一致的设计风格
  - 修复列表滚动问题（覆盖 body overflow 设置）
  - 修复时间字段显示 NaN 问题（增加 Invalid Date 检查）

- 在 index.html 侧边栏添加文档管理入口

- 归档项目文档到 devflow 和 openspec
  - devflow/projects/2026-06-25-doc-management-ui/
  - openspec/changes/doc-management-ui/
  - 更新 devflow/index.md
2026-06-25 15:05:48 +08:00

5.6 KiB
Raw Blame History

文档管理页面开发提案

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 集成

// 后端 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 保持一致
  • 失败文档显示错误信息
  • 上传失败时显示明确的错误提示
Reference in New Issue View Git Blame Copy Permalink