Janady13/missionmatch / internal/modules/alerts/dto.go

1// Package alerts is the proactive alert engine, the watch loop. A best in world capture intelligence does 2// not wait to be asked: it WATCHES the account and tells the analyst, unprompted, when something actionable 3// happens. This module adds the MARKET EVENT arm to the existing scheduled bench watch 4// (staffing.Service.RecomputeProactive) plus a typed, persisted, UI surfaceable alert. 5// 6// Four triggers fire per sweep, all RLS scoped to the caller's org: 7// 8// - clearance_expiring: a candidate the owner holds whose clearance lapses within the window, a staffing 9// risk to flag before the reinvestigation lapses. 10// - recompete_winnable: a recently posted federal opportunity in an agency the owner already shows interest 11// in (a requirement for that agency, or a recorded bid) whose period of performance ends inside the 12// forward recompete window. This is the market event arm: GLOBAL PUBLIC opportunity_records joined to the 13// owner's own interest, RLS scoping only the interest read. 14// - gap_fillable: an open requirement with no green evaluation that the bench NOW structurally covers (at 15// least one candidate holds at least the required clearance level AND at least four fifths of the required 16// skills, the SAME structural test as ai.BenchGapForRequirement, integer arithmetic, no float). This is a 17// STRUCTURAL coverage test, never a match score: the frozen engine stays the only scorer. 18// - collision: a candidate (most sharply a scarce cleared one) proposed or approved on the slates of two or 19// more DISTINCT competing OPEN opportunities at once, the double commit of a scarce cleared person across 20// competing bids. It is an ADVISORY finding with a deterministic best fit suggested primary a human 21// resolves; it never auto rejects a slate member. 22// 23// Each alert UPSERTs ON CONFLICT (organization_id, dedupe_key), so a second sweep of the same event changes 24// nothing new (idempotent). The sweep writes ONE counts only audit event (aedt.alert.swept) with the per type 25// counts and NO PII: no candidate id, no agency value, just counts. 26package alerts 27 28// The four alert types, mirroring the alerts.alert_type CHECK constraint. Each names a distinct actionable 29// event the watch loop detects. Collision is the cross opportunity deconfliction finding: a candidate proposed 30// or approved on two or more distinct competing open opportunities at once. 31const ( 32 TypeRecompeteWinnable = "recompete_winnable" 33 TypeClearanceExpiring = "clearance_expiring" 34 TypeGapFillable = "gap_fillable" 35 TypeCollision = "collision" 36 // TypeRedeploymentDue is the firm's own contractor rolling off a live assignment with nothing next lined 37 // up. It is the only trigger about an event entirely inside the firm's control, and it went unwatched for 38 // the whole life of the alert engine while the data sat in placements. 39 TypeRedeploymentDue = "redeployment_due" 40 // The two opportunity kinds migration 0075 added. They are raised by the opportunities module rather than 41 // by this sweep, and they were MISSING from the vocabulary below until 0099: the map claimed to mirror the 42 // database CHECK and had not been updated when the CHECK was widened. Nothing broke, because the only 43 // consumer of the map is IsValidType and IsValidType has no caller anywhere in the tree, so the read path 44 // returns whatever the table holds. That is a latent trap rather than a live defect: the next person to 45 // wire the validator into a filter would silently drop every opportunity alert. 46 TypeOpportunityAmendment = "opportunity_amendment" 47 TypeOpportunityDeadline = "opportunity_deadline" 48) 49 50// The three severities, mirroring the alerts.severity CHECK constraint, ordered from quiet to loud. 51const ( 52 SeverityInfo = "info" 53 SeverityWatch = "watch" 54 SeverityUrgent = "urgent" 55) 56 57// The three statuses the UI moves an alert through, mirroring the alerts.status CHECK constraint. 58const ( 59 StatusUnread = "unread" 60 StatusRead = "read" 61 StatusDismissed = "dismissed" 62) 63 64// The three subject kinds an alert points at, the owner's own record. An empty subject is allowed (the 65// column defaults to the empty string) but the three triggers always set one. 66const ( 67 SubjectOpportunity = "opportunity" 68 SubjectCandidate = "candidate" 69 SubjectRequirement = "requirement" 70) 71 72// validTypes, validSeverities, and validStatuses are the closed sets the DB CHECK constraints enforce. The 73// service and handler validate against them before a write so a bad value is a clean rejection rather than a 74// raw constraint violation. 75var ( 76 validTypes = map[string]bool{ 77 TypeRecompeteWinnable: true, 78 TypeClearanceExpiring: true, 79 TypeGapFillable: true, 80 TypeCollision: true, 81 TypeRedeploymentDue: true, 82 TypeOpportunityAmendment: true, 83 TypeOpportunityDeadline: true, 84 } 85 validSeverities = map[string]bool{ 86 SeverityInfo: true, 87 SeverityWatch: true, 88 SeverityUrgent: true, 89 } 90 validStatuses = map[string]bool{ 91 StatusUnread: true, 92 StatusRead: true, 93 StatusDismissed: true, 94 } 95) 96 97// IsValidType reports whether t is one of the four allowed alert types. 98func IsValidType(t string) bool { return validTypes[t] } 99 100// IsValidSeverity reports whether s is one of the three allowed severities. 101func IsValidSeverity(s string) bool { return validSeverities[s] } 102 103// IsValidStatus reports whether s is one of the three allowed statuses. 104func IsValidStatus(s string) bool { return validStatuses[s] } 105 106// Alert is one persisted alert row returned to the UI. subject_id is omitted when the alert carries no 107// subject; created_at and updated_at are RFC3339. 108type Alert struct { 109 ID string `json:"id"` 110 AlertType string `json:"alert_type"` 111 Severity string `json:"severity"` 112 SubjectType string `json:"subject_type,omitempty"` 113 SubjectID string `json:"subject_id,omitempty"` 114 Title string `json:"title"` 115 Detail string `json:"detail,omitempty"` 116 Status string `json:"status"` 117 CreatedAt string `json:"created_at"` 118 UpdatedAt string `json:"updated_at"` 119} 120 121// SweepSummary is the per type count of alerts the sweep upserted, the only thing the sweep returns to the 122// caller and the only thing the counts only audit event records. It carries NO PII: no candidate id, no 123// agency value, no requirement title, just counts. 124type SweepSummary struct { 125 ClearanceExpiring int `json:"clearance_expiring"` 126 RecompeteWinnable int `json:"recompete_winnable"` 127 GapFillable int `json:"gap_fillable"` 128 Collision int `json:"collision"` 129 RedeploymentDue int `json:"redeployment_due"` 130} 131 132// Total is the sum of the per type counts, the total number of alerts the sweep upserted. 133func (s SweepSummary) Total() int { 134 return s.ClearanceExpiring + s.RecompeteWinnable + s.GapFillable + s.Collision + s.RedeploymentDue 135} 136 137// dedupeKey builds the stable per (org, the thing alerted) dedupe key the UPSERT keys on. The org scoping is 138// the UNIQUE (organization_id, dedupe_key) constraint, so the key itself carries only the type prefix and the 139// subject id; a re sweep of the same event yields the same key and the UPSERT refreshes the one row. Keeping 140// this pure and named lets the unit test pin the construction. 141func dedupeKey(alertType, subjectID string) string { 142 return alertType + ":" + subjectID 143} 144