AIclinicalresearch/docs/09-架构实施/后端架构增量演进方案.md

后端架构增量演进方案

版本： V1.0
创建日期： 2025-11-14
策略： 新旧并存，增量演进
原则： 零风险改造，新模块新架构

---

🎯 核心策略

"绞杀者模式"（Strangler Fig Pattern）

不改造旧代码，新功能新架构

┌─────────────────────────────────────────────────────┐
│              AI临床研究平台 - Backend                │
├─────────────────────────────────────────────────────┤
│                                                     │
│  ┌──────────────┐          ┌──────────────────┐   │
│  │  现有模块     │          │   新模块         │   │
│  │  (旧架构)    │          │   (新架构)       │   │
│  ├──────────────┤          ├──────────────────┤   │
│  │ • AIA        │          │ • ASL (新)       │   │
│  │ • PKB        │          │ • 未来模块...    │   │
│  │ • RVW        │          │                  │   │
│  └──────────────┘          └──────────────────┘   │
│         ↓                           ↓              │
│    平铺结构               platform/common/modules  │
│    保持不变               标准化三层架构            │
└─────────────────────────────────────────────────────┘

---

📁 新的目录结构（并存版）

backend/
├── src/
│   ├── index.ts                          # 主入口（注册所有模块）
│   │
│   ├── config/                           # 【共用】配置层
│   │   ├── env.ts
│   │   └── database.ts
│   │
│   ├── legacy/                           # 🔸 现有代码（旧架构）
│   │   ├── routes/
│   │   │   ├── agents.ts                 # AIA 路由
│   │   │   ├── conversations.ts
│   │   │   ├── chatRoutes.ts
│   │   │   ├── projects.ts
│   │   │   ├── knowledgeBases.ts         # PKB 路由
│   │   │   ├── batchRoutes.ts
│   │   │   └── reviewRoutes.ts           # RVW 路由
│   │   │
│   │   ├── controllers/
│   │   │   ├── agentController.ts
│   │   │   ├── conversationController.ts
│   │   │   ├── chatController.ts
│   │   │   ├── knowledgeBaseController.ts
│   │   │   └── reviewController.ts
│   │   │
│   │   ├── services/
│   │   │   ├── agentService.ts
│   │   │   ├── conversationService.ts
│   │   │   ├── knowledgeBaseService.ts
│   │   │   └── reviewService.ts
│   │   │
│   │   └── templates/
│   │       └── clinicalResearch.ts
│   │
│   ├── common/                           # 【共用】通用能力层
│   │   ├── llm/                          # LLM 适配器
│   │   │   └── adapters/
│   │   │       ├── DeepSeekAdapter.ts
│   │   │       ├── QwenAdapter.ts
│   │   │       ├── LLMFactory.ts
│   │   │       └── types.ts
│   │   │
│   │   ├── rag/                          # RAG 能力
│   │   │   ├── DifyClient.ts
│   │   │   └── types.ts
│   │   │
│   │   ├── document/                     # 文档处理
│   │   │   ├── ExtractionClient.ts
│   │   │   └── TokenService.ts
│   │   │
│   │   ├── middleware/                   # 中间件
│   │   │   └── validateProject.ts
│   │   │
│   │   └── utils/                        # 工具函数
│   │       └── jsonParser.ts
│   │
│   └── modules/                          # 🌟 新架构模块（标准化）
│       │
│       ├── asl/                          # ⭐ AI智能文献（新模块）
│       │   ├── index.ts                  # 模块导出
│       │   ├── routes/
│       │   │   ├── index.ts              # 路由统一导出
│       │   │   ├── projects.ts           # 项目管理
│       │   │   ├── screening.ts          # 文献筛选
│       │   │   ├── extraction.ts         # 数据提取
│       │   │   └── analysis.ts           # 综合分析
│       │   │
│       │   ├── controllers/
│       │   │   ├── projectController.ts
│       │   │   ├── screeningController.ts
│       │   │   ├── extractionController.ts
│       │   │   └── analysisController.ts
│       │   │
│       │   ├── services/
│       │   │   ├── projectService.ts
│       │   │   ├── screeningService.ts
│       │   │   ├── extractionService.ts
│       │   │   └── analysisService.ts
│       │   │
│       │   └── types/                    # 模块类型定义
│       │       └── index.ts
│       │
│       └── [未来模块]/                   # 未来的新模块都按此结构
│
├── package.json
├── tsconfig.json                         # TypeScript 配置
└── .env

