create-nextdevtpl 2.6.0

package/template/src/features/storage/actions.ts

@@ -0,0 +1,107 @@
+"use server";
+
+/**
+ * 存储系统 Server Actions
+ *
+ * 提供文件上传和管理的服务端操作接口
+ */
+
+import { z } from "zod";
+
+import { protectedAction } from "@/lib/safe-action";
+import { storageService } from "@/services/storage";
+
+import {
+  ALLOWED_IMAGE_TYPES,
+  DEFAULT_UPLOAD_URL_EXPIRES,
+  type AllowedImageType,
+} from "./types";
+import { validateUploadRequest } from "./validation";
+
+const withStorageAction = (name: string) =>
+  protectedAction.metadata({ action: `storage.${name}` });
+
+// ============================================
+// 存储配置
+// ============================================
+
+/**
+ * 获取头像存储桶名称
+ */
+function getAvatarsBucket(): string {
+  const bucket = process.env.NEXT_PUBLIC_AVATARS_BUCKET_NAME;
+  if (!bucket) {
+    throw new Error("NEXT_PUBLIC_AVATARS_BUCKET_NAME 环境变量未设置");
+  }
+  return bucket;
+}
+
+/**
+ * 允许的存储桶白名单
+ *
+ * 安全措施：只允许访问预定义的存储桶
+ */
+function getAllowedBuckets(): string[] {
+  return [getAvatarsBucket()];
+}
+
+// ============================================
+// 上传 URL Actions
+// ============================================
+
+/**
+ * 获取签名上传 URL
+ *
+ * 受保护的 Action - 需要用户登录
+ * 客户端使用此 URL 直接上传文件到存储
+ */
+export const getSignedUploadUrlAction = withStorageAction("getSignedUploadUrl")
+  .schema(
+    z.object({
+      /** 文件键名 (规范格式为 `${userId}/...`，如 user-123/169.jpg) */
+      key: z.string().min(1, "文件键名不能为空").max(255, "文件键名过长"),
+      /** 文件 MIME 类型 */
+      contentType: z.enum(
+        ["image/jpeg", "image/png", "image/gif", "image/webp"],
+        {
+          message: `只支持以下文件类型: ${ALLOWED_IMAGE_TYPES.join(", ")}`,
+        }
+      ),
+      /** 存储桶名称 (可选，默认使用头像桶) */
+      bucket: z.string().optional(),
+    })
+  )
+  .action(async ({ parsedInput, ctx }) => {
+    const { key, contentType, bucket: inputBucket } = parsedInput;
+    const { userId } = ctx;
+
+    // 确定使用的存储桶
+    const bucket = inputBucket ?? getAvatarsBucket();
+
+    // 安全检查：存储桶白名单 + 键名格式(含路径遍历防护) + 文件归属(锚定 userId)
+    // 校验逻辑集中在 ./validation，测试直接 import 同一份函数，避免漂移
+    const validation = validateUploadRequest({
+      key,
+      bucket,
+      contentType,
+      userId,
+      allowedBuckets: getAllowedBuckets(),
+    });
+    if (!validation.valid) {
+      throw new Error(validation.error);
+    }
+
+    // 获取签名上传 URL
+    const uploadUrl = await storageService.createUploadUrl({
+      bucket,
+      key,
+      contentType: contentType as AllowedImageType,
+      expiresIn: DEFAULT_UPLOAD_URL_EXPIRES,
+    });
+
+    return {
+      uploadUrl,
+      key,
+      bucket,
+    };
+  });

package/template/src/features/storage/index.ts

@@ -0,0 +1,6 @@
+// Storage System
+export * from "./actions";
+export * from "./types";
+export * from "./utils";
+export * from "./validation";
+export { storageModule } from "./manifest";

package/template/src/features/storage/manifest.ts

@@ -0,0 +1,22 @@
+import { defineModule } from "@/core/modules";
+
+export const storageModule = defineModule({
+  id: "storage",
+  name: "Storage",
+  description: "文件上传、下载和对象存储访问",
+  kind: "optional",
+  dependencies: [],
+  routes: [
+    {
+      path: "/api/upload/presigned",
+      source: "src/app/api/upload/presigned/route.ts",
+    },
+    {
+      path: "/image-proxy/[...path]",
+      source: "src/app/image-proxy/[...path]/route.ts",
+    },
+  ],
+  navigation: [],
+  translations: [],
+  schema: [],
+});

package/template/src/features/storage/types.ts

