zhuyongxin
92ab8d27ee
- 新增 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
4.1 KiB
4.1 KiB
文档管理页面开发 - 关键决策
决策记录
决策 1: 使用纯静态页面，不引入前端框架
背景: 项目需要开发文档管理页面
决策: 使用纯静态页面（HTML + CSS + JavaScript），不引入 React/Vue 等框架
理由:
- 项目现有页面（index.html）已使用纯静态方式
- 功能相对简单，不需要复杂的状态管理
- 避免引入额外的构建工具和依赖
权衡:
- ✅ 优点: 简单直接，无需构建步骤，与现有代码风格一致
- ❌ 缺点: 手工管理 DOM，大型应用维护成本高（但本项目规模小，可接受）
决策 2: 不实现自动状态轮询
背景: 文档上传后状态会变化（PENDING → PROCESSING → INDEXED/FAILED）
决策: 不实现自动轮询，提供手动刷新按钮
理由:
- 避免增加复杂性（WebSocket 或轮询逻辑）
- 文档上传不是高频操作
- 用户可以手动刷新查看最新状态
权衡:
- ✅ 优点: 实现简单，减少服务器负载
- ❌ 缺点: 用户体验略差，需要手动刷新
未来优化: 可在 P2 阶段增加轮询或 WebSocket 支持
决策 3: 详情面板使用右侧滑出式，而非弹窗
背景: 需要展示文档详细信息
决策: 使用右侧滑出式面板
理由:
- 更符合现代 Web 应用的交互模式
- 不遮挡列表，用户可以同时看到列表和详情
- 滑出动画提供更好的视觉反馈
权衡:
- ✅ 优点: 用户体验好，不遮挡列表
- ❌ 缺点: 移动端需要特殊处理（全屏滑出）
决策 4: 文件上传大小前端限制 10MB
背景: 后端配置了文件上传大小限制
决策: 前端也增加 10MB 的检查
理由:
- 提前拦截大文件，避免无效上传
- 给用户明确的错误提示
- 与后端配置保持一致
实现: 在 handleUpload 中检查 file.size
决策 5: 使用 Result 统一响应格式
背景: 后端使用统一的 Result 响应格式
决策: 前端 API 层统一处理 Result 格式
理由:
- 后端已使用 Result 格式（code、message、data、timestamp）
- 统一的错误处理逻辑
实现:
async handleResponse(response) {
const result = await response.json();
if (result.code !== 200) {
throw new Error(result.message || '请求失败');
}
return result.data;
}
决策 6: 状态徽章使用 4 种颜色区分
背景: 文档有 4 种状态（PENDING/PROCESSING/INDEXED/FAILED）
决策: 使用不同颜色的徽章区分
颜色方案:
- PENDING: 灰色 (#757575) - 中性，表示等待
- PROCESSING: 蓝色 (#1a73e8) - 进行中
- INDEXED: 绿色 (#34a853) - 成功
- FAILED: 红色 (#ea4335) - 错误
理由:
- 符合常见的视觉语言（绿色=成功，红色=失败）
- 快速识别文档状态
决策 7: 删除操作使用确认对话框，明确警告
背景: 删除操作会同时删除 MySQL 和 Milvus 数据，不可恢复
决策: 显示确认对话框，包含明确的警告信息
警告内容: "此操作将删除 MySQL 和 Milvus 中的所有数据，不可恢复。"
理由:
- 防止误删除
- 明确告知用户后果
- 符合最佳实践
技术风险
风险 1: 大文件上传可能超时
描述: 接近 10MB 的文件上传可能超时
缓解措施:
- 前端显示上传中状态
- 后端配置合理的超时时间
- 未来可增加上传进度条
风险 2: 浏览器兼容性
描述: 使用了 ES6 语法和 Fetch API
缓解措施:
- 目标浏览器：Chrome 90+, Firefox 88+, Safari 14+
- 这些浏览器都支持现代 Web 标准
风险 3: 无实时状态更新
描述: 用户上传后需要手动刷新查看状态
缓解措施:
- 明确的刷新按钮
- 上传成功后自动刷新列表
- 未来可增加自动轮询（P2）
未来优化方向
- 实时状态更新: 使用 WebSocket 或轮询
- 批量操作: 批量删除、批量上传
- 文档预览: 显示部分文档内容
- 高级筛选: 多条件组合筛选
- 完整分页: 上一页、下一页、跳转