启动后端服务

后端使用 Kubernetes 部署，需要先启动后端集群（参考后端仓库的部署文档）。
配置端口转发

将后端 Envoy Gateway 转发到本地：
```
kubectl port-forward -n juwan svc/envoy-gateway 8080:80
```

配置环境变量

创建 .env.local 文件：

# 后端 API 地址（通过 kubectl port-forward 转发）
NEXT_PUBLIC_BACKEND_URL=http://localhost:8080

启动前端开发服务器
```
pnpm dev
```
访问 http://localhost:3000

工作原理：
- 前端向 /api/* 发起请求
- Next.js dev server 自动将请求代理到 http://localhost:8080/api/*
- 后端通过 kubectl port-forward 接收请求
- 无需修改前端代码中的 API 调用路径

其他命令

# 类型检查
pnpm typecheck

# 代码检查
pnpm lint

# 代码格式化
pnpm format

# 运行测试
pnpm test

# 完整检查（类型 + lint + 格式）
pnpm check

# 生产构建
pnpm build

# 启动生产服务器
pnpm start

项目结构

juwan-frontend/
├── app/                    # Next.js App Router 页面
│   ├── (auth)/            # 认证相关页面（注册/登录/找回密码）
│   ├── (account)/         # 账户相关页面（个人中心/认证申请）
│   ├── (order)/           # 订单相关页面（下单/聊天/评价/纠纷）
│   └── (main)/            # 主要页面（首页/搜索/打手/店铺）
├── components/            # 可复用组件
├── lib/                   # 工具函数和类型定义
│   ├── api/              # API 调用函数
│   ├── domain/           # 业务逻辑（状态机等）
│   ├── types.ts          # 核心类型定义
│   ├── errors.ts         # 错误处理
│   └── decision.ts       # 权限决策
├── store/                 # Zustand 状态管理
├── tests/                 # 测试文件
└── public/               # 静态资源

API 代理配置说明

开发环境下，Next.js 会自动将 /api/* 请求代理到后端：

// next.config.ts
async rewrites() {
  if (process.env.NODE_ENV !== 'development') {
    return []
  }
  const backendUrl = process.env.NEXT_PUBLIC_BACKEND_URL || 'http://localhost:8080'
  return [
    {
      source: '/api/:path*',
      destination: `${backendUrl}/api/:path*`,
    },
  ]
}

优点：

前端代码无需关心后端地址
避免 CORS 问题（同源请求）
Cookie 自动携带
开发/生产环境无缝切换

环境变量

变量名	说明	默认值
`NEXT_PUBLIC_BACKEND_URL`	后端 API 地址（仅开发环境生效）	`http://localhost:8080`

注意：

此变量仅在开发环境（pnpm dev）生效，用于配置 API 代理目标
生产环境不使用此变量，前后端通过 Envoy Gateway 统一路由

部署

构建 Docker 镜像

docker build -t juwan-frontend:latest .
docker tag juwan-frontend:latest 103.236.53.208:4418/library/juwan-frontend:latest
docker push 103.236.53.208:4418/library/juwan-frontend:latest

部署到 Kubernetes

kubectl apply -f deploy/k8s/frontend.yaml

开发规范

使用 TypeScript 严格模式
遵循 ESLint 规则（pnpm lint）
提交前运行 pnpm check 确保代码质量
所有 API 调用必须有类型定义
组件使用 shadcn/ui 风格

常见问题

Q: 本地开发如何连后端？

A: 按照开发环境设置里的步骤完成 kubectl port-forward，并在 .env.local 配置 NEXT_PUBLIC_BACKEND_URL。前端统一请求 /api/*，开发环境由 Next.js 代理到本地转发端口。

Q: 后端连接失败怎么办？

A: 检查以下几点：

后端 K8s 集群是否正常运行
kubectl port-forward 是否在运行
.env.local 中的 NEXT_PUBLIC_BACKEND_URL 是否正确
浏览器控制台是否有 CORS 错误

Q: 如何添加新的 API？

在 lib/types.ts 定义类型
在 lib/api/ 创建 API 函数
在 store/ 中调用 API

README.md Unescape Escape

聚玩前端

技术栈

开发环境设置

前置要求

安装依赖

连接后端开发