@@ -0,0 +1,143 @@
+/**
+ * 存储系统类型定义
+ *
+ * 定义存储提供者接口和相关类型
+ */
+
+// ============================================
+// 存储提供者接口
+// ============================================
+
+/**
+ * 存储提供者接口
+ *
+ * 所有存储后端 (S3, R2, MinIO 等) 都需要实现此接口
+ */
+export interface StorageProvider {
+  /**
+   * 获取签名读取 URL
+   *
+   * 用于安全地读取存储中的文件
+   *
+   * @param key - 文件键名 (路径)
+   * @param bucket - 存储桶名称
+   * @param expiresIn - URL 有效期 (秒)
+   * @returns 签名后的 URL
+   */
+  getSignedUrl(key: string, bucket: string, expiresIn: number): Promise<string>;
+
+  /**
+   * 获取签名上传 URL
+   *
+   * 用于客户端直接上传文件到存储
+   *
+   * @param key - 文件键名 (路径)
+   * @param bucket - 存储桶名称
+   * @param contentType - 文件 MIME 类型
+   * @param expiresIn - URL 有效期 (秒，可选，默认 300)
+   * @returns 签名后的上传 URL
+   */
+  getSignedUploadUrl(
+    key: string,
+    bucket: string,
+    contentType: string,
+    expiresIn?: number
+  ): Promise<string>;
+
+  /**
+   * 删除文件
+   *
+   * @param key - 文件键名 (路径)
+   * @param bucket - 存储桶名称
+   */
+  deleteObject(key: string, bucket: string): Promise<void>;
+
+  /**
+   * 获取文件内容
+   *
+   * @param key - 文件键名 (路径)
+   * @param bucket - 存储桶名称
+   * @returns 文件内容 Buffer
+   */
+  getObject(key: string, bucket: string): Promise<Buffer>;
+}
+
+// ============================================
+// 存储配置类型
+// ============================================
+
+/**
+ * S3 兼容存储配置
+ */
+export interface S3StorageConfig {
+  /** 访问密钥 ID */
+  accessKeyId: string;
+  /** 访问密钥 */
+  secretAccessKey: string;
+  /** 端点 URL (如 Cloudflare R2, MinIO) */
+  endpoint: string;
+  /** 区域 (如 auto, us-east-1) */
+  region: string;
+}
+
+// ============================================
+// 上传相关类型
+// ============================================
+
+/**
+ * 上传 URL 请求参数
+ */
+export interface GetUploadUrlParams {
+  /** 文件键名 (完整路径，如 avatars/user-123.jpg) */
+  key: string;
+  /** 文件 MIME 类型 */
+  contentType: string;
+  /** 存储桶名称 (可选，默认使用头像桶) */
+  bucket?: string;
+}
+
+/**
+ * 上传 URL 响应
+ */
+export interface GetUploadUrlResult {
+  /** 签名上传 URL */
+  uploadUrl: string;
+  /** 文件键名 */
+  key: string;
+  /** 存储桶名称 */
+  bucket: string;
+}
+
+// ============================================
+// 允许的文件类型
+// ============================================
+
+/**
+ * 允许上传的图片 MIME 类型
+ */
+export const ALLOWED_IMAGE_TYPES = [
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
+] as const;
+
+/**
+ * 允许的图片类型
+ */
+export type AllowedImageType = (typeof ALLOWED_IMAGE_TYPES)[number];
+
+/**
+ * 最大文件大小 (5MB)
+ */
+export const MAX_FILE_SIZE = 5 * 1024 * 1024;
+
+/**
+ * 默认签名 URL 有效期 (秒)
+ */
+export const DEFAULT_SIGNED_URL_EXPIRES = 3600; // 1 小时
+
+/**
+ * 默认上传 URL 有效期 (秒)
+ */
+export const DEFAULT_UPLOAD_URL_EXPIRES = 300; // 5 分钟

package/template/src/features/storage/utils.ts

