28b - API设计与生成

你的项目需要什么类型的 API？
│
├── 对外公开 API（第三方集成）
│   └── REST + OpenAPI ← AI 生成 OpenAPI 规范 + 实现代码
│
├── 前后端分离（多客户端：Web + Mobile + 第三方）
│   ├── 数据关系复杂，客户端需要灵活查询？
│   │   └── GraphQL ← AI 生成 Schema + Resolver
│   └── 数据结构相对固定？
│       └── REST ← AI 生成 RESTful 端点
│
├── 全栈 TypeScript 项目（Next.js / Nuxt / SvelteKit）
│   ├── 团队全部使用 TypeScript？
│   │   └── tRPC ← AI 生成 Router + Procedure
│   └── 团队有非 TypeScript 成员？
│       └── REST 或 GraphQL
│
└── 微服务间通信
    ├── 高性能要求？
    │   └── gRPC（不在本节范围，见微服务章节）
    └── 标准 HTTP 通信？
        └── REST + OpenAPI

┌─────────────────────────────────────────────┐
│              典型混合架构                      │
├─────────────────────────────────────────────┤
│                                             │
│  外部 API（第三方集成）                        │
│  └── REST + OpenAPI 3.1                     │
│                                             │
│  Web 前端 ↔ BFF（Backend for Frontend）       │
│  └── tRPC（全栈 TypeScript 类型安全）          │
│                                             │
│  Mobile App ↔ API Gateway                   │
│  └── GraphQL（灵活数据查询）                   │
│                                             │
│  微服务间通信                                  │
│  └── gRPC / REST（内部服务）                   │
│                                             │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│           Schema-First vs Code-First 对比             │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Schema-First（推荐用于 AI 辅助开发）                  │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐       │
│  │ API 契约  │ →  │ AI 生成  │ →  │ 实现代码  │       │
│  │ (Schema) │    │ 代码骨架  │    │ + 测试    │       │
│  └──────────┘    └──────────┘    └──────────┘       │
│  优点：一致性高、前后端可并行、AI 生成质量高             │
│                                                     │
│  Code-First（传统方式）                                │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐       │
│  │ 写实现   │ →  │ 提取注解  │ →  │ 生成文档  │       │
│  │ 代码     │    │ /装饰器   │    │ (Schema) │       │
│  └──────────┘    └──────────┘    └──────────┘       │
│  优点：开发速度快、适合快速原型                         │
│                                                     │
└─────────────────────────────────────────────────────┘

请为以下业务需求设计 OpenAPI 3.1 规范：

## 业务需求
[描述 API 的业务目的和核心功能]

## 资源列表
[列出核心资源/实体，如 User, Product, Order]

## 设计约束
- API 基础路径：/api/v1
- 认证方式：Bearer Token (JWT)
- 分页方式：cursor-based（使用 cursor + limit 参数）
- 错误响应格式：RFC 7807 Problem Details
- 日期格式：ISO 8601
- ID 格式：CUID2

## 要求
- 每个资源包含 CRUD 端点
- 使用 [占位符] 标记需要替换的部分
- 包含请求/响应 Schema 定义（使用 $ref 引用 components）
- 包含认证安全方案定义
- 包含分页、过滤、排序的查询参数
- 包含标准错误响应（400, 401, 403, 404, 409, 422, 500）

openapi: 3.1.0
info:
  title: 项目管理 API
  version: 1.0.0
  description: 多租户项目管理 SaaS 的 RESTful API
 
servers:
  - url: https://api.example.com/v1
    description: 生产环境
 
security:
  - BearerAuth: []
 
paths:
  /projects:
    get:
      operationId: listProjects
      summary: 获取项目列表
      tags: [Projects]
      parameters:
        - $ref: '#/components/parameters/CursorParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/ProjectStatus'
      responses:
        '200':
          description: 项目列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
 
    post:
      operationId: createProject
      summary: 创建项目
      tags: [Projects]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: 项目创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '422':
          $ref: '#/components/responses/ValidationError'
 
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
 
  schemas:
    ProjectStatus:
      type: string
      enum: [active, archived, deleted]
 
    CreateProjectRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        description:
          type: string
          maxLength: 2000
 
    ProjectResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/ProjectStatus'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
 
    ProjectListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProjectResponse'
        pagination:
          $ref: '#/components/schemas/CursorPagination'
 
    CursorPagination:
      type: object
      properties:
        nextCursor:
          type: string
          nullable: true
        hasMore:
          type: boolean
 
    ProblemDetail:
      type: object
      description: RFC 7807 Problem Details
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
          format: uri
 
  parameters:
    CursorParam:
      name: cursor
      in: query
      schema:
        type: string
    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
 
  responses:
    BadRequest:
      description: 请求参数错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Unauthorized:
      description: 未认证
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    ValidationError:
      description: 输入验证失败
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'

请为以下业务需求设计 GraphQL Schema（SDL 格式）：

## 业务需求
[描述业务领域和核心实体]

## 设计约束
- 使用 Relay 风格的连接分页（Connection/Edge/Node）
- 使用 Input 类型封装变更参数
- 错误处理使用 Union 类型（Result Pattern）
- 包含 Subscription 定义（如需实时功能）

## 要求
- 定义所有 Query、Mutation、Subscription
- 使用自定义标量类型（DateTime, Email, URL）
- 包含权限指令（@auth）
- 包含输入验证指令（@constraint）
- 遵循 GraphQL 命名约定（camelCase 字段，PascalCase 类型）

# schema.graphql — AI 生成的项目管理 GraphQL Schema
 
# 自定义标量
scalar DateTime
scalar Email
scalar URL
 
# 权限指令
directive @auth(requires: Role!) on FIELD_DEFINITION
 
# 枚举类型
enum Role {
  OWNER
  ADMIN
  MEMBER
  VIEWER
}
 
enum TaskStatus {
  TODO
  IN_PROGRESS
  IN_REVIEW
  DONE
  CANCELLED
}
 
enum Priority {
  LOW
  MEDIUM
  HIGH
  URGENT
}
 
enum SortDirection {
  ASC
  DESC
}
 
