Files

HaHafeng e52020409c 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

2025-11-16 15:43:55 +08:00

46 KiB

Raw Blame History

前后端模块化架构设计 V2.0

版本： V2.2
创建日期： 2025-11-12
实施阶段： Week 2（2025-11-13开始）
维护者： 开发团队
状态： ✅ Week 2 Day 6-9 全部完成（前端架构+模块注册+后端分层）⭐⭐⭐

📋 文档说明

本文档是AI临床研究平台的模块化架构设计总纲，定义了：

前端架构：全新的 frontend-v2 模块化架构
后端架构：基于Schema隔离的分层架构
前后端对应关系：模块化的组织方式
开发规范：统一的代码组织和命名规范
实施路线：渐进式的架构改造计划

适用对象：

新加入的开发人员（快速了解系统架构）
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）

目录结构（实际存在）

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）

目录结构（实际存在）⭐ 关键

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）实际代码：

// ============================================
// 【旧架构】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 结构（实际存在）

-- ==================== 平台层 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 配置：

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）

{
  "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）

{
  "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）

设计原则

彻底的模块化 - 每个业务模块完全独立
框架与业务分离 - 框架层提供基础能力，业务模块专注功能
渐进式开发 - 新架构与旧代码并存，逐步替换
独立部署支持 - 模块可独立打包和部署

目录结构

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

模块定义接口

// framework/modules/types.ts

/**
 * 模块定义接口
 * 每个业务模块必须实现这个接口
 */
export interface ModuleDefinition {
  /** 模块唯一标识 */
  id: string
  
  /** 模块名称（显示在导航栏） */
  name: string
  
  /** 模块路由前缀 */
  path: string
  
  /** 模块图标（可选） */
  icon?: ReactNode
  
  /** 模块入口组件（懒加载） */
  component: LazyExoticComponent<ComponentType<any>>
  
  /** 模块路由配置 */
  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[]
}

模块注册示例

// 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: <FileTextOutlined />,
  component: lazy(() => import('./layouts/ASLLayout')),
  routes,
  hasSideNav: true,
  sideNavConfig,
  requiredVersion: 'advanced',
}

export default ASLModule

模块路由示例

// 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）

设计原则

Schema隔离 - 数据库层面的模块隔离（已完成）
代码分层 - platform/common/modules三层架构
模块独立 - 每个模块的API和逻辑独立
保持兼容 - 轻度重构，不破坏现有功能

目录结构

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

模块路由注册

// 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调用示例

// 前端：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   # 删除

响应格式：

// 成功响应
{
  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小时

上午：项目创建和框架层

创建 frontend-v2 项目（Vite + React + TS）
安装依赖（Antd、Router、Zustand、React Query）
配置 Tailwind CSS
创建目录结构（framework/modules/shared）
实现 TopNavigation.tsx
实现 MainLayout.tsx
定义模块接口（ModuleDefinition）

下午：模块占位

为5个模块创建目录
创建 Placeholder.tsx 组件
配置基本路由
测试导航切换

交付物：

✅ 可运行的 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 上午：创建目录结构

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

📝 旧代码处理

frontend/ 目录

状态： ⏸️ 保留，不再开发

处理方式：

添加 README-ARCHIVED.md 说明文件
在根目录 package.json 中区分启动命令
保留3-6个月，作为参考和应急备份
新架构稳定后再删除

参考价值：

UI交互设计
某些组件实现
API调用逻辑
业务流程

启动命令

{
  "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 验收标准

前端：

frontend-v2 项目可运行
顶部导航正常工作
模块注册系统完整
5个模块占位页面
路由切换正常
完整的开发文档

后端：

代码分层完成（platform/common/modules）
所有现有API正常工作
路由前缀统一（/api/v1/[module]/*）
import路径全部更新
API文档更新

文档：

本架构设计文档
前端开发规范文档
后端开发规范文档
Week 2总结报告

📚 相关文档

架构设计

数据库设计

实施报告

项目管理

下一阶段行动计划-V2.2-完整版

🔄 版本历史

版本	日期	变更内容	维护者
V2.0	2025-11-12	创建本文档，定义前后端模块化架构	AI助手
V2.1	2025-11-13	完成权限系统、错误边界、路由守卫实施	AI助手

文档维护者： AI助手 + 开发团队
最后更新： 2025-11-13
文档状态： ✅ 已完成，Week 2 Day 7实施完成

🎉 这是系统架构演进的重要里程碑！

46 KiB Raw Blame History Unescape Escape

前后端模块化架构设计 V2.0

📋 文档说明

🎯 架构演进历史

V1.0 阶段（2025-10之前）

V1.5 阶段（2025-11-12完成）

V2.0 阶段（2025-11-13~14完成）⭐

📸 当前架构真实状态（2025-11-14）

🎯 架构概览

📁 前端真实架构（Frontend-v2）

目录结构（实际存在）

🗄️ 后端真实架构（Backend）

目录结构（实际存在）⭐ 关键

🗃️ 数据库真实架构（PostgreSQL 15）

Schema 结构（实际存在）

🔌 API 真实路由（当前可用）

AIA 模块（AI智能问答）

PKB 模块（个人知识库）

RVW 模块（稿件审查）

系统端点

📊 技术栈真实配置

前端（Frontend-v2）

后端（Backend）

数据库

LLM 集成（CloseAI）

🔄 前后端模块对应关系（当前）

📋 功能测试清单（已验证）

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

开发流程（Week 3）：

📚 相关文档索引

🏗️ 整体架构设计

系统架构图

📁 前端架构设计（frontend-v2）

设计原则

目录结构

模块定义接口

模块注册示例

模块路由示例

📁 后端架构设计（backend）

设计原则

目录结构

模块路由注册

🔗 前后端对应关系

模块映射表

API调用示例

📐 开发规范

命名规范

前端

后端

模块开发规范

1. 新模块开发流程

2. 模块独立性原则

3. API设计规范

🚀 实施计划

Week 2：架构改造（2025-11-13 至 2025-11-17）

Day 6（11-13）：前端架构基础 ⏰ 4-6小时

Day 7（11-14）：模块注册机制 ⏰ 6-8小时

Day 8-9（11-15 至 11-16）：后端代码分层 ⏰ 1-2天

Day 10（11-17）：Week 2 验收 ⏰ 4小时

Week 3-4：ASL模块开发（在新架构下）

📝 旧代码处理

frontend/ 目录

启动命令

🎯 成功标准

Week 2 验收标准

📚 相关文档

架构设计

数据库设计

实施报告

项目管理

🔄 版本历史

46 KiB

Raw Blame History