# 文档管理页面开发 - 关键决策

## 决策记录

### 决策 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. **完整分页**: 上一页、下一页、跳转