# 接口
interface Node {
  id: ID!
}
 
interface Timestamped {
  createdAt: DateTime!
  updatedAt: DateTime!
}
 
# 核心类型
type User implements Node & Timestamped {
  id: ID!
  email: Email!
  name: String!
  avatarUrl: URL
  createdAt: DateTime!
  updatedAt: DateTime!
  memberships: [Membership!]!
}
 
type Project implements Node & Timestamped {
  id: ID!
  name: String!
  description: String
  archived: Boolean!
  createdAt: DateTime!
  updatedAt: DateTime!
  tasks(
    first: Int
    after: String
    filter: TaskFilterInput
    sort: TaskSortInput
  ): TaskConnection!
  taskCount: Int!
}
 
type Task implements Node & Timestamped {
  id: ID!
  title: String!
  description: String
  status: TaskStatus!
  priority: Priority!
  dueDate: DateTime
  assignee: User
  creator: User!
  project: Project!
  createdAt: DateTime!
  updatedAt: DateTime!
}
 
type Membership {
  id: ID!
  role: Role!
  user: User!
  organization: Organization!
}
 
type Organization implements Node & Timestamped {
  id: ID!
  name: String!
  slug: String!
  createdAt: DateTime!
  updatedAt: DateTime!
  members: [Membership!]!
  projects(first: Int, after: String): ProjectConnection!
}
 
