@jahanxu/trellis 0.4.2 → 0.5.0

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

@@ -1,565 +0,0 @@
-# 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)