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// SlateSummaryView is one row of the slate list for a requirement (slateMATCH list). 131type SlateSummaryView struct { 132 SlateID string `json:"slate_id"` 133 Name string `json:"name"` 134 Status string `json:"status"` 135 MemberCount int `json:"member_count"` 136 CreatedAt string `json:"created_at"` 137} 138 139// SlateMemberDetailView is one member on the slate detail: the frozen score and band read from the 140// persisted slate (never recomputed), the human decision, the reviewer note, and the candidate name. 141type SlateMemberDetailView struct { 142 CandidateID string `json:"candidate_id"` 143 FullName string `json:"full_name"` 144 Rank int `json:"rank"` 145 Total string `json:"total_score"` 146 Band string `json:"band"` 147 BandLabel string `json:"band_label"` 148 Components map[string]string `json:"components"` 149 Explanation string `json:"explanation"` 150 GapSummary []string `json:"gap_summary"` 151 Decision string `json:"decision"` 152 DecisionNote string `json:"decision_note"` 153} 154 155// SlateDetailView is a slate with its ranked members and the proposal readiness rollup, all read from 156// the stored slate. 157type SlateDetailView struct { 158 SlateID string `json:"slate_id"` 159 RequirementID string `json:"requirement_id"` 160 RequirementTitle string `json:"requirement_title"` 161 Name string `json:"name"` 162 Status string `json:"status"` 163 Members []SlateMemberDetailView `json:"members"` 164 Readiness ProposalReadinessView `json:"readiness"` 165} 166 167// ProposalReadinessView is the rollup of a slate's persisted members and their human decisions 168// (GET /proposal-readiness). It is computed from the stored slate, never by rescoring candidates, so 169// it always agrees with the frozen member scores. 170type ProposalReadinessView struct { 171 SlateID string `json:"slate_id"` 172 RequirementID string `json:"requirement_id"` 173 TotalMembers int `json:"total_members"` 174 Approved int `json:"approved"` 175 Rejected int `json:"rejected"` 176 Pending int `json:"pending"` 177 ProposalReady int `json:"proposal_ready"` // members in the Green band 178 Potential int `json:"potential"` // members in the Yellow band 179 Recruiting int `json:"recruiting"` // members in the Red band 180 ApprovedReady int `json:"approved_ready"` // approved AND Green 181 ReadinessPct string `json:"readiness_pct"` // approved divided by total, as a percent (decimal) 182 Status string `json:"status"` // overall label 183} 184 185// CandidateListView / RequirementListView are minimal list projections (no embeddings/tsv). 186type CandidateListView struct { 187 ID uuid.UUID `json:"id"` 188 FullName string `json:"full_name"` 189 ClearanceLevel string `json:"clearance_level"` 190 ClearanceStatus string `json:"clearance_status"` 191 YearsExperience int32 `json:"years_experience"` 192 Location string `json:"location,omitempty"` 193 Available bool `json:"available"` 194} 195 196type RequirementListView struct { 197 ID uuid.UUID `json:"id"` 198 Title string `json:"title"` 199 RequiredLevel string `json:"required_level"` 200 CustomerAgency string `json:"customer_agency,omitempty"` 201 KeyPersonnel bool `json:"key_personnel"` 202} 203 204func matchResultView(res engine.MatchResult) MatchResultView { 205 trace := make([]ComponentView, len(res.Trace)) 206 for i, c := range res.Trace { 207 trace[i] = ComponentView{ 208 Component: c.Component, Weight: c.Weight.String(), 209 Raw: c.Raw.StringFixed(2), Weighted: c.Weighted.StringFixed(4), Rationale: c.Rationale, 210 } 211 } 212 ms := make([]MatchedSkillView, len(res.MatchedSkills)) 213 for i, m := range res.MatchedSkills { 214 ms[i] = MatchedSkillView{ 215 RequiredSkill: m.RequiredSkillName, CandidateSkill: m.CandidateName, 216 Similarity: m.Similarity.StringFixed(4), Exact: m.Exact, Matched: m.Matched, 217 } 218 } 219 return MatchResultView{ 220 CandidateID: res.CandidateID, RequirementID: res.RequirementID, 221 Total: res.Total.StringFixed(2), Band: res.Band.Code(), BandLabel: res.Band.Label(), 222 Components: map[string]string{ 223 "clearance": res.Clearance.StringFixed(2), 224 "skills": res.Skills.StringFixed(2), 225 "certifications": res.Certifications.StringFixed(2), 226 "customer_experience": res.CustomerExperience.StringFixed(2), 227 "experience": res.Experience.StringFixed(2), 228 "location_availability": res.Location.StringFixed(2), 229 }, 230 Explanation: res.Explanation, GapSummary: nonNilStrings(res.GapSummary), 231 MatchedSkills: ms, Trace: trace, 232 } 233} 234 235func slateMemberView(candidateID string, rank int, res engine.MatchResult) SlateMemberView { 236 return SlateMemberView{ 237 CandidateID: candidateID, Rank: rank, 238 Total: res.Total.StringFixed(2), Band: res.Band.Code(), BandLabel: res.Band.Label(), 239 Explanation: res.Explanation, GapSummary: nonNilStrings(res.GapSummary), 240 } 241} 242 243func candidateListView(c dbgen.Candidate) CandidateListView { 244 return CandidateListView{ 245 ID: c.ID, FullName: c.FullName, ClearanceLevel: c.ClearanceLevel, ClearanceStatus: c.ClearanceStatus, 246 YearsExperience: c.YearsExperience, Location: deref(c.Location), Available: c.Available, 247 } 248} 249 250func requirementListView(r dbgen.Requirement) RequirementListView { 251 return RequirementListView{ 252 ID: r.ID, Title: r.Title, RequiredLevel: r.RequiredLevel, 253 CustomerAgency: deref(r.CustomerAgency), KeyPersonnel: r.KeyPersonnel, 254 } 255} 256 257func nonNilStrings(s []string) []string { 258 if s == nil { 259 return []string{} 260 } 261 return s 262} 263