feat: swag.

controllers/statistics.go

@@ -34,6 +34,18 @@ type analysisRecordListParams struct {
 
 // --- 查询接口 ---
 
+// @Summary 获取AI分析记录列表
+// @Description 分页查询AI分析记录，支持按区域和时间范围筛选
+// @Tags 统计管理
+// @Produce json
+// @Param pageNum query int false "页码(默认1)"
+// @Param pageSize query int false "每页数量(默认10,最大100)"
+// @Param regionId query int false "区域ID"
+// @Param startTime query int false "开始时间(毫秒时间戳)"
+// @Param endTime query int false "结束时间(毫秒时间戳)"
+// @Security BearerAuth
+// @Success 200 {object} SwagAPIResponse "查询成功"
+// @Router /admin/statistics/ai-analysis-records [get]
 func (sc *StatisticsController) ListAIAnalysisRecords(c *gin.Context) {
 	var params analysisRecordListParams
 	if err := c.ShouldBindQuery(&params); err != nil {
@@ -84,6 +96,15 @@ func (sc *StatisticsController) ListAIAnalysisRecords(c *gin.Context) {
 
 // --- 删除接口 ---
 
+// @Summary 删除AI分析记录
+// @Description 删除指定的AI分析记录
+// @Tags 统计管理
+// @Produce json
+// @Param id path int true "记录ID"
+// @Security BearerAuth
+// @Success 200 {object} SwagAPIResponse "删除成功"
+// @Failure 404 {object} SwagAPIResponse "记录不存在"
+// @Router /admin/statistics/ai-analysis-records/{id} [delete]
 func (sc *StatisticsController) DeleteAIAnalysisRecord(c *gin.Context) {
 	id := strings.TrimSpace(c.Param("id"))
 	if id == "" {
@@ -137,6 +158,16 @@ type regionStatisticsItem struct {
 	LastUsedAt            *time.Time       `json:"lastUsedAt"`
 }
 
+// @Summary AI分析区域统计
+// @Description 按区域统计AI分析的使用情况，包括调用次数、Token消耗、费用等
+// @Tags 统计管理
+// @Produce json
+// @Param regionId query int false "区域ID"
+// @Param startTime query int false "开始时间(毫秒时间戳)"
+// @Param endTime query int false "结束时间(毫秒时间戳)"
+// @Security BearerAuth
+// @Success 200 {object} SwagAPIResponse "查询成功"
+// @Router /admin/statistics/ai-analysis [get]
 func (sc *StatisticsController) StatisticsByRegion(c *gin.Context) {
 	regionIDStr := c.Query("regionId")
 	startTimeStr := c.Query("startTime")
@@ -395,6 +426,17 @@ type trainingSessionRegionStatisticsItem struct {
 	LastPublishedAt  *time.Time       `json:"lastPublishedAt"`
 }
 
+// @Summary 训练会话区域统计
+// @Description 按区域统计MQTT训练会话情况，包括开始、结束、完成、进行中的会话数
+// @Tags 统计管理
+// @Produce json
+// @Param regionId query int false "区域ID"
+// @Param flavorType query string false "类型筛选"
+// @Param startTime query int false "开始时间(毫秒时间戳)"
+// @Param endTime query int false "结束时间(毫秒时间戳)"
+// @Security BearerAuth
+// @Success 200 {object} SwagAPIResponse "查询成功"
+// @Router /admin/statistics/mqtt-training-sessions [get]
 func (sc *StatisticsController) TrainingSessionStatisticsByRegion(c *gin.Context) {
 	regionIDStr := c.Query("regionId")
 	flavorType := strings.TrimSpace(c.Query("flavorType"))
@@ -624,6 +666,16 @@ func (sc *StatisticsController) TrainingSessionStatisticsByRegion(c *gin.Context
 	})
 }
 
+// @Summary AI分析时间线统计
+// @Description 按日期统计AI分析的使用情况趋势，含总体和分区域数据
+// @Tags 统计管理
+// @Produce json
+// @Param regionId query int false "区域ID"
+// @Param startTime query int false "开始时间(毫秒时间戳)"
+// @Param endTime query int false "结束时间(毫秒时间戳)"
+// @Security BearerAuth
+// @Success 200 {object} SwagAPIResponse "查询成功"
+// @Router /admin/statistics/ai-analysis-timeline [get]
 func (sc *StatisticsController) TimelineStatistics(c *gin.Context) {
 	regionIDStr := c.Query("regionId")
 	startTimeStr := c.Query("startTime")