# Relay 风格分页
type TaskConnection {
  edges: [TaskEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}
 
type TaskEdge {
  node: Task!
  cursor: String!
}
 
type ProjectConnection {
  edges: [ProjectEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}
 
type ProjectEdge {
  node: Project!
  cursor: String!
}
 
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}
 
# 输入类型
input CreateProjectInput {
  name: String!
  description: String
}
 
input UpdateProjectInput {
  name: String
  description: String
  archived: Boolean
}
 
input CreateTaskInput {
  title: String!
  description: String
  priority: Priority = MEDIUM
  assigneeId: ID
  dueDate: DateTime
}
 
input UpdateTaskInput {
  title: String
  description: String
  status: TaskStatus
  priority: Priority
  assigneeId: ID
  dueDate: DateTime
}
 
input TaskFilterInput {
  status: [TaskStatus!]
  priority: [Priority!]
  assigneeId: ID
}
 
input TaskSortInput {
  field: TaskSortField!
  direction: SortDirection!
}
 
enum TaskSortField {
  CREATED_AT
  UPDATED_AT
  PRIORITY
  DUE_DATE
}
 
# Result Pattern（错误处理）
union CreateProjectResult = Project | ValidationError | AuthorizationError
union UpdateTaskResult = Task | ValidationError | NotFoundError | AuthorizationError
 
type ValidationError {
  message: String!
  field: String
  code: String!
}
 
type NotFoundError {
  message: String!
  resourceType: String!
  resourceId: ID!
}
 
type AuthorizationError {
  message: String!
  requiredRole: Role
}
 
# 查询
type Query {
  # 当前用户
  me: User! @auth(requires: VIEWER)
 
  # 组织
  organization(slug: String!): Organization @auth(requires: VIEWER)
 
  # 项目
  project(id: ID!): Project @auth(requires: VIEWER)
 
  # 任务
  task(id: ID!): Task @auth(requires: VIEWER)
 
  # Node 接口查询
  node(id: ID!): Node
}
 
# 变更
type Mutation {
  # 项目
  createProject(
    organizationId: ID!
    input: CreateProjectInput!
  ): CreateProjectResult! @auth(requires: MEMBER)
 
  updateProject(
    id: ID!
    input: UpdateProjectInput!
  ): Project! @auth(requires: ADMIN)
 
  deleteProject(id: ID!): Boolean! @auth(requires: OWNER)
 
  # 任务
  createTask(
    projectId: ID!
    input: CreateTaskInput!
  ): Task! @auth(requires: MEMBER)
 
  updateTask(
    id: ID!
    input: UpdateTaskInput!
  ): UpdateTaskResult! @auth(requires: MEMBER)
 
  deleteTask(id: ID!): Boolean! @auth(requires: ADMIN)
}
 
# 订阅
type Subscription {
  taskUpdated(projectId: ID!): Task! @auth(requires: VIEWER)
  taskCreated(projectId: ID!): Task! @auth(requires: VIEWER)
}

// schemas/task.ts — 先定义验证 Schema（这就是 tRPC 的"契约"）
import { z } from 'zod';
 
export const TaskStatus = z.enum([
  'TODO', 'IN_PROGRESS', 'IN_REVIEW', 'DONE', 'CANCELLED'
]);
 
export const Priority = z.enum(['LOW', 'MEDIUM', 'HIGH', 'URGENT']);
 
export const CreateTaskSchema = z.object({
  title: z.string().min(1).max(200),
  description: z.string().max(5000).optional(),
  priority: Priority.default('MEDIUM'),
  assigneeId: z.string().cuid2().optional(),
  dueDate: z.coerce.date().optional(),
});
 
export const UpdateTaskSchema = z.object({
  title: z.string().min(1).max(200).optional(),
  description: z.string().max(5000).optional(),
  status: TaskStatus.optional(),
  priority: Priority.optional(),
  assigneeId: z.string().cuid2().nullable().optional(),
  dueDate: z.coerce.date().nullable().optional(),
});
 
export const TaskFilterSchema = z.object({
  status: z.array(TaskStatus).optional(),
  priority: z.array(Priority).optional(),
  assigneeId: z.string().cuid2().optional(),
  cursor: z.string().optional(),
  limit: z.number().int().min(1).max(100).default(20),
});
 
// 类型自动从 Schema 推断
export type CreateTaskInput = z.infer<typeof CreateTaskSchema>;
export type UpdateTaskInput = z.infer<typeof UpdateTaskSchema>;
export type TaskFilter = z.infer<typeof TaskFilterSchema>;

// routers/task.ts — 基于 Schema 构建 tRPC Router
import { router, protectedProcedure } from '../trpc';
import {
  CreateTaskSchema,
  UpdateTaskSchema,
  TaskFilterSchema,
} from '../schemas/task';
import { z } from 'zod';
 
export const taskRouter = router({
  list: protectedProcedure
    .input(TaskFilterSchema)
    .query(async ({ ctx, input }) => {
      const tasks = await ctx.db.task.findMany({
        where: {
          projectId: ctx.projectId,
          ...(input.status && { status: { in: input.status } }),
          ...(input.priority && { priority: { in: input.priority } }),
          ...(input.assigneeId && { assigneeId: input.assigneeId }),
        },
        take: input.limit + 1,
        ...(input.cursor && {
          cursor: { id: input.cursor },
          skip: 1,
        }),
        orderBy: { createdAt: 'desc' },
      });
 
      const hasMore = tasks.length > input.limit;
      const data = hasMore ? tasks.slice(0, -1) : tasks;
 
      return {
        data,
        nextCursor: hasMore ? data[data.length - 1]?.id : null,
        hasMore,
      };
    }),
 
  create: protectedProcedure
    .input(CreateTaskSchema)
    .mutation(async ({ ctx, input }) => {
      return ctx.db.task.create({
        data: {
          ...input,
          projectId: ctx.projectId,
          creatorId: ctx.user.id,
        },
      });
    }),
 
  update: protectedProcedure
    .input(z.object({
      id: z.string().cuid2(),
      data: UpdateTaskSchema,
    }))
    .mutation(async ({ ctx, input }) => {
      return ctx.db.task.update({
        where: { id: input.id },
        data: input.data,
      });
    }),
 
  delete: protectedProcedure
    .input(z.object({ id: z.string().cuid2() }))
    .mutation(async ({ ctx, input }) => {
      await ctx.db.task.delete({ where: { id: input.id } });
      return { success: true };
    }),
});

# 安装 openapi-generator
npm install @openapitools/openapi-generator-cli -g
 
# 从 OpenAPI 规范生成 NestJS 服务端代码
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-nestjs \
  -o src/generated \
  --additional-properties=useTags=true
 
# 从 OpenAPI 规范生成 FastAPI 服务端代码
openapi-generator-cli generate \
  -i openapi.yaml \
  -g python-fastapi \
  -o src/generated

基于以下 OpenAPI 规范，为每个端点生成 NestJS 的 Controller + Service + DTO：

[粘贴 OpenAPI YAML 或指定文件路径]

## 生成要求
- Controller 使用 @nestjs/swagger 装饰器（与 OpenAPI 规范一致）
- DTO 使用 class-validator + class-transformer 装饰器
- Service 使用 Prisma Client 操作数据库
- 包含统一的异常过滤器（映射到 RFC 7807 格式）
- 每个 Service 方法包含日志记录
- 生成对应的单元测试文件

// 使用 express-zod-api 的 Schema-First 方式
import { createConfig, Routing, EndpointsFactory } from 'express-zod-api';
import { z } from 'zod';
 
const config = createConfig({
  server: { listen: 3000 },
  cors: true,
  logger: { level: 'info' },
});
 
const endpointsFactory = new EndpointsFactory(defaultResultHandler);
 
// 定义端点 — Zod Schema 同时用于验证和文档生成
const createTaskEndpoint = endpointsFactory.build({
  method: 'post',
  input: z.object({
    title: z.string().min(1).max(200),
    description: z.string().max(5000).optional(),
    priority: z.enum(['LOW', 'MEDIUM', 'HIGH', 'URGENT']).default('MEDIUM'),
  }),
  output: z.object({
    id: z.string(),
    title: z.string(),
    status: z.string(),
    createdAt: z.string(),
  }),
  handler: async ({ input }) => {
    const task = await prisma.task.create({ data: input });
    return task;
  },
});
 
// 路由定义
const routing: Routing = {
  v1: {
    tasks: {
      '': createTaskEndpoint,
    },
  },
};

# 使用 Orval 从 OpenAPI 生成 TypeScript 客户端（React Query 集成）
npx orval --input openapi.yaml --output src/api/generated
 
# 使用 openapi-typescript 生成类型定义
npx openapi-typescript openapi.yaml -o src/api/types.ts

请为 [资源名称] 资源生成完整的 RESTful CRUD API：

## 技术栈
- 框架：[NestJS / FastAPI / Express / Gin]
- ORM：[Prisma / SQLAlchemy / TypeORM / GORM]
- 验证：[Zod / Pydantic / class-validator / Joi]
- 数据库：[PostgreSQL / MySQL]

## 资源定义
[描述资源的字段、类型、约束]

## API 端点
- GET    /api/v1/[资源复数]          — 列表（支持分页、过滤、排序）
- GET    /api/v1/[资源复数]/:id      — 详情
- POST   /api/v1/[资源复数]          — 创建
- PATCH  /api/v1/[资源复数]/:id      — 部分更新
- DELETE /api/v1/[资源复数]/:id      — 删除

## 必须包含
1. 输入验证 Schema（创建和更新分开定义）
2. 统一错误响应（RFC 7807 格式）
3. Cursor 分页（cursor + limit）
4. 过滤参数（按 [指定字段] 过滤）
5. 排序参数（sortBy + sortDirection）
6. 认证守卫（JWT Bearer Token）
7. 权限检查（基于角色）
8. 请求日志中间件
9. 单元测试（覆盖正常路径和错误路径）

## 禁止
- 禁止使用 SELECT *
- 禁止在响应中暴露内部错误堆栈
- 禁止硬编码任何密钥或配置值

# 安装 GraphQL Code Generator
npm install -D @graphql-codegen/cli @graphql-codegen/typescript \
  @graphql-codegen/typescript-resolvers
 
# codegen.ts 配置

// codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli';
 
const config: CodegenConfig = {
  schema: 'src/schema.graphql',
  generates: {
    'src/generated/types.ts': {
      plugins: [
        'typescript',
        'typescript-resolvers',
      ],
      config: {
        contextType: '../context#GraphQLContext',
        mappers: {
          User: '../models#UserModel',
          Project: '../models#ProjectModel',
          Task: '../models#TaskModel',
        },
        useIndexSignature: true,
      },
    },
  },
};
 
export default config;

# 生成类型
npx graphql-codegen

基于以下 GraphQL Schema 和生成的 TypeScript 类型，实现 Resolver：

## Schema 文件
[粘贴 schema.graphql 内容]

## 生成的类型文件
[粘贴 generated/types.ts 内容]

## 技术栈
- 运行时：Node.js + TypeScript
- GraphQL 服务器：Apollo Server 4 / Yoga
- ORM：Prisma
- 认证：JWT（通过 context 传递）

## 要求
- 所有关联字段使用 DataLoader 批量加载（防止 N+1）
- Mutation 包含输入验证（使用 Zod）
- 错误处理使用 Result Union 模式
- 包含权限检查（基于 @auth 指令）
- 分页使用 Relay Connection 规范
- 包含查询复杂度分析中间件

// resolvers/task.ts — AI 生成的 Task Resolver
import { Resolvers } from '../generated/types';
import { GraphQLContext } from '../context';
import { CreateTaskSchema, UpdateTaskSchema } from '../schemas/task';
import { GraphQLError } from 'graphql';
 
export const taskResolvers: Resolvers<GraphQLContext> = {
  Query: {
    task: async (_parent, { id }, ctx) => {
      const task = await ctx.prisma.task.findUnique({
        where: { id },
      });
      if (!task) {
        throw new GraphQLError('Task not found', {
          extensions: { code: 'NOT_FOUND' },
        });
      }
      return task;
    },
  },
 
  Mutation: {
    createTask: async (_parent, { projectId, input }, ctx) => {
      // 输入验证
      const validated = CreateTaskSchema.safeParse(input);
      if (!validated.success) {
        return {
          __typename: 'ValidationError',
          message: validated.error.issues[0].message,
          field: validated.error.issues[0].path.join('.'),
          code: 'VALIDATION_ERROR',
        };
      }
 
      // 权限检查
      const membership = await ctx.prisma.membership.findFirst({
        where: {
          userId: ctx.user.id,
          organization: { projects: { some: { id: projectId } } },
          role: { in: ['OWNER', 'ADMIN', 'MEMBER'] },
        },
      });
 
      if (!membership) {
        return {
          __typename: 'AuthorizationError',
          message: 'Insufficient permissions',
          requiredRole: 'MEMBER',
        };
      }
 
      const task = await ctx.prisma.task.create({
        data: {
          ...validated.data,
          projectId,
          creatorId: ctx.user.id,
        },
      });
 
      return { __typename: 'Task', ...task };
    },
  },
 
  Task: {
    // DataLoader 批量加载关联
    assignee: (task, _args, ctx) => {
      if (!task.assigneeId) return null;
      return ctx.loaders.userLoader.load(task.assigneeId);
    },
    creator: (task, _args, ctx) => {
      return ctx.loaders.userLoader.load(task.creatorId);
    },
    project: (task, _args, ctx) => {
      return ctx.loaders.projectLoader.load(task.projectId);
    },
  },
 
  // Result Union 类型解析
  CreateProjectResult: {
    __resolveType(obj) {
      if ('name' in obj && 'id' in obj) return 'Project';
      if ('field' in obj) return 'ValidationError';
      if ('requiredRole' in obj) return 'AuthorizationError';
      return null;
    },
  },
};

请为以下 GraphQL Schema 生成完整的服务端实现：

## Schema
[粘贴 SDL]

## 技术栈
- GraphQL 服务器：[Apollo Server 4 / GraphQL Yoga / Mercurius]
- ORM：[Prisma / TypeORM / Drizzle]
- 验证：Zod

## 必须包含
1. DataLoader 工厂函数（防止 N+1 查询）
2. Relay Connection 分页辅助函数
3. 输入验证（Zod Schema）
4. Result Union 错误处理
5. 权限中间件（基于 @auth 指令）
6. 查询深度限制（最大 [N] 层）
7. 查询复杂度分析（最大 [N] 点）
8. 上下文工厂函数（包含认证、DataLoader、Prisma）

src/
├── server/
│   ├── trpc.ts              # tRPC 初始化（context, middleware）
│   ├── routers/
│   │   ├── _app.ts          # 根 Router（合并所有子 Router）
│   │   ├── auth.ts          # 认证相关
│   │   ├── user.ts          # 用户管理
│   │   ├── project.ts       # 项目管理
│   │   └── task.ts          # 任务管理
│   ├── schemas/             # Zod Schema（共享验证逻辑）
│   │   ├── auth.ts
│   │   ├── user.ts
│   │   ├── project.ts
│   │   └── task.ts
│   └── services/            # 业务逻辑层
│       ├── auth.service.ts
│       ├── user.service.ts
│       ├── project.service.ts
│       └── task.service.ts
├── client/
│   └── trpc.ts              # tRPC 客户端配置
└── shared/
    └── types.ts             # 共享类型（从 Zod Schema 推断）

// server/trpc.ts — tRPC 初始化
import { initTRPC, TRPCError } from '@trpc/server';
import { type CreateNextContextOptions } from '@trpc/server/adapters/next';
import superjson from 'superjson';
import { ZodError } from 'zod';
import { prisma } from '../lib/prisma';
import { verifyToken } from '../lib/auth';
 
// Context 创建
export const createTRPCContext = async (opts: CreateNextContextOptions) => {
  const token = opts.req.headers.authorization?.replace('Bearer ', '');
  const user = token ? await verifyToken(token) : null;
 
  return {
    prisma,
    user,
    req: opts.req,
  };
};
 
type Context = Awaited<ReturnType<typeof createTRPCContext>>;
 
// tRPC 初始化
const t = initTRPC.context<Context>().create({
  transformer: superjson,
  errorFormatter({ shape, error }) {
    return {
      ...shape,
      data: {
        ...shape.data,
        zodError:
          error.cause instanceof ZodError
            ? error.cause.flatten()
            : null,
      },
    };
  },
});
 
// 导出
export const router = t.router;
export const publicProcedure = t.procedure;
export const createCallerFactory = t.createCallerFactory;
 
// 认证中间件
const enforceAuth = t.middleware(({ ctx, next }) => {
  if (!ctx.user) {
    throw new TRPCError({ code: 'UNAUTHORIZED' });
  }
  return next({
    ctx: { ...ctx, user: ctx.user },
  });
});
 
export const protectedProcedure = t.procedure.use(enforceAuth);
 
// 日志中间件
const loggerMiddleware = t.middleware(async ({ path, type, next }) => {
  const start = Date.now();
  const result = await next();
  const duration = Date.now() - start;
  console.log(`[tRPC] ${type} ${path} - ${duration}ms`);
  return result;
});
 
export const loggedProcedure = t.procedure.use(loggerMiddleware);

请基于以下 Zod Schema 生成 tRPC Router：

## Zod Schema
[粘贴 schemas/ 目录下的 Schema 定义]

## 技术栈
- tRPC v11
- Prisma ORM
- Zod 验证
- SuperJSON 序列化

## 要求
- 使用 protectedProcedure（需要认证的端点）
- 列表查询支持 cursor 分页
- 包含输入验证（使用已定义的 Zod Schema）
- 包含权限检查中间件
- 错误处理使用 TRPCError
- 业务逻辑封装在 Service 层
- 包含乐观更新支持（返回更新后的完整对象）

// client/trpc.ts — Next.js 客户端配置
import { createTRPCReact } from '@trpc/react-query';
import { httpBatchLink } from '@trpc/client';
import superjson from 'superjson';
import type { AppRouter } from '../server/routers/_app';
 
export const trpc = createTRPCReact<AppRouter>();
 
export function getTRPCClient() {
  return trpc.createClient({
    links: [
      httpBatchLink({
        url: '/api/trpc',
        transformer: superjson,
        headers() {
          return {
            authorization: `Bearer ${getToken()}`,
          };
        },
      }),
    ],
  });
}

// 客户端使用 — 完全类型安全，零代码生成
// 修改服务端 Schema → 客户端自动获得类型错误提示
 
// 列表查询
const { data, fetchNextPage, hasNextPage } =
  trpc.task.list.useInfiniteQuery(
    { limit: 20, status: ['TODO', 'IN_PROGRESS'] },
    { getNextPageParam: (lastPage) => lastPage.nextCursor }
  );
 
// 创建任务（带乐观更新）
const utils = trpc.useUtils();
const createTask = trpc.task.create.useMutation({
  onSuccess: () => {
    utils.task.list.invalidate();
  },
});
 
// 调用 — 参数类型自动推断，拼写错误立即报错
createTask.mutate({
  title: '实现用户注册 API',
  priority: 'HIGH',  // 类型安全：只能是 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT'
});

// schemas/user.ts — Zod Schema 最佳实践
import { z } from 'zod';
 
// 基础字段定义（可复用）
const emailField = z.string().email('请输入有效的邮箱地址').max(255);
const passwordField = z.string()
  .min(8, '密码至少 8 个字符')
  .max(128, '密码最多 128 个字符')
  .regex(/[A-Z]/, '密码必须包含至少一个大写字母')
  .regex(/[a-z]/, '密码必须包含至少一个小写字母')
  .regex(/[0-9]/, '密码必须包含至少一个数字');
const nameField = z.string().min(1).max(100).trim();
 
// 创建用户 Schema
export const CreateUserSchema = z.object({
  email: emailField,
  password: passwordField,
  name: nameField,
});
 
// 更新用户 Schema（所有字段可选，使用 .partial()）
export const UpdateUserSchema = CreateUserSchema
  .omit({ password: true })  // 更新时不允许直接修改密码
  .partial();                  // 所有字段变为可选
 
// 修改密码 Schema
export const ChangePasswordSchema = z.object({
  currentPassword: z.string().min(1),
  newPassword: passwordField,
  confirmPassword: z.string(),
}).refine(
  (data) => data.newPassword === data.confirmPassword,
  { message: '两次输入的密码不一致', path: ['confirmPassword'] }
);
 
// 查询参数 Schema
export const UserQuerySchema = z.object({
  search: z.string().max(100).optional(),
  role: z.enum(['ADMIN', 'MEMBER', 'VIEWER']).optional(),
  cursor: z.string().cuid2().optional(),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  sortBy: z.enum(['name', 'email', 'createdAt']).default('createdAt'),
  sortDir: z.enum(['asc', 'desc']).default('desc'),
});
 
// 类型导出（从 Schema 自动推断）
export type CreateUserInput = z.infer<typeof CreateUserSchema>;
export type UpdateUserInput = z.infer<typeof UpdateUserSchema>;
export type UserQuery = z.infer<typeof UserQuerySchema>;

// middleware/validate.ts — 通用 Zod 验证中间件
import { Request, Response, NextFunction } from 'express';
import { ZodSchema, ZodError } from 'zod';
 
type ValidationTarget = 'body' | 'query' | 'params';
 
interface ValidationConfig {
  body?: ZodSchema;
  query?: ZodSchema;
  params?: ZodSchema;
}
 
export function validate(config: ValidationConfig) {
  return (req: Request, res: Response, next: NextFunction) => {
    const errors: Array<{
      target: ValidationTarget;
      issues: Array<{ path: string; message: string }>;
    }> = [];
 
    for (const [target, schema] of Object.entries(config)) {
      if (!schema) continue;
 
      const result = schema.safeParse(req[target as ValidationTarget]);
      if (!result.success) {
        errors.push({
          target: target as ValidationTarget,
          issues: result.error.issues.map((issue) => ({
            path: issue.path.join('.'),
            message: issue.message,
          })),
        });
      } else {
        // 用验证后的数据替换原始数据（包含默认值和类型转换）
        (req as any)[target] = result.data;
      }
    }
 
    if (errors.length > 0) {
      return res.status(422).json({
        type: 'https://api.example.com/errors/validation',
        title: 'Validation Error',
        status: 422,
        detail: 'One or more fields failed validation',
        errors,
      });
    }
 
    next();
  };
}
 
// 使用示例
import { CreateUserSchema, UserQuerySchema } from '../schemas/user';
 
router.post(
  '/users',
  validate({ body: CreateUserSchema }),
  userController.create
);
 
router.get(
  '/users',
  validate({ query: UserQuerySchema }),
  userController.list
);

# schemas/user.py — Pydantic v2 Schema
from pydantic import BaseModel, EmailStr, Field, field_validator
from typing import Optional
from enum import Enum
from datetime import datetime
import re
 
 
class UserRole(str, Enum):
    ADMIN = "admin"
    MEMBER = "member"
    VIEWER = "viewer"
 
 
class SortDirection(str, Enum):
    ASC = "asc"
    DESC = "desc"
 
 
class CreateUserRequest(BaseModel):
    email: EmailStr = Field(..., max_length=255)
    password: str = Field(..., min_length=8, max_length=128)
    name: str = Field(..., min_length=1, max_length=100)
 
    @field_validator("password")
    @classmethod
    def validate_password_strength(cls, v: str) -> str:
        if not re.search(r"[A-Z]", v):
            raise ValueError("密码必须包含至少一个大写字母")
        if not re.search(r"[a-z]", v):
            raise ValueError("密码必须包含至少一个小写字母")
        if not re.search(r"[0-9]", v):
            raise ValueError("密码必须包含至少一个数字")
        return v
 
    @field_validator("name")
    @classmethod
    def strip_name(cls, v: str) -> str:
        return v.strip()
 
 
class UpdateUserRequest(BaseModel):
    name: Optional[str] = Field(None, min_length=1, max_length=100)
    email: Optional[EmailStr] = Field(None, max_length=255)
 
 
class UserQueryParams(BaseModel):
    search: Optional[str] = Field(None, max_length=100)
    role: Optional[UserRole] = None
    cursor: Optional[str] = None
    limit: int = Field(default=20, ge=1, le=100)
    sort_by: str = Field(default="created_at")
    sort_dir: SortDirection = Field(default=SortDirection.DESC)
 
 
class UserResponse(BaseModel):
    id: str
    email: str
    name: str
    role: UserRole
    created_at: datetime
    updated_at: datetime
 
    model_config = {"from_attributes": True}

# routes/user.py — FastAPI 路由（Pydantic 自动验证 + OpenAPI 文档生成）
from fastapi import APIRouter, Depends, HTTPException, Query
from typing import Annotated
from ..schemas.user import (
    CreateUserRequest,
    UpdateUserRequest,
    UserQueryParams,
    UserResponse,
)
from ..services.user import UserService
from ..dependencies import get_current_user, get_user_service
 
router = APIRouter(prefix="/api/v1/users", tags=["Users"])
 
 
@router.post("/", response_model=UserResponse, status_code=201)
async def create_user(
    body: CreateUserRequest,  # Pydantic 自动验证请求体
    service: Annotated[UserService, Depends(get_user_service)],
):
    """创建新用户。密码要求：至少 8 位，包含大小写字母和数字。"""
    return await service.create(body)
 
 
@router.get("/", response_model=list[UserResponse])
async def list_users(
    params: Annotated[UserQueryParams, Query()],  # 自动验证查询参数
    current_user=Depends(get_current_user),
    service: Annotated[UserService, Depends(get_user_service)],
):
    """获取用户列表，支持搜索、过滤和分页。"""
    return await service.list(params)
 
 
@router.patch("/{user_id}", response_model=UserResponse)
async def update_user(
    user_id: str,
    body: UpdateUserRequest,
    current_user=Depends(get_current_user),
    service: Annotated[UserService, Depends(get_user_service)],
):
    """更新用户信息。仅传入需要修改的字段。"""
    return await service.update(user_id, body)

请为以下 API 端点生成输入验证 Schema：

## 技术栈
- 验证库：[Zod / Pydantic / Joi]
- 框架：[Express / NestJS / FastAPI / Hono]

## 端点列表
[列出每个端点的路径、方法、参数]

## 验证要求
- 字符串字段：最小/最大长度、格式（email/url/uuid）、trim
- 数字字段：最小/最大值、整数/浮点数
- 枚举字段：明确列出允许的值
- 日期字段：格式验证、范围限制
- 数组字段：最小/最大长度、元素类型验证
- 嵌套对象：递归验证
- 可选字段：明确标注，提供默认值
- 自定义验证：[描述业务规则]

## 安全要求
- 所有字符串输入必须有最大长度限制（防止 DoS）
- 分页 limit 参数必须有上限（如 100）
- ID 参数必须验证格式（CUID2/UUID）
- 禁止接受未定义的额外字段（strict mode）

## 输出要求
- 创建和更新使用不同的 Schema（更新字段可选）
- 导出 TypeScript 类型（从 Schema 推断）
- 包含自定义错误消息（中文）

// main.ts — NestJS Swagger 配置
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
 
  // Swagger 文档配置
  const config = new DocumentBuilder()
    .setTitle('项目管理 API')
    .setDescription('多租户项目管理 SaaS 的 RESTful API')
    .setVersion('1.0.0')
    .addBearerAuth(
      { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
      'JWT-auth'
    )
    .addTag('Projects', '项目管理')
    .addTag('Tasks', '任务管理')
    .addTag('Users', '用户管理')
    .addServer('https://api.example.com', '生产环境')
    .addServer('http://localhost:3000', '开发环境')
    .build();
 
  const document = SwaggerModule.createDocument(app, config);
 
  // 导出 OpenAPI JSON（用于客户端代码生成）
  const fs = await import('fs');
  fs.writeFileSync('./openapi.json', JSON.stringify(document, null, 2));
 
  // 挂载 Swagger UI
  SwaggerModule.setup('docs', app, document, {
    swaggerOptions: {
      persistAuthorization: true,
      tagsSorter: 'alpha',
      operationsSorter: 'alpha',
    },
  });
 
  await app.listen(3000);
}
bootstrap();

// dto/create-task.dto.ts — 使用装饰器生成文档
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import { IsString, IsEnum, IsOptional, MinLength, MaxLength } from 'class-validator';
 
export class CreateTaskDto {
  @ApiProperty({
    description: '任务标题',
    example: '实现用户注册 API',
    minLength: 1,
    maxLength: 200,
  })
  @IsString()
  @MinLength(1)
  @MaxLength(200)
  title: string;
 
  @ApiPropertyOptional({
    description: '任务描述',
    example: '包含邮箱验证和密码强度检查',
    maxLength: 5000,
  })
  @IsOptional()
  @IsString()
  @MaxLength(5000)
  description?: string;
 
  @ApiPropertyOptional({
    description: '优先级',
    enum: ['LOW', 'MEDIUM', 'HIGH', 'URGENT'],
    default: 'MEDIUM',
  })
  @IsOptional()
  @IsEnum(['LOW', 'MEDIUM', 'HIGH', 'URGENT'])
  priority?: string;
}

# main.py — FastAPI 自动文档
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
 
app = FastAPI(
    title="项目管理 API",
    description="多租户项目管理 SaaS 的 RESTful API",
    version="1.0.0",
    docs_url="/docs",        # Swagger UI
    redoc_url="/redoc",      # ReDoc
    openapi_url="/openapi.json",
)
 
# 自定义 OpenAPI Schema
def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title=app.title,
        version=app.version,
        description=app.description,
        routes=app.routes,
    )
    # 添加安全方案
    openapi_schema["components"]["securitySchemes"] = {
        "BearerAuth": {
            "type": "http",
            "scheme": "bearer",
            "bearerFormat": "JWT",
        }
    }
    openapi_schema["security"] = [{"BearerAuth": []}]
    app.openapi_schema = openapi_schema
    return app.openapi_schema
 
