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

1// Package matching is the slate-loop application layer: it loads candidates and requirements from 2// the DB, runs the pure engine, and persists the explainable result as a slate. The engine stays 3// pure; THIS package owns the DB<->engine boundary, including enum encode/decode (engine.Code/Parse) 4// and the clearance-expiry-as-of-date rule. 5package matching 6 7import ( 8 "encoding/json" 9 "fmt" 10 "time" 11 12 "github.com/google/uuid" 13 "github.com/jackc/pgx/v5/pgtype" 14 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) 19 20// ClearanceFactsFrom builds the intelligence ClearanceFacts (with the clearance dates the engine 21// omits) from a DB candidate row plus its loaded customer agencies. Codes are CHECK-constrained at 22// the DB so parsing always succeeds for a stored row. 23func ClearanceFactsFrom(c dbgen.Candidate, customerAgencies []string) intelligence.ClearanceFacts { 24 level, _ := engine.ParseClearanceLevel(c.ClearanceLevel) 25 poly, _ := engine.ParsePolygraph(c.ClearancePoly) 26 status, _ := engine.ParseClearanceStatus(c.ClearanceStatus) 27 return intelligence.ClearanceFacts{ 28 Level: level, 29 Poly: poly, 30 Status: status, 31 GrantedAt: datePtr(c.ClearanceGrantedAt), 32 ExpiresAt: datePtr(c.ClearanceExpiresAt), 33 ReinvestigationDueAt: datePtr(c.ReinvestigationDueAt), 34 CustomerAgencies: customerAgencies, 35 } 36} 37 38func datePtr(d pgtype.Date) *time.Time { 39 if !d.Valid { 40 return nil 41 } 42 t := d.Time 43 return &t 44} 45 46// ToEngineCandidate maps a DB candidate (+ its loaded skills/certs/customer-experience) into the 47// pure engine input. asOf is the evaluation date: clearance_expires_at is the source of truth, so an 48// Active flag with a past expiry is treated as Expired (review COMPL-1). It NEVER reads a demographic 49// field — there is none on the candidate row by design (AEDT). 50func ToEngineCandidate(c dbgen.Candidate, skills []dbgen.ListCandidateSkillsRow, certs, custExp []string, asOf time.Time) (engine.Candidate, error) { 51 level, err := engine.ParseClearanceLevel(c.ClearanceLevel) 52 if err != nil { 53 return engine.Candidate{}, fmt.Errorf("candidate %s: %w", c.ID, err) 54 } 55 poly, err := engine.ParsePolygraph(c.ClearancePoly) 56 if err != nil { 57 return engine.Candidate{}, fmt.Errorf("candidate %s: %w", c.ID, err) 58 } 59 status, err := engine.ParseClearanceStatus(c.ClearanceStatus) 60 if err != nil { 61 return engine.Candidate{}, fmt.Errorf("candidate %s: %w", c.ID, err) 62 } 63 status = effectiveStatus(status, c.ClearanceExpiresAt, asOf) 64 65 es := make([]engine.CandidateSkill, len(skills)) 66 for i, s := range skills { 67 es[i] = engine.CandidateSkill{SkillID: s.ID.String(), Name: s.Name} 68 } 69 70 return engine.Candidate{ 71 ID: c.ID.String(), 72 Clearance: engine.Clearance{Level: level, Poly: poly, Status: status}, 73 Skills: es, 74 Certifications: certs, 75 CustomerExperience: custExp, 76 YearsExperience: int(c.YearsExperience), 77 Location: deref(c.Location), 78 Remote: c.Remote, 79 Relocatable: c.Relocatable, 80 Available: c.Available, 81 }, nil 82} 83 84// effectiveStatus downgrades an Active clearance to Expired when its expiry date has passed as-of the 85// evaluation date. The date column is authoritative over the stored flag. The comparison is on the 86// CIVIL DATE (asOf truncated to midnight UTC of its Y/M/D) so a clearance expiring exactly on the 87// as-of day is still effective — matching the Command Center's `clearance_expires_at >= as_of::date` 88// byte-for-byte regardless of the wall-clock time carried by asOf [review ENGINE-1/EN-1]. 89func effectiveStatus(stored engine.ClearanceStatus, expires pgtype.Date, asOf time.Time) engine.ClearanceStatus { 90 asOfDate := time.Date(asOf.Year(), asOf.Month(), asOf.Day(), 0, 0, 0, 0, time.UTC) 91 if stored == engine.StatusActive && expires.Valid && expires.Time.Before(asOfDate) { 92 return engine.StatusExpired 93 } 94 return stored 95} 96 97// ToEngineRequirement maps a DB requirement (+ its required skills/certs) into the pure engine input. 98func ToEngineRequirement(r dbgen.Requirement, reqSkills []dbgen.ListRequiredSkillsRow, reqCerts []string) (engine.Requirement, error) { 99 level, err := engine.ParseClearanceLevel(r.RequiredLevel) 100 if err != nil { 101 return engine.Requirement{}, fmt.Errorf("requirement %s: %w", r.ID, err) 102 } 103 poly, err := engine.ParsePolygraph(r.RequiredPoly) 104 if err != nil { 105 return engine.Requirement{}, fmt.Errorf("requirement %s: %w", r.ID, err) 106 } 107 108 rs := make([]engine.RequiredSkill, len(reqSkills)) 109 for i, s := range reqSkills { 110 rs[i] = engine.RequiredSkill{SkillID: s.ID.String(), Name: s.Name, Mandatory: s.Mandatory} 111 } 112 113 return engine.Requirement{ 114 ID: r.ID.String(), 115 RequiredLevel: level, 116 RequiredPoly: poly, 117 RequiredSkills: rs, 118 RequiredCerts: reqCerts, 119 CustomerAgency: deref(r.CustomerAgency), 120 RequiredYears: int(r.RequiredYears), 121 WorkLocation: deref(r.WorkLocation), 122 RemoteAllowed: r.RemoteAllowed, 123 KeyPersonnel: r.KeyPersonnel, 124 }, nil 125} 126 127// ToSlateMemberParams freezes an engine result into the AEDT decision record. Band is the DB Code() 128// (never String()), and the full trace + gap summary are persisted as jsonb so the decision is 129// reproducible and explainable. 130func ToSlateMemberParams(orgID, slateID, candidateID uuid.UUID, res engine.MatchResult, rank *int32) (dbgen.AddSlateMemberParams, error) { 131 trace, err := json.Marshal(res.Trace) 132 if err != nil { 133 return dbgen.AddSlateMemberParams{}, fmt.Errorf("marshal decision trace: %w", err) 134 } 135 gaps := []byte("[]") 136 if len(res.GapSummary) > 0 { 137 if gaps, err = json.Marshal(res.GapSummary); err != nil { 138 return dbgen.AddSlateMemberParams{}, fmt.Errorf("marshal gap summary: %w", err) 139 } 140 } 141 142 return dbgen.AddSlateMemberParams{ 143 OrganizationID: orgID, 144 SlateID: slateID, 145 CandidateID: candidateID, 146 TotalScore: res.Total, 147 Band: res.Band.Code(), 148 ClearanceScore: res.Clearance, 149 SkillsScore: res.Skills, 150 CertsScore: res.Certifications, 151 CustomerScore: res.CustomerExperience, 152 ExperienceScore: res.Experience, 153 LocationScore: res.Location, 154 Explanation: res.Explanation, 155 Trace: trace, 156 GapSummary: gaps, 157 Rank: rank, 158 ModelVersion: strPtr(engine.ModelVersion), 159 }, nil 160} 161 162func strPtr(s string) *string { return &s } 163 164func deref(s *string) string { 165 if s == nil { 166 return "" 167 } 168 return *s 169} 170