feat: integrate ts-rest (#5741)

* feat: integrate ts-rest

* chore: classify core contract and pro contract

* chore: update lockfile

* chore: tweak dir structure

* chore: tweak dir structure

packages/global/common/tsRest/fastgpt/client.ts

@@ -0,0 +1,172 @@
+import { contract } from './contracts';
+import { initClient, tsRestFetchApi } from '@ts-rest/core';
+import { TOKEN_ERROR_CODE } from '../../error/errorCode';
+import { getNanoid } from '../../string/tools';
+import { type ApiFetcherArgs } from '@ts-rest/core';
+import { AnyResponseSchema } from '../../type';
+import { ZodError } from 'zod';
+import { getWebReqUrl } from '../../../../web/common/system/utils';
+
+export const client = initClient(contract, {
+  baseUrl: getWebReqUrl('/api'),
+  throwOnUnknownStatus: true,
+  validateResponse: false,
+  credentials: 'include',
+  baseHeaders: {
+    'Content-Type': 'application/json;charset=utf-8'
+  },
+  api: async (args: BeforeFetchOptions) => {
+    const prepare = beforeFetch(args);
+    const response = await tsRestFetchApi(args);
+    return afterFetch(response, prepare);
+  }
+});
+
+const WHITE_LIST = ['/chat/share', '/chat', '/login'];
+async function isTokenExpired() {
+  if (WHITE_LIST.includes(window.location.pathname)) return;
+
+  await client.support.user.account.logout();
+  const lastRoute = encodeURIComponent(location.pathname + location.search);
+  window.location.replace(getWebReqUrl(`/login?lastRoute=${lastRoute}`));
+}
+
+export function checkBusinessCode(code: number) {
+  if (code in TOKEN_ERROR_CODE) {
+    isTokenExpired();
+    return;
+  }
+}
+
+type Item = { id: string; controller: AbortController };
+const queue = new Map<string, Item[]>();
+function checkMaxRequestLimitation(options: { url: string; max: number }): {
+  id: string;
+  signal: AbortSignal;
+  release: () => void;
+} {
+  const { url, max } = options;
+  const id = getNanoid();
+  const controller = new AbortController();
+  const item = queue.get(url);
+
+  const current = item ?? [];
+  if (current.length >= max) {
+    const first = current.shift()!;
+    first.controller.abort();
+  }
+  current.push({ id, controller });
+  if (!item) queue.set(url, current);
+
+  const release = () => {
+    const item = queue.get(url);
+    if (!item) return;
+
+    const index = item.findIndex((item) => item.id === id);
+    if (index !== -1) {
+      item.splice(index, 1);
+    }
+
+    if (item.length <= 0) {
+      queue.delete(url);
+    }
+  };
+
+  return { id, signal: controller.signal, release };
+}
+
+function checkHttpStatus(status: number): status is 200 {
+  if (status !== 200) return false;
+  return true;
+}
+
+type BeforeFetchOptions = ApiFetcherArgs & { max?: number };
+function beforeFetch(options: BeforeFetchOptions):
+  | {
+      limit: { id: string; url: string; release: () => void };
+    }
+  | undefined {
+  const { max, ...args } = options;
+  if (!max || max <= 0) return;
+
+  const { id, signal, release } = checkMaxRequestLimitation({ url: args.path, max });
+  args.fetchOptions ??= {};
+  args.fetchOptions.signal = signal;
+
+  return {
+    limit: { id, url: args.path, release }
+  };
+}
+
+function afterFetch(
+  response: Awaited<ReturnType<typeof tsRestFetchApi>>,
+  prepare?: ReturnType<typeof beforeFetch>
+) {
+  if (checkHttpStatus(response.status)) {
+    try {
+      const body = AnyResponseSchema.parse(response.body);
+
+      response.body = body.data;
+
+      if (prepare?.limit) {
+        prepare.limit.release();
+      }
+
+      return response;
+    } catch (error) {
+      if (error instanceof ZodError) {
+        throw new Error(error.message);
+      }
+
+      throw new Error('Unknown error while intercept response');
+    }
+  } else {
+    throw new Error(`HTTP error, status: ${response.status}`);
+  }
+}
+
+type Client = typeof client;
+type U<T> = { [K in keyof T]: T[K] extends (...args: any[]) => any ? T[K] : U<T[K]> }[keyof T];
+export type Endpoints = U<Client>;
+type _Options<T extends Endpoints> = NonNullable<Parameters<T>[0]>;
+type ExtractBodySchema<T extends Endpoints> = 'body' extends keyof _Options<T>
+  ? _Options<T>['body']
+  : never;
+type ExtractQuerySchema<T extends Endpoints> = 'query' extends keyof _Options<T>
+  ? _Options<T>['query']
+  : never;
+export type Params<T extends Endpoints> = (ExtractBodySchema<T> extends never
+  ? {}
+  : ExtractBodySchema<T>) &
+  (ExtractQuerySchema<T> extends never ? {} : ExtractQuerySchema<T>);
+export type Options<T extends Endpoints> = Omit<_Options<T>, 'body' | 'query'>;
+type Body<T extends Endpoints> = Extract<Awaited<ReturnType<T>>, { status: 200 }>['body'];
+type RestAPIResult<T extends Endpoints> = Body<T>;
+
+const call = async <T extends Endpoints>(
+  api: T,
+  options: _Options<T>
+): Promise<RestAPIResult<T>> => {
+  const res = await api(options as any);
+
+  if (res.status !== 200) {
+    throw new Error(`Unexpected status: ${res.status}`);
+  }
+
+  return res.body as RestAPIResult<T>;
+};
+
+export const RestAPI = <T extends Endpoints>(
+  endpoint: T,
+  transform?: (params: Params<T>) => {
+    body?: ExtractBodySchema<T> extends never ? any : ExtractBodySchema<T>;
+    query?: ExtractQuerySchema<T> extends never ? any : ExtractQuerySchema<T>;
+  }
+) => {
+  return (params?: Params<T>, options?: Options<T>) => {
+    const transformedData = params && transform ? transform(params) : {};
+    const finalOptions = { ...options, ...transformedData } as _Options<T>;
+
+    return call(endpoint, finalOptions);
+  };
+};

packages/global/common/tsRest/fastgpt/contracts/chat/index.ts

@@ -0,0 +1,6 @@
+import { settingContract } from './setting';
+import { c } from '../../../init';
+
+export const chatContract = c.router({
+  setting: settingContract
+});

packages/global/common/tsRest/fastgpt/contracts/chat/setting/favourite/index.ts

@@ -0,0 +1,94 @@
+import { ObjectIdSchema } from '../../../../../../type';
+import {
+  ChatFavouriteAppResponseItemSchema,
+  ChatFavouriteAppUpdateSchema
+} from '../../../../../../../core/chat/favouriteApp/type';
+import { c } from '../../../../../init';
+import { z } from 'zod';
+
+export const favouriteContract = c.router({
+  list: {
+    path: '/proApi/core/chat/setting/favourite/list',
+    method: 'GET',
+    query: z.object({
+      name: z.string().optional().openapi({ example: 'FastGPT' }),
+      tag: z.string().optional().openapi({ example: 'i7Ege2W2' })
+    }),
+    responses: {
+      200: z.array(ChatFavouriteAppResponseItemSchema)
+    },
+    metadata: {
+      tags: ['chat']
+    },
+    description: '获取精选应用列表',
+    summary: '获取精选应用列表'
+  },
+
+  update: {
+    path: '/proApi/core/chat/setting/favourite/update',
+    method: 'PUT',
+    body: ChatFavouriteAppUpdateSchema,
+    responses: {
+      200: c.type<void>()
+    },
+    metadata: {
+      tags: ['chat']
+    },
+    description: '更新精选应用',
+    summary: '更新精选应用'
+  },
+
+  delete: {
+    path: '/proApi/core/chat/setting/favourite/delete',
+    method: 'DELETE',
+    query: z.object({
+      id: ObjectIdSchema
+    }),
+    responses: {
+      200: c.type<void>()
+    },
+    metadata: {
+      tags: ['chat']
+    },
+    description: '删除精选应用',
+    summary: '删除精选应用'
+  },
+
+  order: {
+    path: '/proApi/core/chat/setting/favourite/order',
+    method: 'PUT',
+    body: z.array(
+      z.object({
+        id: ObjectIdSchema,
+        order: z.number()
+      })
+    ),
+    responses: {
+      200: c.type<void>()
+    },
+    metadata: {
+      tags: ['chat']
+    },
+    description: '更新精选应用顺序',
+    summary: '更新精选应用顺序'
+  },
+
+  tags: {
+    path: '/proApi/core/chat/setting/favourite/tags',
+    method: 'PUT',
+    body: z.array(
+      z.object({
+        id: z.string(),
+        tags: z.array(z.string())
+      })
+    ),
+    responses: {
+      200: c.type<void>()
+    },
+    metadata: {
+      tags: ['chat']
+    },
+    description: '更新精选应用标签',
+    summary: '更新精选应用标签'
+  }
+});

packages/global/common/tsRest/fastgpt/contracts/chat/setting/index.ts

@@ -0,0 +1,37 @@
+import {
+  ChatSettingResponseSchema,
+  ChatSettingSchema
+} from '../../../../../../core/chat/setting/type';
+import { c } from '../../../../init';
+import { favouriteContract } from './favourite';
+
+export const settingContract = c.router({
+  favourite: favouriteContract,
+
+  detail: {
+    path: '/proApi/core/chat/setting/detail',
+    method: 'GET',
+    responses: {
+      200: ChatSettingResponseSchema
+    },
+    metadata: {
+      tags: ['chat']
+    },
+    description: '获取聊天设置',
+    summary: '获取聊天设置'
+  },
+
+  update: {
+    path: '/proApi/core/chat/setting/update',
+    method: 'PUT',
+    body: ChatSettingSchema.partial(),
+    responses: {
+      200: c.type<void>()
+    },
+    metadata: {
+      tags: ['chat']
+    },
+    description: '更新聊天设置',
+    summary: '更新聊天设置'
+  }
+});

packages/global/common/tsRest/fastgpt/contracts/index.ts

@@ -0,0 +1,14 @@
+import { supportContract } from './support';
+import { chatContract } from './chat';
+import { c } from '../../init';
+
+// 前端使用的完整合约（开源 + Pro）
+// FastGPT 后端使用的合约
+export const contract = c.router({
+  chat: {
+    ...chatContract
+  },
+  support: {
+    ...supportContract
+  }
+});

packages/global/common/tsRest/fastgpt/contracts/support/index.ts

@@ -0,0 +1,6 @@
+import { userContract } from './user';
+import { c } from '../../../init';
+
+export const supportContract = c.router({
+  user: userContract
+});

packages/global/common/tsRest/fastgpt/contracts/support/user/account/index.ts

@@ -0,0 +1,17 @@
+import { c } from '../../../../../init';
+
+export const accountContract = c.router({
+  logout: {
+    path: '/support/user/account/login',
+    method: 'POST',
+    body: c.type<undefined>(),
+    responses: {
+      200: c.type<void>()
+    },
+    metadata: {
+      tags: ['support']
+    },
+    description: '退出登录',
+    summary: '退出登录'
+  }
+});

packages/global/common/tsRest/fastgpt/contracts/support/user/index.ts

@@ -0,0 +1,6 @@
+import { accountContract } from '../../../../fastgpt/contracts/support/user/account';
+import { c } from '../../../../init';
+
+export const userContract = c.router({
+  account: accountContract
+});

packages/global/common/tsRest/fastgpt/server.ts

@@ -0,0 +1,21 @@
+import { createNextRouter } from '@ts-rest/next';
+import { createNextRoute } from '@ts-rest/next';
+import { contract } from './contracts';
+
+/**
+ * 创建 FastGPT 单个路由
+ */
+export function createServerRoute(
+  implementation: Parameters<typeof createNextRoute<typeof contract>>[1]
+) {
+  return createNextRoute(contract, implementation);
+}
+
+/**
+ * 创建 FastGPT 路由器
+ */
+export function createServerRouter(
+  router: Parameters<typeof createNextRouter<typeof contract>>[1]
+) {
+  return createNextRouter(contract, router);
+}

packages/global/common/tsRest/fastgptpro/contracts/index.ts

@@ -0,0 +1,55 @@
+import { chatContract } from '../../fastgpt/contracts/chat';
+import { c } from '../../init';
+
+// 通过 FastGPT 后端转发到 Pro 后端使用的合约
+const transformedProContract = c.router({
+  chat: transformPaths(chatContract)
+});
+
+// Pro 后端独有的接口
+const proOnlyContract = c.router({
+  // TODO
+  // admin: adminContract,
+});
+
+// 最终的 Pro 合约 = 转换后的 Pro 接口 + Pro 后端独有的接口
+// Pro 后端使用的合约
+export const proContract = c.router({
+  ...transformedProContract,
+  ...proOnlyContract
+});
+
+/**
+ * 转换路径前缀
+ * 将 /proApi 替换为空字符串，用于 Pro 后端
+ */
+function transformPaths<T extends Record<string, any>>(
+  router: T,
+  removePrefix: string = '/proApi',
+  replaceWith: string = ''
+): T {
+  const transform = (obj: any): any => {
+    if (typeof obj !== 'object' || obj === null) return obj;
+
+    // 如果是路由定义（有 path 属性）
+    if ('path' in obj && typeof obj.path === 'string') {
+      return {
+        ...obj,
+        path: obj.path.replace(removePrefix, replaceWith),
+        metadata: {
+          ...obj.metadata,
+          originalPath: obj.path
+        }
+      };
+    }
+
+    // 递归处理嵌套的路由
+    const result: any = {};
+    for (const key in obj) {
+      result[key] = transform(obj[key]);
+    }
+    return result;
+  };
+
+  return transform(router) as T;
+}

packages/global/common/tsRest/fastgptpro/server.ts

@@ -0,0 +1,21 @@
+import { proContract } from './contracts';
+import { createNextRoute, createNextRouter } from '@ts-rest/next';
+
+/**
+ * 创建 Pro 单个路由
+ */
+export function createProServerRoute(
+  implementation: Parameters<typeof createNextRoute<typeof proContract>>[1]
+) {
+  return createNextRoute(proContract, implementation);
+}
+
+/**
+ * 创建 Pro 路由器
+ * 只需实现 Pro 接口（路径已自动转换 /proApi → 空）
+ */
+export function createProServerRouter(
+  router: Parameters<typeof createNextRouter<typeof proContract>>[1]
+) {
+  return createNextRouter(proContract, router);
+}

packages/global/common/tsRest/init.ts

@@ -0,0 +1,3 @@
+import { initContract } from '@ts-rest/core';
+
+export const c = initContract();

packages/global/common/tsRest/openapi.ts

@@ -0,0 +1,34 @@
+import type { contract } from './fastgpt/contracts';
+import { generateOpenApi } from '@ts-rest/open-api';
+
+const hasCustomTags = (metadata: unknown): metadata is { tags: string[] } => {
+  return !!metadata && typeof metadata === 'object' && 'tags' in metadata;
+};
+
+export type OpenAPIObject = ReturnType<typeof generateOpenApi>;
+export function generateOpenApiDocument(c: typeof contract): OpenAPIObject {
+  return generateOpenApi(
+    c,
+    {
+      info: {
+        title: 'FastGPT OpenAPI',
+        version: '4.12.4',
+        description: 'FastGPT OpenAPI'
+      },
+      servers: [{ url: '/api' }]
+    },
+    {
+      operationMapper(operation, appRoute) {
+        return {
+          ...operation,
+          ...(hasCustomTags(appRoute.metadata)
+            ? {
+                tags: appRoute.metadata.tags
+              }
+            : {})
+        };
+      },
+      setOperationId: false
+    }
+  );
+}

packages/global/common/tsRest/type.ts

@@ -0,0 +1,14 @@
+import type { AppRoute } from '@ts-rest/core';
+import type { createSingleRouteHandler } from '@ts-rest/next';
+
+export type { AppRoute } from '@ts-rest/core';
+
+export type Endpoint<T extends AppRoute> = Parameters<typeof createSingleRouteHandler<T>>[1];
+export type Args<T extends AppRoute> = Parameters<Endpoint<T>>[0];
+type Result<T extends AppRoute> = Awaited<ReturnType<Endpoint<T>>>;
+
+type Ok<T extends AppRoute> = Extract<Result<T>, { status: 200 }>;
+type Response<T extends AppRoute> =
+  Ok<T> extends { body: infer B } ? (B extends { data: infer D } ? D : B) : never;
+
+export type Handler<T extends AppRoute> = (args: Args<T>) => Promise<Response<T>>;