kunnel

2025-03-13 20:06:58 +08:00
parent b8ea4e7097
commit 72c040cf19
4 changed files with 381 additions and 14 deletions
--- a/backend/src/swagger/index.ts
+++ b/backend/src/swagger/index.ts
@@ -2239,6 +2239,120 @@ export const openAPISpec = {
        }
      }
    },
+    '/api/analytics/kol-funnel': {
+      get: {
+        summary: 'Get KOL conversion funnel data',
+        description: 'Returns user counts and conversion rates for each funnel stage in the KOL collaboration process',
+        tags: ['Analytics'],
+        parameters: [
+          {
+            name: 'timeRange',
+            in: 'query',
+            description: 'Number of days to look back',
+            schema: {
+              type: 'string',
+              enum: ['7', '30', '90'],
+              default: '30'
+            }
+          },
+          {
+            name: 'projectId',
+            in: 'query',
+            description: 'Filter by project ID',
+            schema: {
+              type: 'string'
+            }
+          },
+          {
+            name: 'debug',
+            in: 'query',
+            description: 'Enable debug mode (non-production environments only)',
+            schema: {
+              type: 'string',
+              enum: ['true', 'false'],
+              default: 'false'
+            }
+          }
+        ],
+        responses: {
+          '200': {
+            description: 'Successful response with funnel data',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: {
+                      type: 'boolean',
+                      example: true
+                    },
+                    data: {
+                      type: 'object',
+                      properties: {
+                        stages: {
+                          type: 'array',
+                          items: {
+                            type: 'object',
+                            properties: {
+                              stage: { type: 'string', example: 'exposure' },
+                              stage_display: { type: 'string', example: '曝光' },
+                              count: { type: 'integer', example: 10000 },
+                              percentage: { type: 'number', example: 100 },
+                              conversion_rate: { 
+                                type: 'number', 
+                                nullable: true,
+                                example: 75.5 
+                              }
+                            }
+                          }
+                        },
+                        overview: {
+                          type: 'object',
+                          properties: {
+                            average_conversion_rate: { type: 'number', example: 45.2 },
+                            highest_conversion_stage: { type: 'string', example: '兴趣' },
+                            lowest_conversion_stage: { type: 'string', example: '购买' }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          '400': {
+            description: 'Bad request - invalid parameters',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean', example: false },
+                    error: { type: 'string', example: 'Invalid timeRange. Must be 7, 30, or 90.' }
+                  }
+                }
+              }
+            }
+          },
+          '500': {
+            description: 'Server error',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean', example: false },
+                    error: { type: 'string', example: 'Failed to fetch KOL funnel data' },
+                    message: { type: 'string', example: 'ClickHouse query error: Connection refused' }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
  },
  components: {
    schemas: {