app.openapi = custom_openapi

// openapi.ts — 从 Zod Schema 生成 OpenAPI 文档
import {
  OpenAPIRegistry,
  OpenApiGeneratorV31,
  extendZodWithOpenApi,
} from '@asteasolutions/zod-to-openapi';
import { z } from 'zod';
 
extendZodWithOpenApi(z);
 
const registry = new OpenAPIRegistry();
 
// 注册 Schema
const TaskSchema = z.object({
  id: z.string().cuid2().openapi({ example: 'clx1234567890' }),
  title: z.string().min(1).max(200).openapi({ example: '实现用户注册 API' }),
  status: z.enum(['TODO', 'IN_PROGRESS', 'IN_REVIEW', 'DONE']),
  priority: z.enum(['LOW', 'MEDIUM', 'HIGH', 'URGENT']),
  createdAt: z.string().datetime(),
}).openapi('Task');
 
const CreateTaskSchema = z.object({
  title: z.string().min(1).max(200),
  description: z.string().max(5000).optional(),
  priority: z.enum(['LOW', 'MEDIUM', 'HIGH', 'URGENT']).default('MEDIUM'),
}).openapi('CreateTaskInput');
 
// 注册端点
registry.registerPath({
  method: 'post',
  path: '/api/v1/tasks',
  summary: '创建任务',
  tags: ['Tasks'],
  request: {
    body: {
      content: { 'application/json': { schema: CreateTaskSchema } },
    },
  },
  responses: {
    201: {
      description: '任务创建成功',
      content: { 'application/json': { schema: TaskSchema } },
    },
    422: {
      description: '输入验证失败',
    },
  },
});
 
