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

1package matching 2 3import ( 4 "time" 5 6 "github.com/google/uuid" 7 8 "github.com/missionworkforce/missionmatch/internal/modules/matching/engine" 9 "github.com/missionworkforce/missionmatch/internal/modules/matching/intelligence" 10 "github.com/missionworkforce/missionmatch/internal/platform/database/dbgen" 11) 12 13// ScreenView is the full screenMATCH™ intelligence output for POST /api/screen: the explainable 14// match plus the derived Mission Readiness panels (User Guide + the "Defining" brief). 15type ScreenView struct { 16 Match MatchResultView `json:"match"` 17 MissionReadiness intelligence.MissionReadiness `json:"mission_readiness"` 18 BattleCard intelligence.BattleCard `json:"battle_card"` 19 ClearanceIntel intelligence.ClearanceIntel `json:"clearance_intelligence"` 20 ContractReadiness intelligence.ContractReadiness `json:"contract_readiness"` 21 WinImpact intelligence.WinImpact `json:"win_impact"` 22 NextSteps []intelligence.NextStep `json:"next_steps"` 23} 24 25// RankedCandidateView is one row of the Candidate Screening Queue (Screen 1): a candidate scored 26// against a requirement, with the operational Mission Readiness status. Read-only (no slate persisted). 27type RankedCandidateView struct { 28 CandidateID uuid.UUID `json:"candidate_id"` 29 FullName string `json:"full_name"` 30 ClearanceLevel string `json:"clearance_level"` 31 ClearanceStatus string `json:"clearance_status"` 32 YearsExperience int32 `json:"years_experience"` 33 Location string `json:"location,omitempty"` 34 Available bool `json:"available"` 35 Score string `json:"score"` 36 Band string `json:"band"` 37 Status string `json:"status"` 38} 39 40func rankedCandidateView(c dbgen.Candidate, res engine.MatchResult) RankedCandidateView { 41 return RankedCandidateView{ 42 CandidateID: c.ID, FullName: c.FullName, 43 ClearanceLevel: c.ClearanceLevel, ClearanceStatus: c.ClearanceStatus, 44 YearsExperience: c.YearsExperience, Location: deref(c.Location), Available: c.Available, 45 Score: res.Total.StringFixed(2), Band: res.Band.Code(), Status: intelligence.MissionStatusLabel(res.Band), 46 } 47} 48 49// OpportunityFitView is one ranked "best opportunity for this person" (Opportunity Fit Engine™). 50type OpportunityFitView struct { 51 RequirementID uuid.UUID `json:"requirement_id"` 52 Title string `json:"title"` 53 CustomerAgency string `json:"customer_agency,omitempty"` 54 Score string `json:"score"` 55 Band string `json:"band"` 56 Status string `json:"status"` // operational status, e.g. "Mission Ready" 57} 58 59func assembleScreenView(c engine.Candidate, r engine.Requirement, res engine.MatchResult, facts intelligence.ClearanceFacts, asOf time.Time) ScreenView { 60 return ScreenView{ 61 Match: matchResultView(res), 62 MissionReadiness: intelligence.Readiness(res), 63 BattleCard: intelligence.BattleCardFor(c, r, res), 64 ClearanceIntel: intelligence.Clearance(facts, asOf), 65 ContractReadiness: intelligence.Contract(c, r, res, facts, asOf), 66 WinImpact: intelligence.Win(c, r, res), 67 NextSteps: intelligence.NextSteps(res), 68 } 69} 70 71// GenerateSlateInput is the validated input to slate generation. 72type GenerateSlateInput struct { 73 RequirementID uuid.UUID 74 Name string 75 CreatedBy *uuid.UUID 76 MaxCandidates int32 77} 78 79// ComponentView is one row of the decision trace, JSON-friendly (decimals as fixed strings). 80type ComponentView struct { 81 Component string `json:"component"` 82 Weight string `json:"weight"` 83 Raw string `json:"raw"` 84 Weighted string `json:"weighted"` 85 Rationale string `json:"rationale"` 86} 87 88// MatchedSkillView is one required->candidate skill resolution. 89type MatchedSkillView struct { 90 RequiredSkill string `json:"required_skill"` 91 CandidateSkill string `json:"candidate_skill,omitempty"` 92 Similarity string `json:"similarity"` 93 Exact bool `json:"exact"` 94 Matched bool `json:"matched"` 95} 96 97// MatchResultView is the full, explainable result for POST /match (screenMATCH). 98type MatchResultView struct { 99 CandidateID string `json:"candidate_id"` 100 RequirementID string `json:"requirement_id"` 101 Total string `json:"total_score"` 102 Band string `json:"band"` 103 BandLabel string `json:"band_label"` 104 Components map[string]string `json:"components"` 105 Explanation string `json:"explanation"` 106 GapSummary []string `json:"gap_summary"` 107 MatchedSkills []MatchedSkillView `json:"matched_skills"` 108 Trace []ComponentView `json:"trace"` 109} 110 111// SlateMemberView is one ranked member of a generated slate. 112type SlateMemberView struct { 113 CandidateID string `json:"candidate_id"` 114 Rank int `json:"rank"` 115 Total string `json:"total_score"` 116 Band string `json:"band"` 117 BandLabel string `json:"band_label"` 118 Explanation string `json:"explanation"` 119 GapSummary []string `json:"gap_summary"` 120} 121 122// SlateResult is the output of POST /slates/generate (slateMATCH). 123type SlateResult struct { 124 SlateID uuid.UUID `json:"slate_id"` 125 RequirementID uuid.UUID `json:"requirement_id"` 126 Name string `json:"name"` 127 Members []SlateMemberView `json:"members"` 128} 129 130// CandidateListView / RequirementListView are minimal list projections (no embeddings/tsv). 131type CandidateListView struct { 132 ID uuid.UUID `json:"id"` 133 FullName string `json:"full_name"` 134 ClearanceLevel string `json:"clearance_level"` 135 ClearanceStatus string `json:"clearance_status"` 136 YearsExperience int32 `json:"years_experience"` 137 Location string `json:"location,omitempty"` 138 Available bool `json:"available"` 139} 140 141type RequirementListView struct { 142 ID uuid.UUID `json:"id"` 143 Title string `json:"title"` 144 RequiredLevel string `json:"required_level"` 145 CustomerAgency string `json:"customer_agency,omitempty"` 146 KeyPersonnel bool `json:"key_personnel"` 147} 148 149func matchResultView(res engine.MatchResult) MatchResultView { 150 trace := make([]ComponentView, len(res.Trace)) 151 for i, c := range res.Trace { 152 trace[i] = ComponentView{ 153 Component: c.Component, Weight: c.Weight.String(), 154 Raw: c.Raw.StringFixed(2), Weighted: c.Weighted.StringFixed(4), Rationale: c.Rationale, 155 } 156 } 157 ms := make([]MatchedSkillView, len(res.MatchedSkills)) 158 for i, m := range res.MatchedSkills { 159 ms[i] = MatchedSkillView{ 160 RequiredSkill: m.RequiredSkillName, CandidateSkill: m.CandidateName, 161 Similarity: m.Similarity.StringFixed(4), Exact: m.Exact, Matched: m.Matched, 162 } 163 } 164 return MatchResultView{ 165 CandidateID: res.CandidateID, RequirementID: res.RequirementID, 166 Total: res.Total.StringFixed(2), Band: res.Band.Code(), BandLabel: res.Band.Label(), 167 Components: map[string]string{ 168 "clearance": res.Clearance.StringFixed(2), 169 "skills": res.Skills.StringFixed(2), 170 "certifications": res.Certifications.StringFixed(2), 171 "customer_experience": res.CustomerExperience.StringFixed(2), 172 "experience": res.Experience.StringFixed(2), 173 "location_availability": res.Location.StringFixed(2), 174 }, 175 Explanation: res.Explanation, GapSummary: nonNilStrings(res.GapSummary), 176 MatchedSkills: ms, Trace: trace, 177 } 178} 179 180func slateMemberView(candidateID string, rank int, res engine.MatchResult) SlateMemberView { 181 return SlateMemberView{ 182 CandidateID: candidateID, Rank: rank, 183 Total: res.Total.StringFixed(2), Band: res.Band.Code(), BandLabel: res.Band.Label(), 184 Explanation: res.Explanation, GapSummary: nonNilStrings(res.GapSummary), 185 } 186} 187 188func candidateListView(c dbgen.Candidate) CandidateListView { 189 return CandidateListView{ 190 ID: c.ID, FullName: c.FullName, ClearanceLevel: c.ClearanceLevel, ClearanceStatus: c.ClearanceStatus, 191 YearsExperience: c.YearsExperience, Location: deref(c.Location), Available: c.Available, 192 } 193} 194 195func requirementListView(r dbgen.Requirement) RequirementListView { 196 return RequirementListView{ 197 ID: r.ID, Title: r.Title, RequiredLevel: r.RequiredLevel, 198 CustomerAgency: deref(r.CustomerAgency), KeyPersonnel: r.KeyPersonnel, 199 } 200} 201 202func nonNilStrings(s []string) []string { 203 if s == nil { 204 return []string{} 205 } 206 return s 207} 208