docs: add admin coupon openapi schema (#7272)

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

 import { AdminUserPath } from './user';
 import { AdminUserPath } from './user';
+import { AdminWalletPath } from './wallet';
 import type { OpenAPIPath } from '../../type';
 import type { OpenAPIPath } from '../../type';
 
 
 export const AdminSupportPath: OpenAPIPath = {
 export const AdminSupportPath: OpenAPIPath = {
-  ...AdminUserPath
+  ...AdminUserPath,
+  ...AdminWalletPath
 };
 };

packages/global/openapi/admin/support/wallet/coupon/api.ts

+import z from 'zod';
+import { IntSchema, NumSchema } from '../../../../../common/zod';
+import { CouponTypeEnum } from '../../../../../support/wallet/sub/coupon/constants';
+import { StandardSubLevelEnum, SubTypeEnum } from '../../../../../support/wallet/sub/constants';
+
+export const CreateCouponSubscriptionSchema = z.object({
+  type: z.enum(SubTypeEnum).meta({
+    description: '套餐类型',
+    example: SubTypeEnum.standard
+  }),
+  durationDay: NumSchema.positive().meta({
+    description: '套餐有效天数',
+    example: 30
+  }),
+  level: z.enum(StandardSubLevelEnum).optional().meta({
+    description: '标准套餐等级，仅标准套餐需要',
+    example: StandardSubLevelEnum.basic
+  }),
+  extraDatasetSize: NumSchema.nonnegative().optional().meta({
+    description: '额外数据集容量',
+    example: 1000
+  }),
+  totalPoints: NumSchema.nonnegative().optional().meta({
+    description: '额外积分或套餐积分',
+    example: 5000
+  }),
+  customConfig: z.any().optional().meta({
+    description: '自定义套餐配置'
+  })
+});
+export type CreateCouponSubscriptionType = z.infer<typeof CreateCouponSubscriptionSchema>;
+
+export const CreateCouponBodySchema = z.object({
+  subscriptions: z.array(CreateCouponSubscriptionSchema).min(1).meta({
+    description: '兑换码包含的套餐列表'
+  }),
+  count: IntSchema.positive().optional().default(1).meta({
+    description: '生成兑换码数量',
+    example: 1
+  }),
+  type: z.enum(CouponTypeEnum).meta({
+    description: '兑换码类型',
+    example: CouponTypeEnum.activity
+  }),
+  price: NumSchema.nonnegative().optional().meta({
+    description: '订单原价',
+    example: 100
+  }),
+  paidAmount: NumSchema.nonnegative().optional().meta({
+    description: '实付金额',
+    example: 80
+  }),
+  transactionId: z.string().trim().optional().meta({
+    description: '线下交易流水号',
+    example: 'TXN20260324001'
+  }),
+  description: z.string().optional().meta({
+    description: '兑换码说明',
+    example: '线下付款兑换码'
+  })
+});
+export type CreateCouponBodyType = z.infer<typeof CreateCouponBodySchema>;
+
+export const CreateCouponResponseSchema = z
+  .array(
+    z.string().meta({
+      description: '兑换码',
+      example: 'AbCdEfGhIjKlMnOpQrStUvWx'
+    })
+  )
+  .meta({
+    description: '生成的兑换码列表'
+  });
+export type CreateCouponResponseType = z.infer<typeof CreateCouponResponseSchema>;
+
+export const ListCouponItemSchema = z.object({
+  key: z.string().meta({
+    description: '兑换码',
+    example: 'AbCdEfGhIjKlMnOpQrStUvWx'
+  }),
+  subscriptions: z.array(CreateCouponSubscriptionSchema).meta({
+    description: '兑换码包含的套餐列表'
+  }),
+  expiredAt: z.coerce.date().meta({
+    description: '过期时间',
+    example: '2026-03-24T00:00:00.000Z'
+  })
+});
+export const ListCouponResponseSchema = z.array(ListCouponItemSchema).meta({
+  description: '未过期且未使用的兑换码列表'
+});
+export type ListCouponResponseType = z.infer<typeof ListCouponResponseSchema>;
+
+export const DisableCouponBodySchema = z.object({
+  keys: z
+    .array(z.string().min(1))
+    .min(1)
+    .meta({
+      description: '需要禁用的兑换码列表',
+      example: ['AbCdEfGhIjKlMnOpQrStUvWx']
+    })
+});
+export type DisableCouponBodyType = z.infer<typeof DisableCouponBodySchema>;
+
+export const DisableCouponResponseSchema = z.undefined().meta({
+  description: '操作成功'
+});
+export type DisableCouponResponseType = z.infer<typeof DisableCouponResponseSchema>;

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

+import type { OpenAPIPath } from '../../../../type';
+import { DevApiTagsMap } from '../../../../tag';
+import {
+  CreateCouponBodySchema,
+  CreateCouponResponseSchema,
+  DisableCouponBodySchema,
+  DisableCouponResponseSchema,
+  ListCouponResponseSchema
+} from './api';
+
+export const AdminCouponPath: OpenAPIPath = {
+  '/admin/support/wallet/coupon/create': {
+    post: {
+      summary: '创建兑换码',
+      description: '管理员创建一个或多个订阅兑换码，可用于活动赠送或线下付款兑换',
+      tags: [DevApiTagsMap.adminWalletCoupon],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: CreateCouponBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '创建成功，返回生成的兑换码列表',
+          content: {
+            'application/json': {
+              schema: CreateCouponResponseSchema
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/support/wallet/coupon/list': {
+    get: {
+      summary: '获取兑换码列表',
+      description: '管理员获取未过期且未使用的兑换码列表',
+      tags: [DevApiTagsMap.adminWalletCoupon],
+      responses: {
+        200: {
+          description: '成功获取兑换码列表',
+          content: {
+            'application/json': {
+              schema: ListCouponResponseSchema
+            }
+          }
+        }
+      }
+    }
+  },
+  '/admin/support/wallet/coupon/disable': {
+    post: {
+      summary: '禁用兑换码',
+      description: '管理员将指定兑换码设置为已过期',
+      tags: [DevApiTagsMap.adminWalletCoupon],
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: DisableCouponBodySchema
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: '禁用成功',
+          content: {
+            'application/json': {
+              schema: DisableCouponResponseSchema
+            }
+          }
+        }
+      }
+    }
+  }
+};

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

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

packages/global/openapi/provider/admin.ts

@@ -27,6 +27,10 @@ export const adminOpenAPIDocument = createDocument({
     {
     {
       name: '系统配置',
       name: '系统配置',
       tags: [DevApiTagsMap.adminInform]
       tags: [DevApiTagsMap.adminInform]
+    },
+    {
+      name: '钱包管理',
+      tags: [DevApiTagsMap.adminWalletCoupon]
     }
     }
   ]
   ]
 });
 });

packages/global/openapi/tag.ts

@@ -71,7 +71,8 @@ export const DevApiTagsMap = {
   /* 管理员-系统管理 */
   /* 管理员-系统管理 */
   adminDashboard: '仪表盘',
   adminDashboard: '仪表盘',
   adminInform: '通知管理',
   adminInform: '通知管理',
-  adminApps: '应用管理'
+  adminApps: '应用管理',
+  adminWalletCoupon: '兑换码管理'
 };
 };
 
 
 export const SystemOpenApiTagMap = {
 export const SystemOpenApiTagMap = {

pro @ cb39de11

-Subproject commit 26ea071c930f2638203ba8049b01d0cbd20f51e0
+Subproject commit cb39de11f8364bc2496ee04804379b3347f322cf