chore(dev): add /api proxy and docs

2026-02-28 10:33:50 +08:00
parent e9b0dced0e
commit 8589dbc16b
3 changed files with 216 additions and 3 deletions
@@ -0,0 +1,196 @@
+# 聚玩前端
+
+基于 Next.js 15 的游戏代练平台前端应用。
+
+## 技术栈
+
+- **框架**: Next.js 15 (App Router)
+- **语言**: TypeScript
+- **样式**: Tailwind CSS 4
+- **状态管理**: Zustand
+- **表单**: React Hook Form + Zod
+- **UI 组件**: Radix UI + shadcn/ui
+- **测试**: Vitest
+
+## 开发环境设置
+
+### 前置要求
+
+- Node.js 20+
+- pnpm 9+
+
+### 安装依赖
+
+```bash
+pnpm install
+```
+
+### 连接后端开发
+
+1. **启动后端服务**
+
+   后端使用 Kubernetes 部署，需要先启动后端集群（参考后端仓库的部署文档）。
+
+2. **配置端口转发**
+
+   将后端 Envoy Gateway 转发到本地：
+
+   ```bash
+   kubectl port-forward -n juwan svc/envoy-gateway 8080:80
+   ```
+
+3. **配置环境变量**
+
+   创建 `.env.local` 文件：
+
+   ```bash
+   # 后端 API 地址（通过 kubectl port-forward 转发）
+   NEXT_PUBLIC_BACKEND_URL=http://localhost:8080
+
+   ```
+
+4. **启动前端开发服务器**
+
+   ```bash
+   pnpm dev
+   ```
+
+   访问 http://localhost:3000
+
+   **工作原理**：
+   - 前端向 `/api/*` 发起请求
+   - Next.js dev server 自动将请求代理到 `http://localhost:8080/api/*`
+   - 后端通过 `kubectl port-forward` 接收请求
+   - 无需修改前端代码中的 API 调用路径
+
+### 其他命令
+
+```bash
+# 类型检查
+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/*` 请求代理到后端：
+
+```typescript
+// 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 镜像
+
+```bash
+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
+
+```bash
+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: 检查以下几点：
+
+1. 后端 K8s 集群是否正常运行
+2. `kubectl port-forward` 是否在运行
+3. `.env.local` 中的 `NEXT_PUBLIC_BACKEND_URL` 是否正确
+4. 浏览器控制台是否有 CORS 错误
+
+### Q: 如何添加新的 API？
+
+A:
+
+1. 在 `lib/types.ts` 定义类型
+2. 在 `lib/api/` 创建 API 函数
+3. 在 `store/` 中调用 API
@@ -1,5 +1,22 @@
 import type { NextConfig } from "next"

-const nextConfig: NextConfig = {}
+const nextConfig: NextConfig = {
+  async rewrites() {
+    // 仅在开发环境启用 API 代理
+    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*`,
+      },
+    ]
+  },
+}

 export default nextConfig
@@ -1,7 +1,7 @@
 # 聚玩 (Juwan) API 设计文档

 ## 1. 文档概述
-本文档为“聚玩”游戏陪玩平台的后端 API 设计规范，旨在指导后端开发人员实现真实的 API 接口，以替换当前纯前端的 Mock 系统。
+本文档为“聚玩”游戏陪玩平台的后端 API 设计规范，用于前后端联调与上线部署。
 - **基础路径 (Base URL)**: `/api/v1`
 - **数据格式**: `application/json`

@@ -10,7 +10,7 @@
 ### 2.1 认证与授权 (Auth)

 - 采用 Cookie `JToken` 进行认证（Phase 2 接入后端时实现）。
- Phase 1 阶段仅为纯前端 Mock，不涉及真实后端交互。
+- 当前前端仍以本地数据实现为主，不涉及真实后端交互；接入后端后会删除本地数据实现。
 - 接口权限标识：
  - 🔒：需要登录认证。
  - 🛡️：需要管理员权限。