---

🔄 主入口文件（index.ts）

/**
 * AI临床研究平台 - 统一入口
 * 
 * 架构演进策略：新旧并存
 * - Legacy 模块：保持现有结构
 * - New 模块：采用标准化三层架构
 */

import Fastify from 'fastify';
import cors from '@fastify/cors';
import multipart from '@fastify/multipart';
import { config, validateEnv } from './config/env.js';
import { testDatabaseConnection, prisma } from './config/database.js';

// ============================================
// 【旧架构】Legacy 模块 - 保持不变
// ============================================
import { projectRoutes } from './legacy/routes/projects.js';
import { agentRoutes } from './legacy/routes/agents.js';
import { conversationRoutes } from './legacy/routes/conversations.js';
import { chatRoutes } from './legacy/routes/chatRoutes.js';
import knowledgeBaseRoutes from './legacy/routes/knowledgeBases.js';
import batchRoutes from './legacy/routes/batchRoutes.js';
import reviewRoutes from './legacy/routes/reviewRoutes.js';

// ============================================
// 【新架构】标准化模块
// ============================================
import { aslRoutes } from './modules/asl/routes/index.js';  // ASL 模块（新）

const fastify = Fastify({ logger: true });

// 注册插件
await fastify.register(cors, { origin: true });
await fastify.register(multipart, { limits: { fileSize: 10 * 1024 * 1024 } });

// 健康检查
fastify.get('/health', async () => ({
  status: 'ok',
  architecture: 'hybrid',  // 混合架构
  modules: {
    legacy: ['aia', 'pkb', 'rvw'],
    modern: ['asl'],
  },
}));

// ============================================
// 注册 Legacy 模块路由（旧架构）
// ============================================
console.log('\n📦 加载 Legacy 模块...');
await fastify.register(projectRoutes, { prefix: '/api/v1/aia' });
await fastify.register(agentRoutes, { prefix: '/api/v1/aia' });
await fastify.register(conversationRoutes, { prefix: '/api/v1/aia' });
await fastify.register(chatRoutes, { prefix: '/api/v1/aia' });
await fastify.register(knowledgeBaseRoutes, { prefix: '/api/v1/pkb' });
await fastify.register(batchRoutes, { prefix: '/api/v1/pkb' });
await fastify.register(reviewRoutes, { prefix: '/api/v1/rvw' });
console.log('✅ Legacy 模块加载完成（AIA, PKB, RVW）');

// ============================================
// 注册新架构模块路由
// ============================================
console.log('\n🌟 加载新架构模块...');
await fastify.register(aslRoutes, { prefix: '/api/v1/asl' });
console.log('✅ 新架构模块加载完成（ASL）');

// 启动服务器
async function start() {
  try {
    validateEnv();
    await testDatabaseConnection();
    await fastify.listen({ port: config.port, host: config.host });
    
    console.log('\n' + '='.repeat(60));
    console.log('🚀 AI临床研究平台启动成功！');
    console.log('='.repeat(60));
    console.log(`📍 服务地址: http://${config.host}:${config.port}`);
    console.log('\n📦 模块架构:');
    console.log('   🔸 Legacy 架构: AIA, PKB, RVW (稳定运行)');
    console.log('   🌟 新架构: ASL (标准化模块)');
    console.log('='.repeat(60) + '\n');
    
  } catch (error) {
    console.error('❌ 启动失败:', error);
    await prisma.$disconnect();
    process.exit(1);
  }
}

start();

---

🌟 新模块开发指南（ASL 为例）

1. 创建模块骨架

# 一次性创建所有目录
mkdir -p backend/src/modules/asl/{routes,controllers,services,types}

2. 创建模块导出（index.ts）

// backend/src/modules/asl/index.ts
/**
 * ASL 模块统一导出
 */
export { aslRoutes } from './routes/index.js';
export * from './types/index.js';

3. 创建路由统一导出

// backend/src/modules/asl/routes/index.ts
import { FastifyInstance } from 'fastify';
import { projectRoutes } from './projects.js';
import { screeningRoutes } from './screening.js';
import { extractionRoutes } from './extraction.js';
import { analysisRoutes } from './analysis.js';

/**
 * ASL 模块路由注册
 */
