diff --git a/README.md b/README.md index 66a846b..4351cff 100644 --- a/README.md +++ b/README.md @@ -45,83 +45,125 @@ 页面内操作是否需要关联到 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 +- Prettier +2. 安装 Bun 参照 https://bun.com/docs/installation#windows 官方文档命令 -核心框架: + +使用方式: +1. 拉取本项目 +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 当前项目的页面点击 发布 --- 发布最新版本 + +#### 上传到线上操作 + + +## 项目使用到的技术栈: +#### 核心框架: - 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 / 样式体系: +#### 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 -表单与数据验证: +#### 表单与数据验证: - react-hook-form 表单处理库 https://react-hook-form.com/get-started - zod 表单验证库 https://zustand-demo.pmnd.rs/ - date-fns 时间处理库 https://date-fns.org/ -数据管理与通信: +#### 数据管理与通信: - 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 -功能类库: +#### 功能类库: - 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原型图地址: +#### 项目UI原型图地址: - https://lanhuapp.com/link/#/invite?sid=lxgnSyga 蓝湖原型图 -前端核心概念与实现: -组件化开发模式:组件复用模式 -展示组件:纯 UI 组件, -容器组件:处理业务逻辑和数据获取 (页面级组件、数据获取组件) -高阶组件 (HOC):用于横切关注点(例如:权限验证、日志记录、数据获取) -自定义 Hooks:封装可复用的逻辑(如 useAuth、usePayment、useTheme) +#### 前端核心概念与实现: +1. 组件化开发模式:组件复用模式 +2. 展示组件:纯 UI 组件, +3. 容器组件:处理业务逻辑和数据获取 (页面级组件、数据获取组件) +4. 高阶组件 (HOC):用于横切关注点(例如:权限验证、日志记录、数据获取) +5. 自定义 Hooks:封装可复用的逻辑(如 useAuth、usePayment、useTheme) -数据流与状态管理: 组件间通信方式 +#### 数据流与状态管理: 组件间通信方式 -通信方式:Props 父传子 / 回调函数 子传父 / Context 跨组件 useContext() / Zustand Store 全局状态管理useStore() / URL 参数 页面间状态共享 useSearchParams() +- 通信方式:Props 父传子 / 回调函数 子传父 / Context 跨组件 useContext() / Zustand Store 全局状态管理useStore() / URL 参数 页面间状态共享 useSearchParams() 路由与导航: 路由使用的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 布局系统,响应式设计 -页面布局与样式:TailwindCSS 布局系统,响应式设计 - -表单处理与验证:React Hook Form + Zod 集成 - +#### 表单处理与验证:React Hook Form + Zod 集成 +```jsx import { useForm } from 'react-hook-form'; import { zodResolver } from '@hookform/resolvers/zod'; import { z } from 'zod'; @@ -154,13 +196,14 @@ const LoginForm = () => { ); }; +``` -数据展示与操作:TanStack Table 表格,Recharts 图表 +#### 数据展示与操作:TanStack Table 表格,Recharts 图表 -认证与权限控制:登录流程-路由守卫(中间件) - -支付流程实现: 支付二维码生成 +#### 认证与权限控制:登录流程-路由守卫(中间件) +#### 支付流程实现: 支付二维码生成 +```jsx import QRCode from 'qrcode'; const generatePaymentQR = async (paymentUrl: string) => { @@ -171,7 +214,10 @@ const generatePaymentQR = async (paymentUrl: string) => { console.error('二维码生成失败', err); } }; -SSE 支付状态监听: +``` + +#### SSE 支付状态监听: +```jsx const usePaymentStatus = (orderId: string) => { const [status, setStatus] = useState('pending'); @@ -192,113 +238,57 @@ const usePaymentStatus = (orderId: string) => { return status; }; +``` +#### 缓存策略:Next.js 缓存机制 使用 cache 函数缓存数据 -缓存策略:Next.js 缓存机制 使用 cache 函数缓存数据 - -城市组件树 +#### 城市组件树 -开发规范: -组件文件:PascalCase.tsx (如 Button.tsx) -工具函数:camelCase.ts (如 formatDate.ts) -常量:UPPER_SNAKE_CASE +#### 开发规范: +- 组件文件:PascalCase.tsx (如 Button.tsx) +- 工具函数:camelCase.ts (如 formatDate.ts) +- 常量:UPPER_SNAKE_CASE +#### 性能优化策略: +#### 代码层面: +- 使用 React.memo 避免不必要的重渲染 +- 使用 useMemo/useCallback 缓存计算和函数 +- 图片使用 Next.js Image 组件自动优化 +#### 构建层面: +- 动态导入 (next/dynamic) 实现代码分割 +- 使用 Turbopack 加速开发构建 +- Tree Shaking 移除未使用代码 -TypeScript 严格模式: -{ - "compilerOptions": { - "strict": true, - "noUncheckedIndexedAccess": true, - "noImplicitReturns": true - } -} +#### 数据层面: +- 使用 Next.js 缓存策略 (cache, revalidate) +- API 响应数据压缩 +- 使用 SWR 或 TanStack Query 管理服务端状态 +#### 前端安全措施: +- XSS 防护:React 默认转义,避免 dangerouslySetInnerHTML +- CSRF 防护:使用 SameSite Cookie 和 CSRF Token +- 敏感信息:不在前端存储密码等敏感信息 +- HTTPS:生产环境强制使用 -性能优化策略: -代码层面: -使用 React.memo 避免不必要的重渲染 +#### 认证: +- Token 存储在 httpOnly Cookie 或内存中 +- 使用 refresh token 轮换机制 +- 实现请求重试和 token 自动刷新 -使用 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 -服务端状态 TanStack Query -表单状态 React Hook Form +| 场景 | 推荐方案 | 原因 | +|------|----------|------| +| 简单跨组件通信 | React Context | 内置、轻量、适合低频更新 | +| 复杂全局状态 | Zustand + persist | 简单 API、支持持久化、中间件 | +| 服务端状态 | TanStack Query | 缓存、重试、轮询、分页 | +| 表单状态 | React Hook Form | 高性能、少渲染、验证集成 | +| 路由状态 | Next.js 内置 | useSearchParams、useParams | -总结: -- 核心框架:Next.js 16 + React 19 + TypeScript 5,使用 Bun 作为包管理器和运行时 -- UI / 样式体系:shadcn UI(基于 radix-ui) + TailwindCSS 4 + Lucide 图标 -- 功能类库:表单处理 (react-hook-form+zod)、状态管理 (zustand)、表格 (tanstack/react-table)、时间处理 (date-fns)、图表 (recharts) -- 工程化工具:ESLint、Husky、TypeScript 类型检查,支持 MDX 和 Turbopack 构建 - -代码设计到的技术: -技术库:next.js react,ts -路由:next.JS框架里的路由,actions文件 -传参:父传子/子传父/状态共享 -状态共享:使用的react的createContext和useContext以及zustand的useStore和persist -缓存功能:next.js的use cache -页面布局:css库使用tailwindcss 包含flex和grid布局,shadcn UI,Lucide 图标 -权限控制,网站登录时http细节-访问令牌/token,封装api接口,静态页面,页面导航功能,img, -sse处理方式检查支付状态,支付二维码(qrcode),Docker构建脚本,bun包处理器,菜单,页面路由导航,表格,图表(recharts) -第三方支付(支付宝/微信,渠道微信/商福通) -购买套餐流程,套餐计费, -从访问网站首页布局渲染-菜单栏/-跳转登录页面-完成登录后-进入后台 -后台布局-侧边栏伸缩/模块的页面转换-img渲染/表单校验/路由/图标/表格/购买套餐流程/支付渠道/支付成功/生成订单提取Ip后的维护记录 -城市组件树, -开发环境搭建指南: -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 -- Prettier -2. 安装 Bun 参照 https://bun.com/docs/installation#windows 官方文档命令 - -.env文件---开发环境配置文件 - -