# PKB个人知识�?- 超级安全迁移执行计划

> **创建日期�?* 2026-01-06  
> **目标�?* 将PKB从旧架构迁移到新架构，确保零风险、可回滚、可验证  
> **原则�?* 保守、渐进、每步可验证、随时可回滚

---

## 🎯 迁移目标

将PKB从旧架构迁移到新架构，同时：
- �?保持现有功能100%可用
- �?不影响正在使用的用户
- �?每一步都可以验证和回�?
- �?数据零损�?

---

## 📊 当前状态分�?

### 旧架构位�?
```
后端：backend/src/legacy/
├─ controllers/knowledgeBaseController.ts
├─ services/knowledgeBaseService.ts
└─ routes/knowledgeBases.ts

前端：frontend/src/
└─ pages/KnowledgePage.tsx

数据库：�?pkb_schema（已在独立Schema，无需迁移�?
```

### 新架构位�?
```
后端：backend/src/modules/pkb/
├─ controllers/
├─ services/
└─ routes/

前端：frontend-v2/src/modules/pkb/
├─ pages/
├─ components/
└─ api/
```

---

## 🚀 分阶段执行计�?

### ⏱️ 时间估算

| 阶段 | 任务 | 预估时间 | 可回�?| 风险 |
|-----|------|---------|--------|-----|
| **阶段0** | 代码审查和准�?| 0.5�?| N/A | �?|
| **阶段1** | 后端代码复制（不删除旧代码） | 0.5�?| �?| 极低 |
| **阶段2** | 后端API路由添加（双路由共存�?| 0.5�?| �?| 极低 |
| **阶段3** | 后端功能验证 | 0.5�?| �?| �?|
| **阶段4** | 前端代码复制 | 0.5�?| �?| 极低 |
| **阶段5** | 前端路由添加（双路由共存�?| 0.5�?| �?| 极低 |
| **阶段6** | 前端功能验证 | 0.5�?| �?| �?|
| **阶段7** | 灰度发布（功能开关） | 1�?| �?| �?|
| **阶段8** | 全量切换 | 0.5�?| �?| �?|
| **阶段9** | 清理旧代码（可选） | 0.5�?| ⚠️ | �?|

**总计：约 5-6天（保守估计�?*

---

## 📝 阶段0：代码审查和准备�?.5天）

### 目标
- 理解现有代码的所有功能点
- 确认依赖关系
- 制定详细的迁移清�?

### 任务清单

#### Task 0.1：审查旧代码结构
```bash
# 后端代码审查
- [ ] 阅读 knowledgeBaseController.ts（所有API端点�?
- [ ] 阅读 knowledgeBaseService.ts（所有业务逻辑�?
- [ ] 阅读 knowledgeBases.ts（路由定义）
- [ ] 列出所有API端点和功�?

# 前端代码审查
- [ ] 阅读 KnowledgePage.tsx（UI和交互）
- [ ] 列出所有用户操作流�?
- [ ] 确认状态管理方�?
```

#### Task 0.2：确认数据库Schema
```bash
- [ ] 验证pkb_schema表结�?
- [ ] 确认Prisma模型定义
- [ ] 检查是否有旧数�?
- [ ] 确认索引和约�?
```

#### Task 0.3：创建功能清�?
```bash
- [ ] 列出所有功能（CRUD、上传、检索等�?
- [ ] 创建测试用例
- [ ] 准备测试数据
```

### 验证标准
- �?所有代码已阅读并理�?
- �?功能清单已创�?
- �?测试用例已准�?

### 回滚方案
- 无需回滚（只是阅读代码）

---

## 📝 阶段1：后端代码复制（0.5天）

### 目标
- 将旧代码复制到新位置
- **不删除、不修改旧代�?*
- 确保新代码可以独立编�?

### 任务清单