// 生成 OpenAPI 文档
const generator = new OpenApiGeneratorV31(registry.definitions);
const document = generator.generateDocument({
  openapi: '3.1.0',
  info: { title: '项目管理 API', version: '1.0.0' },
  servers: [{ url: 'https://api.example.com' }],
});
 
// 导出为 JSON 文件
import fs from 'fs';
fs.writeFileSync('openapi.json', JSON.stringify(document, null, 2));

请为以下 API 端点生成完整的 OpenAPI 3.1 文档：

## 端点列表
[列出所有端点的路径、方法、参数、请求体、响应]

## 文档要求
- 每个端点包含 summary 和 description（中文）
- 每个参数包含 description 和 example
- 每个 Schema 包含 example 值
- 包含认证安全方案（Bearer Token）
- 包含标准错误响应（400, 401, 403, 404, 422, 500）
- 使用 $ref 引用共享的 Schema 组件
- 包含 tags 分组

## 输出格式
- YAML 格式
- 符合 OpenAPI 3.1.0 规范
- 可直接导入 Swagger UI / Scalar / Redocly

// NestJS — URL 路径版本管理
// main.ts
import { VersioningType } from '@nestjs/common';
 
app.enableVersioning({
  type: VersioningType.URI,
  defaultVersion: '1',
  prefix: 'api/v',
});
 
