packages/global/openapi/
├── api.ts                          # 公共 Schema (分页等)
├── type.ts                         # OpenAPIPath 类型
├── tag.ts                          # API 标签定义
├── index.ts                        # 用户 API 文档入口
├── admin.ts                        # 管理员 API 文档入口
└── core/
    └── dataset/
        ├── api.ts                  # ← Schema 定义 (入参/出参)
        ├── index.ts                # ← OpenAPI 路由注册
        ├── collection/
        │   ├── api.ts
        │   └── index.ts
        └── data/
            ├── api.ts
            └── index.ts

import { z } from 'zod';
import { ObjectIdSchema } from '../../../common/type/mongo';
import { ParentIdSchema } from '../../../common/parentFolder/type';

/* ============================================================================
 * API: 创建知识库
 * Route: POST /api/core/dataset/create
 * ============================================================================ */
// 入参 Schema
export const CreateDatasetBodySchema = z.object({
  parentId: ParentIdSchema.meta({
    example: '68ad85a7463006c963799a05',
    description: '父级文件夹 ID'
  }),
  name: z.string().meta({
    example: '我的知识库',
    description: '知识库名称'
  })
});
export type CreateDatasetBodyType = z.infer<typeof CreateDatasetBodySchema>;

// 出参 Schema
export const CreateDatasetResponseSchema = ObjectIdSchema.meta({
  example: '68ad85a7463006c963799a05',
  description: '新创建的知识库 ID'
});
export type CreateDatasetResponseType = z.infer<typeof CreateDatasetResponseSchema>;

import { NextAPI } from '@/service/middleware/entry';
import type { ApiRequestProps } from '@fastgpt/service/type/next';
import {
  CreateDatasetBodySchema,
  CreateDatasetResponseSchema,
  type CreateDatasetResponseType
} from '@fastgpt/global/openapi/core/dataset/api';

// ❌ 不要在路由文件中重导出类型别名
// export type DatasetCreateBodyType = CreateDatasetBodyType;

async function handler(req: ApiRequestProps): Promise<CreateDatasetResponseType> {
  // 1. 入参验证
  const { parentId, name } = CreateDatasetBodySchema.parse(req.body);

  // 2. 业务逻辑
  const datasetId = await createDataset({ parentId, name });

  // 3. 出参验证
  return CreateDatasetResponseSchema.parse(datasetId);
}

export default NextAPI(handler);

export const DevApiTagsMap = {
  // Dataset
  datasetCommon: '知识库管理',    // ← 新增
  datasetCollection: '集合管理',
  // ...
};

import type { OpenAPIPath } from '../../type';
import { DevApiTagsMap } from '../../tag';
import { CreateDatasetBodySchema } from './api';

export const DatasetPath: OpenAPIPath = {
  '/core/dataset/create': {
    post: {
      summary: '创建知识库',
      description: '创建新的知识库,支持多种类型',
      tags: [DevApiTagsMap.datasetCommon],
      requestBody: {
        content: {
          'application/json': {
            schema: CreateDatasetBodySchema
          }
        }
      },
      responses: {
        200: {
          description: '成功返回新创建的知识库 ID'
        }
      }
    }
  },
  ...DatasetCollectionPath,
  ...DatasetDataPath
};

// ✅ 正确: 从 openapi 导入
import type { CreateDatasetBodyType } from '@fastgpt/global/openapi/core/dataset/api';

// ❌ 错误: 从路由文件导入
import type { DatasetCreateBodyType } from '@/pages/api/core/dataset/create';

// ❌ 错误: 从旧的 global 文件导入
import type { CreateDatasetParams } from '@/global/core/dataset/api';

import createHandler from '@/pages/api/core/dataset/create';
import type {
  CreateDatasetBodyType,
  CreateDatasetResponseType
} from '@fastgpt/global/openapi/core/dataset/api';
import { Call } from '@test/utils/request';

const res = await Call<CreateDatasetBodyType, {}, CreateDatasetResponseType>(createHandler, {
  auth: users.members[0],
  body: { name: 'test', intro: 'intro', avatar: 'avatar', type: DatasetTypeEnum.dataset }
});

// ❌ 出参验证会失败 — ObjectId 不是 string
export const ResponseSchema = z.string();
return ResponseSchema.parse(document._id); // ZodError!

// ✅ ObjectIdSchema 内置 preprocess，自动转换
import { ObjectIdSchema } from '../../../common/type/mongo';
export const ResponseSchema = ObjectIdSchema;
return ResponseSchema.parse(document._id); // "68ad85a7463006c963799a05"

z.string().meta({
  example: '[email protected]',
  description: '用户邮箱'
})

// 可选 (undefined)
z.string().optional().meta({ description: '...' })

// 可空 (undefined | null) — 用于 parentId 等场景
z.string().nullish().meta({ description: '...' })

import { DatasetTypeEnum } from '../../../core/dataset/constants';

// TypeScript enum — 使用 z.enum
z.enum(DatasetTypeEnum).meta({
  example: DatasetTypeEnum.dataset,
  description: '知识库类型'
})

const FileItemSchema = z.object({
  fileId: z.string().meta({ example: 'temp/abc.pdf', description: '文件 ID' }),
  name: z.string().meta({ example: '文档.pdf', description: '文件名' })
});

export const CreateWithFilesBodySchema = z.object({
  files: z.array(FileItemSchema).meta({ description: '文件列表' })
});

# 搜索旧类型名
grep -r "CreateDatasetParams" projects/app/src/

// ❌ 删除这些
export type DatasetCreateQuery = {};
export type DatasetCreateBodyType = CreateDatasetBodyType;
export type DatasetCreateResponse = CreateDatasetResponseType;