#### Task 1.1：创建新目录结构
```bash
# 创建目录
mkdir -p backend/src/modules/pkb/controllers
mkdir -p backend/src/modules/pkb/services
mkdir -p backend/src/modules/pkb/routes
mkdir -p backend/src/modules/pkb/types
mkdir -p backend/src/modules/pkb/utils
```

#### Task 1.2：复制Controller代码
```bash
# 复制文件（保留旧文件�?
cp backend/src/legacy/controllers/knowledgeBaseController.ts \
   backend/src/modules/pkb/controllers/knowledgeBaseController.ts

# 验证：旧文件仍存�?
ls -la backend/src/legacy/controllers/knowledgeBaseController.ts
```

#### Task 1.3：复制Service代码
```bash
cp backend/src/legacy/services/knowledgeBaseService.ts \
   backend/src/modules/pkb/services/knowledgeBaseService.ts
```

#### Task 1.4：复制Route代码
```bash
cp backend/src/legacy/routes/knowledgeBases.ts \
   backend/src/modules/pkb/routes/knowledgeBases.ts
```

#### Task 1.5：更新导入路�?
```typescript
// 在新代码中，更新所�?import 路径
// �? import { xxx } from '../../legacy/...'
// �? import { xxx } from '../services/...'

// 但是：依赖common层的保持不变
import { prisma } from '../../../../common/database/prisma';
```

#### Task 1.6：编译验�?
```bash
# 编译检查（不运行）
cd backend
npm run build

# 检查是否有编译错误
# 如果有错误，只修复导入路径问题，不修改逻辑
```

### 验证标准
- �?新代码编译通过
- �?旧代码完全未�?
- �?旧系统仍可正常运�?

### 回滚方案
```bash
# 如果出问题，直接删除新目�?
rm -rf backend/src/modules/pkb
# 旧代码完全未动，系统继续运行
```

---

## 📝 阶段2：后端API路由添加（双路由共存）（0.5天）

### 目标
- 在新位置添加API路由
- **旧路由保持不变，继续工作**
- 新旧路由同时可用

### 任务清单

#### Task 2.1：注册新路由（不影响旧路由）
```typescript
// backend/src/index.ts �?routes/index.ts

// 旧路由（保持不变�?
import legacyKnowledgeRoutes from './legacy/routes/knowledgeBases';
app.use('/api/v1/knowledge', legacyKnowledgeRoutes);

// 新路由（新增�?
import newKnowledgeRoutes from './modules/pkb/routes/knowledgeBases';
app.use('/api/v2/knowledge', newKnowledgeRoutes);  // 使用v2路径
```

#### Task 2.2：确认路由隔�?
```bash
# 新路由路径：/api/v2/knowledge/*
# 旧路由路径：/api/v1/knowledge/*
# 两者完全独立，互不干扰
```

#### Task 2.3：添加健康检查端�?
```typescript
// 在新路由中添加健康检�?
router.get('/health', (req, res) => {
  res.json({ 
    status: 'ok', 
    module: 'pkb-v2',
    timestamp: new Date().toISOString() 
  });
});
```

### 验证标准

#### 验证新路由可�?
```bash
# 启动服务�?
npm run dev

# 测试新路由健康检�?
curl http://localhost:3000/api/v2/knowledge/health
# 期望返回：{"status":"ok","module":"pkb-v2",...}

# 确认旧路由仍工作
curl http://localhost:3000/api/v1/knowledge/xxx
# 期望返回：正常数�?
```

#### 验证旧路由未受影�?
```bash
# 使用Postman或curl测试所有旧API
# 确保所有功能正�?

# 例如�?
curl -X GET http://localhost:3000/api/v1/knowledge/list
curl -X POST http://localhost:3000/api/v1/knowledge/create
# ... 测试所有端�?
```

### 回滚方案
```typescript
// 如果新路由有问题，直接注释掉新路由注�?
// import newKnowledgeRoutes from './modules/pkb/routes/knowledgeBases';
// app.use('/api/v2/knowledge', newKnowledgeRoutes);  // 注释�?

// 旧路由继续工作，用户无感�?
```

