KOL贴文表现

backend/src/swagger/index.ts

@@ -2353,6 +2353,182 @@ export const openAPISpec = {
         }
       }
     },
+    '/api/analytics/post-performance': {
+      get: {
+        summary: 'Get KOL post performance data',
+        description: 'Returns table data of posts with key metrics including views, likes, comments, shares and sentiment scores',
+        tags: ['Analytics'],
+        parameters: [
+          {
+            name: 'kolId',
+            in: 'query',
+            description: 'Filter by KOL ID',
+            schema: {
+              type: 'string'
+            }
+          },
+          {
+            name: 'platform',
+            in: 'query',
+            description: 'Filter by platform',
+            schema: {
+              type: 'string',
+              enum: ['youtube', 'instagram', 'tiktok', 'twitter', 'facebook']
+            }
+          },
+          {
+            name: 'startDate',
+            in: 'query',
+            description: 'Start date filter (YYYY-MM-DD)',
+            schema: {
+              type: 'string',
+              format: 'date'
+            }
+          },
+          {
+            name: 'endDate',
+            in: 'query',
+            description: 'End date filter (YYYY-MM-DD)',
+            schema: {
+              type: 'string',
+              format: 'date'
+            }
+          },
+          {
+            name: 'sortBy',
+            in: 'query',
+            description: 'Field to sort by',
+            schema: {
+              type: 'string',
+              enum: ['publish_date', 'views', 'likes', 'comments', 'shares', 'sentiment_score'],
+              default: 'publish_date'
+            }
+          },
+          {
+            name: 'sortOrder',
+            in: 'query',
+            description: 'Sort order',
+            schema: {
+              type: 'string',
+              enum: ['asc', 'desc'],
+              default: 'desc'
+            }
+          },
+          {
+            name: 'limit',
+            in: 'query',
+            description: 'Number of posts to return',
+            schema: {
+              type: 'integer',
+              default: 20
+            }
+          },
+          {
+            name: 'offset',
+            in: 'query',
+            description: 'Offset for pagination',
+            schema: {
+              type: 'integer',
+              default: 0
+            }
+          },
+          {
+            name: 'useMockData',
+            in: 'query',
+            description: 'Force use of mock data (useful for testing and UI development)',
+            schema: {
+              type: 'boolean',
+              default: false
+            }
+          }
+        ],
+        responses: {
+          '200': {
+            description: 'Successful response with post performance data',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: {
+                      type: 'boolean',
+                      example: true
+                    },
+                    data: {
+                      type: 'array',
+                      items: {
+                        type: 'object',
+                        properties: {
+                          post_id: { type: 'string', example: 'post-123' },
+                          title: { type: 'string', example: '夏季新品分享' },
+                          kol_id: { type: 'string', example: 'kol-456' },
+                          kol_name: { type: 'string', example: '時尚達人' },
+                          platform: { type: 'string', example: 'instagram' },
+                          publish_date: { type: 'string', format: 'date-time', example: '2023-06-15T08:30:00Z' },
+                          metrics: {
+                            type: 'object',
+                            properties: {
+                              views: { type: 'integer', example: 15000 },
+                              likes: { type: 'integer', example: 1200 },
+                              comments: { type: 'integer', example: 85 },
+                              shares: { type: 'integer', example: 45 }
+                            }
+                          },
+                          sentiment_score: { type: 'number', example: 0.75 },
+                          post_url: { type: 'string', format: 'uri', example: 'https://instagram.com/p/abc123' }
+                        }
+                      }
+                    },
+                    pagination: {
+                      type: 'object',
+                      properties: {
+                        limit: { type: 'integer', example: 20 },
+                        offset: { type: 'integer', example: 0 },
+                        total: { type: 'integer', example: 156 }
+                      }
+                    },
+                    is_mock_data: {
+                      type: 'boolean',
+                      description: '标识返回的是否是模拟数据',
+                      example: false
+                    }
+                  }
+                }
+              }
+            }
+          },
+          '400': {
+            description: 'Bad request - invalid parameters',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean', example: false },
+                    error: { type: 'string', example: 'Invalid sortBy. Must be one of: publish_date, views, likes, comments, shares, sentiment_score' }
+                  }
+                }
+              }
+            }
+          },
+          '500': {
+            description: 'Server error',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean', example: false },
+                    error: { type: 'string', example: 'Failed to fetch post performance data' },
+                    message: { type: 'string', example: 'ClickHouse query error: Connection refused' }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
   },
   components: {
     schemas: {