interaction api

2025-03-14 22:31:45 +08:00
parent bd1a5ce384
commit d0f2ab0620
4 changed files with 422 additions and 0 deletions
--- a/backend/src/swagger/index.ts
+++ b/backend/src/swagger/index.ts
@@ -3320,6 +3320,148 @@ export const openAPISpec = {
        }
      }
    },
+    '/api/analytics/interaction-time': {
+      get: {
+        summary: '获取用户互动时间分析',
+        description: '返回按小时统计的用户互动数量和分布，帮助了解用户最活跃的时间段',
+        tags: ['Analytics'],
+        parameters: [
+          {
+            name: 'timeRange',
+            in: 'query',
+            description: '时间范围（天）',
+            schema: {
+              type: 'integer',
+              enum: [7, 30, 90],
+              default: 30
+            }
+          },
+          {
+            name: 'projectId',
+            in: 'query',
+            description: '项目ID（可选）',
+            schema: {
+              type: 'string'
+            }
+          },
+          {
+            name: 'platform',
+            in: 'query',
+            description: '平台（可选）',
+            schema: {
+              type: 'string',
+              enum: ['weibo', 'xiaohongshu', 'douyin', 'bilibili']
+            }
+          },
+          {
+            name: 'eventType',
+            in: 'query',
+            description: '互动事件类型',
+            schema: {
+              type: 'string',
+              enum: ['all', 'comment', 'like', 'view', 'share', 'follow'],
+              default: 'all'
+            }
+          }
+        ],
+        responses: {
+          '200': {
+            description: '成功获取互动时间分析数据',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: {
+                      type: 'boolean',
+                      example: true
+                    },
+                    data: {
+                      type: 'array',
+                      items: {
+                        type: 'object',
+                        properties: {
+                          hour: {
+                            type: 'integer',
+                            example: 20
+                          },
+                          count: {
+                            type: 'integer',
+                            example: 256
+                          },
+                          percentage: {
+                            type: 'number',
+                            format: 'float',
+                            example: 15.2
+                          }
+                        }
+                      }
+                    },
+                    metadata: {
+                      type: 'object',
+                      properties: {
+                        total: {
+                          type: 'integer',
+                          example: 1680
+                        },
+                        peak_hour: {
+                          type: 'integer',
+                          example: 20
+                        },
+                        lowest_hour: {
+                          type: 'integer',
+                          example: 4
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          '400': {
+            description: '请求参数错误',
+            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: '服务器错误',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: {
+                      type: 'boolean',
+                      example: false
+                    },
+                    error: {
+                      type: 'string',
+                      example: 'Failed to fetch interaction time analysis data'
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
  },
  components: {
    schemas: {