688 lines
19 KiB
Markdown
688 lines
19 KiB
Markdown
# 海洋项目管理系统 - 前端技术架构文档
|
||
|
||
## 1. 前端技术栈
|
||
|
||
### 1.1 核心框架
|
||
- **React 18**: 用于构建用户界面的JavaScript库
|
||
- **React Router 6**: 客户端路由管理
|
||
- **Vite**: 现代化的前端构建工具（替代Create React App）
|
||
|
||
### 1.2 UI组件库
|
||
- **Ant Design 5**: 企业级UI组件库
|
||
- **@ant-design/icons**: Ant Design图标库
|
||
|
||
### 1.3 HTTP客户端
|
||
- **Axios**: HTTP请求库
|
||
|
||
### 1.4 状态管理
|
||
- **React Context API**: 轻量级状态管理
|
||
- **useReducer Hook**: 复杂状态逻辑
|
||
|
||
### 1.5 表单处理
|
||
- **Ant Design Form**: 表单组件和验证
|
||
- **react-hook-form**: 表单状态管理（可选）
|
||
|
||
### 1.6 工具库
|
||
- **dayjs**: 日期处理（轻量级替代moment.js）
|
||
- **lodash**: 工具函数库
|
||
- **classnames**: 条件类名处理
|
||
|
||
### 1.7 开发工具
|
||
- **ESLint**: 代码质量检查
|
||
- **Prettier**: 代码格式化
|
||
- **Vitest**: 单元测试框架
|
||
- **React Testing Library**: 组件测试
|
||
- **TypeScript**: 类型检查（可选，当前使用JavaScript）
|
||
|
||
### 1.8 构建和部署
|
||
- **Vite**: 开发服务器和构建工具
|
||
- **Docker**: 容器化部署（生产环境）
|
||
|
||
## 2. 前端目录结构
|
||
|
||
```
|
||
frontend/
|
||
├── src/ # 源代码目录
|
||
│ ├── assets/ # 静态资源
|
||
│ │ ├── images/ # 图片
|
||
│ │ ├── fonts/ # 字体文件
|
||
│ │ └── styles/ # 全局样式
|
||
│ │ ├── global.css # 全局CSS
|
||
│ │ ├── variables.css # CSS变量
|
||
│ │ └── mixins.css # CSS mixins
|
||
│ ├── components/ # 可复用组件
|
||
│ │ ├── Layout/ # 布局组件
|
||
│ │ │ ├── Layout.jsx # 主布局
|
||
│ │ │ ├── Header.jsx # 顶部导航
|
||
│ │ │ └── Sidebar.jsx # 侧边栏
|
||
│ │ ├── Common/ # 通用组件
|
||
│ │ │ ├── Button.jsx # 按钮组件
|
||
│ │ │ ├── Input.jsx # 输入框组件
|
||
│ │ │ ├── Select.jsx # 选择框组件
|
||
│ │ │ ├── Table.jsx # 表格组件
|
||
│ │ │ ├── Modal.jsx # 弹窗组件
|
||
│ │ │ ├── Form.jsx # 表单组件
|
||
│ │ │ ├── Card.jsx # 卡片组件
|
||
│ │ │ └── Tag.jsx # 标签组件
|
||
│ │ ├── Business/ # 业务组件
|
||
│ │ │ ├── ProjectCard.jsx # 项目卡片
|
||
│ │ │ ├── StatCard.jsx # 统计卡片
|
||
│ │ │ └── UserAvatar.jsx # 用户头像
|
||
│ │ └── index.js # 组件导出
|
||
│ ├── pages/ # 页面组件
|
||
│ │ ├── Login/ # 登录页
|
||
│ │ │ └── Login.jsx
|
||
│ │ ├── Dashboard/ # 仪表盘
|
||
│ │ │ └── Dashboard.jsx
|
||
│ │ ├── Projects/ # 项目管理
|
||
│ │ │ ├── ProjectList.jsx # 项目列表
|
||
│ │ │ ├── ProjectForm.jsx # 项目表单
|
||
│ │ │ ├── ProjectDetail.jsx # 项目详情
|
||
│ │ │ └── ProjectStatistics.jsx # 项目统计
|
||
│ │ ├── Users/ # 用户管理（仅管理员）
|
||
│ │ │ ├── UserList.jsx # 用户列表
|
||
│ │ │ ├── UserForm.jsx # 用户表单
|
||
│ │ │ └── UserResetPassword.jsx # 重置密码
|
||
│ │ └── Statistics/ # 统计分析
|
||
│ │ └── Statistics.jsx
|
||
│ ├── contexts/ # Context上下文
|
||
│ │ ├── AuthContext.jsx # 认证上下文
|
||
│ │ └── ThemeContext.jsx # 主题上下文（可选）
|
||
│ ├── hooks/ # 自定义Hooks
|
||
│ │ ├── useAuth.js # 认证Hook
|
||
│ │ ├── useApi.js # API调用Hook
|
||
│ │ ├── usePermission.js # 权限检查Hook
|
||
│ │ ├── useTable.js # 表格Hook
|
||
│ │ ├── useForm.js # 表单Hook
|
||
│ │ └── useDebounce.js # 防抖Hook
|
||
│ ├── services/ # API服务
|
||
│ │ ├── api.js # Axios配置
|
||
│ │ ├── auth.js # 认证API
|
||
│ │ ├── user.js # 用户API
|
||
│ │ ├── project.js # 项目API
|
||
│ │ └── statistics.js # 统计API
|
||
│ ├── utils/ # 工具函数
|
||
│ │ ├── request.js # 请求封装
|
||
│ │ ├── storage.js # 本地存储
|
||
│ │ ├── auth.js # 认证工具
|
||
│ │ ├── format.js # 格式化函数
|
||
│ │ ├── validation.js # 验证函数
|
||
│ │ └── constants.js # 常量定义
|
||
│ ├── config/ # 配置文件
|
||
│ │ ├── routes.js # 路由配置
|
||
│ │ ├── menu.js # 菜单配置
|
||
│ │ ├── colors.js # 颜色配置
|
||
│ │ └── app.config.js # 应用配置
|
||
│ ├── router/ # 路由相关
|
||
│ │ ├── index.jsx # 路由配置
|
||
│ │ ├── PrivateRoute.jsx # 路由守卫
|
||
│ │ └── routes.js # 路由定义
|
||
│ ├── styles/ # 样式文件
|
||
│ │ └── index.css # 主样式文件
|
||
│ ├── App.jsx # 根组件
|
||
│ └── main.jsx # 应用入口
|
||
├── tests/ # 测试目录
|
||
│ ├── components/ # 组件测试
|
||
│ ├── pages/ # 页面测试
|
||
│ ├── hooks/ # Hooks测试
|
||
│ └── utils/ # 工具测试
|
||
├── public/ # 公共资源
|
||
│ ├── favicon.ico # 网站图标
|
||
│ ├── logo.png # Logo
|
||
│ └── robots.txt # 爬虫配置
|
||
├── docs/ # 前端文档
|
||
│ ├── frontend-architecture.md # 前端技术架构（本文档）
|
||
│ ├── component-design.md # 组件设计文档
|
||
│ ├── api-service.md # API服务封装
|
||
│ ├── state-management.md # 状态管理设计
|
||
│ ├── routing-design.md # 路由设计文档
|
||
│ └── development-guide.md # 开发指南
|
||
├── .env # 环境变量
|
||
├── .env.development # 开发环境变量
|
||
├── .env.production # 生产环境变量
|
||
├── .eslintrc.js # ESLint配置
|
||
├── .prettierrc # Prettier配置
|
||
├── package.json # 项目依赖
|
||
├── vite.config.js # Vite配置
|
||
├── index.html # HTML模板
|
||
├── WORKSTANDARDS.md # 前端工作规范
|
||
└── README.md # 前端说明文档
|
||
```
|
||
|
||
## 3. 组件架构
|
||
|
||
### 3.1 组件层级
|
||
|
||
```
|
||
App
|
||
├── AuthProvider (认证上下文)
|
||
├── Router (路由)
|
||
│ ├── PrivateRoute (路由守卫)
|
||
│ ├── Login (登录页)
|
||
│ └── Layout (主布局)
|
||
│ ├── Header (顶部导航)
|
||
│ ├── Sidebar (侧边栏)
|
||
│ └── Content (内容区)
|
||
│ ├── Dashboard (仪表盘)
|
||
│ ├── ProjectList (项目列表)
|
||
│ ├── ProjectForm (项目表单)
|
||
│ ├── ProjectDetail (项目详情)
|
||
│ ├── UserList (用户列表)
|
||
│ ├── UserForm (用户表单)
|
||
│ └── Statistics (统计页)
|
||
```
|
||
|
||
### 3.2 组件设计原则
|
||
|
||
#### 3.2.1 单一职责原则
|
||
- 每个组件只负责一个功能
|
||
- 避免组件过大，合理拆分
|
||
|
||
#### 3.2.2 组件复用性
|
||
- 提取可复用的通用组件到 `components/Common/`
|
||
- 提取业务相关组件到 `components/Business/`
|
||
|
||
#### 3.2.3 组件分类
|
||
- **布局组件**: Layout, Header, Sidebar
|
||
- **通用组件**: Button, Input, Form, Modal, Table
|
||
- **业务组件**: ProjectCard, StatCard, UserAvatar
|
||
- **页面组件**: Login, Dashboard, ProjectList等
|
||
|
||
#### 3.2.4 组件Props规范
|
||
```jsx
|
||
// 推荐的Props定义方式
|
||
const MyComponent = ({
|
||
title, // 必填props
|
||
value, // 可选props
|
||
onChange, // 事件回调
|
||
className, // 样式类名
|
||
style, // 内联样式
|
||
children, // 子元素
|
||
}) => {
|
||
return <div>{title}</div>;
|
||
};
|
||
|
||
MyComponent.propTypes = {
|
||
title: PropTypes.string.isRequired,
|
||
value: PropTypes.string,
|
||
onChange: PropTypes.func,
|
||
className: PropTypes.string,
|
||
style: PropTypes.object,
|
||
children: PropTypes.node,
|
||
};
|
||
|
||
MyComponent.defaultProps = {
|
||
value: '',
|
||
onChange: () => {},
|
||
className: '',
|
||
style: {},
|
||
};
|
||
```
|
||
|
||
## 4. 状态管理
|
||
|
||
### 4.1 Context API方案
|
||
|
||
#### 4.1.1 AuthContext（认证上下文）
|
||
```javascript
|
||
// contexts/AuthContext.jsx
|
||
const AuthContext = createContext();
|
||
|
||
export const AuthProvider = ({ children }) => {
|
||
const [user, setUser] = useState(null);
|
||
const [token, setToken] = useState(null);
|
||
const [loading, setLoading] = useState(true);
|
||
|
||
// 登录
|
||
const login = async (username, password) => {
|
||
// 登录逻辑
|
||
};
|
||
|
||
// 登出
|
||
const logout = () => {
|
||
// 登出逻辑
|
||
};
|
||
|
||
// 检查登录状态
|
||
const checkAuth = async () => {
|
||
// 检查逻辑
|
||
};
|
||
|
||
return (
|
||
<AuthContext.Provider
|
||
value={{
|
||
user,
|
||
token,
|
||
loading,
|
||
login,
|
||
logout,
|
||
checkAuth,
|
||
isAuthenticated: !!user,
|
||
}}
|
||
>
|
||
{children}
|
||
</AuthContext.Provider>
|
||
);
|
||
};
|
||
```
|
||
|
||
#### 4.1.2 ThemeContext（主题上下文，可选）
|
||
```javascript
|
||
// contexts/ThemeContext.jsx
|
||
const ThemeContext = createContext();
|
||
|
||
export const ThemeProvider = ({ children }) => {
|
||
const [theme, setTheme] = useState('light');
|
||
|
||
const toggleTheme = () => {
|
||
setTheme(prev => prev === 'light' ? 'dark' : 'light');
|
||
};
|
||
|
||
return (
|
||
<ThemeContext.Provider value={{ theme, toggleTheme }}>
|
||
{children}
|
||
</ThemeContext.Provider>
|
||
);
|
||
};
|
||
```
|
||
|
||
### 4.2 本地状态管理
|
||
- 使用 `useState` 管理组件内部状态
|
||
- 使用 `useReducer` 管理复杂的状态逻辑
|
||
|
||
### 4.3 表单状态管理
|
||
- 使用 Ant Design Form 组件
|
||
- 使用 `react-hook-form`（可选）
|
||
|
||
## 5. 路由设计
|
||
|
||
### 5.1 路由配置
|
||
|
||
```javascript
|
||
// router/routes.js
|
||
const routes = [
|
||
{
|
||
path: '/login',
|
||
element: <Login />,
|
||
meta: { title: '登录', requiresAuth: false },
|
||
},
|
||
{
|
||
path: '/',
|
||
element: <Layout />,
|
||
meta: { title: '主页', requiresAuth: true },
|
||
children: [
|
||
{
|
||
path: '/dashboard',
|
||
element: <Dashboard />,
|
||
meta: { title: '仪表盘', icon: 'DashboardOutlined' },
|
||
},
|
||
{
|
||
path: '/projects',
|
||
element: <ProjectList />,
|
||
meta: { title: '项目管理', icon: 'FileTextOutlined' },
|
||
},
|
||
{
|
||
path: '/projects/create',
|
||
element: <ProjectForm />,
|
||
meta: { title: '创建项目' },
|
||
},
|
||
{
|
||
path: '/projects/:id',
|
||
element: <ProjectDetail />,
|
||
meta: { title: '项目详情' },
|
||
},
|
||
{
|
||
path: '/projects/:id/edit',
|
||
element: <ProjectForm />,
|
||
meta: { title: '编辑项目' },
|
||
},
|
||
{
|
||
path: '/users',
|
||
element: <UserList />,
|
||
meta: { title: '用户管理', icon: 'UserOutlined', requiresRole: ['admin'] },
|
||
},
|
||
{
|
||
path: '/users/create',
|
||
element: <UserForm />,
|
||
meta: { title: '创建用户', requiresRole: ['admin'] },
|
||
},
|
||
{
|
||
path: '/statistics',
|
||
element: <Statistics />,
|
||
meta: { title: '统计分析', icon: 'BarChartOutlined' },
|
||
},
|
||
],
|
||
},
|
||
];
|
||
```
|
||
|
||
### 5.2 路由守卫
|
||
|
||
```javascript
|
||
// router/PrivateRoute.jsx
|
||
const PrivateRoute = ({ children, requiresAuth, requiresRole }) => {
|
||
const { isAuthenticated, user } = useAuth();
|
||
const navigate = useNavigate();
|
||
|
||
if (requiresAuth && !isAuthenticated) {
|
||
return <Navigate to="/login" replace />;
|
||
}
|
||
|
||
if (requiresRole && !requiresRole.includes(user?.role)) {
|
||
return <Navigate to="/403" replace />;
|
||
}
|
||
|
||
return children;
|
||
};
|
||
```
|
||
|
||
## 6. API服务封装
|
||
|
||
### 6.1 Axios配置
|
||
|
||
```javascript
|
||
// services/api.js
|
||
import axios from 'axios';
|
||
import { message } from 'antd';
|
||
|
||
const api = axios.create({
|
||
baseURL: import.meta.env.VITE_API_BASE_URL || 'http://localhost:5000/api/v1',
|
||
timeout: 10000,
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
},
|
||
});
|
||
|
||
// 请求拦截器
|
||
api.interceptors.request.use(
|
||
(config) => {
|
||
const token = localStorage.getItem('token');
|
||
if (token) {
|
||
config.headers.Authorization = `Bearer ${token}`;
|
||
}
|
||
return config;
|
||
},
|
||
(error) => {
|
||
return Promise.reject(error);
|
||
}
|
||
);
|
||
|
||
// 响应拦截器
|
||
api.interceptors.response.use(
|
||
(response) => {
|
||
return response.data;
|
||
},
|
||
(error) => {
|
||
if (error.response) {
|
||
const { status, data } = error.response;
|
||
|
||
switch (status) {
|
||
case 401:
|
||
message.error('登录已过期，请重新登录');
|
||
localStorage.removeItem('token');
|
||
window.location.href = '/login';
|
||
break;
|
||
case 403:
|
||
message.error('权限不足');
|
||
break;
|
||
case 404:
|
||
message.error('请求的资源不存在');
|
||
break;
|
||
case 500:
|
||
message.error('服务器错误');
|
||
break;
|
||
default:
|
||
message.error(data.message || '请求失败');
|
||
}
|
||
} else {
|
||
message.error('网络错误，请检查网络连接');
|
||
}
|
||
|
||
return Promise.reject(error);
|
||
}
|
||
);
|
||
|
||
export default api;
|
||
```
|
||
|
||
### 6.2 API模块化
|
||
|
||
```javascript
|
||
// services/project.js
|
||
import api from './api';
|
||
|
||
export const projectAPI = {
|
||
// 获取项目列表
|
||
getList: (params) => api.get('/projects', { params }),
|
||
|
||
// 获取项目详情
|
||
getDetail: (id) => api.get(`/projects/${id}`),
|
||
|
||
// 创建项目
|
||
create: (data) => api.post('/projects', data),
|
||
|
||
// 更新项目
|
||
update: (id, data) => api.put(`/projects/${id}`, data),
|
||
|
||
// 删除项目
|
||
delete: (id) => api.delete(`/projects/${id}`),
|
||
|
||
// 获取统计信息
|
||
getStatistics: (params) => api.get('/projects/statistics', { params }),
|
||
|
||
// 获取分组统计
|
||
getGroupStatistics: (params) => api.get('/projects/statistics/group', { params }),
|
||
|
||
// 获取时间维度统计
|
||
getTimelineStatistics: (params) => api.get('/projects/statistics/timeline', { params }),
|
||
};
|
||
```
|
||
|
||
## 7. 权限控制
|
||
|
||
### 7.1 路由级权限
|
||
- 使用 `PrivateRoute` 组件检查认证状态
|
||
- 使用 `requiresRole` 属性检查角色权限
|
||
|
||
### 7.2 组件级权限
|
||
```javascript
|
||
// hooks/usePermission.js
|
||
export const usePermission = () => {
|
||
const { user } = useAuth();
|
||
|
||
const hasRole = (roles) => {
|
||
if (!user) return false;
|
||
return roles.includes(user.role);
|
||
};
|
||
|
||
const canEdit = (resource, createdBy) => {
|
||
if (!user) return false;
|
||
if (user.role === 'admin') return true;
|
||
if (user.role === 'market' && createdBy === user.id) return true;
|
||
return false;
|
||
};
|
||
|
||
return { hasRole, canEdit };
|
||
};
|
||
```
|
||
|
||
### 7.3 按钮级权限
|
||
```javascript
|
||
// 组件中使用
|
||
const { hasRole } = usePermission();
|
||
|
||
{hasRole(['admin', 'market']) && (
|
||
<Button type="primary">创建项目</Button>
|
||
)}
|
||
```
|
||
|
||
## 8. 性能优化
|
||
|
||
### 8.1 代码分割
|
||
```javascript
|
||
import { lazy, Suspense } from 'react';
|
||
|
||
const ProjectList = lazy(() => import('./pages/Projects/ProjectList'));
|
||
const ProjectDetail = lazy(() => import('./pages/Projects/ProjectDetail'));
|
||
|
||
<Suspense fallback={<Spin />}>
|
||
<ProjectList />
|
||
</Suspense>
|
||
```
|
||
|
||
### 8.2 图片优化
|
||
- 使用懒加载
|
||
- 压缩图片文件
|
||
- 使用WebP格式
|
||
|
||
### 8.3 请求优化
|
||
- 防抖处理搜索请求
|
||
- 取消重复请求
|
||
- 使用缓存策略
|
||
|
||
### 8.4 渲染优化
|
||
- 使用 `React.memo` 避免不必要的重渲染
|
||
- 使用 `useMemo` 缓存计算结果
|
||
- 使用 `useCallback` 缓存函数引用
|
||
|
||
## 9. 前端安全
|
||
|
||
### 9.1 XSS防护
|
||
- React自动转义HTML
|
||
- 避免使用 `dangerouslySetInnerHTML`
|
||
- 输入验证和过滤
|
||
|
||
### 9.2 CSRF防护
|
||
- 使用Cookie SameSite属性
|
||
- 添加CSRF Token（可选）
|
||
|
||
### 9.3 敏感信息保护
|
||
- Token存储在LocalStorage（可改为HttpOnly Cookie）
|
||
- 不在URL中传递敏感信息
|
||
- 使用HTTPS（生产环境）
|
||
|
||
### 9.4 内容安全策略（CSP）
|
||
- 设置CSP头部
|
||
- 限制外部资源加载
|
||
|
||
## 10. 开发规范
|
||
|
||
### 10.1 代码风格
|
||
- 使用ESLint进行代码检查
|
||
- 使用Prettier进行代码格式化
|
||
- 遵循Airbnb JavaScript风格指南
|
||
|
||
### 10.2 命名规范
|
||
- 组件名使用PascalCase（如 `ProjectList`）
|
||
- 函数和变量使用camelCase（如 `getUserById`）
|
||
- 常量使用UPPER_SNAKE_CASE（如 `API_BASE_URL`）
|
||
- CSS类名使用kebab-case（如 `project-card`）
|
||
|
||
### 10.3 注释规范
|
||
```javascript
|
||
/**
|
||
* 获取项目列表
|
||
* @param {Object} params - 查询参数
|
||
* @param {number} params.page - 页码
|
||
* @param {number} params.pageSize - 每页数量
|
||
* @returns {Promise} 项目列表数据
|
||
*/
|
||
const getProjectList = async (params) => {
|
||
// 实现代码
|
||
};
|
||
```
|
||
|
||
### 10.4 Git提交规范
|
||
```
|
||
[frontend] feat: 添加项目列表页面
|
||
[frontend] fix: 修复登录bug
|
||
[frontend] style: 优化代码格式
|
||
[frontend] refactor: 重构API服务
|
||
[frontend] test: 添加组件测试
|
||
[frontend] docs: 更新文档
|
||
[frontend] chore: 更新依赖
|
||
```
|
||
|
||
## 11. 测试策略
|
||
|
||
### 11.1 单元测试
|
||
- 测试工具函数和自定义Hooks
|
||
- 使用Vitest测试框架
|
||
|
||
### 11.2 组件测试
|
||
- 测试组件渲染和交互
|
||
- 使用React Testing Library
|
||
|
||
### 11.3 集成测试
|
||
- 测试页面和路由
|
||
- 测试API调用
|
||
|
||
### 11.4 E2E测试（可选）
|
||
- 测试完整用户流程
|
||
- 使用Playwright
|
||
|
||
## 12. 部署方案
|
||
|
||
### 12.1 开发环境
|
||
```bash
|
||
npm run dev
|
||
# 访问 http://localhost:3000
|
||
```
|
||
|
||
### 12.2 生产构建
|
||
```bash
|
||
npm run build
|
||
# 生成 dist 目录
|
||
```
|
||
|
||
### 12.3 Docker部署
|
||
```dockerfile
|
||
# Dockerfile
|
||
FROM node:18-alpine as builder
|
||
WORKDIR /app
|
||
COPY package*.json ./
|
||
RUN npm ci
|
||
COPY . .
|
||
RUN npm run build
|
||
|
||
FROM nginx:alpine
|
||
COPY --from=builder /app/dist /usr/share/nginx/html
|
||
COPY nginx.conf /etc/nginx/conf.d/default.conf
|
||
EXPOSE 80
|
||
CMD ["nginx", "-g", "daemon off;"]
|
||
```
|
||
|
||
### 12.4 Nginx配置
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name localhost;
|
||
|
||
location / {
|
||
root /usr/share/nginx/html;
|
||
index index.html;
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
location /api {
|
||
proxy_pass http://backend:5000;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 13. 相关文档
|
||
|
||
- [组件设计文档](component-design.md) - 详细的组件设计规范
|
||
- [API服务封装](api-service.md) - API服务封装详解
|
||
- [状态管理设计](state-management.md) - 状态管理方案详解
|
||
- [路由设计文档](routing-design.md) - 路由设计详解
|
||
- [开发指南](development-guide.md) - 前端开发指南
|
||
|
||
---
|
||
|
||
**文档维护**: 前端程序员
|
||
**文档类型**: 前端技术架构文档
|
||
**最后更新**: 2026-01-25
|