AIclinicalresearch/docs/01-平台基础层/06-前端架构/01-前端总体架构设计.md

平台前端总体架构设计

文档版本： v1.0
创建日期： 2025-10-29
维护者： 前端开发团队
最后更新： 2025-10-29

---

📋 文档说明

本文档是平台级前端架构设计，涵盖整个AI科研平台的前端架构，包括：

• 统一的顶部导航设计
• 模块化架构设计
• 路由设计
• 权限控制系统（版本配置完全可调整）
• 模块独立性设计（支持未来独立分拆）

注意： 本文档是平台级设计，各模块的详细架构设计请参考各模块的专属文档。

重要提示： 本文档中涉及的版本权限分配（基础版、高级版、旗舰版的模块分配）均为初始方案，可以根据业务需求随时调整，无需改动代码逻辑。推荐从后端API动态获取版本配置。

---

🎯 设计原则

1. 模块化设计

• 每个功能模块独立开发、独立部署
• 模块间无依赖关系，可独立运行
• 支持模块独立产品化（如AI智能文献独立售卖）

2. 权限控制设计

• 基于用户版本的权限控制
• 灵活的功能模块开关机制
• 支持未来商业模式拓展（基础版、高级版、旗舰版）

3. 可扩展性设计

• 预留新模块接入接口
• 插件化的模块加载机制
• 配置驱动的功能开关

4. 一致性设计

• 统一的UI/UX规范
• 统一的交互模式
• 统一的状态管理

---

🧭 顶部导航设计

导航结构

┌──────────────────────────────────────────────────────────────────────────────┐
│ Logo  [AI问答] [AI智能文献] [知识库] [智能数据清洗] [智能统计分析] [统计分析工具]  [用户名 ▼] │
└──────────────────────────────────────────────────────────────────────────────┘

导航项详情