---

## 📝 阶段3：后端功能验证（0.5天）

### 目标
- 验证新后端所有功�?
- 对比新旧API返回结果
- 确保新后端与旧后端行为完全一�?

### 任务清单

#### Task 3.1：准备测试环�?
```bash
# 创建测试用户
# 准备测试数据（知识库、文档）
# 准备Postman测试集合
```

#### Task 3.2：逐个测试API端点

```bash
测试清单�?
- [ ] GET /api/v2/knowledge/list - 获取知识库列�?
- [ ] POST /api/v2/knowledge/create - 创建知识�?
- [ ] GET /api/v2/knowledge/:id - 获取知识库详�?
- [ ] PUT /api/v2/knowledge/:id - 更新知识�?
- [ ] DELETE /api/v2/knowledge/:id - 删除知识�?
- [ ] POST /api/v2/knowledge/:id/upload - 上传文档
- [ ] GET /api/v2/knowledge/:id/documents - 获取文档列表
- [ ] DELETE /api/v2/knowledge/:id/documents/:docId - 删除文档
- [ ] POST /api/v2/knowledge/:id/query - RAG检�?
- [ ] GET /api/v2/knowledge/:id/batch-tasks - 批处理任务列�?
- [ ] POST /api/v2/knowledge/:id/batch-tasks - 创建批处理任�?
```

#### Task 3.3：对比测试（新旧API�?
```bash
# 对于每个API，使用相同参数同时调用新旧接�?
# 对比返回结果是否一�?

# 示例�?
curl /api/v1/knowledge/list > old_result.json
curl /api/v2/knowledge/list > new_result.json
diff old_result.json new_result.json
```

#### Task 3.4：边界测�?
```bash
- [ ] 测试无效参数
- [ ] 测试权限控制
- [ ] 测试并发请求
- [ ] 测试大文件上�?
- [ ] 测试错误处理
```

#### Task 3.5：性能测试
```bash
# 简单的性能对比
- [ ] 测试响应时间
- [ ] 测试内存使用
- [ ] 确认无明显性能劣化
```

### 验证标准
- �?所有API端点测试通过
- �?新旧API返回结果一�?
- �?边界情况处理正确
- �?性能无明显下�?

### 发现问题的处�?
```bash
如果发现问题�?
1. 记录问题详情
2. 修复新代�?
3. 重新测试
4. 不影响旧系统（旧路由继续工作�?
5. 可以随时暂停迁移
```

### 回滚方案
- 发现严重问题时，停止使用新路�?
- 旧路由继续工�?
- 有时间慢慢修复新代码

---

## 📝 阶段4：前端代码复制（0.5天）

### 目标
- 将旧前端代码复制到新位置
- **不删除、不修改旧代�?*
- 确保新代码可以独立编�?

### 任务清单

#### Task 4.1：创建新目录结构
```bash
mkdir -p frontend-v2/src/modules/pkb/pages
mkdir -p frontend-v2/src/modules/pkb/components
mkdir -p frontend-v2/src/modules/pkb/api
mkdir -p frontend-v2/src/modules/pkb/types
mkdir -p frontend-v2/src/modules/pkb/hooks
```

#### Task 4.2：复制页面代�?
```bash
cp frontend/src/pages/KnowledgePage.tsx \
   frontend-v2/src/modules/pkb/pages/KnowledgePage.tsx
```

#### Task 4.3：创建API服务
```typescript
// frontend-v2/src/modules/pkb/api/knowledgeApi.ts
// 创建新的API调用层，指向 /api/v2/knowledge/*
```

#### Task 4.4：更新导入路�?
```typescript
// 更新所有import路径
// 但保持调用相同的UI组件�?
```

#### Task 4.5：编译验�?
```bash
cd frontend-v2
npm run build
# 检查编译错�?
```

