web/README.md

## TODO

分离公共 api 接口 env 定义

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

购买页固定套餐

优惠问题

### 禁止直接依赖 form

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

### 次要

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

帮助中心文档优化

购买与提取手机端优化，尽量一页展示全部

全部替换封装时间范围组件，检查结束时间字段手机端适配问题（需要尾部对齐）

树组件优化

## 目录结构

```
├── 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，可以带来更高的性能提升。

1. 拉取项目：`git clone https://43.226.58.254:53000/lanhu/web`
2. 安装依赖包：`bun install`
3. 创建环境变量文件 .env，复制 .env.example 中的内容到 .env，并根据实际情况修改
4. 运行项目 `bun run dev`

## 构建项目 & 版本管理

1. 在 package.json 文件中修改版本号
2. 构建并上传镜像, 终端运行 `./publish.ps1 <版本号>`
3. 终端执行成功后在 `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) 实现纯客户端组件