企业微信智能机器人API插件

server/dukang-api/src/integrations/wecom/wecom-plugin.openapi.ts

@@ -0,0 +1,157 @@
+const envelope = (dataSchema: Record<string, unknown>) => ({
+  type: 'object',
+  properties: {
+    code: { type: 'integer', example: 0 },
+    message: { type: 'string', example: 'ok' },
+    data: dataSchema,
+  },
+  required: ['code', 'message', 'data'],
+});
+
+const qParam = {
+  name: 'q',
+  in: 'query',
+  required: true,
+  schema: { type: 'string' },
+  description: '查询关键词',
+};
+
+const pageParams = [
+  {
+    name: 'page',
+    in: 'query',
+    required: false,
+    schema: { type: 'integer', default: 1, minimum: 1 },
+  },
+  {
+    name: 'pageSize',
+    in: 'query',
+    required: false,
+    schema: { type: 'integer', default: 5, minimum: 1, maximum: 10 },
+    description: '默认 5，最大 10',
+  },
+];
+
+const unauthorized = {
+  description: '缺少或错误的 X-Api-Key，或插件未启用',
+  content: {
+    'application/json': {
+      schema: {
+        type: 'object',
+        properties: {
+          code: { type: 'integer' },
+          message: { type: 'string' },
+        },
+      },
+    },
+  },
+};
+
+function listPath(summary: string, description: string, qDescription: string) {
+  return {
+    get: {
+      summary,
+      description,
+      operationId: summary,
+      parameters: [{ ...qParam, description: qDescription }, ...pageParams],
+      responses: {
+        200: {
+          description: '查询结果',
+          content: {
+            'application/json': {
+              schema: envelope({
+                type: 'object',
+                properties: {
+                  total: { type: 'integer' },
+                  items: { type: 'array', items: { type: 'object' } },
+                },
+              }),
+            },
+          },
+        },
+        401: unauthorized,
+      },
+    },
+  };
+}
+
+/** OpenAPI 3.0：企微「添加插件工具」可导入。须原样返回，不要套 {code,message,data}。 */
+export const WECOM_PLUGIN_OPENAPI = {
+  openapi: '3.0.3',
+  info: {
+    title: '杜康好客运营查询',
+    description:
+      '企业内部只读查询。手机号已脱敏。鉴权：Header X-Api-Key。响应除本文件外均为 { code, message, data }。',
+    version: '1.0.0',
+  },
+  servers: [
+    { url: 'https://api.dukanghaoke.com/api/v1/wecom/plugin', description: '生产' },
+    { url: 'https://api-test.dukanghaoke.com/api/v1/wecom/plugin', description: '测试' },
+  ],
+  security: [{ ApiKeyAuth: [] }],
+  components: {
+    securitySchemes: {
+      ApiKeyAuth: {
+        type: 'apiKey',
+        in: 'header',
+        name: 'X-Api-Key',
+      },
+    },
+  },
+  paths: {
+    '/orders': listPath('查询订单', '按订单号模糊查询', '订单号，如 DK20260903xxxx'),
+    '/users': listPath('查询用户', '按用户号或 11 位手机号查询；手机号脱敏', '用户号或手机号'),
+    '/stores': listPath('查询门店', '按门店名称模糊查询', '门店名称关键词'),
+    '/redeems': listPath('查询核销', '按核销单号或门店名查询', '核销单号或门店名'),
+    '/promo-codes': listPath('查询推广码', '按推广码 code 或名称查询', '推广码或名称'),
+    '/promo-codes/{code}/stats': {
+      get: {
+        summary: '推广码统计',
+        operationId: '查询推广码统计',
+        parameters: [
+          {
+            name: 'code',
+            in: 'path',
+            required: true,
+            schema: { type: 'string' },
+            description: '推广码 code',
+          },
+        ],
+        responses: {
+          200: {
+            description: '扫码/成交统计',
+            content: { 'application/json': { schema: envelope({ type: 'object' }) } },
+          },
+          401: unauthorized,
+        },
+      },
+    },
+    '/metrics': {
+      get: {
+        summary: '经营指标',
+        description:
+          'today=今日截至当前；daily/weekly/monthly 与企微经营报告同一口径（用户有效未合并，订单金额=已付 payAmount）。',
+        operationId: '查询经营指标',
+        parameters: [
+          {
+            name: 'kind',
+            in: 'query',
+            required: false,
+            schema: {
+              type: 'string',
+              enum: ['today', 'daily', 'weekly', 'monthly'],
+              default: 'today',
+            },
+          },
+        ],
+        responses: {
+          200: {
+            description: '存量与新增',
+            content: { 'application/json': { schema: envelope({ type: 'object' }) } },
+          },
+          401: unauthorized,
+        },
+      },
+    },
+  },
+} as const;