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

1package matching 2 3import ( 4 "encoding/json" 5 "errors" 6 "net/http" 7 "strconv" 8 "strings" 9 "time" 10 11 "github.com/go-chi/chi/v5" 12 "github.com/google/uuid" 13 14 "github.com/missionworkforce/missionmatch/internal/platform/database/dbgen" 15 "github.com/missionworkforce/missionmatch/internal/platform/security" 16 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 17) 18 19// Handler exposes the matching/slate API. Routes are mounted under a tenant-scoped group. 20type Handler struct{ svc *Service } 21 22// NewHandler builds the HTTP handler. 23func NewHandler(svc *Service) *Handler { return &Handler{svc: svc} } 24 25// Routes registers the API endpoints on r (already wrapped by the session resolver). Every person 26// scoring surface is an AEDT output and carries a capability check, so authorization is enforced at 27// the API from the validated session, never hidden in the UI. Scoring and ranking need search.run; 28// the slate write and the human decision need slate.write; reads need candidate.read. 29func (h *Handler) Routes(r chi.Router) { 30 r.With(security.RequireCapability(security.CapSearchRun)).Post("/match", h.postMatch) 31 r.With(security.RequireCapability(security.CapSearchRun)).Post("/screen", h.postScreen) 32 r.With(security.RequireCapability(security.CapSlateEdit)).Post("/slates/generate", h.postGenerate) 33 r.With(security.RequireCapability(security.CapSlateEdit)).Patch("/slates/{slateID}/members/{candidateID}/decision", h.postDecision) 34 r.With(security.RequireCapability(security.CapCandidateRead)).Get("/slates/{slateID}/members/{candidateID}/trace", h.getTrace) 35 r.With(security.RequireCapability(security.CapCandidateRead)).Get("/candidates", h.getCandidates) 36 r.With(security.RequireCapability(security.CapSearchRun)).Get("/candidates/intelligence", h.getCandidateIntelligence) 37 r.With(security.RequireCapability(security.CapCandidateRead)).Get("/candidates/{candidateID}", h.getCandidate) 38 r.With(security.RequireCapability(security.CapSearchRun)).Get("/candidates/{candidateID}/opportunities", h.getOpportunities) 39 r.With(security.RequireCapability(security.CapCandidateRead)).Get("/requirements", h.getRequirements) 40 r.With(security.RequireCapability(security.CapCandidateRead)).Get("/requirements/{requirementID}", h.getRequirement) 41 r.With(security.RequireCapability(security.CapSearchRun)).Get("/requirements/{requirementID}/candidates", h.getRankedCandidates) 42 // Mission Check (W1): scoring an in memory resume is a search.run AEDT output; the optional Save 43 // Candidate is a recruiter write. Both ride the same session auth, RBAC, and audit as every surface. 44 r.With(security.RequireCapability(security.CapSearchRun)).Post("/mission-check/opportunities", h.postMissionCheckOpportunities) 45 r.With(security.RequireCapability(security.CapSearchRun)).Post("/mission-check/screen", h.postMissionCheckJD) 46 r.With(security.RequireCapability(security.CapCandidateWrite)).Post("/candidates", h.postCreateCandidate) 47 r.With(security.RequireCapability(security.CapCandidateWrite)).Patch("/candidates/{candidateID}/clearance-provenance", h.patchClearanceProvenance) 48} 49 50type matchRequest struct { 51 CandidateID uuid.UUID `json:"candidate_id"` 52 RequirementID uuid.UUID `json:"requirement_id"` 53} 54 55func (h *Handler) postMatch(w http.ResponseWriter, r *http.Request) { 56 var req matchRequest 57 if !decodeJSON(w, r, &req) { 58 return 59 } 60 if req.CandidateID == uuid.Nil || req.RequirementID == uuid.Nil { 61 writeError(w, http.StatusBadRequest, "candidate_id and requirement_id are required") 62 return 63 } 64 res, err := h.svc.ScreenCandidate(r.Context(), req.CandidateID, req.RequirementID) 65 if err != nil { 66 writeServiceError(w, err) 67 return 68 } 69 writeJSON(w, http.StatusOK, matchResultView(res)) 70} 71 72func (h *Handler) postScreen(w http.ResponseWriter, r *http.Request) { 73 var req matchRequest 74 if !decodeJSON(w, r, &req) { 75 return 76 } 77 if req.CandidateID == uuid.Nil || req.RequirementID == uuid.Nil { 78 writeError(w, http.StatusBadRequest, "candidate_id and requirement_id are required") 79 return 80 } 81 view, err := h.svc.Screen(r.Context(), req.CandidateID, req.RequirementID) 82 if err != nil { 83 writeServiceError(w, err) 84 return 85 } 86 writeJSON(w, http.StatusOK, view) 87} 88 89func (h *Handler) getRankedCandidates(w http.ResponseWriter, r *http.Request) { 90 reqID, err := uuid.Parse(chi.URLParam(r, "requirementID")) 91 if err != nil { 92 writeError(w, http.StatusBadRequest, "invalid requirement id") 93 return 94 } 95 out, err := h.svc.RankCandidates(r.Context(), reqID) 96 if err != nil { 97 writeServiceError(w, err) 98 return 99 } 100 writeJSON(w, http.StatusOK, out) 101} 102 103func (h *Handler) getOpportunities(w http.ResponseWriter, r *http.Request) { 104 candidateID, err := uuid.Parse(chi.URLParam(r, "candidateID")) 105 if err != nil { 106 writeError(w, http.StatusBadRequest, "invalid candidate id") 107 return 108 } 109 limit := 10 110 if v, err := strconv.Atoi(r.URL.Query().Get("limit")); err == nil && v > 0 && v <= 100 { 111 limit = v 112 } 113 fits, err := h.svc.OpportunitiesForCandidate(r.Context(), candidateID, limit) 114 if err != nil { 115 writeServiceError(w, err) 116 return 117 } 118 writeJSON(w, http.StatusOK, fits) 119} 120 121type generateRequest struct { 122 RequirementID uuid.UUID `json:"requirement_id"` 123 Name string `json:"name"` 124 MaxCandidates int32 `json:"max_candidates"` 125} 126 127func (h *Handler) postGenerate(w http.ResponseWriter, r *http.Request) { 128 var req generateRequest 129 if !decodeJSON(w, r, &req) { 130 return 131 } 132 if req.RequirementID == uuid.Nil { 133 writeError(w, http.StatusBadRequest, "requirement_id is required") 134 return 135 } 136 out, err := h.svc.GenerateSlate(r.Context(), GenerateSlateInput{ 137 RequirementID: req.RequirementID, Name: req.Name, MaxCandidates: req.MaxCandidates, 138 CreatedBy: principalID(r), 139 }) 140 if err != nil { 141 writeServiceError(w, err) 142 return 143 } 144 writeJSON(w, http.StatusCreated, out) 145} 146 147type decisionRequest struct { 148 Decision string `json:"decision"` // approved or rejected 149} 150 151func (h *Handler) postDecision(w http.ResponseWriter, r *http.Request) { 152 slateID, err := uuid.Parse(chi.URLParam(r, "slateID")) 153 if err != nil { 154 writeError(w, http.StatusBadRequest, "invalid slate id") 155 return 156 } 157 candidateID, err := uuid.Parse(chi.URLParam(r, "candidateID")) 158 if err != nil { 159 writeError(w, http.StatusBadRequest, "invalid candidate id") 160 return 161 } 162 var req decisionRequest 163 if !decodeJSON(w, r, &req) { 164 return 165 } 166 if err := h.svc.DecideSlateMember(r.Context(), slateID, candidateID, req.Decision); err != nil { 167 writeServiceError(w, err) 168 return 169 } 170 writeJSON(w, http.StatusOK, map[string]string{"status": req.Decision}) 171} 172 173func (h *Handler) getTrace(w http.ResponseWriter, r *http.Request) { 174 slateID, err := uuid.Parse(chi.URLParam(r, "slateID")) 175 if err != nil { 176 writeError(w, http.StatusBadRequest, "invalid slate id") 177 return 178 } 179 candidateID, err := uuid.Parse(chi.URLParam(r, "candidateID")) 180 if err != nil { 181 writeError(w, http.StatusBadRequest, "invalid candidate id") 182 return 183 } 184 m, err := h.svc.SlateMemberTrace(r.Context(), slateID, candidateID) 185 if err != nil { 186 writeServiceError(w, err) 187 return 188 } 189 writeJSON(w, http.StatusOK, slateMemberTraceView(m)) 190} 191 192// principalID returns the validated session user id for the actor on a decision or generation. 193func principalID(r *http.Request) *uuid.UUID { 194 if p, ok := tenant.UserFromContext(r.Context()); ok { 195 if id, err := uuid.Parse(p.UserID); err == nil { 196 return &id 197 } 198 } 199 return nil 200} 201 202func (h *Handler) getCandidateIntelligence(w http.ResponseWriter, r *http.Request) { 203 limit := 0 204 if v, err := strconv.Atoi(r.URL.Query().Get("limit")); err == nil { 205 limit = v 206 } 207 out, err := h.svc.CandidateIntelligence(r.Context(), limit) 208 if err != nil { 209 writeServiceError(w, err) 210 return 211 } 212 if out == nil { 213 out = []CandidateIntelligenceView{} 214 } 215 writeJSON(w, http.StatusOK, out) 216} 217 218func (h *Handler) getCandidates(w http.ResponseWriter, r *http.Request) { 219 limit, offset := pageParams(r) 220 rows, err := h.svc.ListCandidates(r.Context(), limit, offset) 221 if err != nil { 222 writeServiceError(w, err) 223 return 224 } 225 out := make([]CandidateListView, len(rows)) 226 for i, c := range rows { 227 out[i] = candidateListView(c) 228 } 229 writeJSON(w, http.StatusOK, out) 230} 231 232func (h *Handler) getRequirements(w http.ResponseWriter, r *http.Request) { 233 limit, offset := pageParams(r) 234 rows, err := h.svc.ListRequirements(r.Context(), limit, offset) 235 if err != nil { 236 writeServiceError(w, err) 237 return 238 } 239 out := make([]RequirementListView, len(rows)) 240 for i, rq := range rows { 241 out[i] = requirementListView(rq) 242 } 243 writeJSON(w, http.StatusOK, out) 244} 245 246func (h *Handler) getCandidate(w http.ResponseWriter, r *http.Request) { 247 id, err := uuid.Parse(chi.URLParam(r, "candidateID")) 248 if err != nil { 249 writeError(w, http.StatusBadRequest, "invalid candidate id") 250 return 251 } 252 c, err := h.svc.GetCandidate(r.Context(), id) 253 if err != nil { 254 writeServiceError(w, err) 255 return 256 } 257 writeJSON(w, http.StatusOK, candidateListView(c)) 258} 259 260func (h *Handler) getRequirement(w http.ResponseWriter, r *http.Request) { 261 id, err := uuid.Parse(chi.URLParam(r, "requirementID")) 262 if err != nil { 263 writeError(w, http.StatusBadRequest, "invalid requirement id") 264 return 265 } 266 rq, err := h.svc.GetRequirement(r.Context(), id) 267 if err != nil { 268 writeServiceError(w, err) 269 return 270 } 271 writeJSON(w, http.StatusOK, requirementListView(rq)) 272} 273 274// ---------- Mission Check (W1) ---------- 275 276type missionCheckOpportunitiesRequest struct { 277 ResumeText string `json:"resume_text"` 278 Limit int `json:"limit"` 279} 280 281func (h *Handler) postMissionCheckOpportunities(w http.ResponseWriter, r *http.Request) { 282 var req missionCheckOpportunitiesRequest 283 if !decodeJSON(w, r, &req) { 284 return 285 } 286 if strings.TrimSpace(req.ResumeText) == "" { 287 writeError(w, http.StatusBadRequest, "resume_text is required") 288 return 289 } 290 out, err := h.svc.MissionCheckOpportunities(r.Context(), req.ResumeText, req.Limit) 291 if err != nil { 292 writeServiceError(w, err) 293 return 294 } 295 writeJSON(w, http.StatusOK, out) 296} 297 298type missionCheckJDRequest struct { 299 ResumeText string `json:"resume_text"` 300 JobDescriptionText string `json:"job_description_text"` 301} 302 303func (h *Handler) postMissionCheckJD(w http.ResponseWriter, r *http.Request) { 304 var req missionCheckJDRequest 305 if !decodeJSON(w, r, &req) { 306 return 307 } 308 if strings.TrimSpace(req.ResumeText) == "" || strings.TrimSpace(req.JobDescriptionText) == "" { 309 writeError(w, http.StatusBadRequest, "resume_text and job_description_text are required") 310 return 311 } 312 out, err := h.svc.MissionCheckJD(r.Context(), req.ResumeText, req.JobDescriptionText) 313 if err != nil { 314 writeServiceError(w, err) 315 return 316 } 317 writeJSON(w, http.StatusOK, out) 318} 319 320type createCandidateRequest struct { 321 FullName string `json:"full_name"` 322 ClearanceLevel string `json:"clearance_level"` 323 ClearancePoly string `json:"clearance_poly"` 324 ClearanceStatus string `json:"clearance_status"` 325 YearsExperience int `json:"years_experience"` 326 Location string `json:"location"` 327 Remote bool `json:"remote"` 328 Relocatable bool `json:"relocatable"` 329 Available bool `json:"available"` 330 Skills []string `json:"skills"` 331 Certifications []string `json:"certifications"` 332 CustomerExperience []string `json:"customer_experience"` 333} 334 335func (h *Handler) postCreateCandidate(w http.ResponseWriter, r *http.Request) { 336 var req createCandidateRequest 337 if !decodeJSON(w, r, &req) { 338 return 339 } 340 if strings.TrimSpace(req.FullName) == "" { 341 writeError(w, http.StatusBadRequest, "full_name is required") 342 return 343 } 344 id, err := h.svc.SaveCandidate(r.Context(), SaveCandidateInput{ 345 FullName: req.FullName, ClearanceLevel: req.ClearanceLevel, ClearancePoly: req.ClearancePoly, 346 ClearanceStatus: req.ClearanceStatus, YearsExperience: req.YearsExperience, Location: req.Location, 347 Remote: req.Remote, Relocatable: req.Relocatable, Available: req.Available, 348 Skills: req.Skills, Certifications: req.Certifications, CustomerExperience: req.CustomerExperience, 349 }) 350 if err != nil { 351 writeServiceError(w, err) 352 return 353 } 354 writeJSON(w, http.StatusCreated, map[string]string{"id": id.String()}) 355} 356 357type setProvenanceRequest struct { 358 Provenance string `json:"provenance"` // self_reported | sponsor_verified | document | continuous_vetting 359 VerifiedAt *string `json:"verified_at,omitempty"` // optional YYYY-MM-DD, the FSO verification date 360} 361 362func (h *Handler) patchClearanceProvenance(w http.ResponseWriter, r *http.Request) { 363 id, err := uuid.Parse(chi.URLParam(r, "candidateID")) 364 if err != nil { 365 writeError(w, http.StatusBadRequest, "invalid candidate id") 366 return 367 } 368 var req setProvenanceRequest 369 if !decodeJSON(w, r, &req) { 370 return 371 } 372 var va *time.Time 373 if req.VerifiedAt != nil && *req.VerifiedAt != "" { 374 t, perr := time.Parse("2006-01-02", *req.VerifiedAt) 375 if perr != nil { 376 writeError(w, http.StatusBadRequest, "verified_at must be YYYY-MM-DD") 377 return 378 } 379 va = &t 380 } 381 if err := h.svc.SetClearanceProvenance(r.Context(), id, req.Provenance, va); err != nil { 382 writeServiceError(w, err) 383 return 384 } 385 writeJSON(w, http.StatusOK, map[string]string{"status": "updated"}) 386} 387 388// ---------- helpers ---------- 389 390func pageParams(r *http.Request) (limit, offset int32) { 391 limit, offset = 50, 0 392 if v, err := strconv.Atoi(r.URL.Query().Get("limit")); err == nil && v > 0 && v <= 500 { 393 limit = int32(v) 394 } 395 if v, err := strconv.Atoi(r.URL.Query().Get("offset")); err == nil && v >= 0 { 396 offset = int32(v) 397 } 398 return limit, offset 399} 400 401func decodeJSON(w http.ResponseWriter, r *http.Request, dst any) bool { 402 dec := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)) 403 dec.DisallowUnknownFields() 404 if err := dec.Decode(dst); err != nil { 405 writeError(w, http.StatusBadRequest, "invalid JSON body: "+err.Error()) 406 return false 407 } 408 return true 409} 410 411func writeJSON(w http.ResponseWriter, status int, v any) { 412 w.Header().Set("Content-Type", "application/json") 413 w.WriteHeader(status) 414 _ = json.NewEncoder(w).Encode(v) 415} 416 417func writeError(w http.ResponseWriter, status int, msg string) { 418 writeJSON(w, status, map[string]string{"error": msg}) 419} 420 421// writeServiceError maps service/tenant errors to HTTP status without leaking internals. 422func writeServiceError(w http.ResponseWriter, err error) { 423 switch { 424 case errors.Is(err, tenant.ErrNoTenant): 425 writeError(w, http.StatusForbidden, "no validated tenant") 426 case errors.Is(err, ErrNotFound): 427 writeError(w, http.StatusNotFound, "not found") 428 case errors.Is(err, ErrBadRequest): 429 writeError(w, http.StatusBadRequest, "bad request") 430 case errors.Is(err, ErrNoDatabase): 431 writeError(w, http.StatusServiceUnavailable, "database not configured") 432 case errors.Is(err, ErrNoExtractor): 433 writeError(w, http.StatusServiceUnavailable, "mission check extraction not configured") 434 default: 435 writeError(w, http.StatusInternalServerError, "internal error") 436 } 437} 438 439// SlateMemberTraceView is the audit and candidate facing explanation of a frozen decision: the per 440// component trace, the human rationale, the gap summary, the decision, and the model version that 441// produced it. The trace and gap summary are passed through as the stored JSON. 442type SlateMemberTraceView struct { 443 CandidateID string `json:"candidate_id"` 444 TotalScore string `json:"total_score"` 445 Band string `json:"band"` 446 Explanation string `json:"explanation"` 447 Trace json.RawMessage `json:"trace"` 448 GapSummary json.RawMessage `json:"gap_summary"` 449 Decision string `json:"decision"` 450 ModelVersion string `json:"model_version"` 451} 452 453func slateMemberTraceView(m dbgen.SlateMember) SlateMemberTraceView { 454 v := SlateMemberTraceView{ 455 CandidateID: m.CandidateID.String(), 456 TotalScore: m.TotalScore.StringFixed(2), 457 Band: m.Band, 458 Explanation: m.Explanation, 459 Trace: json.RawMessage(m.Trace), 460 GapSummary: json.RawMessage(m.GapSummary), 461 Decision: m.Decision, 462 } 463 if m.ModelVersion != nil { 464 v.ModelVersion = *m.ModelVersion 465 } 466 return v 467} 468