@jahanxu/trellis 0.4.1

package/dist/templates/trellis/spec/roles/frontend-impl/api-integration.md

@@ -0,0 +1,565 @@
+# API 集成指南
+
+> Frontend 角色将原型 Mock API 替换为真实 API 的指南
+
+---
+
+## 核心原则
+
+API 集成的目标是：
+1. **定位准确** - 快速找到所有需要替换的 Mock API
+2. **类型安全** - 使用 TypeScript 确保 API 响应类型正确
+3. **错误处理** - 完善处理网络错误、业务错误
+4. **复用性强** - API 调用逻辑集中管理，便于维护
+
+---
+
+## 定位 Mock API
+
+### 1. 搜索 TODO 注释
+
+Designer 会用 TODO 注释标注需要替换的位置：
+
+```bash
+# 搜索所有需要替换的 Mock API
+grep -r "TODO:.*Frontend.*API" src/
+```
+
+**示例输出**：
+```
+src/pages/LoginPage.tsx:45:  // TODO: [Frontend] 替换为真实API调用 POST /api/auth/login
+src/pages/UserList.tsx:23:   // TODO: [Frontend] 替换为真实API调用 GET /api/users
+```
+
+### 2. 搜索 Mock 函数调用
+
+```bash
+# 搜索 mock 关键字
+grep -r "mock.*API\|\.mock\." src/
+```
+
+### 3. 检查 HANDOFF 文档
+
+Designer 的 HANDOFF.md 会列出所有需要替换的 API：
+
+```markdown
+## 需要Frontend补充的逻辑
+
+1. **API集成点**
+   - 文件：`LoginPage.tsx:45`
+   - Mock: `mockLoginAPI()`
+   - 真实API: `POST /api/auth/login`
+```
+
+---
+
+## API 客户端配置
+
+### 1. 创建 API 客户端
+
+使用 Axios 或 Fetch 封装统一的 API 客户端：
+
+```typescript
+// src/lib/api/client.ts
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+const baseURL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:3000';
+
+export const apiClient: AxiosInstance = axios.create({
+  baseURL,
+  timeout: 10000,
+  headers: {
+    'Content-Type': 'application/json',
+  },
+});
+
+// 请求拦截器：添加 token
+apiClient.interceptors.request.use(
+  (config) => {
+    const token = localStorage.getItem('auth_token');
+    if (token) {
+      config.headers.Authorization = `Bearer ${token}`;
+    }
+    return config;
+  },
+  (error) => Promise.reject(error)
+);
+
+// 响应拦截器：统一错误处理
+apiClient.interceptors.response.use(
+  (response) => response.data, // 直接返回 data
+  (error) => {
+    if (error.response?.status === 401) {
+      // Token 过期，跳转登录
+      localStorage.removeItem('auth_token');
+      window.location.href = '/login';
+    }
+    return Promise.reject(error);
+  }
+);
+```
+
+### 2. 环境变量配置
+
+```bash
+# .env.development
+VITE_API_BASE_URL=http://localhost:3000
+
+# .env.production
+VITE_API_BASE_URL=https://api.example.com
+```
+
+---
+
+## API 函数封装
+
+### 1. 按模块组织 API
+
+```
+src/lib/api/
+├── client.ts       # API 客户端配置
+├── auth.ts         # 认证相关 API
+├── user.ts         # 用户相关 API
+├── product.ts      # 产品相关 API
+└── index.ts        # 统一导出
+```
+
+### 2. 定义 API 函数
+
+```typescript
+// src/lib/api/auth.ts
+import { apiClient } from './client';
+import type { User } from '@/types/user';
+
+export interface LoginRequest {
+  email: string;
+  password: string;
+}
+
+export interface LoginResponse {
+  user: User;
+  token: string;
+}
+
+/**
+ * 用户登录
+ * POST /api/auth/login
+ */
+export const login = async (data: LoginRequest): Promise<LoginResponse> => {
+  return apiClient.post('/api/auth/login', data);
+};
+
+/**
+ * 用户登出
+ * POST /api/auth/logout
+ */
+export const logout = async (): Promise<void> => {
+  return apiClient.post('/api/auth/logout');
+};
+
+/**
+ * 获取当前用户信息
+ * GET /api/auth/me
+ */
+export const getCurrentUser = async (): Promise<User> => {
+  return apiClient.get('/api/auth/me');
+};
+```
+
+### 3. 列表 API 封装
+
+```typescript
+// src/lib/api/user.ts
+import { apiClient } from './client';
+import type { User } from '@/types/user';
+import type { ApiListResponse } from '@/types/api';
+
+export interface GetUsersParams {
+  page?: number;
+  pageSize?: number;
+  keyword?: string;
+}
+
+/**
+ * 获取用户列表
+ * GET /api/users?page=1&pageSize=10&keyword=xxx
+ */
+export const getUsers = async (
+  params: GetUsersParams = {}
+): Promise<ApiListResponse<User>> => {
+  return apiClient.get('/api/users', { params });
+};
+
+/**
+ * 获取用户详情
+ * GET /api/users/:id
+ */
+export const getUserById = async (id: string): Promise<User> => {
+  return apiClient.get(`/api/users/${id}`);
+};
+```
+
+---
+
+## 替换 Mock API
+
+### Before（Designer 的 Mock）
+
+```typescript
+// src/pages/LoginPage.tsx
+import { mockLoginAPI } from '@/mocks/api/auth.mock';
+
+const LoginPage = () => {
+  const handleSubmit = async (email: string, password: string) => {
+    try {
+      // TODO: [Frontend] 替换为真实API调用 POST /api/auth/login
+      const { user, token } = await mockLoginAPI(email, password);
+      localStorage.setItem('auth_token', token);
+      setUser(user);
+    } catch (error) {
+      setError('登录失败');
+    }
+  };
+
+  // ...
+};
+```
+
+### After（真实 API）
+
+```typescript
+// src/pages/LoginPage.tsx
+import { login } from '@/lib/api/auth';
+
+const LoginPage = () => {
+  const handleSubmit = async (email: string, password: string) => {
+    try {
+      const { user, token } = await login({ email, password });
+      localStorage.setItem('auth_token', token);
+      setUser(user);
+      navigate('/dashboard');
+    } catch (error) {
+      if (error.response?.status === 401) {
+        setError('邮箱或密码错误');
+      } else {
+        setError('登录失败，请稍后重试');
+      }
+    }
+  };
+
+  // ...
+};
+```
+
+---
+
+## 错误处理规范
+
+### 1. 错误类型定义
+
+```typescript
+// src/lib/api/errors.ts
+export class ApiError extends Error {
+  constructor(
+    public status: number,
+    public message: string,
+    public data?: any
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+export class NetworkError extends Error {
+  constructor(message: string = '网络连接失败') {
+    super(message);
+    this.name = 'NetworkError';
+  }
+}
+```
+
+### 2. 统一错误处理
+
+```typescript
+// src/lib/api/client.ts（响应拦截器）
+apiClient.interceptors.response.use(
+  (response) => response.data,
+  (error) => {
+    if (error.response) {
+      // 服务器返回错误
+      const { status, data } = error.response;
+      throw new ApiError(status, data.message || '请求失败', data);
+    } else if (error.request) {
+      // 网络错误
+      throw new NetworkError('网络连接失败，请检查网络设置');
+    } else {
+      // 其他错误
+      throw new Error('请求失败，请稍后重试');
+    }
+  }
+);
+```
+
+### 3. 组件中处理错误
+
+```typescript
+const LoginPage = () => {
+  const [error, setError] = useState<string | null>(null);
+
+  const handleSubmit = async (email: string, password: string) => {
+    setError(null);
+    try {
+      await login({ email, password });
+    } catch (err) {
+      if (err instanceof ApiError) {
+        // 业务错误
+        if (err.status === 401) {
+          setError('邮箱或密码错误');
+        } else if (err.status === 429) {
+          setError('请求过于频繁，请稍后重试');
+        } else {
+          setError(err.message);
+        }
+      } else if (err instanceof NetworkError) {
+        // 网络错误
+        setError('网络连接失败，请检查网络设置');
+      } else {
+        // 未知错误
+        setError('登录失败，请稍后重试');
+      }
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {error && <p className="text-red-500">{error}</p>}
+      {/* ... */}
+    </form>
+  );
+};
+```
+
+---
+
+## 加载状态管理
+
+### 1. 基本加载状态
+
+```typescript
+const UserList = () => {
+  const [users, setUsers] = useState<User[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const fetchUsers = async () => {
+      setLoading(true);
+      setError(null);
+      try {
+        const response = await getUsers({ page: 1, pageSize: 10 });
+        setUsers(response.data.items);
+      } catch (err) {
+        setError('加载用户列表失败');
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    fetchUsers();
+  }, []);
+
+  if (loading) return <div>加载中...</div>;
+  if (error) return <div>错误: {error}</div>;
+
+  return (
+    <ul>
+      {users.map((user) => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+};
+```
+
+### 2. 使用 React Query（推荐）
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { getUsers } from '@/lib/api/user';
+
+const UserList = () => {
+  const {
+    data,
+    isLoading,
+    error,
+    refetch
+  } = useQuery({
+    queryKey: ['users', { page: 1 }],
+    queryFn: () => getUsers({ page: 1, pageSize: 10 }),
+  });
+
+  if (isLoading) return <div>加载中...</div>;
+  if (error) return <div>错误: {error.message}</div>;
+
+  return (
+    <div>
+      <button onClick={() => refetch()}>刷新</button>
+      <ul>
+        {data?.data.items.map((user) => (
+          <li key={user.id}>{user.name}</li>
+        ))}
+      </ul>
+    </div>
+  );
+};
+```
+
+---
+
+## 类型安全保证
+
+### 1. API 响应类型定义
+
+```typescript
+// src/types/api.ts
+export interface ApiResponse<T> {
+  code: number;
+  message: string;
+  data: T;
+}
+
+export interface ApiListResponse<T> {
+  code: number;
+  message: string;
+  data: {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+  };
+}
+```
+
+### 2. 运行时类型验证（可选）
+
+使用 Zod 进行运行时验证：
+
+```typescript
+import { z } from 'zod';
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user', 'guest']),
+});
+
+export const login = async (data: LoginRequest): Promise<LoginResponse> => {
+  const response = await apiClient.post('/api/auth/login', data);
+
+  // 验证响应数据
+  const user = UserSchema.parse(response.user);
+
+  return {
+    user,
+    token: response.token,
+  };
+};
+```
+
+---
+
+## 检查清单
+
+API 集成完成前，确保：
+
+- [ ] 所有 TODO 标记的 Mock API 已替换
+- [ ] API 客户端配置完成（baseURL、拦截器）
+- [ ] 环境变量配置正确
+- [ ] 所有 API 函数包含类型定义
+- [ ] 错误处理完善（网络错误、业务错误）
+- [ ] 加载状态管理完善
+- [ ] Token 刷新逻辑实现（如需要）
+- [ ] API 调用已测试（手动测试或单元测试）
+
+---
+
+## 常见问题
+
+### Q: 如何处理 Token 过期？
+A: 在响应拦截器中检测 401 状态，自动刷新 Token 或跳转登录页
+
+```typescript
+apiClient.interceptors.response.use(
+  (response) => response.data,
+  async (error) => {
+    if (error.response?.status === 401) {
+      const refreshToken = localStorage.getItem('refresh_token');
+      if (refreshToken) {
+        // 尝试刷新 Token
+        try {
+          const { token } = await refreshAuthToken(refreshToken);
+          localStorage.setItem('auth_token', token);
+          // 重试原请求
+          return apiClient.request(error.config);
+        } catch {
+          // 刷新失败，跳转登录
+          window.location.href = '/login';
+        }
+      } else {
+        window.location.href = '/login';
+      }
+    }
+    return Promise.reject(error);
+  }
+);
+```
+
+### Q: 如何处理并发请求？
+A: 使用 Promise.all 或 React Query 的并发查询
+
+```typescript
+// Promise.all
+const [users, products] = await Promise.all([
+  getUsers(),
+  getProducts(),
+]);
+
+// React Query
+const usersQuery = useQuery(['users'], getUsers);
+const productsQuery = useQuery(['products'], getProducts);
+```
+
+### Q: 如何实现请求取消？
+A: 使用 AbortController
+
+```typescript
+useEffect(() => {
+  const controller = new AbortController();
+
+  const fetchData = async () => {
+    try {
+      await apiClient.get('/api/users', {
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        // 请求被取消
+        return;
+      }
+    }
+  };
+
+  fetchData();
+
+  return () => controller.abort(); // 组件卸载时取消请求
+}, []);
+```
+
+---
+
+## 相关文档
+
+- [错误处理规范](./error-handling.md)
+- [状态管理规范](./state-management.md)
+- [Frontend 工作规范](./index.md)