First Commit

notify/event.go

@@ -0,0 +1,69 @@
+package notify
+
+// Snapshot 是 notification_events.snapshot 这一 JSONB 列的契约。写方是 db 层的
+// 漏洞落库事务，读方是 server 层的投递引擎与过滤匹配。定义放在本包是因为它是
+// 「通知领域」的载荷：db 只负责序列化，不理解字段含义。
+//
+// 为什么冗余存漏洞字段而不在渲染时回查：漏洞事后会被改名、改级别、改状态，
+// 而推送内容应当反映**事发当时**的结论——回查会得到「事后被改成 low」的
+// 危险误导。另外 fan-out 与渲染因此不必 JOIN findings/tasks/assets 三张表。
+type Snapshot struct {
+	// 事件类型：finding_created / finding_status_changed
+	Kind      string  `json:"kind"`
+	FindingID int64   `json:"finding_id"`
+	TaskID    int64   `json:"task_id"`
+	VulnClass string  `json:"vulnclass"`
+	Name      string  `json:"name"`
+	Severity  string  `json:"severity"`
+	Summary   string  `json:"summary"`
+	AssetIDs  []int64 `json:"asset_ids"`
+	// 仅 kind=finding_status_changed 时非空。
+	FromStatus string `json:"from_status,omitempty"`
+	ToStatus   string `json:"to_status,omitempty"`
+}
+
+// Item 是一条待推送的漏洞，供渠道渲染。
+type Item struct {
+	FindingID int64
+	Name      string
+	VulnClass string
+	Severity  string
+	Summary   string
+	// Assets 是解析后的资产展示名（如域名/IP）。由 server 层填充——
+	// 本包不碰数据库，拿不到名字。
+	Assets []string
+	// DetailURL 是漏洞详情回链；为空表示未配 public_base_url，渲染时省略。
+	DetailURL string
+	// 状态变更事件专用；两项均非空时渲染成「待处理 → 已修复」。
+	FromStatus string
+	ToStatus   string
+}
+
+// IsStatusChange 报告该条目是否为状态变更事件。
+func (i Item) IsStatusChange() bool { return i.FromStatus != "" || i.ToStatus != "" }
+
+// Title 返回条目的展示标题：优先人工命名的 name，回退漏洞类型 vulnclass，
+// 两者都空时用一个占位符——绝不输出空标题。
+func (i Item) Title() string {
+	if i.Name != "" {
+		return i.Name
+	}
+	if i.VulnClass != "" {
+		return i.VulnClass
+	}
+	return "(이름 없는 취약점)"
+}
+
+// Message 是一次渠道发送的完整内容。
+type Message struct {
+	// 单条推送时长度为 1；汇总推送（digest）时为一整批。
+	// 空切片是非法的，调用方须保证至少一条。
+	Items []Item
+	// Batch=true 时按汇总消息渲染（换标题、带上时间窗与条数）。
+	Batch bool
+	// WindowMinutes 是汇总周期（分钟），仅 Batch=true 时用于文案「近 N 分钟」。
+	// 刻意由配置显式传入而不是渲染时算 time.Since：渲染保持确定性，才好测。
+	WindowMinutes int
+	// HomeURL 是平台面板地址（全局 public_base_url）；空则不带面板入口。
+	HomeURL string
+}