export async function aslRoutes(fastify: FastifyInstance) {
  // 注册各子模块路由
  await fastify.register(projectRoutes);       // /projects
  await fastify.register(screeningRoutes);     // /screening
  await fastify.register(extractionRoutes);    // /extraction
  await fastify.register(analysisRoutes);      // /analysis
  
  console.log('✅ ASL 模块路由注册完成');
}

4. 标准化的 Controller 模式

// backend/src/modules/asl/controllers/projectController.ts
import { FastifyRequest, FastifyReply } from 'fastify';
import * as projectService from '../services/projectService.js';

export class ProjectController {
  /**
   * 获取项目列表
   */
  async getProjects(request: FastifyRequest, reply: FastifyReply) {
    try {
      const projects = await projectService.getProjects();
      return reply.send({ success: true, data: projects });
    } catch (error) {
      console.error('获取项目列表失败:', error);
      return reply.status(500).send({ 
        success: false, 
        message: error instanceof Error ? error.message : '服务器错误' 
      });
    }
  }
  
  // ... 其他方法
}

export const projectController = new ProjectController();

---

🔧 TSConfig 路径别名配置

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@config/*": ["src/config/*"],
      "@common/*": ["src/common/*"],
      "@legacy/*": ["src/legacy/*"],
      "@modules/*": ["src/modules/*"]
    }
  }
}

使用示例：

// 新模块中导入通用能力
import { LLMFactory } from '@common/llm/adapters/LLMFactory.js';
import { DifyClient } from '@common/rag/DifyClient.js';
import { config } from '@config/env.js';

// Legacy 模块保持原有导入不变
import { agentService } from '../services/agentService.js';

---

📋 实施步骤（零风险）

第 1 步：文件重组（5分钟）⭐

# 1. 创建 legacy 目录
mkdir backend/src/legacy

# 2. 移动现有代码到 legacy（保持相对路径不变）
mv backend/src/routes backend/src/legacy/
mv backend/src/controllers backend/src/legacy/
mv backend/src/services backend/src/legacy/
mv backend/src/templates backend/src/legacy/

# 3. 创建新架构目录
mkdir -p backend/src/modules/asl/{routes,controllers,services,types}

验证： 无需修改任何代码，只是移动目录位置

---

第 2 步：更新主入口（5分钟）

只修改 src/index.ts 的导入路径：

// 旧：from './routes/agents.js'
// 新：from './legacy/routes/agents.js'

验证： npm run dev 服务器正常启动

---

第 3 步：配置 TSConfig（2分钟）

添加路径别名配置。

验证： IDE 能识别 @legacy/*, @modules/* 等路径

---

第 4 步：开发 ASL 模块（新功能）

按新架构标准开发，完全不影响现有模块。

---

✅ 方案优势

1. 零风险改造

• ✅ 现有代码只移动目录，不修改内容
• ✅ 只改一个文件的导入路径
• ✅ 可随时回滚

2. 清晰的架构边界

legacy/  ← 旧代码，明确标识
modules/ ← 新代码，标准化

3. 新模块新架构

• ✅ ASL 直接按标准实施
• ✅ 成为未来模块的范本
• ✅ 不受旧代码约束

4. 平滑演进路径

现在：7个旧模块 + 0个新模块
未来：7个旧模块 + 1个新模块（ASL）
更远：7个旧模块 + N个新模块
最终：按需逐步迁移旧模块（可选）

---

🎯 演进时间轴

阶段	时间	工作内容	风险
今天	15分钟	重组目录+更新入口	极低
Week 3	-	开发 ASL 模块（新架构）	无（新功能）
Week 4+	-	继续开发新模块	无
未来	按需	逐步迁移旧模块（可选）	可控

---

📝 开发规范

Legacy 模块规范

• ⚠️ 不主动修改，除非修复bug
• ⚠️ 保持现有结构不变
• ⚠️ 可以引用 common/ 层的能力

新模块规范

• ✅ 必须按标准三层架构
• ✅ 必须使用路径别名
• ✅ 必须独立可部署
• ✅ 必须有完整的类型定义

---

🚀 下一步行动

1. 今天（15分钟）：执行第1-3步，完成目录重组
2. 明天：开始 ASL 模块开发（新架构）
3. Week 3：ASL 模块上线
4. 未来：新模块持续按标准开发

---

最后更新： 2025-11-14
维护者： 开发团队