@@ -0,0 +1,85 @@
+/**
+ * 存储 URL 工具函数
+ *
+ * 处理存储键名和外部 URL 的转换
+ */
+
+// ============================================
+// 头像 URL 工具
+// ============================================
+
+/**
+ * 判断是否为外部 URL
+ *
+ * 外部 URL 包括:
+ * - OAuth 提供的头像 (GitHub, Google 等)
+ * - 其他完整 URL
+ *
+ * @param value - URL 或存储键名
+ * @returns 是否为外部 URL
+ */
+export function isExternalUrl(value: string | null | undefined): boolean {
+  if (!value) return false;
+  return value.startsWith("http://") || value.startsWith("https://");
+}
+
+/**
+ * 获取头像显示 URL
+ *
+ * 根据传入的值返回正确的 URL:
+ * - 如果是外部 URL (http/https 开头)，直接返回
+ * - 如果是存储键名，转换为 image-proxy URL
+ * - 如果为空，返回 undefined
+ *
+ * @param image - 用户的 image 字段值 (可能是 URL 或存储键名)
+ * @returns 头像显示 URL 或 undefined
+ *
+ * @example
+ * ```ts
+ * // 外部 URL (OAuth 头像)
+ * getAvatarUrl("https://avatars.githubusercontent.com/u/12345")
+ * // => "https://avatars.githubusercontent.com/u/12345"
+ *
+ * // 存储键名
+ * getAvatarUrl("user-abc123/1234567890.jpg")
+ * // => "/image-proxy/avatars/user-abc123/1234567890.jpg"
+ *
+ * // 空值
+ * getAvatarUrl(null) // => undefined
+ * ```
+ */
+export function getAvatarUrl(
+  image: string | null | undefined
+): string | undefined {
+  if (!image) {
+    return undefined;
+  }
+
+  // 如果是外部 URL，直接返回
+  if (isExternalUrl(image)) {
+    return image;
+  }
+
+  // 否则是存储键名，转换为 image-proxy URL
+  const avatarsBucket =
+    process.env.NEXT_PUBLIC_AVATARS_BUCKET_NAME ?? "avatars";
+  return `/image-proxy/${avatarsBucket}/${image}`;
+}
+
+/**
+ * 生成唯一的头像文件键名
+ *
+ * 格式: {userId}/{timestamp}.{extension}
+ *
+ * 将 userId 作为**首个路径段**，使服务端可锚定校验文件归属
+ * (参见 validation.ts 的 isKeyOwnedByUser)，避免子串伪造攻击。
+ *
+ * @param userId - 用户 ID
+ * @param file - 上传的文件
+ * @returns 唯一的文件键名
+ */
+export function generateAvatarKey(userId: string, file: File): string {
+  const timestamp = Date.now();
+  const extension = file.name.split(".").pop()?.toLowerCase() ?? "jpg";
+  return `${userId}/${timestamp}.${extension}`;
+}

package/template/src/features/storage/validation.ts

