305 lines
9.3 KiB
Markdown
305 lines
9.3 KiB
Markdown
## TODO
|
||
|
||
分离公共 api 接口 env 定义
|
||
|
||
统一前端基础库（类型，api）
|
||
|
||
购买页固定套餐
|
||
|
||
优惠问题
|
||
|
||
### 禁止直接依赖 form
|
||
|
||
`\[(.*,)?form(,.*)?\]`
|
||
|
||
### 次要
|
||
|
||
业务定制页面每月需求用量，可选项需要确认是否合理
|
||
|
||
页头高度降低
|
||
|
||
帮助中心文档优化
|
||
|
||
考虑重新组织导航栏
|
||
- 产品购买
|
||
- 提取 IP
|
||
- 业务场景
|
||
- 帮助中心
|
||
- 大客户定制
|
||
|
||
购买与提取手机端优化，尽量一页展示全部
|
||
|
||
全部替换封装时间范围组件，检查结束时间字段手机端适配问题（需要尾部对齐）
|
||
|
||
迁移到 tanstack form
|
||
|
||
页尾链接完善跳转地址
|
||
|
||
树组件优化
|
||
|
||
### 架构改进
|
||
|
||
考虑使用 swr 或 react query 来代替直接的服务端 react cache 缓存以及客户端 zustand 缓存，以将服务端请求的数据能够水合到客户端，避免重复请求
|
||
|
||
### 需要确认
|
||
|
||
页面内操作是否需要关联到 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文件---开发环境配置文件
|
||
|
||
|