Janady13/missionmatch / internal/modules/matching/intel.go

1package matching 2 3import ( 4 "context" 5 "fmt" 6 "sort" 7 "strings" 8 "time" 9 10 "github.com/google/uuid" 11 "github.com/jackc/pgx/v5" 12 "github.com/shopspring/decimal" 13 14 "github.com/missionworkforce/missionmatch/internal/modules/commandcenter" 15 "github.com/missionworkforce/missionmatch/internal/modules/matching/engine" 16 "github.com/missionworkforce/missionmatch/internal/modules/matching/intelligence" 17 "github.com/missionworkforce/missionmatch/internal/platform/database/dbgen" 18 "github.com/missionworkforce/missionmatch/internal/platform/missionclass" 19) 20 21// CandidateIntelligenceView is the workforce intelligence projection of one candidate for the 22// Candidates page. Every value is computed from the same scoring engine the dashboard, Top Matches, 23// and the evaluation view use (Mission Readiness ties out), plus the Command Center coverage logic 24// (Win Impact). Nothing here is hardcoded. 25type CandidateIntelligenceView struct { 26 ID uuid.UUID `json:"id"` 27 FullName string `json:"full_name"` 28 Source string `json:"source"` // seed or external 29 Headline string `json:"headline,omitempty"` // self reported title and skills (External leads) 30 YearsExperience int32 `json:"years_experience"` 31 Location string `json:"location,omitempty"` 32 Available bool `json:"available"` 33 Clearance ClearanceCell `json:"clearance"` 34 MissionReadiness ReadinessCell `json:"mission_readiness"` 35 ProposalReady ProposalCell `json:"proposal_ready"` 36 WinImpact WinImpactCell `json:"win_impact"` 37 BestFit BestFitCell `json:"best_fit"` 38 LaborCategoryCoverage []string `json:"labor_category_coverage"` 39} 40 41// ClearanceCell is the clearance intelligence indicator (self reported, never verified). When the 42// level is unknown it is shown plainly as Unknown so the layout stays balanced. 43type ClearanceCell struct { 44 Level string `json:"level"` // TS/SCI, Secret, Unknown, ... 45 Status string `json:"status"` // Active, Unknown, ... 46 SciEligible bool `json:"sci_eligible"` 47 SciKnown bool `json:"sci_known"` // whether SCI eligibility is determinable 48 InvestigationYear string `json:"investigation_year,omitempty"` 49 Provenance string `json:"provenance"` // honest label, "Self reported, not verified" by default 50 Verified bool `json:"verified"` // true only for a sponsor FSO verification 51 Available bool `json:"available"` 52} 53 54// ReadinessCell is the candidate's Mission Readiness against their best fit requirement. 55type ReadinessCell struct { 56 Score string `json:"score"` 57 Band string `json:"band"` 58 Status string `json:"status"` 59} 60 61// ProposalCell is the derived Proposal Ready gate. Value is YES or REVIEW, never a bare NO; REVIEW 62// always carries a reason. 63type ProposalCell struct { 64 Value string `json:"value"` 65 Reason string `json:"reason"` 66} 67 68// WinImpactCell is HIGH, MEDIUM, or LOW, derived from the candidate's best gap filling value across 69// every open requirement they are eligible for (the Command Center slate coverage logic): filling an 70// under covered slot is HIGH, backfilling a thin qualified pool is MEDIUM, redundant depth is LOW. 71type WinImpactCell struct { 72 Level string `json:"level"` 73 Basis string `json:"basis"` 74} 75 76// BestFitCell is the candidate's top matching open requirement from the shared matching engine. 77type BestFitCell struct { 78 RequirementID uuid.UUID `json:"requirement_id"` 79 Name string `json:"name"` 80 CustomerAgency string `json:"customer_agency,omitempty"` 81 Score string `json:"score"` 82 Band string `json:"band"` 83} 84 85// reqEntry is one requirement prepared for scoring plus its metadata. 86type reqEntry struct { 87 id uuid.UUID 88 er engine.Requirement 89 lcat string 90 title string 91 customer string 92 kp bool 93} 94 95// CandidateIntelligence scores up to limit candidates against every requirement using the SHARED 96// engine (so Mission Readiness equals the value shown everywhere else), picks each candidate's best 97// fit open requirement, and derives Proposal Ready, Win Impact (from the Command Center coverage), and 98// the labor categories they qualify for. Read only. 99func (s *Service) CandidateIntelligence(ctx context.Context, limit int) ([]CandidateIntelligenceView, error) { 100 if s.db == nil { 101 return nil, ErrNoDatabase 102 } 103 if limit <= 0 || limit > 400 { 104 limit = 120 105 } 106 asOf := s.clock() 107 var out []CandidateIntelligenceView 108 err := s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 109 q := dbgen.New(tx) 110 111 // Reuse the Command Center slate coverage logic (greedy assignment) for Win Impact thinness, plus 112 // its hard eligibility edges so Win Impact gates on the same eligibility the assignment uses. 113 coverage, eligible, err := commandcenter.Coverage(ctx, tx, asOf) 114 if err != nil { 115 return fmt.Errorf("coverage: %w", err) 116 } 117 118 reqRows, err := q.ListRequirements(ctx, dbgen.ListRequirementsParams{Limit: 500, Offset: 0}) 119 if err != nil { 120 return fmt.Errorf("list requirements: %w", err) 121 } 122 reqs := make([]reqEntry, 0, len(reqRows)) 123 validLcat := map[string]bool{} 124 for _, rr := range reqRows { 125 er, err := reqFromRow(ctx, q, rr) 126 if err != nil { 127 return err 128 } 129 lc := strings.TrimSpace(deref(rr.LaborCategory)) 130 reqs = append(reqs, reqEntry{id: rr.ID, er: er, lcat: lc, title: rr.Title, customer: deref(rr.CustomerAgency), kp: rr.KeyPersonnel}) 131 if lc != "" { 132 validLcat[lc] = true 133 } 134 } 135 136 cands, err := q.ListCandidatesForIntel(ctx, int32(limit)) 137 if err != nil { 138 return fmt.Errorf("list candidates: %w", err) 139 } 140 out = make([]CandidateIntelligenceView, 0, len(cands)) 141 for _, c := range cands { 142 ec, err := loadCandidate(ctx, q, c, asOf) 143 if err != nil { 144 return err 145 } 146 view, bestRes := buildCandidateIntel(ctx, c, ec, asOf, reqs, validLcat, coverage, eligible, s.matcher) 147 // The Candidates page scores every candidate against the open requirement set, the highest 148 // volume screening stage AEDT output in the product. Record each candidate's best fit served 149 // score so the screening stage adverse impact denominator is complete, not biased toward the 150 // focused single candidate screens, and fail closed if it cannot be written. Skip when the org 151 // has no requirements: nothing was scored, so there is no served score to record. 152 if len(reqs) > 0 { 153 if e := s.auditOnTx(ctx, tx, servedScoreEvent("screenMATCH.intelligence", c.ID, bestRes)); e != nil { 154 return e 155 } 156 } 157 out = append(out, view) 158 } 159 // Strongest first so the page opens on proposal ready talent; name breaks ties deterministically. 160 sort.SliceStable(out, func(i, j int) bool { 161 // Compare the scores as decimals, never float64, to keep the order byte stable for the AEDT asset. 162 si, _ := decimal.NewFromString(out[i].MissionReadiness.Score) 163 sj, _ := decimal.NewFromString(out[j].MissionReadiness.Score) 164 if c := si.Cmp(sj); c != 0 { 165 return c > 0 166 } 167 return out[i].FullName < out[j].FullName 168 }) 169 return nil 170 }) 171 return out, err 172} 173 174// buildCandidateIntel scores one candidate against every requirement and assembles the intelligence. It 175// also returns the best fit MatchResult so the caller can record it as a served score (the AEDT audit); 176// the result is the zero value when the org has no requirements (nothing was scored). 177func buildCandidateIntel(ctx context.Context, c dbgen.Candidate, ec engine.Candidate, asOf time.Time, reqs []reqEntry, validLcat map[string]bool, coverage map[string]commandcenter.ReqCoverage, eligible map[string]map[string]bool, matcher engine.SkillMatcher) (CandidateIntelligenceView, engine.MatchResult) { 178 facts := ClearanceFactsFrom(c, ec.CustomerExperience) 179 if len(reqs) == 0 { // org has no requirements yet; render a complete, requirement free view 180 return CandidateIntelligenceView{ 181 ID: c.ID, FullName: c.FullName, Source: c.Source, Headline: deref(c.Headline), 182 YearsExperience: c.YearsExperience, Location: deref(c.Location), Available: c.Available, 183 Clearance: clearanceCell(c, facts, asOf), 184 MissionReadiness: ReadinessCell{Score: "0.00", Band: engine.BandRed.Code(), Status: "No open requirements"}, 185 ProposalReady: ProposalCell{Value: "REVIEW", Reason: "No open requirements to evaluate against yet"}, 186 WinImpact: WinImpactCell{Level: "LOW", Basis: "Not yet eligible for an open requirement"}, 187 BestFit: BestFitCell{}, 188 LaborCategoryCoverage: []string{}, 189 }, engine.MatchResult{} 190 } 191 candID := c.ID.String() 192 bandLcat := map[string]bool{} 193 // Best fit and Mission Readiness: the candidate's strongest OPEN match (ties out via the engine). 194 bestIdx, anyIdx, bestOpen := -1, -1, false 195 var bestRes, anyRes engine.MatchResult 196 // Win Impact: their best gap filling value across every open requirement they are eligible for. 197 winTier, winUnmet, winQty := 0, 0, 0 198 winLcat := "" 199 for i, re := range reqs { 200 res := engine.ScoreCandidate(ctx, ec, re.er, matcher) 201 if re.lcat != "" && res.Band >= engine.BandYellow { 202 bandLcat[re.lcat] = true 203 } 204 // Break score ties on requirement id so the Best Fit pick is stable regardless of row order. 205 if anyIdx == -1 || res.Total.GreaterThan(anyRes.Total) || 206 (res.Total.Equal(anyRes.Total) && re.id.String() < reqs[anyIdx].id.String()) { 207 anyRes, anyIdx = res, i 208 } 209 cvg, open := coverage[re.id.String()] 210 if !open { 211 continue 212 } 213 if !bestOpen || res.Total.GreaterThan(bestRes.Total) || 214 (res.Total.Equal(bestRes.Total) && re.id.String() < reqs[bestIdx].id.String()) { 215 bestRes, bestIdx, bestOpen = res, i, true 216 } 217 if eligible[re.id.String()][candID] { // hard eligible per the assignment (clearance, years, mandatory skills) 218 unmet := cvg.Quantity - cvg.Assigned 219 if unmet < 0 { 220 unmet = 0 221 } 222 t := 1 // eligible but the role is fully staffed with a deep pool (redundant depth) 223 if unmet > 0 { 224 t = 3 // fills a current open gap 225 } else if cvg.Qualified <= cvg.Quantity*2 { 226 t = 2 // thin qualified pool, valuable backfill depth 227 } 228 // Highest tier wins; within a tier the larger open gap wins so the basis cites the biggest gap. 229 if t > winTier || (t == winTier && unmet > winUnmet) { 230 winTier, winUnmet, winQty, winLcat = t, unmet, cvg.Quantity, re.lcat 231 } 232 } 233 } 234 if bestIdx == -1 { // no open requirement; fall back to the strongest overall 235 bestIdx, bestRes = anyIdx, anyRes 236 } 237 best := reqs[bestIdx] 238 239 // Labor category coverage: union of band based qualification and profile text keywords, filtered 240 // to the labor categories the org actually has open. 241 cov := map[string]bool{} 242 for l := range bandLcat { 243 cov[l] = true 244 } 245 text := deref(c.Headline) + " " + skillText(ec.Skills) 246 for _, lc := range missionclass.ClassifyLabor(text) { 247 if validLcat[lc] { 248 cov[lc] = true 249 } 250 } 251 labor := make([]string, 0, len(cov)) 252 for l := range cov { 253 labor = append(labor, l) 254 } 255 sort.Strings(labor) 256 257 return CandidateIntelligenceView{ 258 ID: c.ID, FullName: c.FullName, Source: c.Source, Headline: deref(c.Headline), 259 YearsExperience: c.YearsExperience, Location: deref(c.Location), Available: c.Available, 260 Clearance: clearanceCell(c, facts, asOf), 261 MissionReadiness: ReadinessCell{Score: bestRes.Total.StringFixed(2), Band: bestRes.Band.Code(), Status: intelligence.MissionStatusLabel(bestRes.Band)}, 262 ProposalReady: proposalReady(bestRes, best.kp), 263 WinImpact: winImpactCell(winTier, winUnmet, winQty, winLcat), 264 BestFit: BestFitCell{RequirementID: best.id, Name: best.title, CustomerAgency: best.customer, Score: bestRes.Total.StringFixed(2), Band: bestRes.Band.Code()}, 265 LaborCategoryCoverage: labor, 266 }, bestRes 267} 268 269func clearanceCell(c dbgen.Candidate, facts intelligence.ClearanceFacts, asOf time.Time) ClearanceCell { 270 ci := intelligence.Clearance(facts, asOf) 271 known := c.ClearanceStatus != "unknown" && c.ClearanceLevel != "unknown" 272 status := ci.Status 273 if ci.Expired { // a lapsed active clearance is not active; show it as Expired, never confidently active 274 status = "Expired" 275 } 276 cell := ClearanceCell{ 277 Level: ci.Current, Status: status, SciEligible: ci.SCIEligible, SciKnown: known, 278 Provenance: ci.ProvenanceLabel, Verified: ci.Verified, Available: c.Available, 279 } 280 if c.ClearanceGrantedAt.Valid { 281 cell.InvestigationYear = fmt.Sprintf("%d", c.ClearanceGrantedAt.Time.Year()) 282 } 283 return cell 284} 285 286func proposalReady(res engine.MatchResult, kp bool) ProposalCell { 287 green := res.Band == engine.BandGreen 288 certsMet := res.Certifications.GreaterThanOrEqual(decimal.NewFromInt(100)) 289 if green && certsMet { 290 note := "Green band, certifications complete" 291 if kp { 292 note = "Green band, certifications complete, key personnel eligible" 293 } 294 return ProposalCell{Value: "YES", Reason: note} 295 } 296 if !green { 297 return ProposalCell{Value: "REVIEW", Reason: fmt.Sprintf("Mission Readiness %s, below the green threshold of 90", res.Total.StringFixed(0))} 298 } 299 if g := firstCertGap(res.GapSummary); g != "" { 300 return ProposalCell{Value: "REVIEW", Reason: g} 301 } 302 return ProposalCell{Value: "REVIEW", Reason: "Certifications incomplete for this labor category"} 303} 304 305// winImpactCell maps the gap filling tier to a label and a basis. Tier 3 fills a current open gap, 306// tier 2 backfills a thin qualified pool, tier 1 is redundant depth on a staffed role. 307func winImpactCell(tier, unmet, quantity int, lcat string) WinImpactCell { 308 label := lcat 309 if label == "" { 310 label = "an open role" 311 } 312 switch tier { 313 case 3: 314 return WinImpactCell{Level: "HIGH", Basis: fmt.Sprintf("Fills an open %s slot, %d of %d still unfilled", label, unmet, quantity)} 315 case 2: 316 return WinImpactCell{Level: "MEDIUM", Basis: "Thin qualified pool for " + label + ", valuable backfill depth"} 317 case 1: 318 return WinImpactCell{Level: "LOW", Basis: label + " is fully staffed, this adds redundant depth"} 319 default: 320 return WinImpactCell{Level: "LOW", Basis: "Not yet eligible for an open requirement"} 321 } 322} 323 324func firstCertGap(gaps []string) string { 325 for _, g := range gaps { 326 if strings.Contains(strings.ToLower(g), "cert") { 327 return g 328 } 329 } 330 return "" 331} 332 333func skillText(skills []engine.CandidateSkill) string { 334 if len(skills) == 0 { 335 return "" 336 } 337 names := make([]string, 0, len(skills)) 338 for _, s := range skills { 339 names = append(names, s.Name) 340 } 341 return strings.Join(names, " ") 342} 343