@@ -0,0 +1,151 @@
+/**
+ * 存储安全校验
+ *
+ * 这些是纯函数，既被 storage/actions.ts 在生产路径中调用，
+ * 也被 src/test/storage/security.test.ts 直接导入测试 ——
+ * 单一事实来源，避免测试与生产逻辑漂移。
+ */
+
+import { ALLOWED_IMAGE_TYPES, type AllowedImageType } from "./types";
+
+/** 文件键名允许的字符集（字母、数字、连字符、下划线、斜杠、点） */
+export const STORAGE_KEY_REGEX = /^[a-zA-Z0-9\-_/.]+$/;
+
+/** 文件键名最大长度 */
+export const MAX_KEY_LENGTH = 255;
+
+/**
+ * 校验文件键名格式
+ *
+ * 安全检查:
+ * - 长度 1-255
+ * - 显式拦截路径遍历 `..`（注意: 字符正则允许 `.`，故必须单独拦截 `..`）
+ * - 禁止以 `/` 开头/结尾、禁止空路径段 `//`
+ * - 仅允许白名单字符
+ */
+export function validateKeyFormat(key: string): boolean {
+  if (key.length < 1 || key.length > MAX_KEY_LENGTH) {
+    return false;
+  }
+  // 路径遍历防护：正则允许单个 '.'，'..' 会通过正则，必须显式拦截
+  if (key.includes("..")) {
+    return false;
+  }
+  // 禁止绝对路径、尾随斜杠与空路径段
+  if (key.startsWith("/") || key.endsWith("/") || key.includes("//")) {
+    return false;
+  }
+  return STORAGE_KEY_REGEX.test(key);
+}
+
+/**
+ * 校验文件归属
+ *
+ * 与旧实现 `key.includes(userId)` 的区别：这里要求 userId 必须是键名的
+ * **首个路径段**（锚定匹配），而非任意位置的子串。这样可以阻止：
+ * - 子串伪造：`evil-${userId}/x.jpg`、`${userId}extra/x.jpg`
+ * - 跨用户访问：`other-user/${userId}-decoy/x.jpg`
+ *
+ * 规范键名格式为 `${userId}/...`（参见 utils.ts 的 generateAvatarKey）。
+ */
+export function isKeyOwnedByUser(key: string, userId: string): boolean {
+  if (!userId || !key) {
+    return false;
+  }
+  const segments = key.split("/");
+  const [firstSegment, ...rest] = segments;
+  // 首段必须严格等于 userId，且其后至少还有一个非空文件段
+  return firstSegment === userId && rest.length > 0 && rest.every(Boolean);
+}
+
+/**
+ * 校验存储桶是否在白名单中
+ */
+export function validateBucket(
+  bucket: string,
+  allowedBuckets: string[]
+): boolean {
+  return allowedBuckets.includes(bucket);
+}
+
+/**
+ * 校验 ContentType 是否为允许的图片类型
+ */
+export function validateContentType(
+  contentType: string
+): contentType is AllowedImageType {
+  return (ALLOWED_IMAGE_TYPES as readonly string[]).includes(contentType);
+}
+
+/** 上传校验入参 */
+export interface UploadValidationParams {
+  key: string;
+  bucket: string;
+  contentType: string;
+  userId: string;
+  allowedBuckets: string[];
+}
+
+/** 校验结果 */
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+}
+
+/**
+ * 完整校验上传请求
+ *
+ * 校验顺序: 存储桶 → 键名格式 → 文件归属 → ContentType
+ */
+export function validateUploadRequest(
+  params: UploadValidationParams
+): ValidationResult {
+  const { key, bucket, contentType, userId, allowedBuckets } = params;
+
+  if (!validateBucket(bucket, allowedBuckets)) {
+    return { valid: false, error: "不允许访问该存储桶" };
+  }
+  if (!validateKeyFormat(key)) {
+    return { valid: false, error: "文件键名包含非法字符或长度不符" };
+  }
+  if (!isKeyOwnedByUser(key, userId)) {
+    return { valid: false, error: "文件路径无效：必须以用户 ID 作为前缀" };
+  }
+  if (!validateContentType(contentType)) {
+    return {
+      valid: false,
+      error: `只支持以下文件类型: ${ALLOWED_IMAGE_TYPES.join(", ")}`,
+    };
+  }
+  return { valid: true };
+}
+
+/** 删除校验入参 */
+export interface DeleteValidationParams {
+  key: string;
+  bucket: string;
+  userId: string;
+  allowedBuckets: string[];
+}
+
+/**
+ * 完整校验删除请求
+ *
+ * 校验顺序: 存储桶 → 键名格式 → 文件归属
+ */
+export function validateDeleteRequest(
+  params: DeleteValidationParams
+): ValidationResult {
+  const { key, bucket, userId, allowedBuckets } = params;
+
+  if (!validateBucket(bucket, allowedBuckets)) {
+    return { valid: false, error: "不允许访问该存储桶" };
+  }
+  if (!validateKeyFormat(key)) {
+    return { valid: false, error: "文件键名包含非法字符或长度不符" };
+  }
+  if (!isKeyOwnedByUser(key, userId)) {
+    return { valid: false, error: "无权操作此文件" };
+  }
+  return { valid: true };
+}

package/template/src/features/subscription/actions/get-user-plan.ts

@@ -0,0 +1,26 @@
+"use server";
+
+/**
+ * 获取当前用户订阅计划 Action
+ */
+
+import { getUserPlan } from "@/features/subscription/services/user-plan";
+import { protectedAction } from "@/lib/safe-action";
+
+/**
+ * 获取当前用户的订阅计划
+ */
+export const getMyPlanAction = protectedAction
+  .metadata({ action: "subscription.getMyPlan" })
+  .action(async ({ ctx }) => {
+    const userPlan = await getUserPlan(ctx.userId);
+
+    return {
+      plan: userPlan.plan,
+      planName: userPlan.planName,
+      hasActiveSubscription: userPlan.hasActiveSubscription,
+      currentPeriodEnd: userPlan.currentPeriodEnd?.toISOString() ?? null,
+      priceId: userPlan.priceId,
+      cancelAtPeriodEnd: userPlan.cancelAtPeriodEnd,
+    };
+  });

package/template/src/features/subscription/actions/index.ts

@@ -0,0 +1,5 @@
+/**
+ * 订阅相关 Actions 导出
+ */
+
+export { getMyPlanAction } from "./get-user-plan";

package/template/src/features/subscription/components/current-plan-badge.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+import { useAction } from "next-safe-action/hooks";
+import { useEffect } from "react";
+
+import { getMyPlanAction } from "../actions";
+import { PlanBadge, type PlanType } from "./plan-badge";
+
+export function CurrentPlanBadge() {
+  const { execute: fetchPlan, result } = useAction(getMyPlanAction);
+
+  useEffect(() => {
+    fetchPlan();
+  }, [fetchPlan]);
+
+  const plan = (result.data?.plan as PlanType) || "free";
+  return <PlanBadge plan={plan} size="xs" />;
+}

