全局审计完成

internal/query/audit/risks.go

@@ -26,44 +26,44 @@ type RiskFilter struct {
 
 // RiskOverview 是风险信号、固定维度与时间趋势的只读聚合。
 type RiskOverview struct {
-	Total     int64               `json:"total"`
-	Bucket    string              `json:"bucket"`
-	Signals   []RiskNamedCount    `json:"signals"`
-	Risks     []RiskNamedCount    `json:"risks"`
-	Results   []RiskNamedCount    `json:"results"`
-	Actions   []RiskNamedCount    `json:"actions"`
-	Sources   []RiskNamedCount    `json:"sources"`
-	Trend     []RiskTrendPoint    `json:"trend"`
-	Retention retentionquery.Info `json:"retention"`
+	Total     int64               `json:"total" description:"固定风险集合内的事件总数"`
+	Bucket    string              `json:"bucket" enum:"hour,day" description:"服务端选择的趋势时间粒度"`
+	Signals   []RiskNamedCount    `json:"signals" description:"固定信号分布，code为high_risk、finance、security、failed、denied、partial或unknown，name为中文展示名"`
+	Risks     []RiskNamedCount    `json:"risks" description:"风险等级分布，code为low、normal、high或critical，name为中文展示名"`
+	Results   []RiskNamedCount    `json:"results" description:"结果分布，code为success、failed、denied、partial或unknown，name为中文展示名"`
+	Actions   []RiskNamedCount    `json:"actions" description:"动作分布，code为稳定action_code，name为中文action_name"`
+	Sources   []RiskNamedCount    `json:"sources" description:"来源分布，code为admin_api、personal_api、openapi、worker、scheduler或callback，name为中文展示名"`
+	Trend     []RiskTrendPoint    `json:"trend" description:"固定风险信号的时间趋势"`
+	Retention retentionquery.Info `json:"retention" description:"在线查询留存边界"`
 }
 
 // RiskNamedCount 是风险聚合维度的稳定编码、中文名称和数量。
 type RiskNamedCount 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:"该编码的事件数量"`
 }
 
 // RiskTrendPoint 是固定时间桶内的风险信号趋势。
 type RiskTrendPoint struct {
-	BucketAt time.Time `json:"bucket_at"`
-	Total    int64     `json:"total"`
-	HighRisk int64     `json:"high_risk"`
-	Finance  int64     `json:"finance"`
-	Security int64     `json:"security"`
-	Failed   int64     `json:"failed"`
-	Denied   int64     `json:"denied"`
-	Partial  int64     `json:"partial"`
-	Unknown  int64     `json:"unknown"`
+	BucketAt time.Time `json:"bucket_at" description:"时间桶起点"`
+	Total    int64     `json:"total" description:"桶内固定风险集合事件数"`
+	HighRisk int64     `json:"high_risk" description:"桶内high或critical风险事件数"`
+	Finance  int64     `json:"finance" description:"桶内资金类风险事件数"`
+	Security int64     `json:"security" description:"桶内安全类风险事件数"`
+	Failed   int64     `json:"failed" description:"桶内failed事件数"`
+	Denied   int64     `json:"denied" description:"桶内denied事件数"`
+	Partial  int64     `json:"partial" description:"桶内partial事件数"`
+	Unknown  int64     `json:"unknown" description:"桶内unknown事件数"`
 }
 
 // RiskEventPage 是风险事件的稳定分页结果。
 type RiskEventPage struct {
-	Total     int64               `json:"total"`
-	Page      int                 `json:"page"`
-	PageSize  int                 `json:"page_size"`
-	Items     []EventView         `json:"items"`
-	Retention retentionquery.Info `json:"retention"`
+	Total     int64               `json:"total" description:"符合条件的风险事件总数"`
+	Page      int                 `json:"page" description:"当前页码"`
+	PageSize  int                 `json:"page_size" description:"每页数量"`
+	Items     []EventView         `json:"items" description:"风险事件及稳定调查引用"`
+	Retention retentionquery.Info `json:"retention" description:"在线查询留存边界"`
 }
 
 // RiskOverview 查询指定时间范围内的固定风险调查总览。