// controllers/user.controller.ts
@Controller({ path: 'users', version: '1' })
export class UserControllerV1 {
  @Get()
  findAll() {
    return this.userService.findAllV1();
  }
}
 
@Controller({ path: 'users', version: '2' })
export class UserControllerV2 {
  @Get()
  findAll() {
    // V2 返回不同的响应格式
    return this.userService.findAllV2();
  }
}

// middleware/deprecation.ts — 版本废弃通知中间件
import { Request, Response, NextFunction } from 'express';
 
interface VersionConfig {
  current: string;
  supported: string[];
  deprecated: Record<string, { sunset: string; successor: string }>;
}
 
const versionConfig: VersionConfig = {
  current: 'v2',
  supported: ['v1', 'v2'],
  deprecated: {
    v1: {
      sunset: '2026-06-01',
      successor: 'v2',
    },
  },
};
 
export function versionDeprecationMiddleware(
  req: Request,
  res: Response,
  next: NextFunction
) {
  const version = req.path.match(/\/api\/(v\d+)\//)?.[1];
  if (!version) return next();
 
  const deprecation = versionConfig.deprecated[version];
  if (deprecation) {
    res.setHeader('Deprecation', 'true');
    res.setHeader('Sunset', deprecation.sunset);
    res.setHeader(
      'Link',
      `</api/${deprecation.successor}${req.path.replace(`/api/${version}`, '')}>; rel="successor-version"`
    );
    // 可选：记录废弃版本的使用情况
    console.warn(
      `[DEPRECATED] ${version} API called: ${req.method} ${req.path}`
    );
  }
 
  next();
}

请帮我将以下 API 从 v1 迁移到 v2：

## v1 API 定义
[粘贴 v1 的 OpenAPI 规范或代码]

## v2 变更列表
- [描述每个破坏性变更]
- 例如：User 响应中 fullName 拆分为 firstName + lastName
- 例如：分页从 offset 改为 cursor
- 例如：错误格式从自定义改为 RFC 7807

## 要求
1. 生成 v2 的 Controller/Router 代码
2. 生成 v1 → v2 的兼容适配层（让 v1 调用者平滑过渡）
3. 生成迁移指南文档（面向 API 消费者）
4. v1 添加 Deprecation 响应头
5. 包含版本路由配置

请分析以下业务需求，提取 API 资源模型：

## 业务需求
[描述业务场景]

## 输出要求
1. 核心资源列表（名称、描述、关键属性）
2. 资源间关系图（Mermaid ER 图）
3. 每个资源的 CRUD 需求分析
4. 非 CRUD 操作识别（如"审批"、"发布"、"归档"）
5. 建议的 URL 结构

# 使用 Prism 从 OpenAPI 生成 Mock 服务
npx @stoplight/prism-cli mock openapi.yaml --port 4010
 
# 使用 MSW（Mock Service Worker）生成前端 Mock
# AI 可以从 OpenAPI 规范生成 MSW handlers

请基于以下 OpenAPI 规范生成 API 集成测试：

## OpenAPI 规范
[粘贴规范]

## 测试框架
- [Jest + Supertest / Pytest + httpx / Go testing]

## 测试覆盖要求
- 每个端点的正常路径（200/201）
- 输入验证失败（422）
- 认证失败（401）
- 权限不足（403）
- 资源不存在（404）
- 分页边界（空列表、最后一页）
- 并发创建（幂等性验证）

# 使用 Scalar 渲染美观的 API 文档
npx @scalar/cli serve openapi.yaml --port 3100
 
# 使用 Redocly 生成静态文档站点
npx @redocly/cli build-docs openapi.yaml --output docs/api/index.html

我需要为一个电商平台设计 API，核心功能包括：
1. 商品管理（CRUD、分类、搜索、库存管理）
2. 购物车（添加/移除/更新数量）
3. 订单（创建、支付、发货、退款）
4. 用户（注册、登录、地址管理）

请提取资源模型和 URL 结构。

核心资源：
- Product（商品）: id, name, description, price, stock, categoryId, images, status
- Category（分类）: id, name, slug, parentId
- Cart（购物车）: id, userId, items[]
- CartItem（购物车项）: id, cartId, productId, quantity
- Order（订单）: id, userId, items[], status, totalAmount, shippingAddress
- OrderItem（订单项）: id, orderId, productId, quantity, unitPrice
- User（用户）: id, email, name, addresses[]
- Address（地址）: id, userId, street, city, state, zipCode, isDefault

URL 结构：
/api/v1/products          — 商品 CRUD + 搜索
/api/v1/categories        — 分类 CRUD
/api/v1/cart              — 当前用户购物车
/api/v1/cart/items        — 购物车项操作
/api/v1/orders            — 订单 CRUD
/api/v1/orders/:id/pay    — 支付（非 CRUD 操作）
/api/v1/orders/:id/ship   — 发货（非 CRUD 操作）
/api/v1/orders/:id/refund — 退款（非 CRUD 操作）
/api/v1/users/me          — 当前用户信息
/api/v1/users/me/addresses — 地址管理

# 订单相关端点（OpenAPI 3.1 片段）
paths:
  /api/v1/orders:
    post:
      operationId: createOrder
      summary: 创建订单
      tags: [Orders]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shippingAddressId]
              properties:
                shippingAddressId:
                  type: string
                  description: 收货地址 ID
                note:
                  type: string
                  maxLength: 500
                  description: 订单备注
      responses:
        '201':
          description: 订单创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: 购物车为空或库存不足
 
  /api/v1/orders/{orderId}/pay:
    post:
      operationId: payOrder
      summary: 支付订单
      tags: [Orders]
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [paymentMethod]
              properties:
                paymentMethod:
                  type: string
                  enum: [credit_card, alipay, wechat_pay]
                paymentToken:
                  type: string
                  description: 支付网关返回的 token
      responses:
        '200':
          description: 支付成功
        '402':
          description: 支付失败
        '409':
          description: 订单状态不允许支付