### 验证标准
- �?新代码编译通过
- �?旧前端完全未�?
- �?旧前端仍可正常访�?

### 回滚方案
```bash
# 删除新目�?
rm -rf frontend-v2/src/modules/pkb
# 旧前端继续工�?
```

---

## 📝 阶段5：前端路由添加（双路由共存）�?.5天）

### 目标
- 在新前端添加路由
- **旧路由保持不�?*
- 新旧页面同时可用

### 任务清单

#### Task 5.1：注册新路由
```typescript
// frontend-v2/src/router/index.ts

// 旧路由（保持不变�? 如果旧前端还在运�?
// 访问：http://localhost:5173/knowledge

// 新路由（新增�?
{
  path: '/pkb',  // 使用新路�?
  component: () => import('@/modules/pkb/pages/KnowledgePage.tsx'),
  meta: { title: 'PKB个人知识库（新版�? }
}
```

#### Task 5.2：更新API调用
```typescript
// 确保新前端调用的�?/api/v2/knowledge/* 路由
const API_BASE = '/api/v2/knowledge';
```

#### Task 5.3：添加版本标�?
```typescript
// 在页面上添加版本标识，方便区分新旧版�?
<div className="version-badge">V2 (新架�?</div>
```

### 验证标准
- �?新路由可访问：http://localhost:5174/pkb
- �?页面正常渲染
- �?无编译错�?

### 回滚方案
```typescript
// 注释掉新路由
// {
//   path: '/pkb',
//   component: ...
// }
```

---

## 📝 阶段6：前端功能验证（0.5天）

### 目标
- 验证新前端所有功�?
- 确保用户体验一�?
- 发现并修复UI问题

### 任务清单

#### Task 6.1：手动功能测�?
```bash
测试流程�?
1. [ ] 访问新页面：http://localhost:5174/pkb
2. [ ] 登录功能
3. [ ] 查看知识库列�?
4. [ ] 创建新知识库
5. [ ] 上传文档
6. [ ] 查看文档列表
7. [ ] RAG检索功�?
8. [ ] 编辑知识�?
9. [ ] 删除文档
10. [ ] 删除知识�?
11. [ ] 批处理功�?
12. [ ] 错误提示
```

#### Task 6.2：UI一致性检�?
```bash
- [ ] 布局是否正确
- [ ] 样式是否正常
- [ ] 交互是否流畅
- [ ] 加载状态显�?
- [ ] 错误提示友好
```

#### Task 6.3：浏览器兼容�?
```bash
- [ ] Chrome测试
- [ ] Firefox测试
- [ ] Safari测试（如有Mac�?
```

#### Task 6.4：响应式测试
```bash
- [ ] 桌面端（1920x1080�?
- [ ] 平板端（768x1024�?
- [ ] 移动端（375x667�?
```

### 验证标准
- �?所有功能正常工�?
- �?UI显示正确
- �?无明显bug
- �?用户体验良好

### 发现问题的处�?
- 修复新前端代�?
- 旧前端继续可�?
- 不影响现有用�?

---

## 📝 阶段7：灰度发布（功能开关）�?天）

### 目标
- 让部分用户使用新版本
- 收集真实使用反馈
- 发现潜在问题

### 任务清单

#### Task 7.1：实现功能开�?
```typescript
// backend/src/common/config/featureFlags.ts
export const featureFlags = {
  usePKBv2: process.env.USE_PKB_V2 === 'true' || false,
  pkbV2UserWhitelist: process.env.PKB_V2_WHITELIST?.split(',') || [],
};

// 中间件检�?
function pkbVersionRouter(req, res, next) {
  const userId = req.user?.id;
  
  // 白名单用户使用新版本
  if (featureFlags.pkbV2UserWhitelist.includes(userId)) {
    req.usePKBv2 = true;
  }
  
  // 或全局开�?
  if (featureFlags.usePKBv2) {
    req.usePKBv2 = true;
  }
  
  next();
}
```