package/template/src/features/subscription/components/index.ts

@@ -0,0 +1,6 @@
+/**
+ * 订阅相关组件导出
+ */
+
+export { type BadgeSize, PlanBadge, type PlanType } from "./plan-badge";
+export { CurrentPlanBadge } from "./current-plan-badge";

package/template/src/features/subscription/components/plan-badge.tsx

@@ -0,0 +1,98 @@
+"use client";
+
+/**
+ * 订阅等级徽章组件
+ *
+ * 全部走设计系统 token，靠「中性 → 主色浅 → 金 → 主色实」的层次区分
+ * 四档计划，不再用紫粉/琥珀彩虹渐变 + 光晕（旧版那套是 AI 廉价感来源）。
+ * - free:   muted（中性，最低存在感）
+ * - starter: primary 浅底（品牌色淡）
+ * - pro:    warning 浅底（金色 = 高级感）
+ * - ultra:  primary 实底（最突出）
+ */
+
+import { Crown, Gem, Sparkles, User } from "lucide-react";
+import { useTranslations } from "next-intl";
+
+import { cn } from "@/lib/utils";
+
+export type PlanType = "free" | "starter" | "pro" | "ultra";
+export type BadgeSize = "xs" | "sm" | "md" | "lg";
+
+interface PlanBadgeProps {
+  plan: PlanType;
+  size?: BadgeSize;
+  showLabel?: boolean;
+  className?: string;
+}
+
+const sizeConfig: Record<
+  BadgeSize,
+  { badge: string; icon: string; text: string }
+> = {
+  xs: { badge: "h-5 px-1.5 gap-0.5", icon: "h-3 w-3", text: "text-[10px]" },
+  sm: { badge: "h-6 px-2 gap-1", icon: "h-3.5 w-3.5", text: "text-xs" },
+  md: { badge: "h-7 px-2.5 gap-1.5", icon: "h-4 w-4", text: "text-sm" },
+  lg: { badge: "h-8 px-3 gap-2", icon: "h-5 w-5", text: "text-base" },
+};
+
+const planConfig: Record<
+  PlanType,
+  { icon: typeof User; labelKey: string; baseStyles: string }
+> = {
+  free: {
+    icon: User,
+    labelKey: "free",
+    baseStyles: "bg-muted text-muted-foreground",
+  },
+  starter: {
+    icon: Sparkles,
+    labelKey: "starter",
+    baseStyles: "bg-primary/15 text-primary",
+  },
+  pro: {
+    icon: Crown,
+    labelKey: "pro",
+    baseStyles: "bg-warning/15 text-warning",
+  },
+  ultra: {
+    icon: Gem,
+    labelKey: "ultra",
+    baseStyles: "bg-primary text-primary-foreground",
+  },
+};
+
+export function PlanBadge({
+  plan,
+  size = "sm",
+  showLabel = true,
+  className,
+}: PlanBadgeProps) {
+  const t = useTranslations("Subscription");
+  const config = planConfig[plan];
+  const sizeStyles = sizeConfig[size];
+  const Icon = config.icon;
+
+  return (
+    <div
+      className={cn(
+        "inline-flex items-center justify-center rounded-full font-medium",
+        sizeStyles.badge,
+        config.baseStyles,
+        className
+      )}
+    >
+      <Icon className={sizeStyles.icon} />
+      {showLabel && (
+        <span
+          className={cn(
+            "font-semibold tracking-wide uppercase",
+            sizeStyles.text
+          )}
+        >
+          {t(`plans.${config.labelKey}`)}
+        </span>
+      )}
+    </div>
+  );
+}

package/template/src/features/subscription/index.ts

@@ -0,0 +1,25 @@
+/**
+ * 订阅功能模块
+ *
+ * 导出订阅计划相关的服务和工具函数
+ */
+
+// Actions
+export { getMyPlanAction } from "./actions";
+// 组件
+export {
+  type BadgeSize,
+  CurrentPlanBadge,
+  PlanBadge,
+  type PlanType,
+} from "./components";
+
+// 服务
+export {
+  checkFileSizePrivilege,
+  getUserPlan,
+  getUserPlanType,
+  type PrivilegeCheckResult,
+  type UserPlanInfo,
+} from "./services/user-plan";
+export { subscriptionModule } from "./manifest";