TODO
分离公共 api 接口 env 定义
统一前端基础库（类型，api）
购买页固定套餐
树组件优化
目录结构
├── node_modules/ # 项目依赖包
├── public/ # 静态资源（如 favicon、图片等，可直接通过根路径访问）
├── src/ # 源代码目录
│ ├── actions/ # 服务端操作或 API 逻辑（如 Server Actions）
│ ├── app/ # Next.js 13+ App Router 目录，存放页面、布局、路由等
| | ├── (api)/ # API 路由目录
| | ├── (auth)/ # 认证相关页面
| | ├── (home)/ # 首页模块
| | ├── admin/ # 管理后台模块
| | ├── effects.tsx # 全局副作用/状态管理（如 Redux、SWR 初始化）
| | ├── favicon.ico # 网站图标
| | ├── globals.css # 全局样式
| | └── layout.tsx # 根布局组件（所有页面共享的布局结构）
| |
│ ├── assets/ # 项目资源文件（如图片、字体、样式等）
│ ├── components/ # 可复用的 React 组件
│ ├── lib/ # 工具函数、配置、服务等
│ ├── mdx-components.tsx # MDX 组件配置
│ └── proxy.ts # 代理配置（如 API 代理）
├── .dockerignore # Docker 忽略文件
├── .env # 环境变量文件
├── .gitignore # Git 忽略文件
├── .npmrc # npm 配置
├── bun.lock # Bun 包管理器锁文件
├── components.json # 组件库配置（如 shadcn/ui）
├── Dockerfile # Docker 构建配置
├── eslint.config.mjs # ESLint 代码检查配置
├── next-env.d.ts # Next.js 类型声明
├── next.config.ts # Next.js 配置文件
├── package.json # 项目依赖和脚本
├── postcss.config.mjs # PostCSS 配置
├── 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 码生成库 |
搭建开发环境
项目基于 bun 运行，bun 是一个 typescript 原生的运行时环境，用于代替 nodejs，可以带来更高的性能提升。
- 拉取项目：
git clone https://43.226.58.254:53000/lanhu/web - 安装依赖包：
bun install - 创建环境变量文件 .env，复制 .env.example 中的内容到 .env，并根据实际情况修改
- 运行项目
bun run dev
构建项目 & 版本管理
- 在 package.json 文件中修改版本号
- 构建并上传镜像, 终端运行
./publish.ps1 <版本号> - 终端执行成功后在
https://43.226.58.254:53000/lanhu/web发布最新版本
生产环境的项目部署通过单独的部署脚本进行管理，前端开发上线只需要构建以及发布版本，无需考虑部署问题。
开发规范 & 主要业务逻辑
原型图：https://lanhuapp.com/link/#/invite?sid=lxgnSyga
快速创建前台新页面
wrap.tsx ：新页面间距复用组件 page.tsx：新页面统一布局 stores：共享状态组件
数据流与状态管理： 组件间通信方式
- 通信方式：Props 父传子 / 回调函数 子传父 / Context 跨组件 useContext() / Zustand Store 全局状态管理useStore() / URL 参数 页面间状态共享 useSearchParams() 路由与导航: 路由使用的Next.js App Router 架构 Server Actions 实现。
认证与权限控制：登录流程-路由守卫(中间件)
支付流程实现： 支付二维码生成
SSE 支付状态监听
注意事项
- 图片使用 Next.js Image 组件自动优化
- 动态导入 (next/dynamic) 实现纯客户端组件