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 EVERY matching endpoint on r at its flat path (already wrapped by the session 26// resolver). It is the alias surface: it keeps the pre split paths (POST /match, /slates/..., etc.) 27// working unchanged while the three tool routers mount the same handlers under their namespaces. It is 28// the sum of the four tool route groups below, so a path appears in exactly one group and the flat and 29// namespaced mounts share one handler. Every person scoring surface is an AEDT output and carries a 30// capability check, so authorization is enforced at the API from the validated session, never hidden 31// in the UI. Scoring and ranking need search.run; the slate write and the human decision need 32// slate.write; reads need candidate.read. 33func (h *Handler) Routes(r chi.Router) { 34 h.ScreenRoutes(r) 35 h.SlateRoutes(r) 36 h.ReadRoutes(r) 37 h.IntelRoutes(r) 38 h.MissionRoutes(r) 39} 40 41// ScreenRoutes are the screenMATCH endpoints: single candidate qualification, the pool ranked against 42// one requirement, the Opportunity Fit for one candidate, the Mission Check resume flow, and the 43// candidate writes that flow saves. POST /match is the original alias of POST /screen's raw result. 44func (h *Handler) ScreenRoutes(r chi.Router) { 45 r.With(security.RequireCapability(security.CapSearchRun)).Post("/match", h.postMatch) 46 r.With(security.RequireCapability(security.CapSearchRun)).Post("/screen", h.postScreen) 47 r.With(security.RequireCapability(security.CapSearchRun)).Get("/requirements/{requirementID}/candidates", h.getRankedCandidates) 48 r.With(security.RequireCapability(security.CapSearchRun)).Get("/candidates/{candidateID}/opportunities", h.getOpportunities) 49 // Mission Check (W1): scoring an in memory resume is a search.run AEDT output; the optional Save 50 // Candidate is a recruiter write. Both ride the same session auth, RBAC, and audit as every surface. 51 r.With(security.RequireCapability(security.CapSearchRun)).Post("/mission-check/opportunities", h.postMissionCheckOpportunities) 52 r.With(security.RequireCapability(security.CapSearchRun)).Post("/mission-check/screen", h.postMissionCheckJD) 53 r.With(security.RequireCapability(security.CapCandidateWrite)).Post("/candidates", h.postCreateCandidate) 54 r.With(security.RequireCapability(security.CapCandidateWrite)).Patch("/candidates/{candidateID}/clearance-provenance", h.patchClearanceProvenance) 55} 56 57// SlateRoutes are the slateMATCH endpoints: generate a slate, the human approve or reject of a member, 58// and the frozen decision trace for a member. 59func (h *Handler) SlateRoutes(r chi.Router) { 60 r.With(security.RequireCapability(security.CapSlateEdit)).Post("/slates/generate", h.postGenerate) 61 r.With(security.RequireCapability(security.CapSlateEdit)).Patch("/slates/{slateID}/members/{candidateID}/decision", h.postDecision) 62 r.With(security.RequireCapability(security.CapCandidateRead)).Get("/slates/{slateID}/members/{candidateID}/trace", h.getTrace) 63 r.With(security.RequireCapability(security.CapCandidateRead)).Get("/requirements/{requirementID}/slates", h.getSlates) 64 r.With(security.RequireCapability(security.CapCandidateRead)).Get("/slates/{slateID}", h.getSlateDetail) 65 r.With(security.RequireCapability(security.CapCandidateRead)).Get("/slates/{slateID}/proposal-readiness", h.getProposalReadiness) 66 // The branded CSV is a bulk egress of candidate PII, so it needs export.run (owner, admin, recruiter), 67 // not the read capability every role holds. The egress is also recorded in the audit (ExportSlate). 68 r.With(security.RequireCapability(security.CapExportRun)).Get("/slates/{slateID}/export", h.exportSlate) 69} 70 71// ReadRoutes are the shared candidate and requirement pickers every tool needs to choose a target. 72func (h *Handler) ReadRoutes(r chi.Router) { 73 r.With(security.RequireCapability(security.CapCandidateRead)).Get("/candidates", h.getCandidates) 74 r.With(security.RequireCapability(security.CapCandidateRead)).Get("/candidates/{candidateID}", h.getCandidate) 75 r.With(security.RequireCapability(security.CapCandidateRead)).Get("/requirements", h.getRequirements) 76 r.With(security.RequireCapability(security.CapCandidateRead)).Get("/requirements/{requirementID}", h.getRequirement) 77} 78 79// IntelRoutes is the missionMATCH Candidates Intelligence View (the whole pool scored once, a 80// screening stage AEDT output, so it needs search.run). 81func (h *Handler) IntelRoutes(r chi.Router) { 82 r.With(security.RequireCapability(security.CapSearchRun)).Get("/candidates/intelligence", h.getCandidateIntelligence) 83} 84 85// MissionRoutes are the missionMATCH reads that consume the stored artifacts: who can support a mission 86// today, read from the persisted screenMATCH evaluations (never a rescore). It surfaces frozen scores, 87// so it needs search.run like the other AEDT read surfaces. 88func (h *Handler) MissionRoutes(r chi.Router) { 89 r.With(security.RequireCapability(security.CapSearchRun)).Get("/requirements/{requirementID}/support", h.getWhoCanSupport) 90} 91 92type matchRequest struct { 93 CandidateID uuid.UUID `json:"candidate_id"` 94 RequirementID uuid.UUID `json:"requirement_id"` 95} 96 97func (h *Handler) postMatch(w http.ResponseWriter, r *http.Request) { 98 var req matchRequest 99 if !decodeJSON(w, r, &req) { 100 return 101 } 102 if req.CandidateID == uuid.Nil || req.RequirementID == uuid.Nil { 103 writeError(w, http.StatusBadRequest, "candidate_id and requirement_id are required") 104 return 105 } 106 res, err := h.svc.ScreenCandidate(r.Context(), req.CandidateID, req.RequirementID) 107 if err != nil { 108 writeServiceError(w, err) 109 return 110 } 111 writeJSON(w, http.StatusOK, matchResultView(res)) 112} 113 114func (h *Handler) postScreen(w http.ResponseWriter, r *http.Request) { 115 var req matchRequest 116 if !decodeJSON(w, r, &req) { 117 return 118 } 119 if req.CandidateID == uuid.Nil || req.RequirementID == uuid.Nil { 120 writeError(w, http.StatusBadRequest, "candidate_id and requirement_id are required") 121 return 122 } 123 view, err := h.svc.Screen(r.Context(), req.CandidateID, req.RequirementID) 124 if err != nil { 125 writeServiceError(w, err) 126 return 127 } 128 writeJSON(w, http.StatusOK, view) 129} 130 131func (h *Handler) getRankedCandidates(w http.ResponseWriter, r *http.Request) { 132 reqID, err := uuid.Parse(chi.URLParam(r, "requirementID")) 133 if err != nil { 134 writeError(w, http.StatusBadRequest, "invalid requirement id") 135 return 136 } 137 out, err := h.svc.RankCandidates(r.Context(), reqID) 138 if err != nil { 139 writeServiceError(w, err) 140 return 141 } 142 writeJSON(w, http.StatusOK, out) 143} 144 145func (h *Handler) getOpportunities(w http.ResponseWriter, r *http.Request) { 146 candidateID, err := uuid.Parse(chi.URLParam(r, "candidateID")) 147 if err != nil { 148 writeError(w, http.StatusBadRequest, "invalid candidate id") 149 return 150 } 151 limit := 10 152 if v, err := strconv.Atoi(r.URL.Query().Get("limit")); err == nil && v > 0 && v <= 100 { 153 limit = v 154 } 155 fits, err := h.svc.OpportunitiesForCandidate(r.Context(), candidateID, limit) 156 if err != nil { 157 writeServiceError(w, err) 158 return 159 } 160 writeJSON(w, http.StatusOK, fits) 161} 162 163type generateRequest struct { 164 RequirementID uuid.UUID `json:"requirement_id"` 165 Name string `json:"name"` 166 MaxCandidates int32 `json:"max_candidates"` 167} 168 169func (h *Handler) postGenerate(w http.ResponseWriter, r *http.Request) { 170 var req generateRequest 171 if !decodeJSON(w, r, &req) { 172 return 173 } 174 if req.RequirementID == uuid.Nil { 175 writeError(w, http.StatusBadRequest, "requirement_id is required") 176 return 177 } 178 out, err := h.svc.GenerateSlate(r.Context(), GenerateSlateInput{ 179 RequirementID: req.RequirementID, Name: req.Name, MaxCandidates: req.MaxCandidates, 180 CreatedBy: principalID(r), 181 }) 182 if err != nil { 183 writeServiceError(w, err) 184 return 185 } 186 writeJSON(w, http.StatusCreated, out) 187} 188 189type decisionRequest struct { 190 Decision string `json:"decision"` // approved or rejected 191 Note string `json:"note,omitempty"` // optional reviewer note 192} 193 194func (h *Handler) postDecision(w http.ResponseWriter, r *http.Request) { 195 slateID, err := uuid.Parse(chi.URLParam(r, "slateID")) 196 if err != nil { 197 writeError(w, http.StatusBadRequest, "invalid slate id") 198 return 199 } 200 candidateID, err := uuid.Parse(chi.URLParam(r, "candidateID")) 201 if err != nil { 202 writeError(w, http.StatusBadRequest, "invalid candidate id") 203 return 204 } 205 var req decisionRequest 206 if !decodeJSON(w, r, &req) { 207 return 208 } 209 if err := h.svc.DecideSlateMember(r.Context(), slateID, candidateID, req.Decision, req.Note); err != nil { 210 writeServiceError(w, err) 211 return 212 } 213 writeJSON(w, http.StatusOK, map[string]string{"status": req.Decision}) 214} 215 216func (h *Handler) getTrace(w http.ResponseWriter, r *http.Request) { 217 slateID, err := uuid.Parse(chi.URLParam(r, "slateID")) 218 if err != nil { 219 writeError(w, http.StatusBadRequest, "invalid slate id") 220 return 221 } 222 candidateID, err := uuid.Parse(chi.URLParam(r, "candidateID")) 223 if err != nil { 224 writeError(w, http.StatusBadRequest, "invalid candidate id") 225 return 226 } 227 m, err := h.svc.SlateMemberTrace(r.Context(), slateID, candidateID) 228 if err != nil { 229 writeServiceError(w, err) 230 return 231 } 232 writeJSON(w, http.StatusOK, slateMemberTraceView(m)) 233} 234 235func (h *Handler) getSlates(w http.ResponseWriter, r *http.Request) { 236 reqID, err := uuid.Parse(chi.URLParam(r, "requirementID")) 237 if err != nil { 238 writeError(w, http.StatusBadRequest, "invalid requirement id") 239 return 240 } 241 out, err := h.svc.ListSlates(r.Context(), reqID) 242 if err != nil { 243 writeServiceError(w, err) 244 return 245 } 246 if out == nil { 247 out = []SlateSummaryView{} 248 } 249 writeJSON(w, http.StatusOK, out) 250} 251 252func (h *Handler) getSlateDetail(w http.ResponseWriter, r *http.Request) { 253 slateID, err := uuid.Parse(chi.URLParam(r, "slateID")) 254 if err != nil { 255 writeError(w, http.StatusBadRequest, "invalid slate id") 256 return 257 } 258 out, err := h.svc.SlateDetail(r.Context(), slateID) 259 if err != nil { 260 writeServiceError(w, err) 261 return 262 } 263 writeJSON(w, http.StatusOK, out) 264} 265 266func (h *Handler) getProposalReadiness(w http.ResponseWriter, r *http.Request) { 267 slateID, err := uuid.Parse(chi.URLParam(r, "slateID")) 268 if err != nil { 269 writeError(w, http.StatusBadRequest, "invalid slate id") 270 return 271 } 272 out, err := h.svc.ProposalReadiness(r.Context(), slateID) 273 if err != nil { 274 writeServiceError(w, err) 275 return 276 } 277 writeJSON(w, http.StatusOK, out) 278} 279 280func (h *Handler) exportSlate(w http.ResponseWriter, r *http.Request) { 281 slateID, err := uuid.Parse(chi.URLParam(r, "slateID")) 282 if err != nil { 283 writeError(w, http.StatusBadRequest, "invalid slate id") 284 return 285 } 286 csvText, err := h.svc.ExportSlate(r.Context(), slateID) 287 if err != nil { 288 writeServiceError(w, err) 289 return 290 } 291 w.Header().Set("Content-Type", "text/csv; charset=utf-8") 292 w.Header().Set("Content-Disposition", "attachment; filename=\"slate-"+slateID.String()+".csv\"") 293 w.WriteHeader(http.StatusOK) 294 _, _ = w.Write([]byte(csvText)) 295} 296 297func (h *Handler) getWhoCanSupport(w http.ResponseWriter, r *http.Request) { 298 reqID, err := uuid.Parse(chi.URLParam(r, "requirementID")) 299 if err != nil { 300 writeError(w, http.StatusBadRequest, "invalid requirement id") 301 return 302 } 303 out, err := h.svc.WhoCanSupport(r.Context(), reqID) 304 if err != nil { 305 writeServiceError(w, err) 306 return 307 } 308 if out == nil { 309 out = []SupportView{} 310 } 311 writeJSON(w, http.StatusOK, out) 312} 313 314// principalID returns the validated session user id for the actor on a decision or generation. 315func principalID(r *http.Request) *uuid.UUID { 316 if p, ok := tenant.UserFromContext(r.Context()); ok { 317 if id, err := uuid.Parse(p.UserID); err == nil { 318 return &id 319 } 320 } 321 return nil 322} 323 324func (h *Handler) getCandidateIntelligence(w http.ResponseWriter, r *http.Request) { 325 limit := 0 326 if v, err := strconv.Atoi(r.URL.Query().Get("limit")); err == nil { 327 limit = v 328 } 329 out, err := h.svc.CandidateIntelligence(r.Context(), limit) 330 if err != nil { 331 writeServiceError(w, err) 332 return 333 } 334 if out == nil { 335 out = []CandidateIntelligenceView{} 336 } 337 writeJSON(w, http.StatusOK, out) 338} 339 340func (h *Handler) getCandidates(w http.ResponseWriter, r *http.Request) { 341 limit, offset := pageParams(r) 342 rows, err := h.svc.ListCandidates(r.Context(), limit, offset) 343 if err != nil { 344 writeServiceError(w, err) 345 return 346 } 347 out := make([]CandidateListView, len(rows)) 348 for i, c := range rows { 349 out[i] = candidateListView(c) 350 } 351 writeJSON(w, http.StatusOK, out) 352} 353 354func (h *Handler) getRequirements(w http.ResponseWriter, r *http.Request) { 355 limit, offset := pageParams(r) 356 rows, err := h.svc.ListRequirements(r.Context(), limit, offset) 357 if err != nil { 358 writeServiceError(w, err) 359 return 360 } 361 out := make([]RequirementListView, len(rows)) 362 for i, rq := range rows { 363 out[i] = requirementListView(rq) 364 } 365 writeJSON(w, http.StatusOK, out) 366} 367 368func (h *Handler) getCandidate(w http.ResponseWriter, r *http.Request) { 369 id, err := uuid.Parse(chi.URLParam(r, "candidateID")) 370 if err != nil { 371 writeError(w, http.StatusBadRequest, "invalid candidate id") 372 return 373 } 374 c, err := h.svc.GetCandidate(r.Context(), id) 375 if err != nil { 376 writeServiceError(w, err) 377 return 378 } 379 writeJSON(w, http.StatusOK, candidateListView(c)) 380} 381 382func (h *Handler) getRequirement(w http.ResponseWriter, r *http.Request) { 383 id, err := uuid.Parse(chi.URLParam(r, "requirementID")) 384 if err != nil { 385 writeError(w, http.StatusBadRequest, "invalid requirement id") 386 return 387 } 388 rq, err := h.svc.GetRequirement(r.Context(), id) 389 if err != nil { 390 writeServiceError(w, err) 391 return 392 } 393 writeJSON(w, http.StatusOK, requirementListView(rq)) 394} 395 396// ---------- Mission Check (W1) ---------- 397 398type missionCheckOpportunitiesRequest struct { 399 ResumeText string `json:"resume_text"` 400 Limit int `json:"limit"` 401} 402 403func (h *Handler) postMissionCheckOpportunities(w http.ResponseWriter, r *http.Request) { 404 var req missionCheckOpportunitiesRequest 405 if !decodeJSON(w, r, &req) { 406 return 407 } 408 if strings.TrimSpace(req.ResumeText) == "" { 409 writeError(w, http.StatusBadRequest, "resume_text is required") 410 return 411 } 412 out, err := h.svc.MissionCheckOpportunities(r.Context(), req.ResumeText, req.Limit) 413 if err != nil { 414 writeServiceError(w, err) 415 return 416 } 417 writeJSON(w, http.StatusOK, out) 418} 419 420type missionCheckJDRequest struct { 421 ResumeText string `json:"resume_text"` 422 JobDescriptionText string `json:"job_description_text"` 423} 424 425func (h *Handler) postMissionCheckJD(w http.ResponseWriter, r *http.Request) { 426 var req missionCheckJDRequest 427 if !decodeJSON(w, r, &req) { 428 return 429 } 430 if strings.TrimSpace(req.ResumeText) == "" || strings.TrimSpace(req.JobDescriptionText) == "" { 431 writeError(w, http.StatusBadRequest, "resume_text and job_description_text are required") 432 return 433 } 434 out, err := h.svc.MissionCheckJD(r.Context(), req.ResumeText, req.JobDescriptionText) 435 if err != nil { 436 writeServiceError(w, err) 437 return 438 } 439 writeJSON(w, http.StatusOK, out) 440} 441 442type createCandidateRequest struct { 443 FullName string `json:"full_name"` 444 ClearanceLevel string `json:"clearance_level"` 445 ClearancePoly string `json:"clearance_poly"` 446 ClearanceStatus string `json:"clearance_status"` 447 YearsExperience int `json:"years_experience"` 448 Location string `json:"location"` 449 Remote bool `json:"remote"` 450 Relocatable bool `json:"relocatable"` 451 Available bool `json:"available"` 452 Skills []string `json:"skills"` 453 Certifications []string `json:"certifications"` 454 CustomerExperience []string `json:"customer_experience"` 455} 456 457func (h *Handler) postCreateCandidate(w http.ResponseWriter, r *http.Request) { 458 var req createCandidateRequest 459 if !decodeJSON(w, r, &req) { 460 return 461 } 462 if strings.TrimSpace(req.FullName) == "" { 463 writeError(w, http.StatusBadRequest, "full_name is required") 464 return 465 } 466 id, err := h.svc.SaveCandidate(r.Context(), SaveCandidateInput(req)) 467 if err != nil { 468 writeServiceError(w, err) 469 return 470 } 471 writeJSON(w, http.StatusCreated, map[string]string{"id": id.String()}) 472} 473 474type setProvenanceRequest struct { 475 Provenance string `json:"provenance"` // self_reported | sponsor_verified | document | continuous_vetting 476 VerifiedAt *string `json:"verified_at,omitempty"` // optional YYYY-MM-DD, the FSO verification date 477} 478 479func (h *Handler) patchClearanceProvenance(w http.ResponseWriter, r *http.Request) { 480 id, err := uuid.Parse(chi.URLParam(r, "candidateID")) 481 if err != nil { 482 writeError(w, http.StatusBadRequest, "invalid candidate id") 483 return 484 } 485 var req setProvenanceRequest 486 if !decodeJSON(w, r, &req) { 487 return 488 } 489 var va *time.Time 490 if req.VerifiedAt != nil && *req.VerifiedAt != "" { 491 t, perr := time.Parse("2006-01-02", *req.VerifiedAt) 492 if perr != nil { 493 writeError(w, http.StatusBadRequest, "verified_at must be YYYY-MM-DD") 494 return 495 } 496 va = &t 497 } 498 if err := h.svc.SetClearanceProvenance(r.Context(), id, req.Provenance, va); err != nil { 499 writeServiceError(w, err) 500 return 501 } 502 writeJSON(w, http.StatusOK, map[string]string{"status": "updated"}) 503} 504 505// ---------- helpers ---------- 506 507func pageParams(r *http.Request) (limit, offset int32) { 508 limit, offset = 50, 0 509 if v, err := strconv.Atoi(r.URL.Query().Get("limit")); err == nil && v > 0 && v <= 500 { 510 limit = int32(v) 511 } 512 if v, err := strconv.Atoi(r.URL.Query().Get("offset")); err == nil && v >= 0 { 513 offset = int32(v) 514 } 515 return limit, offset 516} 517 518func decodeJSON(w http.ResponseWriter, r *http.Request, dst any) bool { 519 dec := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20)) 520 dec.DisallowUnknownFields() 521 if err := dec.Decode(dst); err != nil { 522 writeError(w, http.StatusBadRequest, "invalid JSON body: "+err.Error()) 523 return false 524 } 525 return true 526} 527 528func writeJSON(w http.ResponseWriter, status int, v any) { 529 w.Header().Set("Content-Type", "application/json") 530 w.WriteHeader(status) 531 _ = json.NewEncoder(w).Encode(v) 532} 533 534func writeError(w http.ResponseWriter, status int, msg string) { 535 writeJSON(w, status, map[string]string{"error": msg}) 536} 537 538// writeServiceError maps service/tenant errors to HTTP status without leaking internals. 539func writeServiceError(w http.ResponseWriter, err error) { 540 switch { 541 case errors.Is(err, tenant.ErrNoTenant): 542 writeError(w, http.StatusForbidden, "no validated tenant") 543 case errors.Is(err, ErrNotFound): 544 writeError(w, http.StatusNotFound, "not found") 545 case errors.Is(err, ErrBadRequest): 546 writeError(w, http.StatusBadRequest, "bad request") 547 case errors.Is(err, ErrNoDatabase): 548 writeError(w, http.StatusServiceUnavailable, "database not configured") 549 case errors.Is(err, ErrNoExtractor): 550 writeError(w, http.StatusServiceUnavailable, "mission check extraction not configured") 551 default: 552 writeError(w, http.StatusInternalServerError, "internal error") 553 } 554} 555 556// SlateMemberTraceView is the audit and candidate facing explanation of a frozen decision: the per 557// component trace, the human rationale, the gap summary, the decision, and the model version that 558// produced it. The trace and gap summary are passed through as the stored JSON. 559type SlateMemberTraceView struct { 560 CandidateID string `json:"candidate_id"` 561 TotalScore string `json:"total_score"` 562 Band string `json:"band"` 563 Explanation string `json:"explanation"` 564 Trace json.RawMessage `json:"trace"` 565 GapSummary json.RawMessage `json:"gap_summary"` 566 Decision string `json:"decision"` 567 ModelVersion string `json:"model_version"` 568} 569 570func slateMemberTraceView(m dbgen.SlateMember) SlateMemberTraceView { 571 v := SlateMemberTraceView{ 572 CandidateID: m.CandidateID.String(), 573 TotalScore: m.TotalScore.StringFixed(2), 574 Band: m.Band, 575 Explanation: m.Explanation, 576 Trace: json.RawMessage(m.Trace), 577 GapSummary: json.RawMessage(m.GapSummary), 578 Decision: m.Decision, 579 } 580 if m.ModelVersion != nil { 581 v.ModelVersion = *m.ModelVersion 582 } 583 return v 584} 585