web/README.md

TODO

分离公共 api 接口 env 定义

统一前端基础库（类型，api）

购买页固定套餐

优惠问题

禁止直接依赖 form

\[(.*,)?form(,.*)?\]

次要

业务定制页面每月需求用量，可选项需要确认是否合理

页头高度降低

帮助中心文档优化

考虑重新组织导航栏

• 产品购买
• 提取 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
• 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 / 样式体系：

• 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 蓝湖原型图

前端核心概念与实现：

1. 组件化开发模式：组件复用模式
2. 展示组件：纯 UI 组件，
3. 容器组件：处理业务逻辑和数据获取 (页面级组件、数据获取组件)
4. 高阶组件 (HOC)：用于横切关注点（例如：权限验证、日志记录、数据获取）
5. 自定义 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

性能优化策略：

代码层面：

• 使用 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