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
170 lines
4.1 KiB
Markdown
170 lines
4.1 KiB
Markdown
# 文档管理页面开发 - 关键决策
|
||
|
||
## 决策记录
|
||
|
||
### 决策 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<T> 统一响应格式
|
||
|
||
**背景**: 后端使用统一的 Result 响应格式
|
||
|
||
**决策**: 前端 API 层统一处理 Result 格式
|
||
|
||
**理由**:
|
||
- 后端已使用 Result<T> 格式（code、message、data、timestamp）
|
||
- 统一的错误处理逻辑
|
||
|
||
**实现**:
|
||
```javascript
|
||
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）
|
||
|
||
---
|
||
|
||
## 未来优化方向
|
||
|
||
1. **实时状态更新**: 使用 WebSocket 或轮询
|
||
2. **批量操作**: 批量删除、批量上传
|
||
3. **文档预览**: 显示部分文档内容
|
||
4. **高级筛选**: 多条件组合筛选
|
||
5. **完整分页**: 上一页、下一页、跳转
|