114 lines
4.7 KiB
Markdown
114 lines
4.7 KiB
Markdown
## 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，可以带来更高的性能提升。
|
||
|
||
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) 实现纯客户端组件
|