From 10316307125138b3f4bbfe6d20b6de3fe4026c62 Mon Sep 17 00:00:00 2001 From: Eamon-meng <17516219072@163.com> Date: Tue, 10 Mar 2026 17:06:54 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0README.md=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 291 ++++++++++-------------------------------------------- 1 file changed, 50 insertions(+), 241 deletions(-) diff --git a/README.md b/README.md index fe6a05e..41986e5 100644 --- a/README.md +++ b/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 - - 仪表盘 - -``` +### 支付流程实现： 支付二维码生成 -#### 编程式导航 -```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; - -const LoginForm = () => { - const { register, handleSubmit, formState: { errors } } = useForm({ - resolver: zodResolver(schema) - }); - - const onSubmit = (data: FormData) => { - // 处理登录逻辑 - }; - - return ( -
- - {errors.email && {errors.email.message}} - - - {errors.password && {errors.password.message}} - - -
- ); -}; -``` - -#### 数据展示与操作：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) 实现纯客户端组件 +