位置	中文名称	英文标识	路由路径	开发状态	权限要求（初始配置）
1	AI问答	ai-qa	/ai-qa	✅ 已开发	基础版+ ⚠️可调整
2	AI智能文献	literature-platform	/literature	🚧 待开发	高级版+ ⚠️可调整
3	知识库	knowledge-base	/knowledge-base	✅ 已开发	基础版+ ⚠️可调整
4	智能数据清洗	data-cleaning	/data-cleaning	📋 占位	高级版+ ⚠️可调整
5	智能统计分析	statistical-analysis	/intelligent-analysis	✅ 已开发（Java团队）	旗舰版 ⚠️可调整
6	统计分析工具	statistical-tools	/statistical-tools	✅ 已开发（Java团队）	旗舰版 ⚠️可调整
最右侧	个人中心	user-center	/user/*	✅ 已开发	所有用户

说明： 权限要求列中的"基础版+"、"高级版+"、"旗舰版"为初始配置，可根据业务需求随时调整，无需改动代码逻辑。推荐从后端API动态获取版本配置。

路由路径设计

// 主路由结构
const routes = {
  // 模块路由
  '/ai-qa': 'AI问答模块',
  '/literature': 'AI智能文献模块',
  '/knowledge-base': '知识库模块',
  '/data-cleaning': '智能数据清洗模块（占位）',
  '/intelligent-analysis': '智能统计分析模块（Java团队开发，只做顶部导航集成）',
  '/statistical-tools': '统计分析工具模块（Java团队开发，只做顶部导航集成）',
  
  // 用户相关
  '/user/profile': '个人中心 - 个人资料',
  '/user/settings': '个人中心 - 设置',
  '/user/history': '个人中心 - 历史记录',
  '/user/subscription': '个人中心 - 订阅管理',
};

---

🏗️ 整体架构设计

架构层次图

┌─────────────────────────────────────────────────────────────┐
│                    应用层 (Application)                       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      │
│  │ AI问答   │ │AI智能文献│ │ 知识库   │ │ 其他模块 │      │
│  │ Module   │ │ Module   │ │ Module   │ │ Module   │      │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘      │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│                   框架层 (Framework Layer)                    │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐       │
│  │ 导航系统     │ │ 路由系统     │ │ 权限控制     │       │
│  │ Navigation   │ │ Router       │ │ Permission   │       │
│  └──────────────┘ └──────────────┘ └──────────────┘       │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐       │
│  │ 布局系统     │ │ 状态管理     │ │ 配置管理     │       │
│  │ Layout       │ │ State Mgmt   │ │ Config       │       │
│  └──────────────┘ └──────────────┘ └──────────────┘       │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│                   基础层 (Base Layer)                         │
│  React + TypeScript + Ant Design + Tailwind CSS             │
└─────────────────────────────────────────────────────────────┘

目录结构设计

frontend-v2/
├── src/
│   ├── app/                        # 应用入口
│   │   ├── App.tsx                # 根组件
│   │   ├── main.tsx               # 入口文件
│   │   └── routes.tsx             # 路由配置
│   │
│   ├── framework/                 # 框架层（核心）
│   │   ├── navigation/            # 导航系统
│   │   │   ├── TopNavigation.tsx  # 顶部导航
│   │   │   ├── SideNavigation.tsx # 左侧导航
│   │   │   └── navigationConfig.ts # 导航配置
│   │   │
│   │   ├── routing/               # 路由系统
│   │   │   ├── RouterConfig.tsx   # 路由配置
│   │   │   ├── RouteGuard.tsx     # 路由守卫（权限）
│   │   │   └── LazyLoader.tsx     # 懒加载
│   │   │
│   │   ├── permission/            # 权限控制
│   │   │   ├── PermissionProvider.tsx
│   │   │   ├── usePermission.ts   # 权限Hook
│   │   │   ├── permissionConfig.ts # 权限配置
│   │   │   └── versionConfig.ts   # 版本配置
│   │   │
│   │   ├── layout/                # 布局系统
│   │   │   ├── MainLayout.tsx     # 主布局
│   │   │   ├── ModuleLayout.tsx   # 模块布局
│   │   │   └── EmptyLayout.tsx    # 空布局
│   │   │
│   │   ├── config/                # 配置管理
│   │   │   ├── moduleConfig.ts    # 模块配置
│   │   │   ├── appConfig.ts       # 应用配置
│   │   │   └── environment.ts     # 环境配置
│   │   │
│   │   └── state/                 # 全局状态
│   │       ├── userStore.ts       # 用户状态
│   │       ├── navigationStore.ts # 导航状态
│   │       └── permissionStore.ts # 权限状态
│   │
│   ├── modules/                   # 功能模块（独立）
│   │   ├── ai-qa/                 # AI问答模块
│   │   │   ├── index.tsx
│   │   │   ├── routes.tsx
│   │   │   └── ...
│   │   │
│   │   ├── literature/            # AI智能文献模块
│   │   │   ├── index.tsx
│   │   │   ├── routes.tsx
│   │   │   └── ...
│   │   │
│   │   ├── knowledge-base/        # 知识库模块
│   │   │   ├── index.tsx
│   │   │   ├── routes.tsx
│   │   │   └── ...
│   │   │
│   │   ├── data-cleaning/         # 智能数据清洗（占位）
│   │   │   └── Placeholder.tsx
│   │   │
│   │   ├── intelligent-analysis/  # 智能统计分析
│   │   │   └── ...
│   │   │
│   │   └── statistical-tools/     # 统计分析工具
│   │       └── ...
│   │
│   ├── components/                # 通用组件
│   │   ├── common/                # 基础组件
│   │   ├── business/              # 业务组件
│   │   └── hooks/                 # 通用Hooks
│   │
│   ├── api/                       # API层
│   │   ├── client.ts              # API客户端
│   │   ├── modules/               # 模块API
│   │   └── types/                 # API类型
│   │
│   ├── utils/                     # 工具函数
│   └── types/                     # 全局类型

---

🔐 权限控制设计

用户版本定义

重要说明： 版本权限分配是完全可配置、可调整的。以下配置为初始方案，可以根据业务需求随时修改，无需改动代码逻辑。

// 用户版本类型
type UserVersion = 'basic' | 'advanced' | 'premium';

// 版本配置（可配置，支持后期调整）
// 配置文件位置：src/framework/permission/versionConfig.ts
// 或者通过后端API动态获取配置
const VERSION_CONFIG = {
  basic: {
    name: '基础版',
    modules: ['ai-qa', 'knowledge-base'], // 初始配置：基础版包含模块
  },
  advanced: {
    name: '高级版',
    modules: [
      'ai-qa',
      'knowledge-base',
      'literature-platform',
      'data-cleaning',
    ], // 初始配置：高级版包含模块
  },
  premium: {
    name: '旗舰版',
    modules: [
      'ai-qa',
      'knowledge-base',
      'literature-platform',
      'data-cleaning',
      'intelligent-analysis',
      'statistical-tools',
    ], // 初始配置：旗舰版包含全部模块
  },
};

// 说明：
// 1. 以上模块分配为初始方案，可根据实际业务需求调整
// 2. 支持通过配置文件修改，无需改动代码
// 3. 更推荐从后端API动态获取版本配置，便于实时调整

权限控制实现

设计说明： 权限控制采用配置驱动的方式，支持通过配置文件或后端API动态获取版本配置，便于后期灵活调整。

// 权限控制Hook
export const usePermission = () => {
  const userVersion = useUserStore((state) => state.version);
  
  // 方式1：从静态配置读取（适合开发阶段）
  // const allowedModules = VERSION_CONFIG[userVersion].modules;
  
  // 方式2：从后端API动态获取（推荐，支持实时调整）
  const versionConfig = useVersionConfig(); // 从API获取最新配置
  const allowedModules = versionConfig[userVersion]?.modules || [];
  
  const hasAccess = (moduleId: string): boolean => {
    return allowedModules.includes(moduleId);
  };
  
  const getFilteredNavigation = (navigation: NavigationItem[]) => {
    return navigation.filter((item) => {
      // 检查用户版本是否满足模块要求
      if (!item.requiredVersion) return true;
      const versionHierarchy = ['basic', 'advanced', 'premium'];
      const userLevel = versionHierarchy.indexOf(userVersion);
      const requiredLevel = versionHierarchy.indexOf(item.requiredVersion);
      return userLevel >= requiredLevel;
    });
  };
  
  return {
    hasAccess,
    getFilteredNavigation,
    userVersion,
    versionConfig, // 返回当前版本配置，便于调试
  };
};

版本配置动态获取（推荐方案）

// src/framework/permission/useVersionConfig.ts
import { useQuery } from '@tanstack/react-query';

export const useVersionConfig = () => {
  const { data, isLoading } = useQuery({
    queryKey: ['versionConfig'],
    queryFn: async () => {
      // 从后端API获取版本配置
      const response = await fetch('/api/config/version');
      return response.json();
    },
    staleTime: 5 * 60 * 1000, // 缓存5分钟
    refetchOnWindowFocus: false,
  });
  
  // 如果API请求失败，回退到本地配置
  return data || VERSION_CONFIG;
};

优势：

• ✅ 版本配置可在后端实时调整，无需前端发版
• ✅ 支持A/B测试不同版本配置
• ✅ 便于运营人员灵活调整产品策略
• ✅ 前端有本地配置作为兜底方案，保证可用性

路由守卫

// RouteGuard.tsx
export const RouteGuard = ({ moduleId, children }) => {
  const { hasAccess } = usePermission();
  
  if (!hasAccess(moduleId)) {
    return <UpgradePrompt moduleId={moduleId} />;
  }
  
  return children;
};

---

🔌 模块独立性设计

模块注册机制

// 模块接口定义
interface ModuleDefinition {
  id: string;              // 模块唯一标识
  name: string;            // 模块名称
  route: string;           // 路由路径
  icon?: ReactNode;        // 图标
  component: LazyComponent; // 懒加载组件
  sideNav?: SideNavConfig; // 左侧导航配置
  version?: UserVersion[];  // 支持的版本
  standalone?: boolean;     // 是否支持独立运行
  apiBaseUrl?: string;     // 独立运行时的API地址
}

// 模块配置
const MODULES: ModuleDefinition[] = [
  {
    id: 'literature-platform',
    name: 'AI智能文献',
    route: '/literature',
    component: lazy(() => import('@/modules/literature')),
    version: ['advanced', 'premium'],
    standalone: true, // 支持独立运行
    apiBaseUrl: process.env.LITERATURE_API_URL, // 可配置
  },
  // ... 其他模块
];

独立部署支持

// 模块加载器
export const ModuleLoader = ({ moduleId }: { moduleId: string }) => {
  const module = MODULES.find((m) => m.id === moduleId);
  
  if (!module) {
    return <NotFound />;
  }
  
  // 检查是否独立运行模式
  const isStandalone = module.standalone && 
    window.location.hostname === module.apiBaseUrl;
  
  if (isStandalone) {
    // 独立运行：不显示顶部导航，只显示模块内容
    return <StandaloneLayout module={module} />;
  }
  
  // 集成运行：显示完整导航和布局
  return <ModuleLayout module={module} />;
};

配置驱动的模块加载

// 环境变量配置
// .env
REACT_APP_ENABLED_MODULES=ai-qa,knowledge-base,literature-platform
REACT_APP_STANDALONE_MODULE=literature-platform

// 模块配置读取
const getEnabledModules = () => {
  const enabled = process.env.REACT_APP_ENABLED_MODULES?.split(',') || [];
  return MODULES.filter((m) => enabled.includes(m.id));
};

---

📐 布局系统设计

布局层次

MainLayout (主布局)
├── Header (顶部导航)
│   ├── Logo
│   ├── TopNavigation (导航项)
│   └── UserMenu (用户菜单)
│
└── MainContent (主内容区)
    ├── SideNavigation (左侧导航) - 可选
    └── Content (内容区域)
        └── ModuleLayout (模块布局)

布局组件

// MainLayout.tsx
export const MainLayout = () => {
  return (
    <div className="min-h-screen flex flex-col">
      <Header />
      <div className="flex flex-1">
        <SideNavigation /> {/* 根据模块显示/隐藏 */}
        <main className="flex-1">
          <Outlet /> {/* 路由出口 */}
        </main>
      </div>
    </div>
  );
};