#### Task 7.2：前端功能开�?
```typescript
// frontend-v2/src/modules/pkb/config.ts
export const usePKBv2 = () => {
  // 检查localStorage或URL参数
  const forceV2 = localStorage.getItem('force-pkb-v2') === 'true';
  const urlParam = new URLSearchParams(window.location.search).get('v2');
  
  return forceV2 || urlParam === 'true';
};

// 根据开关决定使用哪个API
export const getApiBase = () => {
  return usePKBv2() ? '/api/v2/knowledge' : '/api/v1/knowledge';
};
```

#### Task 7.3：灰度发布策�?
```bash
阶段7.1：内部测试（1-2天）
- [ ] 开发团队使用新版本
- [ ] 设置：localStorage.setItem('force-pkb-v2', 'true')
- [ ] 记录所有问�?

阶段7.2：小范围用户�?-5天）
- [ ] 选择5-10个活跃用�?
- [ ] 加入白名�?
- [ ] 收集反馈

阶段7.3：扩大范围（7天）
- [ ] 25%用户使用新版�?
- [ ] 监控错误�?
- [ ] 对比性能指标
```

#### Task 7.4：监控和日志
```typescript
// 添加详细日志
logger.info('PKB API called', {
  version: req.usePKBv2 ? 'v2' : 'v1',
  userId: req.user.id,
  action: req.path,
});

// 错误监控
if (req.usePKBv2) {
  Sentry.setTag('pkb-version', 'v2');
}
```

### 验证标准
- �?灰度用户正常使用
- �?无重大bug
- �?错误率在可接受范�?
- �?用户反馈积极

### 回滚方案
```bash
# 立即回滚灰度用户
1. 设置环境变量：USE_PKB_V2=false
2. 或清空白名单：PKB_V2_WHITELIST=""
3. 重启服务
4. 所有用户自动回到旧版本
```

---

## 📝 阶段8：全量切换（0.5天）

### 目标
- 所有用户切换到新版�?
- 确保平滑过渡
- 保留回滚能力

### 任务清单

#### Task 8.1：准备切�?
```bash
# 提前通知
- [ ] 通知用户即将升级
- [ ] 准备回滚预案
- [ ] 备份当前配置
```

#### Task 8.2：执行切�?
```bash
# 方式1：修改默认路�?
在frontend-v2中，�?/knowledge 路由指向新页�?

# 方式2：全局开�?
USE_PKB_V2=true

# 方式3：前端重定向
if (location.pathname === '/knowledge') {
  location.href = '/pkb';
}
```

#### Task 8.3：密切监控（24小时�?
```bash
- [ ] 监控错误�?
- [ ] 监控API响应时间
- [ ] 检查用户反�?
- [ ] 查看日志异常
```

### 验证标准
- �?所有用户访问新版本
- �?错误率正�?
- �?性能稳定
- �?无重大投�?

### 回滚方案（保�?天）
```bash
# 紧急回�?
1. USE_PKB_V2=false
2. 或修改路由配�?
3. 重启服务
4. 5分钟内完成回�?
```

---

## 📝 阶段9：清理旧代码（可选，1-2周后�?

### ⚠️ 重要提示
**至少等待2周，确认新版本完全稳定后再执行！**

### 任务清单

#### Task 9.1：备份旧代码
```bash
# 创建备份分支
git checkout -b backup/pkb-legacy-code
git commit -am "Backup: PKB legacy code before cleanup"
git push origin backup/pkb-legacy-code
```

#### Task 9.2：删除旧代码
```bash
# 删除旧后端代�?
rm -rf backend/src/legacy/controllers/knowledgeBaseController.ts
rm -rf backend/src/legacy/services/knowledgeBaseService.ts
rm -rf backend/src/legacy/routes/knowledgeBases.ts

# 删除旧前端代�?
rm -rf frontend/src/pages/KnowledgePage.tsx
```

