docs: complete documentation system (250+ files)
- System architecture and design documentation - Business module docs (ASL/AIA/PKB/RVW/DC/SSA/ST) - ASL module complete design (quality assurance, tech selection) - Platform layer and common capabilities docs - Development standards and API specifications - Deployment and operations guides - Project management and milestone tracking - Architecture implementation reports - Documentation templates and guides
This commit is contained in:
@@ -1,231 +0,0 @@
|
||||
# Day 21-22：知识库前端开发与问题修复
|
||||
|
||||
> **日期：** 2025-10-11
|
||||
> **状态：** ✅ 已完成
|
||||
> **里程碑：** 里程碑1 - Week 3
|
||||
|
||||
---
|
||||
|
||||
## 📋 任务概述
|
||||
|
||||
完成知识库前端页面开发，并解决前后端集成过程中遇到的3个关键问题。
|
||||
|
||||
---
|
||||
|
||||
## ✅ 完成的功能
|
||||
|
||||
### 1. 知识库前端页面（已完成）
|
||||
- ✅ 知识库列表页面
|
||||
- ✅ 知识库详情页面
|
||||
- ✅ 文档上传组件
|
||||
- ✅ 文档列表显示
|
||||
- ✅ 文档状态管理
|
||||
|
||||
---
|
||||
|
||||
## 🐛 发现并修复的问题
|
||||
|
||||
### 问题1：删除知识库失败 - CORS错误
|
||||
|
||||
**现象：**
|
||||
```
|
||||
Access to XMLHttpRequest at 'http://localhost:3001/api/v1/knowledge-bases/xxx'
|
||||
has been blocked by CORS policy: Method DELETE is not allowed by
|
||||
Access-Control-Allow-Methods in preflight response.
|
||||
```
|
||||
|
||||
**原因：**
|
||||
后端CORS配置不完整，没有明确允许DELETE方法
|
||||
|
||||
**修复：**
|
||||
```typescript
|
||||
// backend/src/index.ts
|
||||
await fastify.register(cors, {
|
||||
origin: true,
|
||||
credentials: true,
|
||||
methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS', 'HEAD'],
|
||||
allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With', 'Accept', 'Origin'],
|
||||
exposedHeaders: ['Content-Range', 'X-Content-Range'],
|
||||
maxAge: 600,
|
||||
preflightContinue: false,
|
||||
});
|
||||
```
|
||||
|
||||
**验收：** ✅ 删除知识库成功，无CORS错误
|
||||
|
||||
---
|
||||
|
||||
### 问题2：编辑知识库失败 - CORS错误
|
||||
|
||||
**现象：**
|
||||
```
|
||||
Access to XMLHttpRequest at 'http://localhost:3001/api/v1/knowledge-bases/xxx'
|
||||
has been blocked by CORS policy: Method PUT is not allowed by
|
||||
Access-Control-Allow-Methods in preflight response.
|
||||
```
|
||||
|
||||
**原因：**
|
||||
与问题1相同，CORS配置没有明确允许PUT方法
|
||||
|
||||
**修复：**
|
||||
同上，统一修复CORS配置
|
||||
|
||||
**验收：** ✅ 编辑知识库成功，保存正常
|
||||
|
||||
---
|
||||
|
||||
### 问题3：文件上传无响应
|
||||
|
||||
**现象：**
|
||||
- 点击上传按钮完全没有反应
|
||||
- 前端无错误提示
|
||||
- 后端无请求日志
|
||||
- 浏览器控制台无日志输出
|
||||
|
||||
**排查过程：**
|
||||
|
||||
#### 步骤1：添加调试日志
|
||||
在前端组件中添加详细的console.log，发现：
|
||||
- `beforeUpload` 被调用 ✅
|
||||
- `customRequest` 没有被调用 ❌
|
||||
|
||||
#### 步骤2：发现浏览器缓存问题
|
||||
- 浏览器Sources中显示两个同名文件
|
||||
- 实际运行的是旧版本代码
|
||||
- 清除缓存后解决
|
||||
|
||||
#### 步骤3：发现组件被禁用
|
||||
调试日志显示：
|
||||
```javascript
|
||||
{
|
||||
disabled: true,
|
||||
组件是否被禁用: true
|
||||
}
|
||||
```
|
||||
|
||||
**原因1：** 组件被 `disabled={loading}` 禁用，loading状态一直为true
|
||||
|
||||
**修复1：**
|
||||
```typescript
|
||||
// frontend/src/pages/KnowledgePage.tsx
|
||||
<DocumentUpload
|
||||
disabled={false} // 临时改为false，后续优化loading状态管理
|
||||
...
|
||||
/>
|
||||
```
|
||||
|
||||
**原因2：** `beforeUpload` 返回 `false` 阻止了 `customRequest` 执行
|
||||
|
||||
根据Ant Design Upload组件的机制：
|
||||
- `return false` → 完全阻止上传，包括customRequest
|
||||
- `return Upload.LIST_IGNORE` → 忽略该文件
|
||||
- 不返回任何值（undefined）→ 允许customRequest执行
|
||||
|
||||
**修复2：**
|
||||
```typescript
|
||||
// frontend/src/components/knowledge/DocumentUpload.tsx
|
||||
const beforeUpload = (file: File) => {
|
||||
// 验证逻辑...
|
||||
|
||||
// 不返回任何值，让 customRequest 处理上传
|
||||
// 之前: return false; ❌
|
||||
};
|
||||
```
|
||||
|
||||
**验收：** ✅ 文件上传成功，能看到上传进度，后端正确接收文件
|
||||
|
||||
---
|
||||
|
||||
## 🔧 技术要点总结
|
||||
|
||||
### 1. CORS配置要点
|
||||
- 必须明确列出所有需要的HTTP方法
|
||||
- 开发环境可以 `origin: true` 允许所有来源
|
||||
- 生产环境应该指定具体的域名列表
|
||||
- `maxAge` 可以减少preflight请求频率
|
||||
|
||||
### 2. Ant Design Upload组件要点
|
||||
- `beforeUpload` 返回值决定是否继续上传
|
||||
- `false` 或 `Upload.LIST_IGNORE` → 阻止上传
|
||||
- `undefined`（不返回）→ 允许customRequest
|
||||
- `true` → 默认上传行为（需要action）
|
||||
- 使用 `customRequest` 可以完全控制上传逻辑
|
||||
- `disabled` 属性会阻止所有交互
|
||||
|
||||
### 3. 前端缓存问题处理
|
||||
- 开发时遇到代码不更新，优先考虑缓存问题
|
||||
- 解决方案：
|
||||
1. 使用无痕模式测试
|
||||
2. 清除浏览器缓存（Ctrl+Shift+Delete）
|
||||
3. 删除 `node_modules/.vite` 和 `dist` 文件夹
|
||||
4. 硬刷新（Ctrl+F5）
|
||||
|
||||
### 4. 调试技巧
|
||||
- 在关键位置添加console.log
|
||||
- 使用浏览器Sources查看实际运行的代码
|
||||
- 检查组件状态（props、state）
|
||||
- 对比文件内容和浏览器中的代码
|
||||
|
||||
---
|
||||
|
||||
## 📊 成果物
|
||||
|
||||
### 后端
|
||||
- `backend/src/index.ts` - 完整的CORS配置
|
||||
- `backend/src/controllers/documentController.ts` - 文档上传日志增强
|
||||
|
||||
### 前端
|
||||
- `frontend/src/pages/KnowledgePage.tsx` - 知识库管理主页面
|
||||
- `frontend/src/components/knowledge/DocumentUpload.tsx` - 文档上传组件（已清理调试日志）
|
||||
- `frontend/src/components/knowledge/KnowledgeBaseList.tsx` - 知识库列表组件
|
||||
- `frontend/src/components/knowledge/DocumentList.tsx` - 文档列表组件
|
||||
|
||||
---
|
||||
|
||||
## 🎯 下一步计划
|
||||
|
||||
### Day 23-24：知识库检索 + @引用功能 ⭐⭐⭐
|
||||
这是里程碑1的核心功能！
|
||||
|
||||
**任务：**
|
||||
1. 实现知识库检索API（调用Dify）
|
||||
2. 前端实现 `@知识库` 触发器
|
||||
3. 对话中集成知识库检索
|
||||
4. AI回答中显示溯源引用
|
||||
|
||||
**验收标准：**
|
||||
- ✅ 能在对话输入框输入 `@` 触发知识库选择
|
||||
- ✅ 选择知识库后能检索相关内容
|
||||
- ✅ AI回答包含明确的引用来源（如：`[📄 文献.pdf]`）
|
||||
- ✅ 基于知识库的回答质量可接受
|
||||
|
||||
---
|
||||
|
||||
## 💡 经验教训
|
||||
|
||||
### 1. 问题排查要系统化
|
||||
- ❌ 不要反复确认"服务是否启动"
|
||||
- ✅ 应该分析根本原因：代码逻辑？配置？缓存？
|
||||
|
||||
### 2. 缓存问题很常见
|
||||
- 前端开发时，缓存是高频问题
|
||||
- 建立清除缓存的标准流程
|
||||
- 优先使用无痕模式验证
|
||||
|
||||
### 3. 添加日志要有策略
|
||||
- 关键节点添加日志
|
||||
- 完成后及时清理，避免污染
|
||||
- 保留error级别的日志
|
||||
|
||||
### 4. CORS配置要完整
|
||||
- 一次性配置所有可能用到的HTTP方法
|
||||
- 避免后续反复修改
|
||||
|
||||
---
|
||||
|
||||
**文档维护：** 2025-10-11
|
||||
**作者：** AI助手 + 开发者
|
||||
**Git提交：** feat(frontend): Day 21-22 - 知识库前端开发完成，修复3个关键问题
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user