blank/frontend-v2

Frontend V2 - Next.js 14 + SuperJSON

基于 Next.js 14 App Router 构建的前端应用，使用 SuperJSON 实现 JSON 序列化/反序列化。

技术栈

• Next.js 14.2 - App Router + Server Components
• React 18 - Concurrent Features
• TypeScript - 类型安全
• Tailwind CSS - 样式框架
• SuperJSON - JSON 序列化增强
• 自定义 Hooks - 数据获取和状态管理

项目结构

frontend-v2/
├── app/                    # Next.js App Router
│   ├── auth/              # 认证页面
│   │   └── page.tsx
│   ├── layout.tsx         # 根布局
│   ├── page.tsx           # 主页（聊天界面）
│   └── globals.css        # 全局样式
├── components/            # React 组件
│   ├── Header.tsx         # 页面头部
│   ├── ChatInput.tsx      # 聊天输入
│   ├── ChatMessage.tsx    # 聊天消息
│   └── ToolCallPanel.tsx  # 工具调用面板
├── lib/                   # 工具库
│   ├── api-client.ts      # API 客户端
│   ├── superjson.ts       # SuperJSON 配置
│   ├── react-query.tsx    # React Query 配置
│   └── hooks.ts           # 自定义 Hooks
├── public/                # 静态资源
├── package.json
├── tsconfig.json
├── tailwind.config.ts
├── next.config.js
└── README.md

安装依赖

cd frontend-v2
npm install
# 或
pnpm install
# 或
yarn install

配置环境变量

复制 .env.local.example 为 .env.local：

cp .env.local.example .env.local

编辑 .env.local，配置后端 API 地址：

BACKEND_URL=http://localhost:8080

启动开发服务器

npm run dev

应用将在 http://localhost:3000 启动。

构建生产版本

npm run build
npm start

API 集成

后端端点

端点	方法	说明
/api/health	GET	健康检查
/api/chat	POST	聊天（非流式）
/api/chat/stream	POST	聊天（SSE 流式）
/api/mcp/servers	GET	MCP 服务器列表
/api/mcp/tools	GET	MCP 工具列表
/api/auth/login	POST	用户登录
/api/auth/register	POST	用户注册
/api/auth/status	GET	认证状态

使用 API 客户端

import { apiClient } from '@/lib/api-client';

// 发送聊天消息
const response = await apiClient.chat('你好', []);

// 登录
const result = await apiClient.login('user@example.com', 'password');

// 获取 MCP 工具列表
const tools = await apiClient.listMcpTools();

使用自定义 Hooks

import { useChat, useAuth } from '@/lib/hooks';

function ChatComponent() {
  const { sendMessage, isLoading, response } = useChat();
  const { login, logout, isAuthenticated } = useAuth();

  // 发送消息
  const handleSend = () => {
    sendMessage('你好 AI', []);
  };

  return (
    // ...
  );
}

JSON 序列化 (SuperJSON)

SuperJSON 用于处理 Next.js Server Components 和 Client Components 之间的数据传输，支持：

• Date 对象
• undefined
• Set/Map
• Error 对象

• 自定义类实例

  import { serialize, deserialize } from '@/lib/superjson';
  
  // 序列化
  const json = serialize(data);
  
  // 反序列化
  const data = deserialize(json);
  

外网访问

如果需要通过外网访问后端 API，请配置 .env.local：

BACKEND_URL=https://d8d-ai-vscode-8080-{workspace_id}-{item_id}-template-6-group.dev.d8d.fun

开发说明

1. 端口配置：Next.js 默认使用 3000 端口，可在 package.json 中修改
2. API 代理：开发环境通过 next.config.js 的 rewrites 配置代理
3. 类型定义：所有 API 请求/响应都有完整的 TypeScript 类型定义