# 平台前端总体架构设计

> **文档版本�?* 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)**: 显示�?个，其余折叠�?更多"菜单
- **移动�?(<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