全局审计完成

internal/query/integration/overview.go

@@ -20,44 +20,44 @@ type OverviewFilter struct {
 
 // Overview 是外部交互固定维度聚合结果。
 type Overview struct {
-	Total             int64               `json:"total"`
-	AnomalyCount      int64               `json:"anomaly_count"`
-	UnknownCount      int64               `json:"unknown_count"`
-	StalePendingCount int64               `json:"stale_pending_count"`
-	StateChangedCount int64               `json:"state_changed_count"`
-	AverageDurationMS float64             `json:"average_duration_ms"`
-	P95DurationMS     float64             `json:"p95_duration_ms"`
-	Results           []ResultCount       `json:"results"`
-	Providers         []NamedCount        `json:"providers"`
-	Directions        []NamedCount        `json:"directions"`
-	Trend             []TrendPoint        `json:"trend"`
-	Retention         retentionquery.Info `json:"retention"`
+	Total             int64               `json:"total" description:"外部交互总数"`
+	AnomalyCount      int64               `json:"anomaly_count" description:"failed或indeterminate类别的异常交互数"`
+	UnknownCount      int64               `json:"unknown_count" description:"原始结果为unknown的交互数"`
+	StalePendingCount int64               `json:"stale_pending_count" description:"超过既定阈值仍为pending的交互数"`
+	StateChangedCount int64               `json:"state_changed_count" description:"改变本地业务状态的交互数"`
+	AverageDurationMS float64             `json:"average_duration_ms" description:"平均交互耗时，单位毫秒"`
+	P95DurationMS     float64             `json:"p95_duration_ms" description:"P95交互耗时，单位毫秒"`
+	Results           []ResultCount       `json:"results" description:"原始结果分布，code/name/category分别为稳定编码、中文名和派生类别"`
+	Providers         []NamedCount        `json:"providers" description:"提供方分布，code为provider枚举，name为中文展示名"`
+	Directions        []NamedCount        `json:"directions" description:"方向分布，code为inbound或outbound，name为中文展示名"`
+	Trend             []TrendPoint        `json:"trend" description:"五类派生结果的时间趋势"`
+	Retention         retentionquery.Info `json:"retention" description:"在线查询留存边界"`
 }
 
 // ResultCount 是原始结果及其派生类别计数。
 type ResultCount struct {
-	Code     string `json:"code"`
-	Name     string `json:"name"`
-	Category string `json:"category"`
-	Count    int64  `json:"count"`
+	Code     string `json:"code" enum:"pending,success,failed,unknown,not_found,invalid_payload,conflict,ignored,merged,rate_limited,completed,cancelled" description:"外部交互原始结果稳定编码"`
+	Name     string `json:"name" description:"code对应的中文展示名称"`
+	Category string `json:"category" enum:"processing,succeeded,indeterminate,failed,not_sent" description:"由code派生的固定结果类别"`
+	Count    int64  `json:"count" description:"该原始结果的交互数量"`
 }
 
 // NamedCount 是稳定编码、中文名称和数量。
 type NamedCount struct {
-	Code  string `json:"code"`
-	Name  string `json:"name"`
-	Count int64  `json:"count"`
+	Code  string `json:"code" description:"当前聚合维度的稳定编码，枚举域由所属数组字段说明"`
+	Name  string `json:"name" description:"code对应的中文展示名称"`
+	Count int64  `json:"count" description:"该编码的交互数量"`
 }
 
 // TrendPoint 是固定时间桶内的结果类别趋势。
 type TrendPoint struct {
-	BucketAt      time.Time `json:"bucket_at"`
-	Total         int64     `json:"total"`
-	Succeeded     int64     `json:"succeeded"`
-	Processing    int64     `json:"processing"`
-	Indeterminate int64     `json:"indeterminate"`
-	Failed        int64     `json:"failed"`
-	NotSent       int64     `json:"not_sent"`
+	BucketAt      time.Time `json:"bucket_at" description:"时间桶起点"`
+	Total         int64     `json:"total" description:"桶内外部交互总数"`
+	Succeeded     int64     `json:"succeeded" description:"桶内succeeded类别数量"`
+	Processing    int64     `json:"processing" description:"桶内processing类别数量"`
+	Indeterminate int64     `json:"indeterminate" description:"桶内indeterminate类别数量"`
+	Failed        int64     `json:"failed" description:"桶内failed类别数量"`
+	NotSent       int64     `json:"not_sent" description:"桶内not_sent类别数量"`
 }
 
 // Overview 查询指定时间范围的固定维度外部交互总览。