feat(openapi): 补全 admin API 文档并修复 pg/template 兼容问题 (#7333)

Co-authored-by: 李俊鹏64078 <64078@sangfor.com>

packages/global/openapi/admin/common/index.ts

+import { AdminLicensePath } from './license';
+import { AdminLogsPath } from './log';
+import type { OpenAPIPath } from '../../type';
+
+export const AdminCommonPath: OpenAPIPath = {
+  ...AdminLicensePath,
+  ...AdminLogsPath
+};

packages/global/openapi/admin/common/license/api.ts

+import z from 'zod';
+
+export const ActiveLicenseBodySchema = z.object({
+  license: z.string().meta({ description: '许可证密钥字符串' })
+});

packages/global/openapi/admin/common/license/index.ts

+import type { OpenAPIPath } from '../../../type';
+import { DevApiTagsMap } from '../../../tag';
+import { ActiveLicenseBodySchema } from './api';
+
+export const AdminLicensePath: OpenAPIPath = {
+  '/admin/common/license/active': {
+    post: {
+      summary: '激活许可证',
+      description: '使用许可证密钥激活 FastGPT 商业版',
+      tags: [DevApiTagsMap.adminLicense],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: ActiveLicenseBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '激活成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/common/license/auth': {
+    get: {
+      summary: '获取许可证信息',
+      description: '获取当前激活的许可证信息。已认证返回完整信息，未认证仅返回公司名',
+      tags: [DevApiTagsMap.adminLicense],
+      responses: {
+        200: {
+          description: '成功获取许可证信息',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/common/log/api.ts

+import z from 'zod';
+import { PaginationResponseSchema, PaginationSchema } from '../../../api';
+
+export const LogItemSchema = z.object({
+  _id: z.string().meta({ description: '日志ID' }),
+  level: z.number().meta({ description: '日志等级' }),
+  text: z.string().meta({ description: '日志内容' }),
+  createTime: z.date().meta({ description: '创建时间' })
+});
+
+export const GetLogListBodySchema = PaginationSchema.extend({
+  search: z.string().optional().meta({ description: '搜索关键词（模糊匹配日志内容）' }),
+  logLevel: z
+    .array(z.number().describe('日志等级'))
+    .optional()
+    .meta({ description: '日志等级筛选，默认 [3]（ERROR）' })
+});
+export const GetLogListResponseSchema = PaginationResponseSchema(LogItemSchema);

packages/global/openapi/admin/common/log/index.ts

+import type { OpenAPIPath } from '../../../type';
+import { DevApiTagsMap } from '../../../tag';
+import { GetLogListBodySchema, GetLogListResponseSchema } from './api';
+
+export const AdminLogsPath: OpenAPIPath = {
+  '/admin/common/log/list': {
+    post: {
+      summary: '获取系统日志列表',
+      description: '分页获取系统日志，支持按关键词搜索和日志等级筛选',
+      tags: [DevApiTagsMap.adminLogs],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: GetLogListBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '成功获取日志列表',
+          content: {
+            'application/json': {
+              schema: GetLogListResponseSchema
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/core/app/index.ts

 import type { OpenAPIPath } from '../../../type';
 import { GetAppsBodySchema, GetAppsResponseSchema } from './api';
 import { DevApiTagsMap } from '../../../tag';
+import { AdminTemplatePath } from './templates';
+import { AdminTemplateTypePath } from './templateType';
 
 export const AdminAppPath: OpenAPIPath = {
   '/admin/core/app/getApps': {
@@ -26,5 +28,7 @@ export const AdminAppPath: OpenAPIPath = {
         }
       }
     }
-  }
+  },
+  ...AdminTemplatePath,
+  ...AdminTemplateTypePath
 };

packages/global/openapi/admin/core/app/templateType/api.ts

+import z from 'zod';
+
+export const SaveTemplateTypeBodySchema = z.object({
+  typeId: z.string().meta({ description: '模板类型ID' }),
+  typeName: z.string().meta({ description: '模板类型名称' }),
+  typeOrder: z.number().meta({ description: '模板类型排序值' })
+});
+
+export const UpdateTemplateTypeOrderBodySchema = z.object({
+  types: z
+    .array(
+      z.object({
+        typeId: z.string().meta({ description: '模板类型ID' }),
+        typeOrder: z.number().meta({ description: '排序值' })
+      })
+    )
+    .meta({ description: '模板类型排序列表' })
+});

packages/global/openapi/admin/core/app/templateType/index.ts

+import z from 'zod';
+import type { OpenAPIPath } from '../../../../type';
+import { DevApiTagsMap } from '../../../../tag';
+import { SaveTemplateTypeBodySchema, UpdateTemplateTypeOrderBodySchema } from './api';
+
+export const AdminTemplateTypePath: OpenAPIPath = {
+  '/admin/core/app/templateType/save': {
+    post: {
+      summary: '保存模板类型',
+      description: '管理员创建或更新模板类型',
+      tags: [DevApiTagsMap.adminTemplateType],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: SaveTemplateTypeBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '保存成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/core/app/templateType/delete': {
+    delete: {
+      summary: '删除模板类型',
+      description: '根据类型ID删除模板类型及其关联的模板',
+      tags: [DevApiTagsMap.adminTemplateType],
+      requestParams: {
+        query: z.object({
+          typeId: z.string().meta({ description: '模板类型ID' })
+        })
+      },
+      responses: {
+        200: {
+          description: '删除成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/core/app/templateType/updateOrder': {
+    post: {
+      summary: '更新模板类型排序',
+      description: '批量更新模板类型的排序',
+      tags: [DevApiTagsMap.adminTemplateType],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: UpdateTemplateTypeOrderBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '排序更新成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/core/app/templates/api.ts

+import z from 'zod';
+
+export const CreateTemplateBodySchema = z.object({
+  name: z.string().meta({ description: '模板名称' }),
+  intro: z.string().meta({ description: '模板简介' }),
+  avatar: z.string().meta({ description: '模板头像URL' }),
+  tags: z.array(z.string()).meta({ description: '模板标签列表' }),
+  type: z.string().meta({ description: '模板类型' }),
+  isActive: z.boolean().optional().meta({ description: '是否启用' }),
+  isPromoted: z.boolean().optional().meta({ description: '是否推荐' }),
+  promoteTags: z.array(z.string()).optional().meta({ description: '推荐标签' }),
+  hideTags: z.array(z.string()).optional().meta({ description: '隐藏标签' }),
+  recommendText: z.string().optional().meta({ description: '推荐文案' }),
+  userGuide: z
+    .object({
+      type: z.enum(['markdown', 'link']).meta({ description: '用户引导类型' }),
+      content: z.string().meta({ description: '用户引导内容' })
+    })
+    .optional()
+    .meta({ description: '用户引导配置' }),
+  workflow: z.any().meta({ description: '工作流模板配置' })
+});
+
+export const UpdateTemplateBodySchema = z.object({
+  templateId: z.string().meta({ description: '模板ID' }),
+  name: z.string().optional().meta({ description: '模板名称' }),
+  intro: z.string().optional().meta({ description: '模板简介' }),
+  avatar: z.string().optional().meta({ description: '模板头像URL' }),
+  tags: z.array(z.string()).optional().meta({ description: '模板标签列表' }),
+  type: z.string().optional().meta({ description: '模板类型' }),
+  isActive: z.boolean().optional().meta({ description: '是否启用' }),
+  isPromoted: z.boolean().optional().meta({ description: '是否推荐' }),
+  promoteTags: z.array(z.string()).optional().meta({ description: '推荐标签' }),
+  hideTags: z.array(z.string()).optional().meta({ description: '隐藏标签' }),
+  recommendText: z.string().optional().meta({ description: '推荐文案' }),
+  userGuide: z
+    .object({
+      type: z.enum(['markdown', 'link']).meta({ description: '用户引导类型' }),
+      content: z.string().meta({ description: '用户引导内容' })
+    })
+    .optional()
+    .meta({ description: '用户引导配置' }),
+  workflow: z.any().optional().meta({ description: '工作流模板配置' }),
+  author: z.string().optional().meta({ description: '作者' })
+});
+
+export const UpdateTemplateOrderBodySchema = z.object({
+  templates: z
+    .array(
+      z.object({
+        templateId: z.string().meta({ description: '模板ID' }),
+        order: z.number().meta({ description: '排序值' })
+      })
+    )
+    .meta({ description: '模板排序列表' })
+});
+
+export const UpdateQuickTemplateBodySchema = z.object({
+  templateIds: z.array(z.string()).meta({ description: '设置为快捷模板的模板ID列表' })
+});

packages/global/openapi/admin/core/app/templates/index.ts

+import z from 'zod';
+import type { OpenAPIPath } from '../../../../type';
+import { DevApiTagsMap } from '../../../../tag';
+import {
+  CreateTemplateBodySchema,
+  UpdateTemplateBodySchema,
+  UpdateTemplateOrderBodySchema,
+  UpdateQuickTemplateBodySchema
+} from './api';
+
+export const AdminTemplatePath: OpenAPIPath = {
+  '/admin/core/app/templates/create': {
+    post: {
+      summary: '创建应用模板',
+      description: '管理员创建应用模板',
+      tags: [DevApiTagsMap.adminTemplate],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: CreateTemplateBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '创建成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/core/app/templates/list': {
+    get: {
+      summary: '获取应用模板列表',
+      description: '获取所有应用模板列表',
+      tags: [DevApiTagsMap.adminTemplate],
+      responses: {
+        200: {
+          description: '成功获取模板列表',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/core/app/templates/update': {
+    post: {
+      summary: '更新应用模板',
+      description: '管理员更新应用模板的信息',
+      tags: [DevApiTagsMap.adminTemplate],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: UpdateTemplateBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '更新成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/core/app/templates/delete': {
+    delete: {
+      summary: '删除应用模板',
+      description: '根据模板ID删除应用模板',
+      tags: [DevApiTagsMap.adminTemplate],
+      requestParams: {
+        query: z.object({
+          id: z.string().meta({ description: '模板ID' })
+        })
+      },
+      responses: {
+        200: {
+          description: '删除成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/core/app/templates/updateOrder': {
+    post: {
+      summary: '更新模板排序',
+      description: '批量更新应用模板的排序',
+      tags: [DevApiTagsMap.adminTemplate],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: UpdateTemplateOrderBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '排序更新成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/core/app/templates/updateQuickTemplate': {
+    post: {
+      summary: '设置快捷模板',
+      description: '设置哪些模板为快捷模板',
+      tags: [DevApiTagsMap.adminTemplate],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: UpdateQuickTemplateBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '设置成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/core/index.ts

 import { DashboardPath } from './dashboard';
 import { AdminAppPath } from './app';
+import { AdminRoutesPath } from '../routes';
+import { AdminCommonPath } from '../common';
 import type { OpenAPIPath } from '../../type';
 
 export const AdminCorePath: OpenAPIPath = {
   ...DashboardPath,
-  ...AdminAppPath
+  ...AdminAppPath,
+  ...AdminRoutesPath,
+  ...AdminCommonPath
 };

packages/global/openapi/admin/routes/apps/index.ts

+import type { OpenAPIPath } from '../../../type';
+import { DevApiTagsMap } from '../../../tag';
+import { GetAppsBodySchema, GetAppsResponseSchema } from '../../core/app/api';
+
+export const AdminRoutesAppsPath: OpenAPIPath = {
+  '/admin/routes/apps/getApps': {
+    post: {
+      summary: '获取应用列表（路由层）',
+      description:
+        '分页获取应用列表，支持按名称和应用ID搜索。复用与 core/app/getApps 相同的 schema',
+      tags: [DevApiTagsMap.adminApps],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: GetAppsBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '成功获取应用列表',
+          content: {
+            'application/json': {
+              schema: GetAppsResponseSchema
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/routes/datasets/api.ts

+import z from 'zod';
+import { PaginationResponseSchema } from '../../../api';
+
+export const DatasetItemSchema = z.object({
+  id: z.string().meta({ description: '知识库ID' }),
+  teamId: z.string().meta({ description: '所属团队ID' }),
+  name: z.string().meta({ description: '知识库名称' }),
+  intro: z.string().meta({ description: '知识库简介' }),
+  username: z.string().meta({ description: '创建者用户名' }),
+  totalDatas: z.number().meta({ description: '数据总量' }),
+  totalVectors: z.number().meta({ description: '向量总量' })
+});
+
+export const GetDatasetsResponseSchema = PaginationResponseSchema(DatasetItemSchema);

packages/global/openapi/admin/routes/datasets/index.ts

+import type { OpenAPIPath } from '../../../type';
+import { DevApiTagsMap } from '../../../tag';
+import { GetDatasetsResponseSchema } from './api';
+
+export const AdminDatasetsPath: OpenAPIPath = {
+  '/admin/routes/datasets/getDatasets': {
+    post: {
+      summary: '获取知识库列表',
+      description: '分页获取知识库列表，包含每个知识库的数据量和向量量统计',
+      tags: [DevApiTagsMap.adminDatasets],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: {}
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '成功获取知识库列表',
+          content: {
+            'application/json': {
+              schema: GetDatasetsResponseSchema
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/routes/index.ts

+import { AdminUsersPath } from './users';
+import { AdminTeamsPath } from './teams';
+import { AdminDatasetsPath } from './datasets';
+import { AdminRoutesAppsPath } from './apps';
+import { AdminPaysPath } from './pays';
+import { AdminPlansPath } from './plans';
+import { AdminSettingsPath } from './settings';
+import type { OpenAPIPath } from '../../type';
+
+export const AdminRoutesPath: OpenAPIPath = {
+  ...AdminUsersPath,
+  ...AdminTeamsPath,
+  ...AdminDatasetsPath,
+  ...AdminRoutesAppsPath,
+  ...AdminPaysPath,
+  ...AdminPlansPath,
+  ...AdminSettingsPath
+};

packages/global/openapi/admin/routes/pays/api.ts

+import z from 'zod';
+import { PaginationResponseSchema, PaginationSchema } from '../../../api';
+import { BillTypeEnum, BillStatusEnum } from '../../../../support/wallet/bill/constants';
+
+export const BillItemSchema = z.object({
+  id: z.string().meta({ description: '订单ID' }),
+  orderId: z.string().meta({ description: '订单号' }),
+  type: z.enum(BillTypeEnum).meta({ description: '订单类型' }),
+  status: z.enum(BillStatusEnum).meta({ description: '订单状态' }),
+  price: z.number().meta({ description: '订单金额' }),
+  username: z.string().meta({ description: '关联用户名' }),
+  createTime: z.date().meta({ description: '创建时间' })
+});
+
+export const GetPaysBodySchema = PaginationSchema.extend({
+  username: z.string().meta({ description: '搜索用户名' }),
+  type: z.enum(BillTypeEnum).optional().meta({ description: '订单类型筛选' }),
+  status: z.enum(BillStatusEnum).optional().meta({ description: '订单状态筛选' })
+});
+export const GetPaysResponseSchema = PaginationResponseSchema(BillItemSchema);

packages/global/openapi/admin/routes/pays/index.ts

+import type { OpenAPIPath } from '../../../type';
+import { DevApiTagsMap } from '../../../tag';
+import { GetPaysBodySchema, GetPaysResponseSchema } from './api';
+
+export const AdminPaysPath: OpenAPIPath = {
+  '/admin/routes/pays/getPays': {
+    post: {
+      summary: '获取订单列表',
+      description: '分页获取订单列表，支持按用户名搜索和按类型/状态筛选',
+      tags: [DevApiTagsMap.adminPays],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: GetPaysBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '成功获取订单列表',
+          content: {
+            'application/json': {
+              schema: GetPaysResponseSchema
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/routes/plans/api.ts

+import z from 'zod';
+import { NumSchema } from '../../../../common/zod';
+import { PaginationResponseSchema } from '../../../api';
+import { SubTypeEnum, StandardSubLevelEnum } from '../../../../support/wallet/sub/constants';
+
+export const PlanItemSchema = z.object({
+  id: z.string().meta({ description: '订阅ID' }),
+  teamId: z.string().meta({ description: '团队ID' }),
+  type: z.enum(SubTypeEnum).meta({ description: '套餐类型' }),
+  level: z.enum(StandardSubLevelEnum).meta({ description: '套餐等级' }),
+  totalPoints: z.number().meta({ description: '总积分' }),
+  surplusPoints: z.number().meta({ description: '剩余积分' }),
+  extraDatasetSize: z.number().meta({ description: '额外知识库容量' }),
+  startTime: z.date().meta({ description: '生效时间' }),
+  expiredTime: z.date().meta({ description: '过期时间' }),
+  teamName: z.string().optional().meta({ description: '团队名称' }),
+  userName: z.string().optional().meta({ description: '所有者用户名' }),
+  maxTeamMember: z.number().optional().meta({ description: '最大团队成员数' }),
+  maxApp: z.number().optional().meta({ description: '最大应用数' }),
+  maxDataset: z.number().optional().meta({ description: '最大知识库数' }),
+  maxDatasetSize: z.number().optional().meta({ description: '最大知识库容量' }),
+  requestsPerMinute: z.number().optional().meta({ description: '每分钟请求数' }),
+  websiteSyncPerDataset: z.number().optional().meta({ description: '每知识库站点同步数' }),
+  chatHistoryStoreDuration: z.number().optional().meta({ description: '聊天记录保存天数' }),
+  appRegistrationCount: z.number().optional().meta({ description: '应用注册数' }),
+  auditLogStoreDuration: z.number().optional().meta({ description: '审计日志保存天数' }),
+  ticketResponseTime: z.number().optional().meta({ description: '工单响应时间' }),
+  customDomain: z.number().optional().meta({ description: '自定义域名数' }),
+  maxUploadFileSize: z.number().optional().meta({ description: '最大上传文件大小' }),
+  maxUploadFileCount: z.number().optional().meta({ description: '最大上传文件数' }),
+  enableSandbox: z.boolean().optional().meta({ description: '是否启用沙盒' })
+});
+
+// getPlans
+export const GetPlansBodySchema = z.object({
+  pageNum: z.number().meta({ description: '页码' }),
+  pageSize: z.number().meta({ description: '每页条数' }),
+  search: z.string().meta({ description: '搜索关键词（用户名）' })
+});
+export const GetPlansResponseSchema = PaginationResponseSchema(PlanItemSchema);
+
+// addPlans
+export const AddPlansBodySchema = z.object({
+  teamId: z.string().meta({ description: '团队ID' }),
+  type: z.enum(SubTypeEnum).meta({ description: '套餐类型' }),
+  startTime: z.string().meta({ description: '开始时间' }),
+  expiredTime: z.string().meta({ description: '结束时间' }),
+  price: NumSchema.meta({ description: '价格' }),
+  level: z.enum(StandardSubLevelEnum).meta({ description: '套餐等级（仅标准套餐需要）' }),
+  extraDatasetSize: z.number().optional().meta({ description: '额外知识库容量' }),
+  totalPoints: z.number().optional().meta({ description: '总积分' }),
+  surplusPoints: z.number().optional().meta({ description: '剩余积分' })
+});
+
+// updatePlan
+export const UpdatePlanBodySchema = z.object({
+  id: z.string().meta({ description: '订阅ID' }),
+  type: z.enum(SubTypeEnum).meta({ description: '套餐类型' }),
+  startTime: z.string().meta({ description: '开始时间' }),
+  expiredTime: z.string().meta({ description: '结束时间' }),
+  price: NumSchema.meta({ description: '价格' }),
+  totalPoints: NumSchema.optional().meta({ description: '总积分' }),
+  surplusPoints: NumSchema.optional().meta({ description: '剩余积分' }),
+  extraDatasetSize: NumSchema.optional().meta({ description: '额外知识库容量' }),
+  level: z.enum(StandardSubLevelEnum).optional().meta({ description: '套餐等级' }),
+  maxTeamMember: NumSchema.optional().meta({ description: '最大团队成员数' }),
+  maxApp: NumSchema.optional().meta({ description: '最大应用数' }),
+  maxDataset: NumSchema.optional().meta({ description: '最大知识库数' }),
+  maxDatasetSize: NumSchema.optional().meta({ description: '最大知识库容量' }),
+  requestsPerMinute: NumSchema.optional().meta({ description: '每分钟请求数' }),
+  websiteSyncPerDataset: NumSchema.optional().meta({ description: '每知识库站点同步数' }),
+  chatHistoryStoreDuration: NumSchema.optional().meta({ description: '聊天记录保存天数' }),
+  appRegistrationCount: NumSchema.optional().meta({ description: '应用注册数' }),
+  auditLogStoreDuration: NumSchema.optional().meta({ description: '审计日志保存天数' }),
+  ticketResponseTime: NumSchema.optional().meta({ description: '工单响应时间' }),
+  customDomain: NumSchema.optional().meta({ description: '自定义域名数' }),
+  maxUploadFileSize: NumSchema.optional().meta({ description: '最大上传文件大小' }),
+  maxUploadFileCount: NumSchema.optional().meta({ description: '最大上传文件数' }),
+  enableSandbox: z.boolean().optional().meta({ description: '是否启用沙盒' })
+});

packages/global/openapi/admin/routes/plans/index.ts

+import type { OpenAPIPath } from '../../../type';
+import { DevApiTagsMap } from '../../../tag';
+import {
+  GetPlansBodySchema,
+  GetPlansResponseSchema,
+  AddPlansBodySchema,
+  UpdatePlanBodySchema
+} from './api';
+
+export const AdminPlansPath: OpenAPIPath = {
+  '/admin/routes/plans/getPlans': {
+    post: {
+      summary: '获取套餐列表',
+      description: '分页获取套餐订阅列表，支持按用户名搜索',
+      tags: [DevApiTagsMap.adminPlans],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: GetPlansBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '成功获取套餐列表',
+          content: {
+            'application/json': {
+              schema: GetPlansResponseSchema
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/routes/plans/addPlans': {
+    post: {
+      summary: '添加套餐',
+      description: '管理员为指定团队添加套餐订阅',
+      tags: [DevApiTagsMap.adminPlans],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: AddPlansBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '添加成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/routes/plans/updatePlan': {
+    post: {
+      summary: '更新套餐',
+      description: '管理员修改团队套餐订阅的配置参数',
+      tags: [DevApiTagsMap.adminPlans],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: UpdatePlanBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '更新成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/routes/settings/api.ts

+import z from 'zod';
+
+export const GetConfigResponseSchema = z.object({
+  fastgpt: z.any().optional().meta({ description: '系统 FastGPT 配置' }),
+  fastgptPro: z
+    .any()
+    .optional()
+    .meta({ description: '系统 FastGPT Pro 商业版配置（不含 license）' })
+});
+
+export const UpdateConfigBodySchema = z.object({
+  fastgpt: z.any().optional().meta({ description: 'FastGPT 系统配置对象' }),
+  fastgptPro: z.any().optional().meta({ description: 'FastGPT Pro 商业版配置对象' })
+});

packages/global/openapi/admin/routes/settings/index.ts

+import type { OpenAPIPath } from '../../../type';
+import { DevApiTagsMap } from '../../../tag';
+import { GetConfigResponseSchema, UpdateConfigBodySchema } from './api';
+
+export const AdminSettingsPath: OpenAPIPath = {
+  '/admin/routes/settings/getConfig': {
+    get: {
+      summary: '获取系统配置',
+      description: '获取 FastGPT 和 FastGPT Pro 的当前系统配置',
+      tags: [DevApiTagsMap.adminSettings],
+      responses: {
+        200: {
+          description: '成功获取系统配置',
+          content: {
+            'application/json': {
+              schema: GetConfigResponseSchema
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/routes/settings/updateConfig': {
+    post: {
+      summary: '更新系统配置',
+      description: '更新 FastGPT 和 FastGPT Pro 的系统配置',
+      tags: [DevApiTagsMap.adminSettings],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: UpdateConfigBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '更新成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/routes/teams/api.ts

+import z from 'zod';
+import { PaginationResponseSchema } from '../../../api';
+
+export const TeamItemSchema = z.object({
+  id: z.string().meta({ description: '团队ID' }),
+  name: z.string().meta({ description: '团队名称' }),
+  balance: z.number().meta({ description: '团队余额' }),
+  createTime: z.date().meta({ description: '创建时间' }),
+  ownerName: z.string().meta({ description: '团队所有者用户名' })
+});
+
+export const GetTeamsBodySchema = z.object({
+  pageNum: z.number().meta({ description: '页码' }),
+  pageSize: z.number().meta({ description: '每页条数' }),
+  search: z.string().meta({ description: '搜索关键词（团队名称或所有者用户名）' })
+});
+export const GetTeamsResponseSchema = PaginationResponseSchema(TeamItemSchema);
+
+export const TeamMemberItemSchema = z.object({
+  userName: z.string().meta({ description: '成员用户名' }),
+  teamId: z.string().meta({ description: '团队ID' }),
+  role: z.string().meta({ description: '成员角色' }),
+  status: z.string().meta({ description: '成员状态' })
+});
+
+export const GetTeamMembersResponseSchema = z.object({
+  members: z.array(TeamMemberItemSchema).meta({ description: '团队成员列表' }),
+  team: z
+    .object({
+      _id: z.string().meta({ description: '团队ID' }),
+      name: z.string().meta({ description: '团队名称' })
+    })
+    .meta({ description: '团队基本信息' })
+});
+
+export const UpdateTeamBodySchema = z.object({
+  id: z.string().meta({ description: '团队ID' }),
+  name: z.string().optional().meta({ description: '新团队名称' }),
+  balance: z.number().optional().meta({ description: '新余额' })
+});
+
+export const UpdateTeamResponseSchema = z.object({
+  balance: z.number().optional().meta({ description: '更新后的余额' })
+});

packages/global/openapi/admin/routes/teams/index.ts

+import z from 'zod';
+import type { OpenAPIPath } from '../../../type';
+import { DevApiTagsMap } from '../../../tag';
+import {
+  GetTeamsBodySchema,
+  GetTeamsResponseSchema,
+  GetTeamMembersResponseSchema,
+  UpdateTeamBodySchema,
+  UpdateTeamResponseSchema
+} from './api';
+
+export const AdminTeamsPath: OpenAPIPath = {
+  '/admin/routes/teams/getTeams': {
+    post: {
+      summary: '获取团队列表',
+      description: '分页获取团队列表，支持按团队名称或所有者用户名搜索',
+      tags: [DevApiTagsMap.adminTeams],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: GetTeamsBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '成功获取团队列表',
+          content: {
+            'application/json': {
+              schema: GetTeamsResponseSchema
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/routes/teams/getTeamMembers': {
+    get: {
+      summary: '获取团队成员',
+      description: '根据团队ID获取团队成员列表和团队基本信息',
+      tags: [DevApiTagsMap.adminTeams],
+      requestParams: {
+        query: z.object({
+          teamId: z.string().meta({ description: '团队ID' })
+        })
+      },
+      responses: {
+        200: {
+          description: '成功获取团队成员',
+          content: {
+            'application/json': {
+              schema: GetTeamMembersResponseSchema
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/routes/teams/updateTeam': {
+    post: {
+      summary: '更新团队信息',
+      description: '管理员修改团队的名称或余额',
+      tags: [DevApiTagsMap.adminTeams],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: UpdateTeamBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '更新成功',
+          content: {
+            'application/json': {
+              schema: UpdateTeamResponseSchema
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/routes/users/api.ts

+import z from 'zod';
+import { PaginationResponseSchema, PaginationSchema } from '../../../api';
+import { UserStatusEnum } from '../../../../support/user/constant';
+
+export const UserItemSchema = z.object({
+  _id: z.string().meta({ description: '用户ID' }),
+  username: z.string().meta({ description: '用户名' }),
+  avatar: z.string().optional().meta({ description: '用户头像' }),
+  status: z.enum(UserStatusEnum).meta({ description: '用户状态' }),
+  createTime: z.date().meta({ description: '创建时间' })
+});
+
+// getUsers
+export const GetUsersBodySchema = PaginationSchema.extend({
+  username: z.string().meta({ description: '搜索用户名（支持模糊匹配）' })
+});
+export type GetUsersBodyType = z.infer<typeof GetUsersBodySchema>;
+export const GetUsersResponseSchema = PaginationResponseSchema(UserItemSchema);
+
+// addUser
+export const AddUserBodySchema = z.object({
+  username: z.string().min(1).meta({ description: '用户名' }),
+  password: z.string().min(1).meta({ description: '密码' })
+});
+export const AddUserResponseSchema = z.object({
+  userId: z.string().meta({ description: '新创建的用户ID' }),
+  teamId: z.string().meta({ description: '用户的团队ID' })
+});
+
+// updateUser
+export const UpdateUserBodySchema = z.object({
+  _id: z.string().min(1).meta({ description: '用户ID' }),
+  username: z.string().min(1).optional().meta({ description: '新用户名' }),
+  password: z.string().min(1).optional().meta({ description: '新密码' }),
+  status: z.enum(UserStatusEnum).optional().meta({ description: '用户状态' })
+});
+
+// delete
+export const DeleteUserBodySchema = z.object({
+  username: z.string().min(1).meta({ description: '用户名' })
+});

packages/global/openapi/admin/routes/users/index.ts

+import type { OpenAPIPath } from '../../../type';
+import { DevApiTagsMap } from '../../../tag';
+import {
+  GetUsersBodySchema,
+  GetUsersResponseSchema,
+  AddUserBodySchema,
+  AddUserResponseSchema,
+  UpdateUserBodySchema,
+  DeleteUserBodySchema
+} from './api';
+
+export const AdminUsersPath: OpenAPIPath = {
+  '/admin/routes/users/getUsers': {
+    post: {
+      summary: '获取用户列表',
+      description: '分页获取用户列表，支持按用户名搜索',
+      tags: [DevApiTagsMap.adminUsers],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: GetUsersBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '成功获取用户列表',
+          content: {
+            'application/json': {
+              schema: GetUsersResponseSchema
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/routes/users/addUser': {
+    post: {
+      summary: '添加用户',
+      description: '管理员创建一个新的用户账号',
+      tags: [DevApiTagsMap.adminUsers],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: AddUserBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '创建成功',
+          content: {
+            'application/json': {
+              schema: AddUserResponseSchema
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/routes/users/updateUser': {
+    post: {
+      summary: '更新用户信息',
+      description: '管理员修改用户的用户名、密码或状态',
+      tags: [DevApiTagsMap.adminUsers],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: UpdateUserBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '更新成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/routes/users/delete': {
+    post: {
+      summary: '注销用户',
+      description: '管理员注销指定用户账号，清除用户资源和团队',
+      tags: [DevApiTagsMap.adminUsers],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: DeleteUserBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '注销成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/support/user/auth/api.ts

+import z from 'zod';
+
+export const AdminCertResponseSchema = z.object({
+  userId: z.string().meta({ description: '用户ID' }),
+  teamId: z.string().meta({ description: '团队ID' }),
+  tmbId: z.string().meta({ description: '团队成员ID' }),
+  username: z.string().meta({ description: '用户名' })
+});

packages/global/openapi/admin/support/user/auth/index.ts

+import type { OpenAPIPath } from '../../../../type';
+import { DevApiTagsMap } from '../../../../tag';
+import { AdminCertResponseSchema } from './api';
+
+export const AdminAuthPath: OpenAPIPath = {
+  '/admin/support/user/adminCert': {
+    get: {
+      summary: '管理员认证校验',
+      description: '验证当前请求的管理员身份并返回管理员信息',
+      tags: [DevApiTagsMap.adminAuth],
+      responses: {
+        200: {
+          description: '认证成功，返回管理员信息',
+          content: {
+            'application/json': {
+              schema: AdminCertResponseSchema
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/support/user/index.ts

 import { AdminLoginPath } from './login';
 import { AdminInformPath } from './inform';
+import { AdminAuthPath } from './auth';
 import type { OpenAPIPath } from '../../../type';
 
 export const AdminUserPath: OpenAPIPath = {
   ...AdminInformPath,
-  ...AdminLoginPath
+  ...AdminLoginPath,
+  ...AdminAuthPath
 };

packages/global/openapi/admin/support/wallet/bill/index.ts

+import { AdminInvoicePath } from './invoice';
+import { AdminRefundPath } from './pay';
+import type { OpenAPIPath } from '../../../../type';
+
+export const AdminBillPath: OpenAPIPath = {
+  ...AdminInvoicePath,
+  ...AdminRefundPath
+};

packages/global/openapi/admin/support/wallet/bill/invoice/api.ts

+import z from 'zod';
+import { PaginationResponseSchema } from '../../../../../api';
+
+export const InvoiceItemSchema = z.object({
+  _id: z.string().meta({ description: '发票ID' }),
+  teamName: z.string().meta({ description: '团队名称' }),
+  emailAddress: z.string().meta({ description: '邮箱地址' }),
+  status: z.string().meta({ description: '发票状态' }),
+  createTime: z.date().meta({ description: '创建时间' }),
+  finishTime: z.date().optional().meta({ description: '完成时间' })
+});
+
+export const InvoiceListBodySchema = z.object({
+  pageNum: z.number().meta({ description: '页码' }),
+  pageSize: z.number().meta({ description: '每页条数' }),
+  search: z.string().optional().meta({ description: '搜索关键词（团队名称）' })
+});
+export const InvoiceListResponseSchema = PaginationResponseSchema(InvoiceItemSchema);
+
+// invoice/finish is multipart/form-data
+export const InvoiceFinishBodySchema = z.object({
+  invoiceId: z.string().meta({ description: '发票ID' }),
+  file: z.string().optional().meta({ description: '发票文件（multipart 上传）' })
+});

packages/global/openapi/admin/support/wallet/bill/invoice/index.ts

+import type { OpenAPIPath } from '../../../../../type';
+import { DevApiTagsMap } from '../../../../../tag';
+import { InvoiceListBodySchema, InvoiceListResponseSchema, InvoiceFinishBodySchema } from './api';
+
+export const AdminInvoicePath: OpenAPIPath = {
+  '/admin/support/wallet/bill/invoice/list': {
+    get: {
+      summary: '获取发票列表',
+      description: '分页获取发票申请列表，支持按团队名称搜索',
+      tags: [DevApiTagsMap.adminWalletInvoice],
+      requestParams: {
+        query: InvoiceListBodySchema
+      },
+      responses: {
+        200: {
+          description: '成功获取发票列表',
+          content: {
+            'application/json': {
+              schema: InvoiceListResponseSchema
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/support/wallet/bill/invoice/finish': {
+    post: {
+      summary: '完成发票开具',
+      description: '上传发票文件完成发票开具，需使用 multipart/form-data',
+      tags: [DevApiTagsMap.adminWalletInvoice],
+      requestBody: {
+        content: {
+          'multipart/form-data': {
+            schema: InvoiceFinishBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '发票开具成功',
+          content: {
+            'application/json': {
+              schema: {}
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/support/wallet/bill/pay/api.ts

+import z from 'zod';
+import { NumSchema } from '../../../../../../common/zod';
+
+export const RefundBodySchema = z.object({
+  amount: NumSchema.positive().meta({ description: '退款金额' }),
+  orderId: z.string().min(1).meta({ description: '订单号' })
+});
+
+export const RefundResponseSchema = z.object({
+  message: z.string().meta({ description: '退款结果消息' })
+});

packages/global/openapi/admin/support/wallet/bill/pay/index.ts

+import type { OpenAPIPath } from '../../../../../type';
+import { DevApiTagsMap } from '../../../../../tag';
+import { RefundBodySchema, RefundResponseSchema } from './api';
+
+export const AdminRefundPath: OpenAPIPath = {
+  '/admin/support/wallet/bill/pay/refund': {
+    post: {
+      summary: '订单退款',
+      description: '管理员对已支付订单进行退款操作',
+      tags: [DevApiTagsMap.adminWalletRefund],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: RefundBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '退款操作结果',
+          content: {
+            'application/json': {
+              schema: RefundResponseSchema
+            }
+          }
+        }
+      }
+    }
+  }
+};

packages/global/openapi/admin/support/wallet/index.ts

 import type { OpenAPIPath } from '../../../type';
 import { AdminCouponPath } from './coupon';
+import { AdminBillPath } from './bill';
 
 export const AdminWalletPath: OpenAPIPath = {
-  ...AdminCouponPath
+  ...AdminCouponPath,
+  ...AdminBillPath
 };

packages/global/openapi/core/app/template/api.ts

@@ -73,7 +73,16 @@ export const GetAppTemplateDetailQuerySchema = z.object({
 });
 export type GetAppTemplateDetailQueryType = z.infer<typeof GetAppTemplateDetailQuerySchema>;
 
-export const GetAppTemplateDetailResponseSchema = AppTemplateSchema.optional().meta({
-  description: '模板详情；未找到模板时为空'
-});
+export const GetAppTemplateDetailResponseSchema = AppTemplateSchema.omit({
+  workflow: true
+})
+  .extend({
+    workflow: z.any().meta({
+      description: '模板对应的应用编排配置；不同应用类型可能使用不同结构'
+    })
+  })
+  .optional()
+  .meta({
+    description: '模板详情；未找到模板时为空'
+  });
 export type GetAppTemplateDetailResponseType = z.infer<typeof GetAppTemplateDetailResponseSchema>;

packages/global/openapi/path.ts

@@ -5,6 +5,8 @@ import { ChatPath } from './core/chat';
 import { DatasetPath } from './core/dataset';
 import { PluginPath } from './core/plugin';
 import { SupportPath } from './support';
+import { AdminCorePath } from './admin/core';
+import { AdminSupportPath } from './admin/support';
 import { DevApiTagsMap } from './tag';
 import type { OpenAPIPath } from './type';
 
@@ -104,3 +106,42 @@ export const openAPITagGroups = [
     tags: [DevApiTagsMap.chatAgentHelper]
   }
 ];
+
+export const adminOpenAPIPaths: NonNullable<OpenAPIPath> = {
+  ...AdminCorePath,
+  ...AdminSupportPath
+};
+
+export const adminOpenAPITagGroups = [
+  {
+    name: '管理员-系统概览',
+    tags: [DevApiTagsMap.adminDashboard, DevApiTagsMap.adminLogs, DevApiTagsMap.adminLicense]
+  },
+  {
+    name: '管理员-资源管理',
+    tags: [
+      DevApiTagsMap.adminApps,
+      DevApiTagsMap.adminUsers,
+      DevApiTagsMap.adminTeams,
+      DevApiTagsMap.adminDatasets
+    ]
+  },
+  {
+    name: '管理员-套餐与支付',
+    tags: [
+      DevApiTagsMap.adminPlans,
+      DevApiTagsMap.adminPays,
+      DevApiTagsMap.adminWalletCoupon,
+      DevApiTagsMap.adminWalletInvoice,
+      DevApiTagsMap.adminWalletRefund
+    ]
+  },
+  {
+    name: '管理员-系统配置',
+    tags: [DevApiTagsMap.adminSettings, DevApiTagsMap.adminInform, DevApiTagsMap.adminAuth]
+  },
+  {
+    name: '管理员-模板管理',
+    tags: [DevApiTagsMap.adminTemplate, DevApiTagsMap.adminTemplateType]
+  }
+];

packages/global/openapi/provider/admin.ts

 import { createDocument } from 'zod-openapi';
-import { AdminCorePath } from '../admin/core';
-import { AdminSupportPath } from '../admin/support';
-import { DevApiTagsMap } from '../tag';
+import { adminOpenAPIPaths, adminOpenAPITagGroups } from '../path';
 
 export const adminOpenAPIDocument = createDocument({
   openapi: '3.1.0',
@@ -10,27 +8,7 @@ export const adminOpenAPIDocument = createDocument({
     version: '0.1.0',
     description: 'FastGPT Admin API 文档'
   },
-  paths: {
-    ...AdminCorePath,
-    ...AdminSupportPath
-  },
+  paths: adminOpenAPIPaths,
   servers: [{ url: '/api' }],
-  'x-tagGroups': [
-    {
-      name: '仪表盘',
-      tags: [DevApiTagsMap.adminDashboard]
-    },
-    {
-      name: '核心资源管理',
-      tags: [DevApiTagsMap.adminApps]
-    },
-    {
-      name: '系统配置',
-      tags: [DevApiTagsMap.adminInform]
-    },
-    {
-      name: '钱包管理',
-      tags: [DevApiTagsMap.adminWalletCoupon]
-    }
-  ]
+  'x-tagGroups': adminOpenAPITagGroups
 });

packages/global/openapi/tag.ts

@@ -72,7 +72,20 @@ export const DevApiTagsMap = {
   adminDashboard: '仪表盘',
   adminInform: '通知管理',
   adminApps: '应用管理',
-  adminWalletCoupon: '兑换码管理'
+  adminWalletCoupon: '兑换码管理',
+  adminUsers: '用户管理',
+  adminTeams: '团队管理',
+  adminDatasets: '知识库管理',
+  adminPays: '订单管理',
+  adminPlans: '套餐管理',
+  adminSettings: '系统配置',
+  adminLogs: '系统日志',
+  adminLicense: '许可证管理',
+  adminTemplate: '模板管理',
+  adminTemplateType: '模板类型管理',
+  adminWalletInvoice: '发票管理',
+  adminWalletRefund: '退款管理',
+  adminAuth: '管理员认证'
 };
 
 export const SystemOpenApiTagMap = {

packages/service/common/vectorDB/opengauss/controller.ts

 import { delay } from '@fastgpt/global/common/system/utils';
 import { getLogger, LogCategories } from '../../logger';
-import { Pool } from 'pg';
-import type { QueryResultRow } from 'pg';
+import * as pg from 'pg';
+import type { Pool, QueryResultRow } from 'pg';
 import { OPENGAUSS_ADDRESS } from '../constants';
 import { serviceEnv } from '../../../env';
 
@@ -12,7 +12,7 @@ export const connectOg = async (): Promise<Pool> => {
     return global.pgClient;
   }
 
-  const pool = new Pool({
+  const pool = new pg.Pool({
     connectionString: OPENGAUSS_ADDRESS,
     max: serviceEnv.DB_MAX_LINK,
     min: 15,

packages/service/common/vectorDB/pg/controller.ts

 import { delay } from '@fastgpt/global/common/system/utils';
 import { getLogger, LogCategories } from '../../logger';
-import { Pool } from 'pg';
-import type { QueryResultRow } from 'pg';
+import * as pg from 'pg';
+import type { Pool, QueryResultRow } from 'pg';
 import { PG_ADDRESS } from '../constants';
 import { serviceEnv } from '../../../env';
 
@@ -12,7 +12,7 @@ export const connectPg = async (): Promise<Pool> => {
     return global.pgClient;
   }
 
-  const pool = new Pool({
+  const pool = new pg.Pool({
     connectionString: PG_ADDRESS,
     // 连接池配置
     max: serviceEnv.DB_MAX_LINK, // 支持通过统一 env 配置并发