// ModuleLayout.tsx
export const ModuleLayout = ({ module }: { module: ModuleDefinition }) => {
  return (
    <div className="module-layout">
      {module.sideNav && <ModuleSideNav config={module.sideNav} />}
      <div className="module-content">
        <Outlet />
      </div>
    </div>
  );
};

---

🎨 UI/UX设计规范

顶部导航样式

.top-navigation {
  height: 64px;
  background: #ffffff;
  border-bottom: 1px solid #e5e7eb;
  display: flex;
  align-items: center;
  padding: 0 24px;
}

.nav-item {
  padding: 8px 16px;
  margin: 0 4px;
  color: #4b5563;
  font-weight: 500;
  border-bottom: 2px solid transparent;
  transition: all 0.2s;
}

.nav-item:hover {
  color: #0ea5e9;
}

.nav-item.active {
  color: #0ea5e9;
  border-bottom-color: #0ea5e9;
  font-weight: 600;
}

响应式设计

• 桌面端 (>1024px): 完整显示所有导航项
• 平板端 (768-1024px): 显示前4个，其余折叠到"更多"菜单
• 移动端 (<768px): 汉堡菜单 + 抽屉导航

---

📝 实施计划

第一阶段：框架搭建（Week 1）

• 创建新前端项目结构
• 实现顶部导航组件
• 实现路由系统
• 实现权限控制基础
• 实现基础布局系统

第二阶段：模块集成（Week 2）

• 迁移AI问答模块
• 迁移知识库模块
• 实现占位模块（智能数据清洗）
• 完善权限控制

第三阶段：AI智能文献开发（Week 3+）

• 开发AI智能文献模块
• 实现模块独立运行支持
• 完善文档和测试

---

🔄 未来扩展考虑

1. 模块独立产品化

• 支持通过环境变量配置独立运行
• 独立的API地址配置
• 独立的部署配置

2. 版本权限管理

• 后端API提供用户版本信息
• 版本配置完全可调整（无需改动代码）
• 推荐从后端API动态获取版本配置，支持实时调整模块分配
• 前端根据版本动态显示/隐藏模块
• 支持版本升级提示
• 版本权限分配策略可随时根据业务需求调整

3. 新模块接入

• 遵循模块接口规范
• 在配置文件中注册模块
• 自动集成到导航系统

---

📚 相关文档

• 导航结构设计
• 路由设计
• 布局设计
• 权限控制设计
• AI智能文献模块架构设计

---

文档版本： v1.0
最后更新： 2025-10-29