#### Task 9.3：清理路�?
```typescript
// 移除旧路由注�?
// app.use('/api/v1/knowledge', legacyKnowledgeRoutes);

// 可选：添加重定�?
app.use('/api/v1/knowledge', (req, res) => {
  res.redirect(308, `/api/v2/knowledge${req.path}`);
});
```

### 验证标准
- �?代码已备�?
- �?新版本运�?周无问题
- �?团队一致同意删�?

---

## 🔒 安全措施总结

### 1. 始终可回�?
```bash
每个阶段都可以立即回滚到上一个状�?
回滚时间�? 5分钟
```

### 2. 旧系统保�?
```bash
迁移期间，旧代码完全不动
旧功�?00%可用
用户无感�?
```

### 3. 渐进式验�?
```bash
每个阶段独立验证
发现问题立即修复
不影响下一阶段
```

### 4. 灰度发布
```bash
内部测试 �?小范围用�?�?大范围用�?�?全量
任何阶段发现问题都可以暂�?
```

### 5. 监控告警
```bash
实时监控错误�?
性能指标对比
用户反馈收集
```

---

## 📊 检查点（Checkpoint�?

在每个阶段结束时，必须通过以下检查：

### �?阶段通过标准
```bash
1. [ ] 所有测试用例通过
2. [ ] 无编�?运行时错�?
3. [ ] 旧系统功能正�?
4. [ ] 性能无明显下�?
5. [ ] 代码已提交到Git
6. [ ] 团队评审通过
```

### �?阶段失败处理
```bash
1. 立即停止迁移
2. 分析失败原因
3. 修复问题
4. 重新验证
5. 通过后再继续下一阶段
```

---

## 🎯 成功标准

### 最终目�?
- �?PKB功能100%迁移到新架构
- �?用户无感知切�?
- �?零数据丢�?
- �?零停机时�?
- �?可随时回滚（保留2周）

### KPI指标
```bash
- 错误率：< 0.1%（与旧版本对比）
- 响应时间：不超过旧版本的 110%
- 用户满意度：�?90%
- 回滚次数�?次（理想情况�?
```

---

## 📞 应急联�?

### 发现严重问题�?
```bash
1. 立即停止迁移
2. 评估影响范围
3. 决定是否回滚
4. 通知团队
5. 记录问题详情
```

### 回滚决策
```bash
立即回滚的情况：
- 数据丢失或损�?
- 核心功能不可�?
- 大量用户投诉
- 安全漏洞

可以继续的情况：
- 个别边界case问题
- UI小bug
- 性能轻微下降
- 用户反馈可以接受
```

---

## 📝 迁移日志模板

```markdown
### [日期] 阶段X执行记录

**执行人：** XXX
**开始时间：** YYYY-MM-DD HH:mm
**结束时间�?* YYYY-MM-DD HH:mm

**执行内容�?*
- Task X.1: [完成/失败] [说明]
- Task X.2: [完成/失败] [说明]
...

**测试结果�?*
- 测试用例1: �?通过
- 测试用例2: �?通过
...

**发现的问题：**
1. [问题描述] - [状态：已修�?待修复]
2. ...

**性能指标�?*
- API响应时间：XX ms (旧版�? XX ms)
- 错误率：X%

**结论�?*
[�?通过 / �?失败]

**下一步：**
[继续下一阶段 / 暂停修复问题 / 回滚]
```

---

## 🎓 经验总结

### 这个计划的优�?
```
1. �?极度保守，风险最小化
2. �?每步可验证，问题早发�?
3. �?随时可回滚，不影响业�?
4. �?灰度发布，逐步切换
5. �?旧代码长期保留，双保�?
```

### 与快速迁移的对比
```
快速迁移：1-2天完成，但风险高
安全迁移�?-6天完成，但风险极�?

选择：用4天时间换取安全性和稳定�?
```

---

**准备好了吗？让我们从阶段0开始！** 🚀