更新README.md文档

2026-03-03 13:23:18 +08:00
parent a2187adb05
commit 9201a819be
1 changed files with 258 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -44,3 +44,261 @@
 ### 需要确认

 页面内操作是否需要关联到 url 上，以在使用后退功能时返回到上一次操作
+
+项目使用到的技术栈：
+
+核心框架：
+- 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
+
+表单与数据验证：
+- 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原型图地址：
+- https://lanhuapp.com/link/#/invite?sid=lxgnSyga    蓝湖原型图
+
+前端核心概念与实现：
+组件化开发模式：组件复用模式
+展示组件：纯 UI 组件，
+容器组件：处理业务逻辑和数据获取  (页面级组件、数据获取组件)
+高阶组件 (HOC)：用于横切关注点（例如：权限验证、日志记录、数据获取）
+自定义 Hooks：封装可复用的逻辑（如 useAuth、usePayment、useTheme）
+
+数据流与状态管理： 组件间通信方式
+
+通信方式：Props 父传子 / 回调函数 子传父 / Context 跨组件 useContext() / Zustand Store 全局状态管理useStore() / URL 参数 页面间状态共享 useSearchParams()
+路由与导航: 路由使用的Next.js App Router 架构 Server Actions  实现，
+导航实现：
+
+// 客户端导航
+import Link from 'next/link';
+import { useRouter } from 'next/navigation';
+
+// 声明式导航
+<Link href="/dashboard" className="nav-link">
+  仪表盘
+</Link>
+
+// 编程式导航
+const router = useRouter();
+const handleNavigate = () => {
+  router.push('/orders?status=pending');
+};
+
+页面布局与样式：TailwindCSS 布局系统，响应式设计
+
+表单处理与验证：React Hook Form + Zod 集成
+
+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 图表
+
+认证与权限控制：登录流程-路由守卫(中间件)
+
+支付流程实现： 支付二维码生成
+
+import QRCode from 'qrcode';
+
+const generatePaymentQR = async (paymentUrl: string) => {
+  try {
+    const qrDataUrl = await QRCode.toDataURL(paymentUrl);
+    return qrDataUrl;
+  } catch (err) {
+    console.error('二维码生成失败', err);
+  }
+};
+SSE 支付状态监听：
+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
+
+
+
+TypeScript 严格模式：
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true
+  }
+}
+
+
+性能优化策略：
+代码层面：
+使用 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
+服务端状态	    TanStack Query
+表单状态	    React Hook Form
+
+
+
+
+总结：
+- 核心框架：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文件---开发环境配置文件
+
+