# 前后端模块化架构设计 V2.0 > **版本：** V2.2 > **创建日期：** 2025-11-12 > **实施阶段：** Week 2（2025-11-13开始） > **维护者：** 开发团队 > **状态：** ✅ Week 2 Day 6-9 全部完成（前端架构+模块注册+后端分层）⭐⭐⭐ --- ## 📋 文档说明 本文档是**AI临床研究平台的模块化架构设计总纲**，定义了： 1. **前端架构**：全新的 frontend-v2 模块化架构 2. **后端架构**：基于Schema隔离的分层架构 3. **前后端对应关系**：模块化的组织方式 4. **开发规范**：统一的代码组织和命名规范 5. **实施路线**：渐进式的架构改造计划 **适用对象：** - 新加入的开发人员（快速了解系统架构） - AI助手（理解代码组织结构） - 技术决策者（架构演进参考） --- ## 🎯 架构演进历史 ### V1.0 阶段（2025-10之前） - ❌ 单体前端应用（所有功能耦合） - ❌ 后端代码平铺（无模块划分） - ❌ 数据库表全在public schema ### V1.5 阶段（2025-11-12完成） - ✅ **数据库Schema隔离**（10个Schema） - ✅ Prisma多Schema配置 - ✅ 数据100%迁移成功 - ⚠️ 前后端代码仍需模块化 ### V2.0 阶段（2025-11-13~14完成）⭐ - ✅ **前端模块化架构**（frontend-v2）- Day 6-7完成 - ✅ **模块注册机制**（权限控制+错误边界+路由守卫）- Day 7完成 - ✅ **后端增量演进架构**（legacy/common/modules）- Day 8-9完成 - ✅ 前后端模块对应 - ✅ 支持模块独立开发和部署 - ✅ **所有功能测试通过**（包括批处理修复）⭐⭐⭐ --- ## 📸 当前架构真实状态（2025-11-14） > **⭐ 重要提示：本章节描述当前实际运行的架构状态** > **适用对象：新开发人员、新AI助手、快速上手** > **更新频率：架构变更时立即更新** --- ### 🎯 架构概览 ``` 【当前状态】增量演进架构（新旧并存） Frontend-v2 (新) Backend (混合) Database (隔离) ↓ ↓ ↓ 顶部导航 + 6模块 legacy/ + common/ 10个独立 Schema 占位 + modules/asl (3详细 + 7空) ``` **核心策略：** - ✅ 前端：全新架构（frontend-v2） - ✅ 后端：新旧并存（legacy保持稳定，新模块标准化） - ✅ 数据库：Schema隔离完成 --- ### 📁 前端真实架构（Frontend-v2） #### **目录结构（实际存在）** ```bash frontend-v2/ ├── src/ │ ├── framework/ # 🏗️ 框架层（已实现） │ │ ├── layout/ │ │ │ ├── MainLayout.tsx # ✅ 主布局 │ │ │ ├── TopNavigation.tsx # ✅ 顶部导航 │ │ │ └── UserMenu.tsx # ✅ 用户菜单 │ │ │ │ │ ├── modules/ │ │ │ ├── moduleRegistry.ts # ✅ 模块注册中心 │ │ │ ├── ErrorBoundary.tsx # ✅ 错误边界 │ │ │ └── ModuleErrorFallback.tsx # ✅ 错误回退UI │ │ │ │ │ ├── router/ │ │ │ ├── RouteGuard.tsx # ✅ 路由守卫 │ │ │ └── PermissionDenied.tsx # ✅ 权限拒绝页 │ │ │ │ │ └── permission/ │ │ ├── PermissionContext.tsx # ✅ 权限上下文 │ │ ├── usePermission.ts # ✅ 权限Hook │ │ └── types.ts # ✅ 权限类型 │ │ │ ├── modules/ # 📦 业务模块（占位） │ │ ├── asl/ # 🚧 Week 3开发 │ │ │ └── index.tsx # ✅ 占位页面 │ │ ├── aia/ # 📋 占位 │ │ ├── pkb/ # 📋 占位 │ │ ├── dc/ # 📋 占位 │ │ ├── ssa/ # 📋 占位 │ │ └── st/ # 📋 占位 │ │ │ ├── pages/ │ │ └── Home.tsx # ✅ 首页 │ │ │ └── App.tsx # ✅ 应用入口 │ ├── package.json # ✅ React 19 └── vite.config.ts # ✅ Vite配置 ``` **当前运行状态：** - ✅ 访问地址：http://localhost:3000 - ✅ 顶部导航显示6个模块 - ✅ 权限控制工作正常（mock premium用户） - ✅ 路由守卫生效 - ✅ 错误边界正常捕获 --- ### 🗄️ 后端真实架构（Backend） #### **目录结构（实际存在）⭐ 关键** ```bash backend/ ├── src/ │ ├── legacy/ # 🔸 现有业务代码（稳定运行） │ │ ├── routes/ # 7个路由文件 │ │ │ ├── agents.ts # AIA: 智能体路由 │ │ │ ├── conversations.ts # AIA: 对话路由 │ │ │ ├── chatRoutes.ts # AIA: 通用对话路由 │ │ │ ├── projects.ts # AIA: 项目路由 │ │ │ ├── knowledgeBases.ts # PKB: 知识库路由 │ │ │ ├── batchRoutes.ts # PKB: 批处理路由 │ │ │ └── reviewRoutes.ts # RVW: 稿件审查路由 │ │ │ │ │ ├── controllers/ # 8个控制器 │ │ │ ├── agentController.ts │ │ │ ├── conversationController.ts │ │ │ ├── chatController.ts │ │ │ ├── projectController.ts │ │ │ ├── knowledgeBaseController.ts │ │ │ ├── documentController.ts │ │ │ ├── batchController.ts │ │ │ └── reviewController.ts │ │ │ │ │ ├── services/ # 8个服务 │ │ │ ├── agentService.ts │ │ │ ├── conversationService.ts │ │ │ ├── projectService.ts │ │ │ ├── knowledgeBaseService.ts │ │ │ ├── documentService.ts │ │ │ ├── batchService.ts │ │ │ ├── reviewService.ts │ │ │ └── tokenService.ts │ │ │ │ │ └── templates/ │ │ └── clinicalResearch.ts # 批处理模板 │ │ │ ├── common/ # 🔧 通用能力层（共享） │ │ ├── llm/ │ │ │ └── adapters/ # LLM适配器 │ │ │ ├── DeepSeekAdapter.ts # ✅ DeepSeek-V3 │ │ │ ├── QwenAdapter.ts # ✅ Qwen3-72B + Qwen-Long │ │ │ ├── LLMFactory.ts # ✅ 工厂类 │ │ │ └── types.ts # ✅ LLM类型定义 │ │ │ │ │ ├── rag/ # RAG能力 │ │ │ ├── DifyClient.ts # ✅ Dify客户端 │ │ │ └── types.ts # ✅ RAG类型 │ │ │ │ │ ├── document/ # 文档处理 │ │ │ └── ExtractionClient.ts # ✅ 文档提取客户端 │ │ │ │ │ ├── middleware/ │ │ │ └── validateProject.ts # ✅ 项目验证中间件 │ │ │ │ │ └── utils/ │ │ └── jsonParser.ts # ✅ JSON解析工具 │ │ │ ├── modules/ # 🌟 新架构模块（标准化） │ │ └── asl/ # ⭐ AI智能文献（占位，Week 3开发） │ │ └── (空目录，等待开发) │ │ │ ├── config/ # ⚙️ 配置层 │ │ ├── database.ts # ✅ 数据库配置 │ │ └── env.ts # ✅ 环境变量 │ │ │ ├── scripts/ # 🛠️ 工具脚本 │ │ ├── create-mock-user.ts │ │ └── test-dify-client.ts │ │ │ └── index.ts # ✅ 主入口（统一注册） │ ├── config/ # 外部配置文件 │ └── agents.yaml # ✅ 智能体配置（348行） │ ├── prompts/ # Prompt模板 │ ├── topic_evaluation_system.txt │ ├── review_editorial_system.txt │ └── review_methodology_system.txt │ ├── prisma/ │ ├── schema.prisma # ✅ 10个Schema定义 │ └── migrations/ # ✅ 4个迁移文件 │ ├── package.json # ✅ Fastify + Prisma └── .env # ✅ 环境变量 ``` **当前运行状态：** - ✅ 访问地址：http://localhost:3001 - ✅ 健康检查：http://localhost:3001/health - ✅ Legacy模块（AIA/PKB/RVW）正常运行 - ✅ Common层通用能力可用 - ✅ Modules/asl 占位就绪 **主入口（index.ts）实际代码：** ```typescript // ============================================ // 【旧架构】Legacy 模块 - 保持不变 // ============================================ import { projectRoutes } from './legacy/routes/projects.js'; import { agentRoutes } from './legacy/routes/agents.js'; import { conversationRoutes } from './legacy/routes/conversations.js'; import knowledgeBaseRoutes from './legacy/routes/knowledgeBases.js'; import { chatRoutes } from './legacy/routes/chatRoutes.js'; import { batchRoutes } from './legacy/routes/batchRoutes.js'; import reviewRoutes from './legacy/routes/reviewRoutes.js'; // 注册 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' }); ``` --- ### 🗃️ 数据库真实架构（PostgreSQL 15） #### **Schema 结构（实际存在）** ```sql -- ==================== 平台层 Schema ==================== platform_schema (平台基础表) └── users # ✅ 用户表（已实现） -- ==================== 详细 Schema（数据已迁移）==================== aia_schema (AI智能问答) ├── projects # ✅ 项目表 ├── agents # ✅ 智能体配置表 ├── conversations # ✅ 对话表 └── messages # ✅ 消息表 pkb_schema (个人知识库) ├── knowledge_bases # ✅ 知识库表 ├── documents # ✅ 文档表 ├── batch_tasks # ✅ 批处理任务表 ├── batch_results # ✅ 批处理结果表 └── task_templates # ✅ 任务模板表 rvw_schema (稿件审查) ├── review_tasks # ✅ 审查任务表 └── (在public schema中) # ⚠️ 历史原因 -- ==================== 占位 Schema（数据结构未定义）==================== asl_schema (AI智能文献) # 🚧 Week 3开发 └── (空，等待定义) common_schema (通用工具) # 📋 占位 dc_schema (数据采集) # 📋 占位 ssa_schema (统计分析) # 📋 占位 st_schema (研究工具) # 📋 占位 admin_schema (运营管理) # 📋 占位 ``` **Prisma Schema 配置：** ```prisma datasource db { provider = "postgresql" url = env("DATABASE_URL") schemas = [ "platform_schema", # ✅ 平台 "aia_schema", # ✅ 智能问答 "pkb_schema", # ✅ 知识库 "asl_schema", # 🚧 智能文献（Week 3） "common_schema", # 📋 占位 "dc_schema", # 📋 占位 "rvw_schema", # 📋 占位 "admin_schema", # 📋 占位 "ssa_schema", # 📋 占位 "st_schema", # 📋 占位 "public" # ✅ 历史遗留 ] } ``` --- ### 🔌 API 真实路由（当前可用） #### **AIA 模块（AI智能问答）** ``` 基础路径：/api/v1/aia 项目管理： ✅ GET /projects # 获取项目列表 ✅ POST /projects # 创建项目 ✅ GET /projects/:id # 获取项目详情 ✅ PUT /projects/:id # 更新项目 ✅ DELETE /projects/:id # 删除项目 智能体管理： ✅ GET /agents # 获取智能体列表 ✅ GET /agents/enabled # 获取启用的智能体 ✅ GET /agents/:id # 获取智能体详情 对话管理： ✅ POST /conversations # 创建对话 ✅ GET /conversations # 获取对话列表 ✅ GET /conversations/:id # 获取对话详情 ✅ POST /conversations/:id/messages/stream # 流式发送消息 ✅ POST /conversations/:id/messages # 非流式发送消息 ✅ DELETE /conversations/:id # 删除对话 通用对话： ✅ POST /chat/stream # 通用流式对话 ✅ POST /chat # 通用非流式对话 ``` #### **PKB 模块（个人知识库）** ``` 基础路径：/api/v1/pkb 知识库管理： ✅ GET /knowledge-bases # 获取知识库列表 ✅ POST /knowledge-bases # 创建知识库 ✅ GET /knowledge-bases/:id # 获取知识库详情 ✅ PUT /knowledge-bases/:id # 更新知识库 ✅ DELETE /knowledge-bases/:id # 删除知识库 文档管理： ✅ POST /knowledge-bases/:id/documents # 上传文档 ✅ GET /knowledge-bases/:id/documents # 获取文档列表 ✅ DELETE /knowledge-bases/:kbId/documents/:docId # 删除文档 批处理： ✅ POST /batch/execute # 执行批处理任务 ✅ GET /batch/tasks/:taskId # 获取任务状态 ✅ GET /batch/tasks/:taskId/results # 获取任务结果 ✅ POST /batch/tasks/:taskId/retry-failed # 重试失败项 ``` #### **RVW 模块（稿件审查）** ``` 基础路径：/api/v1/rvw 稿件审查： ✅ POST /review/upload # 上传稿件并开始审查 ✅ GET /review/tasks/:taskId # 查询任务状态 ✅ GET /review/tasks/:taskId/report # 获取完整报告 ✅ GET /review/tasks # 获取任务列表 ✅ DELETE /review/tasks/:taskId # 删除任务 ``` #### **系统端点** ``` ✅ GET /health # 健康检查 ✅ GET /api/v1 # API信息 ``` --- ### 📊 技术栈真实配置 #### **前端（Frontend-v2）** ```json { "react": "^19.0.0", "react-dom": "^19.0.0", "react-router-dom": "^6.x", "typescript": "^5.x", "vite": "^6.x", "antd": "^5.x", "tailwindcss": "^3.x" } ``` #### **后端（Backend）** ```json { "fastify": "^4.x", "typescript": "^5.x", "prisma": "^6.17.0", "@prisma/client": "^6.17.0", "tsx": "^4.x", "axios": "^1.x", "js-yaml": "^4.x", "p-queue": "^8.x" } ``` #### **数据库** ``` PostgreSQL: 15.x Schema数量: 10个（3详细 + 7占位） 迁移文件: 4个 ``` #### **LLM 集成（CloseAI）** ``` ✅ DeepSeek-V3 (主力，性价比) ✅ Qwen3-72B (备用，中文理解) ✅ Qwen-Long (超长上下文1M) ✅ GPT-4o (可选，高质量) ``` --- ### 🔄 前后端模块对应关系（当前） | 前端模块 | 后端位置 | 数据库Schema | API路由 | 状态 | |---------|---------|-------------|---------|------| | frontend-v2/modules/asl/ | backend/modules/asl/ | asl_schema | /api/v1/asl/* | 🚧 Week 3开发 | | frontend-v2/modules/aia/ | backend/legacy/routes/agents.ts等 | aia_schema | /api/v1/aia/* | ✅ 运行中 | | frontend-v2/modules/pkb/ | backend/legacy/routes/knowledgeBases.ts等 | pkb_schema | /api/v1/pkb/* | ✅ 运行中 | | frontend-v2/modules/rvw/ | backend/legacy/routes/reviewRoutes.ts | public + rvw_schema | /api/v1/rvw/* | ✅ 运行中 | | frontend-v2/modules/dc/ | (未实现) | dc_schema | /api/v1/dc/* | 📋 占位 | | frontend-v2/modules/ssa/ | (未实现) | ssa_schema | /api/v1/ssa/* | 📋 占位 | | frontend-v2/modules/st/ | (未实现) | st_schema | /api/v1/st/* | 📋 占位 | --- ### 📋 功能测试清单（已验证） | 功能 | 测试项 | 状态 | 备注 | |------|--------|------|------| | 智能问答 | 创建项目 | ✅ | | | 智能问答 | 对话模式 | ✅ | 流式+非流式 | | 智能问答 | 知识库模式 | ✅ | RAG检索 | | 智能问答 | 批处理模式 | ✅ | 修复rawOutput问题后正常 | | 知识库 | 创建知识库 | ✅ | | | 知识库 | 上传文档 | ✅ | PDF/Word/TXT/MD | | 知识库 | 文档管理 | ✅ | 列表/删除 | | 稿件审查 | 上传稿件 | ✅ | | | 稿件审查 | 审查报告 | ✅ | | | 前端 | 顶部导航 | ✅ | 6个模块 | | 前端 | 权限控制 | ✅ | mock premium | | 前端 | 路由守卫 | ✅ | | | 前端 | 错误边界 | ✅ | | --- ### 🎯 新模块开发指南（以ASL为例） #### **开发流程（Week 3）：** ``` 第1步：数据库设计 ├─ 设计 asl_schema 表结构 ├─ 在 Prisma schema 中定义模型 └─ 运行迁移创建表 第2步：后端开发 ├─ 在 backend/src/modules/asl/ 下开发 ├─ 创建 routes/（路由） ├─ 创建 controllers/（控制器） ├─ 创建 services/（服务） └─ 注册路由到 index.ts 第3步：前端开发 ├─ 在 frontend-v2/src/modules/asl/ 下开发 ├─ 创建 pages/（页面） ├─ 创建 components/（组件） ├─ 创建 api/（API调用） └─ 更新 index.tsx（模块注册） 第4步：联调测试 ├─ 前后端联调 └─ 功能验收 ``` --- ### 📚 相关文档索引 **快速上手：** - ⭐ **本文档** - 架构总纲 + 当前状态 - ⭐ `docs/09-架构实施/后端架构增量演进方案.md` - 后端详细说明（450行） **任务记录：** - `docs/08-项目管理/下一阶段行动计划-V2.2-完整版.md` - 项目计划 - `docs/09-架构实施/前端模块注册机制实施报告.md` - 前端任务17 - `docs/08-项目管理/2025-11-14-任务19完成总结.md` - 后端任务19 **技术规范：** - `docs/09-架构实施/编码规范-UTF8最佳实践.md` - 编码规范 - `.editorconfig` - 编辑器配置 - `.gitattributes` - Git配置 --- **本章节更新日期：** 2025-11-14 **下次更新时机：** ASL模块开发完成后 --- ## 🏗️ 整体架构设计 ### 系统架构图 ``` ┌─────────────────────────────────────────────────────────────────┐ │ AI临床研究平台 │ └─────────────────────────────────────────────────────────────────┘ │ ┌─────────────────────┴─────────────────────┐ │ │ ┌────▼─────┐ ┌─────▼────┐ │ 前端层 │ │ 后端层 │ │frontend-v2│◄────────── HTTP API ────────►│ backend │ └──────────┘ └──────────┘ │ │ │ 模块化 │ 模块化 + Schema隔离 │ │ ┌────┴────────────────────────┐ ┌───────┴──────────────────┐ │ │ │ │ │ ┌─────┐ ┌─────┐ ┌─────┐ │ │ ┌─────────────────────┐ │ │ │ ASL │ │ AIA │ │ PKB │ │ │ │ PostgreSQL │ │ │ │模块 │ │模块 │ │模块 │ │ │ │ ┌─────────────────┐│ │ │ └─────┘ └─────┘ └─────┘ │ │ │ │ platform_schema ││ │ │ ┌─────┐ ┌─────┐ │ │ │ │ aia_schema ││ │ │ │ RVW │ │ DC │ ... │ │ │ │ pkb_schema ││ │ │ │模块 │ │模块 │ │ │ │ │ asl_schema ││ │ │ └─────┘ └─────┘ │ │ │ │ ... ││ │ │ │ │ │ └─────────────────┘│ │ └─────────────────────────────┘ │ └─────────────────────┘ │ └──────────────────────────┘ ``` --- ## 📁 前端架构设计（frontend-v2） ### 设计原则 1. **彻底的模块化** - 每个业务模块完全独立 2. **框架与业务分离** - 框架层提供基础能力，业务模块专注功能 3. **渐进式开发** - 新架构与旧代码并存，逐步替换 4. **独立部署支持** - 模块可独立打包和部署 ### 目录结构 ``` frontend-v2/ ├── src/ │ ├── framework/ # 🏗️ 框架层（平台级基础设施） │ │ │ │ │ ├── layout/ # 布局系统 │ │ │ ├── MainLayout.tsx # 主布局（顶部导航+内容区） │ │ │ ├── TopNavigation.tsx # 顶部导航栏 │ │ │ ├── UserMenu.tsx # 用户菜单 │ │ │ └── ModuleContainer.tsx # 模块容器 │ │ │ │ │ ├── modules/ # 模块管理系统 │ │ │ ├── moduleRegistry.ts # 模块注册中心 │ │ │ ├── ModuleLoader.tsx # 动态模块加载器 │ │ │ ├── types.ts # 模块接口定义 │ │ │ └── config.ts # 模块配置 │ │ │ │ │ ├── router/ # 路由系统 │ │ │ ├── AppRouter.tsx # 应用路由配置 │ │ │ ├── RouteGuard.tsx # 路由守卫 │ │ │ └── routes.ts # 路由定义 │ │ │ │ │ ├── permission/ # 权限控制（预留） │ │ │ ├── PermissionProvider.tsx # 权限上下文 │ │ │ ├── usePermission.ts # 权限Hook │ │ │ └── config.ts # 权限配置 │ │ │ │ │ └── config/ # 全局配置 │ │ ├── env.ts # 环境变量 │ │ ├── api.ts # API配置 │ │ └── theme.ts # 主题配置 │ │ │ ├── modules/ # 📦 业务模块（完全独立） │ │ │ │ │ ├── asl/ # ⭐ AI智能文献模块（优先开发） │ │ │ ├── index.tsx # 模块入口（导出ModuleDefinition） │ │ │ ├── routes.tsx # 模块路由配置 │ │ │ │ │ │ │ ├── layouts/ # 模块布局 │ │ │ │ └── ASLLayout.tsx # ASL左侧导航布局 │ │ │ │ │ │ │ ├── pages/ # 模块页面 │ │ │ │ ├── ProjectList.tsx # 项目列表 │ │ │ │ ├── ProjectCreate.tsx # 创建项目 │ │ │ │ ├── TitleScreening/ # 标题摘要初筛 │ │ │ │ │ ├── index.tsx │ │ │ │ │ ├── ScreeningWorkbench.tsx │ │ │ │ │ └── ResultsView.tsx │ │ │ │ ├── FullTextScreening/ # 全文复筛 │ │ │ │ │ └── ... │ │ │ │ ├── DataExtraction/ # 数据提取 │ │ │ │ │ └── ... │ │ │ │ └── Analysis/ # 综合分析 │ │ │ │ └── ... │ │ │ │ │ │ │ ├── components/ # 模块组件（仅本模块使用） │ │ │ │ ├── LiteratureCard.tsx │ │ │ │ ├── ScreeningPanel.tsx │ │ │ │ ├── LLMSelector.tsx │ │ │ │ └── ... │ │ │ │ │ │ │ ├── api/ # 模块API（对接后端） │ │ │ │ ├── projectApi.ts │ │ │ │ ├── screeningApi.ts │ │ │ │ ├── extractionApi.ts │ │ │ │ └── index.ts │ │ │ │ │ │ │ ├── hooks/ # 模块Hooks │ │ │ │ ├── useProject.ts │ │ │ │ ├── useScreening.ts │ │ │ │ └── useLLMScreening.ts │ │ │ │ │ │ │ ├── store/ # 模块状态管理 │ │ │ │ ├── projectStore.ts │ │ │ │ ├── screeningStore.ts │ │ │ │ └── index.ts │ │ │ │ │ │ │ ├── types/ # 模块类型定义 │ │ │ │ ├── project.ts │ │ │ │ ├── literature.ts │ │ │ │ └── index.ts │ │ │ │ │ │ │ └── utils/ # 模块工具函数 │ │ │ ├── fileParser.ts │ │ │ └── exportHelper.ts │ │ │ │ │ ├── aia/ # 📋 AI智能问答模块（后续重写） │ │ │ ├── index.tsx │ │ │ └── Placeholder.tsx # 临时占位页面 │ │ │ │ │ ├── pkb/ # 📋 个人知识库模块（后续重写） │ │ │ ├── index.tsx │ │ │ └── Placeholder.tsx │ │ │ │ │ ├── rvw/ # 📋 审稿系统模块（后续重写） │ │ │ ├── index.tsx │ │ │ └── Placeholder.tsx │ │ │ │ │ └── dc/ # 📋 数据清洗模块（占位） │ │ ├── index.tsx │ │ └── Placeholder.tsx │ │ │ ├── shared/ # 🔧 共享资源（跨模块使用） │ │ ├── components/ # 通用UI组件 │ │ │ ├── Button/ │ │ │ ├── Table/ │ │ │ ├── Modal/ │ │ │ └── ... │ │ │ │ │ ├── hooks/ # 通用Hooks │ │ │ ├── useDebounce.ts │ │ │ ├── useAsync.ts │ │ │ └── ... │ │ │ │ │ ├── utils/ # 工具函数 │ │ │ ├── date.ts │ │ │ ├── format.ts │ │ │ ├── validation.ts │ │ │ └── ... │ │ │ │ │ └── api/ # API客户端 │ │ ├── client.ts # Axios实例 │ │ ├── request.ts # 请求拦截器 │ │ └── types.ts # API类型 │ │ │ ├── App.tsx # 应用根组件 │ ├── main.tsx # 应用入口 │ └── vite-env.d.ts │ ├── public/ # 静态资源 ├── package.json ├── vite.config.ts # Vite配置 ├── tsconfig.json # TypeScript配置 ├── tailwind.config.js # Tailwind配置 └── README.md ``` ### 模块定义接口 ```typescript // framework/modules/types.ts /** * 模块定义接口 * 每个业务模块必须实现这个接口 */ export interface ModuleDefinition { /** 模块唯一标识 */ id: string /** 模块名称（显示在导航栏） */ name: string /** 模块路由前缀 */ path: string /** 模块图标（可选） */ icon?: ReactNode /** 模块入口组件（懒加载） */ component: LazyExoticComponent> /** 模块路由配置 */ routes?: RouteObject[] /** 模块是否有左侧导航 */ hasSideNav?: boolean /** 左侧导航配置（如果有） */ sideNavConfig?: SideNavItem[] /** 权限要求（可选） */ requiredVersion?: UserVersion /** 是否为占位模块 */ placeholder?: boolean /** 是否支持独立部署 */ standalone?: boolean } /** * 左侧导航项 */ export interface SideNavItem { id: string label: string path: string icon?: ReactNode children?: SideNavItem[] } ``` ### 模块注册示例 ```typescript // modules/asl/index.tsx import { lazy } from 'react' import { ModuleDefinition } from '@/framework/modules/types' import routes from './routes' import { sideNavConfig } from './config' const ASLModule: ModuleDefinition = { id: 'asl', name: 'AI智能文献', path: '/literature', icon: , component: lazy(() => import('./layouts/ASLLayout')), routes, hasSideNav: true, sideNavConfig, requiredVersion: 'advanced', } export default ASLModule ``` ### 模块路由示例 ```typescript // modules/asl/routes.tsx import { lazy } from 'react' import { RouteObject } from 'react-router-dom' const routes: RouteObject[] = [ { path: '', element: lazy(() => import('./pages/ProjectList')), }, { path: 'project/:projectId', children: [ { path: 'title-screening', element: lazy(() => import('./pages/TitleScreening')), }, { path: 'fulltext-screening', element: lazy(() => import('./pages/FullTextScreening')), }, { path: 'extraction', element: lazy(() => import('./pages/DataExtraction')), }, { path: 'analysis', element: lazy(() => import('./pages/Analysis')), }, ], }, ] export default routes ``` --- ## 📁 后端架构设计（backend） ### 设计原则 1. **Schema隔离** - 数据库层面的模块隔离（已完成） 2. **代码分层** - platform/common/modules三层架构 3. **模块独立** - 每个模块的API和逻辑独立 4. **保持兼容** - 轻度重构，不破坏现有功能 ### 目录结构 ``` backend/ ├── src/ │ ├── platform/ # 🏛️ 平台层（基础设施） │ │ ├── auth/ # 认证授权 │ │ │ ├── authController.ts │ │ │ ├── authService.ts │ │ │ ├── authMiddleware.ts │ │ │ └── routes.ts │ │ │ │ │ └── users/ # 用户管理 │ │ ├── userController.ts │ │ ├── userService.ts │ │ └── routes.ts │ │ │ ├── common/ # 🔧 通用层（共享能力） │ │ ├── middleware/ # 中间件 │ │ │ ├── errorHandler.ts │ │ │ ├── logger.ts │ │ │ ├── validation.ts │ │ │ └── cors.ts │ │ │ │ │ ├── utils/ # 工具函数 │ │ │ ├── date.ts │ │ │ ├── encryption.ts │ │ │ └── format.ts │ │ │ │ │ ├── errors/ # 错误处理 │ │ │ ├── AppError.ts │ │ │ ├── errorTypes.ts │ │ │ └── errorHandler.ts │ │ │ │ │ └── types/ # 通用类型 │ │ ├── request.ts │ │ ├── response.ts │ │ └── common.ts │ │ │ ├── modules/ # 📦 业务模块 │ │ │ │ │ ├── aia/ # AI智能问答模块 │ │ │ ├── controllers/ # 控制器 │ │ │ │ ├── projectController.ts │ │ │ │ ├── agentController.ts │ │ │ │ ├── conversationController.ts │ │ │ │ └── chatController.ts │ │ │ │ │ │ │ ├── services/ # 业务逻辑 │ │ │ │ ├── projectService.ts │ │ │ │ ├── conversationService.ts │ │ │ │ └── llmService.ts │ │ │ │ │ │ │ ├── routes/ # 路由配置 │ │ │ │ └── index.ts │ │ │ │ │ │ │ ├── types/ # 模块类型 │ │ │ │ ├── project.ts │ │ │ │ └── conversation.ts │ │ │ │ │ │ │ └── utils/ # 模块工具 │ │ │ └── prompt.ts │ │ │ │ │ ├── pkb/ # 个人知识库模块 │ │ │ ├── controllers/ │ │ │ │ ├── knowledgeBaseController.ts │ │ │ │ ├── documentController.ts │ │ │ │ └── batchController.ts │ │ │ │ │ │ │ ├── services/ │ │ │ │ ├── kbService.ts │ │ │ │ ├── documentService.ts │ │ │ │ ├── batchService.ts │ │ │ │ └── difyService.ts │ │ │ │ │ │ │ ├── routes/ │ │ │ │ └── index.ts │ │ │ │ │ │ │ └── types/ │ │ │ ├── knowledgeBase.ts │ │ │ └── document.ts │ │ │ │ │ ├── rvw/ # 审稿系统模块 │ │ │ ├── controllers/ │ │ │ │ └── reviewController.ts │ │ │ │ │ │ │ ├── services/ │ │ │ │ ├── reviewService.ts │ │ │ │ └── extractionService.ts │ │ │ │ │ │ │ ├── routes/ │ │ │ │ └── index.ts │ │ │ │ │ │ │ └── types/ │ │ │ └── review.ts │ │ │ │ │ └── asl/ # ⭐ AI智能文献模块（Week 3新建） │ │ ├── controllers/ │ │ │ ├── projectController.ts │ │ │ ├── literatureController.ts │ │ │ ├── screeningController.ts │ │ │ └── extractionController.ts │ │ │ │ │ ├── services/ │ │ │ ├── projectService.ts │ │ │ ├── literatureService.ts │ │ │ ├── screeningService.ts │ │ │ ├── llmScreeningService.ts │ │ │ └── extractionService.ts │ │ │ │ │ ├── routes/ │ │ │ └── index.ts │ │ │ │ │ ├── types/ │ │ │ ├── project.ts │ │ │ ├── literature.ts │ │ │ └── screening.ts │ │ │ │ │ └── utils/ │ │ ├── fileParser.ts │ │ ├── llmPrompts.ts │ │ └── exportHelper.ts │ │ │ ├── config/ # 配置文件（现有） │ │ ├── database.ts │ │ ├── env.ts │ │ └── ... │ │ │ └── index.ts # 应用入口 │ ├── prisma/ │ └── schema.prisma # Prisma Schema（已配置10个Schema） │ ├── package.json └── tsconfig.json ``` ### 模块路由注册 ```typescript // src/index.ts import { platformRoutes } from './platform/routes' import { aiaRoutes } from './modules/aia/routes' import { pkbRoutes } from './modules/pkb/routes' import { rvwRoutes } from './modules/rvw/routes' import { aslRoutes } from './modules/asl/routes' // 注册平台路由 fastify.register(platformRoutes, { prefix: '/api/v1/platform' }) // 注册业务模块路由 fastify.register(aiaRoutes, { prefix: '/api/v1/aia' }) fastify.register(pkbRoutes, { prefix: '/api/v1/pkb' }) fastify.register(rvwRoutes, { prefix: '/api/v1/rvw' }) fastify.register(aslRoutes, { prefix: '/api/v1/asl' }) ``` --- ## 🔗 前后端对应关系 ### 模块映射表 | 前端模块 | 后端模块 | 数据库Schema | 路由前缀 | 开发状态 | |---------|---------|-------------|---------|---------| | `frontend-v2/src/modules/asl/` | `backend/src/modules/asl/` | `asl_schema` | `/api/v1/asl/*` | 🚧 Week 3开发 | | `frontend-v2/src/modules/aia/` | `backend/src/modules/aia/` | `aia_schema` | `/api/v1/aia/*` | 📋 后续重写 | | `frontend-v2/src/modules/pkb/` | `backend/src/modules/pkb/` | `pkb_schema` | `/api/v1/pkb/*` | 📋 后续重写 | | `frontend-v2/src/modules/rvw/` | `backend/src/modules/rvw/` | `public.review_tasks` | `/api/v1/rvw/*` | 📋 后续重写 | | `frontend-v2/src/modules/dc/` | `backend/src/modules/dc/` | `dc_schema` | `/api/v1/dc/*` | 📋 占位 | ### API调用示例 ```typescript // 前端：frontend-v2/src/modules/asl/api/projectApi.ts import { apiClient } from '@/shared/api/client' export const aslProjectApi = { // 创建项目 create: (data: CreateProjectDTO) => apiClient.post('/api/v1/asl/projects', data), // 获取项目列表 list: () => apiClient.get('/api/v1/asl/projects'), // 获取项目详情 getById: (id: string) => apiClient.get(`/api/v1/asl/projects/${id}`), } // 后端：backend/src/modules/asl/routes/index.ts import { FastifyInstance } from 'fastify' import { aslProjectController } from '../controllers/projectController' export async function aslRoutes(fastify: FastifyInstance) { fastify.post('/projects', aslProjectController.create) fastify.get('/projects', aslProjectController.list) fastify.get('/projects/:id', aslProjectController.getById) } ``` --- ## 📐 开发规范 ### 命名规范 #### 前端 **文件命名：** - 组件：PascalCase（`ProjectList.tsx`） - Hooks：camelCase + use前缀（`useProject.ts`） - 工具函数：camelCase（`formatDate.ts`） - 类型定义：PascalCase（`Project.ts`） **代码命名：** - 组件：PascalCase（`ProjectList`） - 函数：camelCase（`fetchProjects`） - 常量：UPPER_SNAKE_CASE（`API_BASE_URL`） - 接口：PascalCase + I前缀（`IProject`） - 类型：PascalCase（`Project`） #### 后端 **文件命名：** - Controller：camelCase + Controller后缀（`projectController.ts`） - Service：camelCase + Service后缀（`projectService.ts`） - Routes：`index.ts` 或 `routes.ts` - Types：camelCase（`project.ts`） **代码命名：** - 类：PascalCase（`ProjectService`） - 函数：camelCase（`createProject`） - 常量：UPPER_SNAKE_CASE（`MAX_FILE_SIZE`） - 接口：PascalCase（`ProjectDTO`） ### 模块开发规范 #### 1. 新模块开发流程 ``` 第一步：数据库设计 ├─ 在 docs/03-业务模块/[模块名]/02-技术设计/01-数据库设计.md ├─ 设计表结构 ├─ 在 Prisma schema 中定义模型 └─ 运行迁移 第二步：后端开发 ├─ 创建 backend/src/modules/[模块名]/ ├─ 编写 controllers/ ├─ 编写 services/ ├─ 编写 routes/ └─ 测试 API 第三步：前端开发 ├─ 创建 frontend-v2/src/modules/[模块名]/ ├─ 定义模块接口（index.tsx） ├─ 编写 pages/ ├─ 编写 components/ ├─ 编写 api/ ├─ 编写 hooks/ └─ 测试功能 第四步：集成测试 ├─ 端到端测试 └─ 性能测试 ``` #### 2. 模块独立性原则 **DO ✅：** - 模块内的组件只在模块内使用 - 模块有自己的状态管理 - 模块有自己的API调用 - 模块有自己的类型定义 - 模块可以独立运行和部署 **DON'T ❌：** - 不要在模块间直接import组件 - 不要在模块间共享状态 - 不要在模块间直接调用API - 共享的逻辑放在 `shared/` 目录 #### 3. API设计规范 **RESTful风格：** ``` GET /api/v1/[module]/resources # 列表 GET /api/v1/[module]/resources/:id # 详情 POST /api/v1/[module]/resources # 创建 PUT /api/v1/[module]/resources/:id # 更新 DELETE /api/v1/[module]/resources/:id # 删除 ``` **响应格式：** ```typescript // 成功响应 { success: true, data: any, message?: string } // 错误响应 { success: false, error: { code: string, message: string, details?: any } } ``` --- ## 🚀 实施计划 ### Week 2：架构改造（2025-11-13 至 2025-11-17） #### Day 6（11-13）：前端架构基础 ⏰ 4-6小时 **上午：项目创建和框架层** - [x] 创建 frontend-v2 项目（Vite + React + TS） - [x] 安装依赖（Antd、Router、Zustand、React Query） - [x] 配置 Tailwind CSS - [x] 创建目录结构（framework/modules/shared） - [x] 实现 TopNavigation.tsx - [x] 实现 MainLayout.tsx - [x] 定义模块接口（ModuleDefinition） **下午：模块占位** - [x] 为5个模块创建目录 - [x] 创建 Placeholder.tsx 组件 - [x] 配置基本路由 - [x] 测试导航切换 **交付物：** - ✅ 可运行的 frontend-v2 项目 - ✅ 顶部导航正常工作 - ✅ 5个模块占位页面 #### Day 7（11-14）：模块注册机制 ⏰ 6-8小时 **上午：注册系统** - [ ] 实现 moduleRegistry.ts - [ ] 实现 ModuleLoader.tsx - [ ] 实现动态路由加载 - [ ] 实现懒加载机制 **下午：测试和文档** - [ ] 测试模块注册 - [ ] 测试路由切换 - [ ] 编写开发文档 - [ ] 更新 README **交付物：** - ✅ 完整的模块注册系统 - ✅ 动态路由加载 - ✅ 开发文档 #### Day 8-9（11-15 至 11-16）：后端代码分层 ⏰ 1-2天 **Day 8 上午：创建目录结构** - [ ] 创建 platform/ 目录 - [ ] 创建 common/ 目录 - [ ] 创建 modules/ 目录 **Day 8 下午：迁移 AIA 模块** - [ ] 创建 modules/aia/ 结构 - [ ] 迁移 projectController.ts - [ ] 迁移 conversationController.ts - [ ] 更新路由注册 **Day 9 上午：迁移 PKB 和 RVW** - [ ] 迁移 PKB 模块代码 - [ ] 迁移 RVW 模块代码 - [ ] 更新所有 import 路径 **Day 9 下午：测试和文档** - [ ] 测试所有 API - [ ] 更新 API 文档 - [ ] 编写迁移说明 **交付物：** - ✅ 完成后端代码分层 - ✅ 所有API正常工作 - ✅ 更新文档 #### Day 10（11-17）：Week 2 验收 ⏰ 4小时 - [ ] 前端架构验收 - [ ] 后端分层验收 - [ ] 集成测试 - [ ] 编写 Week 2 总结报告 - [ ] 规划 Week 3 ASL 任务 --- ### Week 3-4：ASL模块开发（在新架构下） **在全新的 frontend-v2 和分层后的 backend 中开发 ASL 模块** 详见：[下一阶段行动计划-V2.2-完整版.md](../08-项目管理/下一阶段行动计划-V2.2-完整版.md) --- ## 📝 旧代码处理 ### frontend/ 目录 **状态：** ⏸️ 保留，不再开发 **处理方式：** 1. 添加 `README-ARCHIVED.md` 说明文件 2. 在根目录 `package.json` 中区分启动命令 3. 保留3-6个月，作为参考和应急备份 4. 新架构稳定后再删除 **参考价值：** - UI交互设计 - 某些组件实现 - API调用逻辑 - 业务流程 ### 启动命令 ```json { "scripts": { "dev:frontend-old": "cd frontend && npm run dev", "dev:frontend-new": "cd frontend-v2 && npm run dev", "dev:frontend": "npm run dev:frontend-new", "dev:backend": "cd backend && npm run dev", "dev": "concurrently \"npm run dev:backend\" \"npm run dev:frontend\"" } } ``` --- ## 🎯 成功标准 ### Week 2 验收标准 **前端：** - [x] frontend-v2 项目可运行 - [x] 顶部导航正常工作 - [x] 模块注册系统完整 - [x] 5个模块占位页面 - [x] 路由切换正常 - [x] 完整的开发文档 **后端：** - [ ] 代码分层完成（platform/common/modules） - [ ] 所有现有API正常工作 - [ ] 路由前缀统一（/api/v1/[module]/*） - [ ] import路径全部更新 - [ ] API文档更新 **文档：** - [x] 本架构设计文档 - [ ] 前端开发规范文档 - [ ] 后端开发规范文档 - [ ] Week 2总结报告 --- ## 📚 相关文档 ### 架构设计 - [Schema隔离架构设计（10个）](../09-架构实施/01-Schema隔离架构设计（10个）.md) - [前端总体架构设计](../01-平台基础层/06-前端架构/01-前端总体架构设计.md) - [导航结构设计](../01-平台基础层/06-前端架构/02-导航结构设计.md) ### 数据库设计 - [AIA数据库设计](../03-业务模块/AIA-AI智能问答/02-技术设计/01-数据库设计.md) - [PKB数据库设计](../03-业务模块/PKB-个人知识库/02-技术设计/01-数据库设计.md) ### 实施报告 - [Schema迁移完成报告](../09-架构实施/Schema迁移完成报告.md) - [Prisma配置完成报告](../09-架构实施/Prisma配置完成报告.md) ### 项目管理 - [下一阶段行动计划-V2.2-完整版](../08-项目管理/下一阶段行动计划-V2.2-完整版.md) --- ## 🔄 版本历史 | 版本 | 日期 | 变更内容 | 维护者 | |------|------|---------|--------| | V2.0 | 2025-11-12 | 创建本文档，定义前后端模块化架构 | AI助手 | | V2.1 | 2025-11-13 | 完成权限系统、错误边界、路由守卫实施 | AI助手 | --- **文档维护者：** AI助手 + 开发团队 **最后更新：** 2025-11-13 **文档状态：** ✅ 已完成，Week 2 Day 7实施完成 **🎉 这是系统架构演进的重要里程碑！**