# 传统的 Flask API 端点
@app.route('/api/project', methods=['POST'])
@jwt_required()
def create_project():
    data = request.get_json()
    # ... 使用 Pydantic 验证数据 ...
    user_id = get_jwt_identity()
    # ... 数据库操作 ...
    return jsonify({"message": "Project created"}), 201

// 传统的客户端 fetch
const handleSubmit = async (data) => {
  const response = await fetch('/api/project', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
    body: JSON.stringify(data),
  });
  // ... 处理响应和 UI 状态 ...
};

// src/actions/project.ts
"use server";

import { z } from "zod";
import { createSafeActionClient } from "next-safe-action";
import { db } from "@/db"; // 我们的 Drizzle 实例
import { auth } from "@/auth"; // 我们的 Better Auth 实例

// 1. 定义 Zod schema (我们的 "Pydantic" / "DRF Serializer")
export const createProjectSchema = z.object({
  name: z.string().min(3, "项目名称至少需要 3 个字符"),
});

// 2. 创建一个 "safe action" 客户端
// 我们可以注入上下文，比如检查用户是否已认证
const action = createSafeActionClient({
  async middleware() {
    const session = await auth(); // 检查认证
    if (!session?.user?.id) {
      throw new Error("未授权：请先登录");
    }
    return { userId: session.user.id };
  },
});

// 3. 定义我们的 Action
export const createProject = action(
  createProjectSchema, // 传入 schema 进行验证
  async ({ name }, { userId }) => { // 接收经过验证的 "name" 和中间件返回的 "userId"

    // 4. 执行业务逻辑 (Drizzle DB 操作)
    try {
      const newProject = await db.insert(projectsTable).values({
        name,
        ownerId: userId,
      }).returning();

      return { success: true, project: newProject[0] };

    } catch (error) {
      console.error(error);
      return { serverError: "创建项目失败，请稍后重试。" };
    }
  }
);

// src/components/create-project-form.tsx
"use client";

import { useAction } from "next-safe-action/hook";
import { createProject, createProjectSchema } from "@/actions/project";

export function CreateProjectForm() {
  // 5. 使用 useAction 钩子
  const { execute, result, validationErrors, serverError, status } =
    useAction(createProject);

  const onSubmit = (data: z.infer<typeof createProjectSchema>) => {
    execute(data); // 直接执行
  };

  // ... 表单 (可以使用 react-hook-form) ...

  {/* 6. 优雅地处理状态 */}
  {status === "executing" && <p>正在创建...</p>}
  {serverError && <p className="text-red-500">{serverError}</p>}
  {validationErrors?.name && <p>{validationErrors.name[0]}</p>}
  {result?.data?.success && <p>项目 "{result.data.project.name}" 创建成功!</p>}
}

// src/actions/project.ts (续)
"use server";

import { redirect } from "next/navigation"; // 导入服务器端 redirect
import { revalidatePath } from "next/cache"; // 导入缓存刷新工具
// ... 其他 imports ...

export const createProject = action(
  createProjectSchema,
  async ({ name }, { userId }) => {

    let newProjectId: string;

    try {
      const newProject = await db.insert(projectsTable).values({
        name,
        ownerId: userId,
      }).returning({ id: projectsTable.id });

      newProjectId = newProject[0].id;

    } catch (error) {
      return { serverError: "创建项目失败" };
    }

    // 成功创建后

    // 1. [重要] 刷新缓存
    // 告诉 Next.js '/dashboard' 页面的数据已经过时了，下次访问时需要重新获取
    revalidatePath("/dashboard");

    // 2. [重要] 执行服务器端重定向
    // 这必须在 try...catch 块之外调用，因为它会抛出一个特殊的异常
    redirect(`/project/${newProjectId}`);

    // 注意：redirect() 之后的代码不会被执行
  }
);

src/actions/
├── auth.actions.ts       # 处理登录、注册、退出 (与 Better Auth 交互)
├── payment.actions.ts    # 处理 Stripe 支付、创建 checkout会话
├── credits.actions.ts    # 处理用户 AI 点数 (credits) 的增减
├── project.actions.ts    # (如上例) 处理项目的 C/U/D
└── user.actions.ts       # 处理用户配置文件的更新、API Key 生成
└── index.ts              # (可选) 导出所有 actions，方便管理

// src/actions/payment.actions.ts
"use server";

import { z } from "zod";
import { createSafeActionClient } from "next-safe-action";
import { db } from "@/db";
import { auth } from "@/auth";
import { stripe } from "@/payment/stripe-server"; // 我们的 Stripe 服务器端实例
import { usersTable } from "@/db/schema";
import { eq } from "drizzle-orm";
import { absoluteUrl } from "@/lib/utils";

// 1. 定义 Schema
const createCheckoutSchema = z.object({
  planId: z.string(), // e.g., "pro_plan_monthly"
});

// 2. 定义 Action (同样需要认证)
const action = createSafeActionClient({ /* ...认证中间件... */ });

export const createCheckoutSession = action(
  createCheckoutSchema,
  async ({ planId }, { userId }) => {

    // 3. 从 Drizzle 获取用户信息 (比如 Stripe Customer ID)
    const user = await db.query.usersTable.findFirst({
      where: eq(usersTable.id, userId),
    });

    if (!user) return { serverError: "用户不存在" };

    const stripeCustomerId = user.stripeCustomerId || await createStripeCustomer(user);

    const returnUrl = absoluteUrl("/dashboard/billing");

    // 4. 调用 Stripe API 创建会话
    try {
      const session = await stripe.checkout.sessions.create({
        payment_method_types: ["card"],
        mode: "subscription",
        customer: stripeCustomerId,
        line_items: [{ price: process.env[planId], quantity: 1 }],
        success_url: returnUrl,
        cancel_url: returnUrl,
      });

      if (!session.url) {
        return { serverError: "无法创建支付会话" };
      }

      // 5. 返回 Stripe Checkout URL
      // 客户端收到这个 URL 后，会重定向到 Stripe 支付页面
      return { success: true, url: session.url };

    } catch (error)_ {
      console.error(error);
      return { serverError: "Stripe 通信失败" };
    }
  }
);