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动态获取版本配置。

### 路由路径设计

```typescript
// 主路由结构
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/                     # 全局类型
```

---

## 🔐 权限控制设计

### 用户版本定义

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

```typescript
// 用户版本类型
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动态获取版本配置，便于后期灵活调整。

```typescript
// 权限控制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, // 返回当前版本配置，便于调试
  };
};
```

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

```typescript
// 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测试不同版本配置
- ✅ 便于运营人员灵活调整产品策略
- ✅ 前端有本地配置作为兜底方案，保证可用性

### 路由守卫

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

---

## 🔌 模块独立性设计

### 模块注册机制

```typescript
// 模块接口定义
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, // 可配置
  },
  // ... 其他模块
];
```

### 独立部署支持

```typescript
// 模块加载器
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} />;
};
```

### 配置驱动的模块加载

```typescript
// 环境变量配置
// .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 (模块布局)
```

### 布局组件

```typescript
// 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设计规范

### 顶部导航样式

```css
.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）
- [x] 创建新前端项目结构
- [ ] 实现顶部导航组件
- [ ] 实现路由系统
- [ ] 实现权限控制基础
- [ ] 实现基础布局系统

### 第二阶段：模块集成（Week 2）
- [ ] 迁移AI问答模块
- [ ] 迁移知识库模块
- [ ] 实现占位模块（智能数据清洗）
- [ ] 完善权限控制

### 第三阶段：AI智能文献开发（Week 3+）
- [ ] 开发AI智能文献模块
- [ ] 实现模块独立运行支持
- [ ] 完善文档和测试

---

## 🔄 未来扩展考虑

### 1. 模块独立产品化
- 支持通过环境变量配置独立运行
- 独立的API地址配置
- 独立的部署配置

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

### 3. 新模块接入
- 遵循模块接口规范
- 在配置文件中注册模块
- 自动集成到导航系统

---

## 📚 相关文档

- [导航结构设计](./02-导航结构设计.md)
- [路由设计](./03-路由设计.md)
- [布局设计](./04-布局设计.md)
- [权限控制设计](./05-权限控制设计.md)
- [AI智能文献模块架构设计](../AI智能文献/00-系统设计/01-模块架构设计.md)

---

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