create-pardx-scaffold 0.1.2 → 0.1.5

package/template/apps/web/lib/deprecation-warning.ts

@@ -0,0 +1,150 @@
+/**
+ * API 废弃警告处理
+ *
+ * 当后端返回废弃响应头时，显示警告通知：
+ * - Deprecation: true
+ * - X-Deprecation-Message: 废弃原因
+ * - Sunset: 下线日期
+ */
+
+import { toast } from 'sonner';
+import {
+  DEPRECATION_HEADER,
+  DEPRECATION_MESSAGE_HEADER,
+  SUNSET_HEADER,
+} from '@repo/constants';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface DeprecationInfo {
+  /** 废弃消息 */
+  message: string;
+  /** 下线日期 (ISO 8601) */
+  sunsetDate: string | null;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEPRECATION_SHOWN_KEY = 'pardx:deprecation_warnings_shown';
+const TOAST_DURATION = 10000; // 10 秒
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * 获取已显示警告的 API 路径集合
+ */
+function getShownWarnings(): Set<string> {
+  if (typeof sessionStorage === 'undefined') {
+    return new Set();
+  }
+  try {
+    const stored = sessionStorage.getItem(DEPRECATION_SHOWN_KEY);
+    return stored ? new Set(JSON.parse(stored)) : new Set();
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * 记录已显示警告的 API 路径
+ */
+function markWarningShown(path: string): void {
+  if (typeof sessionStorage === 'undefined') {
+    return;
+  }
+  try {
+    const shown = getShownWarnings();
+    shown.add(path);
+    sessionStorage.setItem(DEPRECATION_SHOWN_KEY, JSON.stringify(Array.from(shown)));
+  } catch {
+    // Ignore storage errors
+  }
+}
+
+/**
+ * 格式化下线日期
+ */
+function formatSunsetDate(sunsetDate: string): string {
+  try {
+    const date = new Date(sunsetDate);
+    return date.toLocaleDateString('zh-CN', {
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric',
+    });
+  } catch {
+    return sunsetDate;
+  }
+}
+
+// ============================================================================
+// Public Functions
+// ============================================================================
+
+/**
+ * 检查响应是否包含废弃标识
+ */
+export function isDeprecated(headers: Headers): boolean {
+  const deprecation = headers.get(DEPRECATION_HEADER);
+  return deprecation === 'true';
+}
+
+/**
+ * 从响应头中提取废弃信息
+ */
+export function getDeprecationInfo(headers: Headers): DeprecationInfo | null {
+  if (!isDeprecated(headers)) {
+    return null;
+  }
+
+  const message =
+    headers.get(DEPRECATION_MESSAGE_HEADER) || '此 API 即将废弃，请尽快迁移';
+  const sunsetDate = headers.get(SUNSET_HEADER);
+
+  return { message, sunsetDate };
+}
+
+/**
+ * 检查并显示废弃警告
+ *
+ * @param headers 响应头
+ * @param path API 路径
+ */
+export function checkDeprecationWarning(headers: Headers, path: string): void {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  const info = getDeprecationInfo(headers);
+  if (!info) {
+    return;
+  }
+
+  // 检查是否已显示过该路径的警告
+  const shown = getShownWarnings();
+  if (shown.has(path)) {
+    return;
+  }
+
+  // 标记为已显示
+  markWarningShown(path);
+
+  // 构建警告消息
+  let description = info.message;
+  if (info.sunsetDate) {
+    description += `\n下线日期: ${formatSunsetDate(info.sunsetDate)}`;
+  }
+
+  // 显示警告 Toast
+  toast.warning('API 即将废弃', {
+    description,
+    duration: TOAST_DURATION,
+    dismissible: true,
+  });
+}

package/template/apps/web/lib/queries/optimistic-update.ts

@@ -0,0 +1,204 @@
+/**
+ * 乐观更新工具
+ *
+ * 提供 React Query 乐观更新的工具函数和示例
+ */
+
+import type { QueryClient } from '@tanstack/react-query';
+
+/**
+ * 乐观更新配置
+ */
+interface OptimisticUpdateConfig<TData, TVariables> {
+  /** Query Key */
+  queryKey: readonly unknown[];
+  /** 乐观更新函数 - 返回更新后的数据 */
+  updater: (oldData: TData | undefined, variables: TVariables) => TData;
+  /** 回滚函数（可选） */
+  onRollback?: (context: { previousData: TData | undefined }) => void;
+}
+
+/**
+ * 创建乐观更新的 mutation 配置
+ *
+ * @example
+ * ```tsx
+ * const updateTodo = useMutation({
+ *   mutationFn: api.todo.update,
+ *   ...createOptimisticUpdate(queryClient, {
+ *     queryKey: ['todos'],
+ *     updater: (oldData, variables) => {
+ *       return oldData?.map(todo =>
+ *         todo.id === variables.id ? { ...todo, ...variables } : todo
+ *       );
+ *     },
+ *   }),
+ * });
+ * ```
+ */
+export function createOptimisticUpdate<TData, TVariables, TError = unknown>(
+  queryClient: QueryClient,
+  config: OptimisticUpdateConfig<TData, TVariables>,
+) {
+  return {
+    onMutate: async (variables: TVariables) => {
+      // 取消正在进行的查询
+      await queryClient.cancelQueries({ queryKey: config.queryKey });
+
+      // 保存之前的数据
+      const previousData = queryClient.getQueryData<TData>(config.queryKey);
+
+      // 乐观更新
+      queryClient.setQueryData<TData>(config.queryKey, (oldData) =>
+        config.updater(oldData, variables),
+      );
+
+      // 返回上下文用于回滚
+      return { previousData };
+    },
+
+    onError: (
+      _error: TError,
+      _variables: TVariables,
+      context: { previousData: TData | undefined } | undefined,
+    ) => {
+      // 回滚到之前的数据
+      if (context?.previousData !== undefined) {
+        queryClient.setQueryData(config.queryKey, context.previousData);
+      }
+      config.onRollback?.(context || { previousData: undefined });
+    },
+
+    onSettled: () => {
+      // 重新获取数据以确保同步
+      queryClient.invalidateQueries({ queryKey: config.queryKey });
+    },
+  };
+}
+
+/**
+ * 列表项乐观更新 - 更新单个项
+ */
+export function createListItemOptimisticUpdate<
+  TItem extends { id: string | number },
+  TVariables extends { id: string | number },
+>(
+  queryClient: QueryClient,
+  queryKey: readonly unknown[],
+  options?: {
+    onRollback?: () => void;
+  },
+) {
+  return createOptimisticUpdate<TItem[], TVariables>(queryClient, {
+    queryKey,
+    updater: (oldData, variables) => {
+      if (!oldData) return [];
+      return oldData.map((item) =>
+        item.id === variables.id ? { ...item, ...variables } : item,
+      );
+    },
+    onRollback: options?.onRollback,
+  });
+}
+
+/**
+ * 列表项乐观删除
+ */
+export function createListItemOptimisticDelete<
+  TItem extends { id: string | number },
+>(
+  queryClient: QueryClient,
+  queryKey: readonly unknown[],
+  options?: {
+    onRollback?: () => void;
+  },
+) {
+  return createOptimisticUpdate<TItem[], { id: string | number }>(queryClient, {
+    queryKey,
+    updater: (oldData, variables) => {
+      if (!oldData) return [];
+      return oldData.filter((item) => item.id !== variables.id);
+    },
+    onRollback: options?.onRollback,
+  });
+}
+
+/**
+ * 列表项乐观添加
+ */
+export function createListItemOptimisticAdd<TItem>(
+  queryClient: QueryClient,
+  queryKey: readonly unknown[],
+  options?: {
+    prepend?: boolean;
+    onRollback?: () => void;
+  },
+) {
+  return createOptimisticUpdate<TItem[], TItem>(queryClient, {
+    queryKey,
+    updater: (oldData, newItem) => {
+      if (!oldData) return [newItem];
+      return options?.prepend
+        ? [newItem, ...oldData]
+        : [...oldData, newItem];
+    },
+    onRollback: options?.onRollback,
+  });
+}
+
+/**
+ * 使用示例
+ *
+ * @example
+ * ```tsx
+ * // 在组件中使用乐观更新
+ * function TodoList() {
+ *   const queryClient = useQueryClient();
+ *
+ *   // 更新 Todo
+ *   const updateTodo = useMutation({
+ *     mutationFn: (data: { id: string; completed: boolean }) =>
+ *       api.todo.update(data),
+ *     ...createListItemOptimisticUpdate<Todo, { id: string; completed: boolean }>(
+ *       queryClient,
+ *       ['todos'],
+ *     ),
+ *   });
+ *
+ *   // 删除 Todo
+ *   const deleteTodo = useMutation({
+ *     mutationFn: (id: string) => api.todo.delete(id),
+ *     ...createListItemOptimisticDelete<Todo>(queryClient, ['todos']),
+ *   });
+ *
+ *   // 添加 Todo
+ *   const addTodo = useMutation({
+ *     mutationFn: (data: Omit<Todo, 'id'>) => api.todo.create(data),
+ *     ...createListItemOptimisticAdd<Todo>(queryClient, ['todos'], {
+ *       prepend: true,
+ *     }),
+ *   });
+ *
+ *   return (
+ *     <ul>
+ *       {todos.map(todo => (
+ *         <li key={todo.id}>
+ *           <input
+ *             type="checkbox"
+ *             checked={todo.completed}
+ *             onChange={() => updateTodo.mutate({
+ *               id: todo.id,
+ *               completed: !todo.completed,
+ *             })}
+ *           />
+ *           {todo.title}
+ *           <button onClick={() => deleteTodo.mutate({ id: todo.id })}>
+ *             删除
+ *           </button>
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */

package/template/packages/constants/src/index.ts

@@ -54,6 +54,28 @@ export const DATE_FORMAT = {
   ISO: 'YYYY-MM-DDTHH:mm:ss.SSSZ',
 } as const;
 
+// ============================================================================
+// Deprecation Headers (废弃警告响应头)
+// ============================================================================
+
+/**
+ * 废弃标识 Header (响应)
+ * 值为 "true" 表示该 API 已废弃
+ */
+export const DEPRECATION_HEADER = 'deprecation' as const;
+
+/**
+ * 废弃消息 Header (响应)
+ * 包含废弃原因和迁移建议
+ */
+export const DEPRECATION_MESSAGE_HEADER = 'x-deprecation-message' as const;
+
+/**
+ * 下线日期 Header (响应)
+ * 格式: ISO 8601 日期字符串
+ */
+export const SUNSET_HEADER = 'sunset' as const;
+
 // ============================================================================
 // API Versioning Constants
 // ============================================================================

package/template/apps/api/src/modules/health/health.controller.ts

@@ -1,13 +0,0 @@
-import { Controller, Get } from '@nestjs/common';
-
-@Controller('health')
-export class HealthController {
-  @Get()
-  check() {
-    return {
-      status: 'ok',
-      timestamp: new Date().toISOString(),
-      uptime: process.uptime(),
-    };
-  }
-}

package/template/apps/api/src/modules/health/health.module.ts

@@ -1,7 +0,0 @@
-import { Module } from '@nestjs/common';
-import { HealthController } from './health.controller';
-
-@Module({
-  controllers: [HealthController],
-})
-export class HealthModule {}