// schemas/order.ts
import { z } from 'zod';
 
export const PaymentMethod = z.enum(['credit_card', 'alipay', 'wechat_pay']);
 
export const CreateOrderSchema = z.object({
  shippingAddressId: z.string().cuid2(),
  note: z.string().max(500).optional(),
});
 
export const PayOrderSchema = z.object({
  paymentMethod: PaymentMethod,
  paymentToken: z.string().min(1).optional(),
});
 
export const OrderQuerySchema = z.object({
  status: z.enum([
    'PENDING', 'PAID', 'SHIPPED', 'DELIVERED', 'CANCELLED', 'REFUNDED'
  ]).optional(),
  cursor: z.string().optional(),
  limit: z.coerce.number().int().min(1).max(50).default(20),
});

// controllers/order.controller.ts
@Controller('api/v1/orders')
@UseGuards(JwtAuthGuard)
@ApiTags('Orders')
export class OrderController {
  constructor(private readonly orderService: OrderService) {}
 
  @Post()
  @HttpCode(HttpStatus.CREATED)
  @ApiOperation({ summary: '创建订单（从购物车）' })
  async create(
    @CurrentUser() user: AuthUser,
    @Body(new ZodValidationPipe(CreateOrderSchema)) dto: CreateOrderInput,
  ) {
    return this.orderService.createFromCart(user.id, dto);
  }
 
  @Post(':orderId/pay')
  @ApiOperation({ summary: '支付订单' })
  async pay(
    @CurrentUser() user: AuthUser,
    @Param('orderId') orderId: string,
    @Body(new ZodValidationPipe(PayOrderSchema)) dto: PayOrderInput,
  ) {
    return this.orderService.processPayment(user.id, orderId, dto);
  }
 
  @Post(':orderId/refund')
  @Roles('ADMIN')
  @UseGuards(RolesGuard)
  @ApiOperation({ summary: '退款（仅管理员）' })
  async refund(
    @Param('orderId') orderId: string,
    @Body() dto: RefundOrderDto,
  ) {
    return this.orderService.processRefund(orderId, dto);
  }
}