更新README.md文档
This commit is contained in:
Eamon-meng
291
README.md
291
README.md
@@ -16,73 +16,17 @@
|
||||
|
||||
业务定制页面每月需求用量，可选项需要确认是否合理
|
||||
|
||||
页头高度降低
|
||||
|
||||
帮助中心文档优化
|
||||
|
||||
考虑重新组织导航栏
|
||||
- 产品购买
|
||||
- 提取 IP
|
||||
- 业务场景
|
||||
- 帮助中心
|
||||
- 大客户定制
|
||||
|
||||
购买与提取手机端优化，尽量一页展示全部
|
||||
|
||||
全部替换封装时间范围组件，检查结束时间字段手机端适配问题（需要尾部对齐）
|
||||
|
||||
迁移到 tanstack form
|
||||
|
||||
页尾链接完善跳转地址
|
||||
|
||||
树组件优化
|
||||
|
||||
### 架构改进
|
||||
|
||||
考虑使用 swr 或 react query 来代替直接的服务端 react cache 缓存以及客户端 zustand 缓存，以将服务端请求的数据能够水合到客户端，避免重复请求
|
||||
|
||||
### 需要确认
|
||||
|
||||
页面内操作是否需要关联到 url 上，以在使用后退功能时返回到上一次操作
|
||||
|
||||
开发环境搭建指南：
|
||||
1. 环境前置要求
|
||||
首先确保你的电脑安装了以下基础环境：
|
||||
- Node.js：建议 v18.17.0+（Bun 会自带 Node 兼容层，但基础环境仍需）
|
||||
- Bun：项目指定版本 bun@1.3.2（核心包管理器 / 运行时）
|
||||
- Git：用于版本控制
|
||||
代码编辑器：推荐 VS Code（并安装以下插件）：
|
||||
- TypeScript React Plugin (vscode-typescript-nextjs-plugin)
|
||||
- ESLint
|
||||
- Tailwind CSS IntelliSense
|
||||
|
||||
使用方式：
|
||||
1. 拉取本项目，安装依赖包 bun install
|
||||
2. 创建环境变量文件 .env，复制 .env.example 中的内容到 .env，并根据实际情况修改
|
||||
3. 运行 bun run dev
|
||||
4. 上传代码到git master分支上直接使用vscode上传或者git命令：
|
||||
#### 添加所有文件
|
||||
- git add .
|
||||
#### 查看文件状态
|
||||
- git status
|
||||
#### 提交到本地仓库
|
||||
- git commit -m "提交说明"
|
||||
#### 推送到远程仓库
|
||||
- git push -u origin master
|
||||
|
||||
#### 确保已配置Git用户信息：
|
||||
- git config --global user.name "你的用户名"
|
||||
- git config --global user.email "你的邮箱"
|
||||
|
||||
#### 如果是需要打版本 构建到Docker命令 (命令已经整理完毕已经写好了publish.ps1文件脚本)so：
|
||||
只需要终端执行./publish.ps1 <版本号>
|
||||
|
||||
##### 然后在https://43.226.58.254:53000/lanhu/web 当前项目的页面点击 发布 --- 发布最新版本
|
||||
|
||||
#### 上传到线上操作
|
||||
|
||||
#### 目录结构
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
├── node_modules/ # 项目依赖包
|
||||
├── public/ # 静态资源（如 favicon、图片等，可直接通过根路径访问）
|
||||
├── src/ # 源代码目录
|
||||
@@ -117,208 +61,73 @@
|
||||
├── publish.ps1 # PowerShell 发布脚本
|
||||
├── README.md # 项目说明文档
|
||||
└── tsconfig.json # TypeScript 配置
|
||||
```
|
||||
|
||||
## 技术栈
|
||||
| 类别 | 场景/库名 | 推荐方案/用途 |
|
||||
| :--- | :--- | :--- |
|
||||
| **状态管理** | 简单跨组件通信 | React Context |
|
||||
| | 复杂全局状态 | Zustand + persist |
|
||||
| | 服务端状态 | TanStack Query |
|
||||
| | 表单状态 | React Hook Form |
|
||||
| | 路由状态 | Next.js 内置 (useSearchParams, useParams) |
|
||||
| **核心框架** | Next.js | 服务框架 (React 全栈框架) |
|
||||
| **UI / 样式体系** | shadcn/ui | UI 组件库 |
|
||||
| | Radix UI | 无样式基础 UI 组件原语 |
|
||||
| | Tailwind CSS | CSS 框架 (原子化 CSS) |
|
||||
| | lucide-react | 图标库 |
|
||||
| **表单与数据验证** | React Hook Form | 表单状态管理及验证 |
|
||||
| | Zod | 数据验证与类型推断 |
|
||||
| **数据管理与通信** | Zustand | 全局状态管理库 |
|
||||
| | TanStack Query | 服务端状态管理 (数据请求、缓存) |
|
||||
| | TanStack Table | 无头 UI 表格库 |
|
||||
| **图表可视化** | Recharts | 图表库 |
|
||||
| **工具库** | date-fns | 日期时间处理库 |
|
||||
| | qrcode | QR 码生成库 |
|
||||
|
||||
## 项目使用到的技术栈：
|
||||
#### 核心框架：
|
||||
- nextjs 服务框架 https://nextjs.org/docs
|
||||
- react 前端 UI 框架 https://react.dev/learn
|
||||
- typescript (ts) 类型安全的 JavaScript 超集 https://www.typescriptlang.org/docs/
|
||||
- bun 包管理器 / 运行时 https://bun.sh/docs
|
||||
## 搭建开发环境
|
||||
|
||||
#### UI / 样式体系：
|
||||
- shadcn UI 库 https://ui.shadcn.com/docs/installation
|
||||
- radix-ui 无样式的基础 UI 组件库（shadcn 依赖） https://www.radix-ui.com/docs/primitives/overview/introduction
|
||||
- tailwindcss css 库 https://tailwindcss.com/
|
||||
- lucide 图标库 https://lucide.dev/icons/?focus=
|
||||
- next-themes 主题切换（暗黑 / 亮色模式） https://github.com/pacocoursey/next-themes
|
||||
项目基于 bun 运行，bun 是一个 typescript 原生的运行时环境，用于代替 nodejs，可以带来更高的性能提升。
|
||||
|
||||
#### 表单与数据验证：
|
||||
- react-hook-form 表单处理库 https://react-hook-form.com/get-started
|
||||
- zod 表单验证库 https://zustand-demo.pmnd.rs/
|
||||
- date-fns 时间处理库 https://date-fns.org/
|
||||
1. 拉取项目：`git clone https://43.226.58.254:53000/lanhu/web`
|
||||
2. 安装依赖包：`bun install`
|
||||
3. 创建环境变量文件 .env，复制 .env.example 中的内容到 .env，并根据实际情况修改
|
||||
4. 运行项目 `bun run dev`
|
||||
|
||||
#### 数据管理与通信：
|
||||
- zustand 状态管理库 https://zustand-demo.pmnd.rs/
|
||||
- React Context
|
||||
- tanstack/react-table 表格处理库 https://tanstack.com/table/latest
|
||||
- recharts 图表可视化库 https://recharts.org/en-US/
|
||||
## 构建项目 & 版本管理
|
||||
|
||||
#### 工程化与开发工具：
|
||||
- eslint 代码检查工具 https://eslint.org/docs/latest/
|
||||
- husky Git 钩子工具 https://typicode.github.io/husky/
|
||||
- mdx 支持在 React 中编写 Markdown https://mdxjs.com/docs/
|
||||
- remark-gfm Markdown GFM 语法支持 https://github.com/remarkjs/remark-gfm
|
||||
1. 在 package.json 文件中修改版本号
|
||||
2. 构建并上传镜像, 终端运行 `./publish.ps1 <版本号>`
|
||||
3. 终端执行成功后在 `https://43.226.58.254:53000/lanhu/web` 发布最新版本
|
||||
|
||||
#### 功能类库：
|
||||
- sonner 轻量级通知组件 https://sonner.emilkowal.ski/
|
||||
- react-day-picker 日期选择器组件 https://react-day-picker.js.org/
|
||||
- qrcode QR 码生成库 https://github.com/soldair/node-qrcode
|
||||
- clsx/tailwind-merge CSS 类名处理工具 https://github.com/lukeed/clsx
|
||||
生产环境的项目部署通过单独的部署脚本进行管理，前端开发上线只需要构建以及发布版本，无需考虑部署问题。
|
||||
|
||||
#### 部署与运维：
|
||||
- Docker 容器化部署运行环境 https://www.docker.com/
|
||||
- publish.ps1 代码同步后使用运行 .\publish.ps1 v1.1.2 后面是版本号就可以直接运行文件中的脚本上传到服务器上
|
||||
## 开发规范 & 主要业务逻辑
|
||||
|
||||
#### 项目UI原型图地址：
|
||||
- https://lanhuapp.com/link/#/invite?sid=lxgnSyga 蓝湖原型图
|
||||
原型图：https://lanhuapp.com/link/#/invite?sid=lxgnSyga
|
||||
|
||||
#### 前端核心概念与实现：
|
||||
1. 组件化开发模式：组件复用模式
|
||||
2. 展示组件：纯 UI 组件，
|
||||
3. 容器组件：处理业务逻辑和数据获取 (页面级组件、数据获取组件)
|
||||
4. 高阶组件 (HOC)：用于横切关注点（例如：权限验证、日志记录、数据获取）
|
||||
5. 自定义 Hooks：封装可复用的逻辑（如 useAuth、usePayment、useTheme）
|
||||
### 快速创建前台新页面
|
||||
|
||||
#### 数据流与状态管理： 组件间通信方式
|
||||
wrap.tsx ：新页面间距复用组件
|
||||
page.tsx：新页面统一布局
|
||||
stores：共享状态组件
|
||||
|
||||
### 数据流与状态管理： 组件间通信方式
|
||||
|
||||
- 通信方式：Props 父传子 / 回调函数 子传父 / Context 跨组件 useContext() / Zustand Store 全局状态管理useStore() / URL 参数 页面间状态共享 useSearchParams()
|
||||
路由与导航: 路由使用的Next.js App Router 架构 Server Actions 实现，
|
||||
导航实现：
|
||||
路由与导航: 路由使用的Next.js App Router 架构 Server Actions 实现。
|
||||
|
||||
#### 客户端导航
|
||||
import Link from 'next/link';
|
||||
import { useRouter } from 'next/navigation';
|
||||
### 认证与权限控制：登录流程-路由守卫(中间件)
|
||||
|
||||
#### 声明式导航
|
||||
```jsx
|
||||
<Link href="/dashboard" className="nav-link">
|
||||
仪表盘
|
||||
</Link>
|
||||
```
|
||||
### 支付流程实现： 支付二维码生成
|
||||
|
||||
#### 编程式导航
|
||||
```jsx
|
||||
const router = useRouter();
|
||||
const handleNavigate = () => {
|
||||
router.push('/orders?status=pending');
|
||||
};
|
||||
```
|
||||
#### 页面布局与样式：TailwindCSS 布局系统，响应式设计
|
||||
### SSE 支付状态监听
|
||||
|
||||
#### 表单处理与验证：React Hook Form + Zod 集成
|
||||
```jsx
|
||||
import { useForm } from 'react-hook-form';
|
||||
import { zodResolver } from '@hookform/resolvers/zod';
|
||||
import { z } from 'zod';
|
||||
## 注意事项
|
||||
|
||||
const schema = z.object({
|
||||
email: z.string().email('请输入有效的邮箱地址'),
|
||||
password: z.string().min(6, '密码至少6位'),
|
||||
});
|
||||
|
||||
type FormData = z.infer<typeof schema>;
|
||||
|
||||
const LoginForm = () => {
|
||||
const { register, handleSubmit, formState: { errors } } = useForm<FormData>({
|
||||
resolver: zodResolver(schema)
|
||||
});
|
||||
|
||||
const onSubmit = (data: FormData) => {
|
||||
// 处理登录逻辑
|
||||
};
|
||||
|
||||
return (
|
||||
<form onSubmit={handleSubmit(onSubmit)}>
|
||||
<input {...register('email')} />
|
||||
{errors.email && <span>{errors.email.message}</span>}
|
||||
|
||||
<input type="password" {...register('password')} />
|
||||
{errors.password && <span>{errors.password.message}</span>}
|
||||
|
||||
<button type="submit">登录</button>
|
||||
</form>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
#### 数据展示与操作：TanStack Table 表格，Recharts 图表
|
||||
|
||||
#### 认证与权限控制：登录流程-路由守卫(中间件)
|
||||
|
||||
#### 支付流程实现： 支付二维码生成
|
||||
```jsx
|
||||
import QRCode from 'qrcode';
|
||||
|
||||
const generatePaymentQR = async (paymentUrl: string) => {
|
||||
try {
|
||||
const qrDataUrl = await QRCode.toDataURL(paymentUrl);
|
||||
return qrDataUrl;
|
||||
} catch (err) {
|
||||
console.error('二维码生成失败', err);
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
#### SSE 支付状态监听：
|
||||
```jsx
|
||||
const usePaymentStatus = (orderId: string) => {
|
||||
const [status, setStatus] = useState('pending');
|
||||
|
||||
useEffect(() => {
|
||||
const eventSource = new EventSource(`/api/sse/payment/${orderId}`);
|
||||
|
||||
eventSource.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
setStatus(data.status);
|
||||
|
||||
if (data.status === 'success' || data.status === 'failed') {
|
||||
eventSource.close();
|
||||
}
|
||||
};
|
||||
|
||||
return () => eventSource.close();
|
||||
}, [orderId]);
|
||||
|
||||
return status;
|
||||
};
|
||||
```
|
||||
#### 缓存策略：Next.js 缓存机制 使用 cache 函数缓存数据
|
||||
|
||||
#### 城市组件树
|
||||
|
||||
|
||||
#### 开发规范：
|
||||
- 组件文件：PascalCase.tsx (如 Button.tsx)
|
||||
- 工具函数：camelCase.ts (如 formatDate.ts)
|
||||
- 常量：UPPER_SNAKE_CASE
|
||||
|
||||
#### 性能优化策略：
|
||||
#### 代码层面：
|
||||
- 使用 React.memo 避免不必要的重渲染
|
||||
- 使用 useMemo/useCallback 缓存计算和函数
|
||||
- 图片使用 Next.js Image 组件自动优化
|
||||
|
||||
#### 构建层面：
|
||||
- 动态导入 (next/dynamic) 实现代码分割
|
||||
- 使用 Turbopack 加速开发构建
|
||||
- Tree Shaking 移除未使用代码
|
||||
|
||||
#### 数据层面：
|
||||
- 使用 Next.js 缓存策略 (cache, revalidate)
|
||||
- API 响应数据压缩
|
||||
- 使用 SWR 或 TanStack Query 管理服务端状态
|
||||
|
||||
#### 前端安全措施：
|
||||
- XSS 防护：React 默认转义，避免 dangerouslySetInnerHTML
|
||||
- CSRF 防护：使用 SameSite Cookie 和 CSRF Token
|
||||
- 敏感信息：不在前端存储密码等敏感信息
|
||||
- HTTPS：生产环境强制使用
|
||||
|
||||
#### 认证：
|
||||
- Token 存储在 httpOnly Cookie 或内存中
|
||||
- 使用 refresh token 轮换机制
|
||||
- 实现请求重试和 token 自动刷新
|
||||
|
||||
#### 状态管理选择：
|
||||
|
||||
| 场景 | 推荐方案 | 原因 |
|
||||
|------|----------|------|
|
||||
| 简单跨组件通信 | React Context | 内置、轻量、适合低频更新 |
|
||||
| 复杂全局状态 | Zustand + persist | 简单 API、支持持久化、中间件 |
|
||||
| 服务端状态 | TanStack Query | 缓存、重试、轮询、分页 |
|
||||
| 表单状态 | React Hook Form | 高性能、少渲染、验证集成 |
|
||||
| 路由状态 | Next.js 内置 | useSearchParams、useParams |
|
||||
- 动态导入 (next/dynamic) 实现纯客户端组件
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user