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

Source identity

Field	Recorded value
Source type	GitHub source
Original record	Janady13/missionmatch / internal/modules/matching/dto.go
Date	Not specified in source
Repository	Janady13/missionmatch
Revision	720d47fae476b0d38477ae4401697d372b1ea2bc
Branch	feature/opportunity-to-outcome
Path or archive member	internal/modules/matching/dto.go
Original SHA-256	294521d363dbe92b2cdcbacd48bb445bbcf00c0fa373f017cb58422b7be55314
Git blob SHA	11a574338783d4bfe16c6d3e5f8a05e5f23ae2fb
Reading-copy SHA-256	294521d363dbe92b2cdcbacd48bb445bbcf00c0fa373f017cb58422b7be55314
Original source ↗
Every recorded occurrence

These 2 records contain identical original source bytes. Their paths and revisions remain part of the archive.
Original record	Branch or archive	Revision / identifier	Original location
Janady13/missionmatch / internal/modules/matching/dto.go	feature/opportunity-to-outcome	720d47fae476b0d38477ae4401697d372b1ea2bc	Open original
Janady13/missionmatch / internal/modules/matching/dto.go	feature/aioe-upgrade	2178e7298d0e5d9af83afa12402fd587f0ba6ed8	Open original
Recovered source transcript

Download complete source text ↓274 lines · 11.2 KB
package matching

import (
	"time"

	"github.com/google/uuid"

	"github.com/missionworkforce/missionmatch/internal/modules/matching/engine"
	"github.com/missionworkforce/missionmatch/internal/modules/matching/intelligence"
	"github.com/missionworkforce/missionmatch/internal/platform/database/dbgen"
)

// ScreenView is the full screenMATCH™ intelligence output for POST /api/screen: the explainable
// match plus the derived Mission Readiness panels (User Guide + the "Defining" brief).
type ScreenView struct {
	Match             MatchResultView                `json:"match"`
	MissionReadiness  intelligence.MissionReadiness  `json:"mission_readiness"`
	BattleCard        intelligence.BattleCard        `json:"battle_card"`
	ClearanceIntel    intelligence.ClearanceIntel    `json:"clearance_intelligence"`
	ContractReadiness intelligence.ContractReadiness `json:"contract_readiness"`
	WinImpact         intelligence.WinImpact         `json:"win_impact"`
	NextSteps         []intelligence.NextStep        `json:"next_steps"`
}

// RankedCandidateView is one row of the Candidate Screening Queue (Screen 1): a candidate scored
// against a requirement, with the operational Mission Readiness status. Read-only (no slate persisted).
type RankedCandidateView struct {
	CandidateID     uuid.UUID `json:"candidate_id"`
	FullName        string    `json:"full_name"`
	ClearanceLevel  string    `json:"clearance_level"`
	ClearanceStatus string    `json:"clearance_status"`
	YearsExperience int32     `json:"years_experience"`
	Location        string    `json:"location,omitempty"`
	Available       bool      `json:"available"`
	Score           string    `json:"score"`
	Band            string    `json:"band"`
	Status          string    `json:"status"`
}

func rankedCandidateView(c dbgen.Candidate, res engine.MatchResult) RankedCandidateView {
	return RankedCandidateView{
		CandidateID: c.ID, FullName: c.FullName,
		ClearanceLevel: c.ClearanceLevel, ClearanceStatus: c.ClearanceStatus,
		YearsExperience: c.YearsExperience, Location: deref(c.Location), Available: c.Available,
		Score: res.Total.StringFixed(2), Band: res.Band.Code(), Status: intelligence.MissionStatusLabel(res.Band),
	}
}

// OpportunityFitView is one ranked "best opportunity for this person" (Opportunity Fit Engine™).
type OpportunityFitView struct {
	RequirementID  uuid.UUID `json:"requirement_id"`
	Title          string    `json:"title"`
	CustomerAgency string    `json:"customer_agency,omitempty"`
	Score          string    `json:"score"`
	Band           string    `json:"band"`
	Status         string    `json:"status"` // operational status, e.g. "Mission Ready"
}

func assembleScreenView(c engine.Candidate, r engine.Requirement, res engine.MatchResult, facts intelligence.ClearanceFacts, asOf time.Time) ScreenView {
	return ScreenView{
		Match:             matchResultView(res),
		MissionReadiness:  intelligence.Readiness(res),
		BattleCard:        intelligence.BattleCardFor(c, r, res),
		ClearanceIntel:    intelligence.Clearance(facts, asOf),
		ContractReadiness: intelligence.Contract(c, r, res, facts, asOf),
		WinImpact:         intelligence.Win(c, r, res),
		NextSteps:         intelligence.NextSteps(res),
	}
}

// GenerateSlateInput is the validated input to slate generation.
type GenerateSlateInput struct {
	RequirementID uuid.UUID
	Name          string
	CreatedBy     *uuid.UUID
	MaxCandidates int32
}

// ComponentView is one row of the decision trace, JSON-friendly (decimals as fixed strings).
type ComponentView struct {
	Component string `json:"component"`
	Weight    string `json:"weight"`
	Raw       string `json:"raw"`
	Weighted  string `json:"weighted"`
	Rationale string `json:"rationale"`
}

// MatchedSkillView is one required->candidate skill resolution.
type MatchedSkillView struct {
	RequiredSkill  string `json:"required_skill"`
	CandidateSkill string `json:"candidate_skill,omitempty"`
	Similarity     string `json:"similarity"`
	Exact          bool   `json:"exact"`
	Matched        bool   `json:"matched"`
}

// MatchResultView is the full, explainable result for POST /match (screenMATCH).
type MatchResultView struct {
	CandidateID   string             `json:"candidate_id"`
	RequirementID string             `json:"requirement_id"`
	Total         string             `json:"total_score"`
	Band          string             `json:"band"`
	BandLabel     string             `json:"band_label"`
	Components    map[string]string  `json:"components"`
	Explanation   string             `json:"explanation"`
	GapSummary    []string           `json:"gap_summary"`
	MatchedSkills []MatchedSkillView `json:"matched_skills"`
	Trace         []ComponentView    `json:"trace"`
	// WeightProfileVersion names the weight set that produced this score (AEDT explainability):
	// the tenant AIOE profile, or the global default.
	WeightProfileVersion string `json:"weight_profile_version"`
}

// SlateMemberView is one ranked member of a generated slate.
type SlateMemberView struct {
	CandidateID string   `json:"candidate_id"`
	Rank        int      `json:"rank"`
	Total       string   `json:"total_score"`
	Band        string   `json:"band"`
	BandLabel   string   `json:"band_label"`
	Explanation string   `json:"explanation"`
	GapSummary  []string `json:"gap_summary"`
}

// SlateResult is the output of POST /slates/generate (slateMATCH).
type SlateResult struct {
	SlateID       uuid.UUID         `json:"slate_id"`
	RequirementID uuid.UUID         `json:"requirement_id"`
	Name          string            `json:"name"`
	Members       []SlateMemberView `json:"members"`
}

// SlateSummaryView is one row of the slate list for a requirement (slateMATCH list).
type SlateSummaryView struct {
	SlateID     string `json:"slate_id"`
	Name        string `json:"name"`
	Status      string `json:"status"`
	MemberCount int    `json:"member_count"`
	CreatedAt   string `json:"created_at"`
}

// SlateMemberDetailView is one member on the slate detail: the frozen score and band read from the
// persisted slate (never recomputed), the human decision, the reviewer note, and the candidate name.
type SlateMemberDetailView struct {
	CandidateID  string            `json:"candidate_id"`
	FullName     string            `json:"full_name"`
	Rank         int               `json:"rank"`
	Total        string            `json:"total_score"`
	Band         string            `json:"band"`
	BandLabel    string            `json:"band_label"`
	Components   map[string]string `json:"components"`
	Explanation  string            `json:"explanation"`
	GapSummary   []string          `json:"gap_summary"`
	Decision     string            `json:"decision"`
	DecisionNote string            `json:"decision_note"`
}

// SlateDetailView is a slate with its ranked members and the proposal readiness rollup, all read from
// the stored slate.
type SlateDetailView struct {
	SlateID          string                  `json:"slate_id"`
	RequirementID    string                  `json:"requirement_id"`
	RequirementTitle string                  `json:"requirement_title"`
	Name             string                  `json:"name"`
	Status           string                  `json:"status"`
	Members          []SlateMemberDetailView `json:"members"`
	Readiness        ProposalReadinessView   `json:"readiness"`
}

// ProposalReadinessView is the rollup of a slate's persisted members and their human decisions
// (GET /proposal-readiness). It is computed from the stored slate, never by rescoring candidates, so
// it always agrees with the frozen member scores.
type ProposalReadinessView struct {
	SlateID       string `json:"slate_id"`
	RequirementID string `json:"requirement_id"`
	TotalMembers  int    `json:"total_members"`
	Approved      int    `json:"approved"`
	Rejected      int    `json:"rejected"`
	Pending       int    `json:"pending"`
	ProposalReady int    `json:"proposal_ready"` // members in the Green band
	Potential     int    `json:"potential"`      // members in the Yellow band
	Recruiting    int    `json:"recruiting"`     // members in the Red band
	ApprovedReady int    `json:"approved_ready"` // approved AND Green
	ReadinessPct  string `json:"readiness_pct"`  // approved divided by total, as a percent (decimal)
	Status        string `json:"status"`         // overall label
}

// CandidateListView / RequirementListView are minimal list projections (no embeddings/tsv).
type CandidateListView struct {
	ID              uuid.UUID `json:"id"`
	FullName        string    `json:"full_name"`
	ClearanceLevel  string    `json:"clearance_level"`
	ClearanceStatus string    `json:"clearance_status"`
	YearsExperience int32     `json:"years_experience"`
	Location        string    `json:"location,omitempty"`
	Available       bool      `json:"available"`
}

type RequirementListView struct {
	ID             uuid.UUID `json:"id"`
	Title          string    `json:"title"`
	RequiredLevel  string    `json:"required_level"`
	CustomerAgency string    `json:"customer_agency,omitempty"`
	KeyPersonnel   bool      `json:"key_personnel"`
}

func matchResultView(res engine.MatchResult) MatchResultView {
	trace := make([]ComponentView, len(res.Trace))
	for i, c := range res.Trace {
		trace[i] = ComponentView{
			Component: c.Component, Weight: c.Weight.String(),
			Raw: c.Raw.StringFixed(2), Weighted: c.Weighted.StringFixed(4), Rationale: c.Rationale,
		}
	}
	ms := make([]MatchedSkillView, len(res.MatchedSkills))
	for i, m := range res.MatchedSkills {
		ms[i] = MatchedSkillView{
			RequiredSkill: m.RequiredSkillName, CandidateSkill: m.CandidateName,
			Similarity: m.Similarity.StringFixed(4), Exact: m.Exact, Matched: m.Matched,
		}
	}
	return MatchResultView{
		CandidateID: res.CandidateID, RequirementID: res.RequirementID,
		Total: res.Total.StringFixed(2), Band: res.Band.Code(), BandLabel: res.Band.Label(),
		Components: map[string]string{
			"clearance":             res.Clearance.StringFixed(2),
			"skills":                res.Skills.StringFixed(2),
			"certifications":        res.Certifications.StringFixed(2),
			"customer_experience":   res.CustomerExperience.StringFixed(2),
			"experience":            res.Experience.StringFixed(2),
			"location_availability": res.Location.StringFixed(2),
		},
		Explanation: res.Explanation, GapSummary: nonNilStrings(res.GapSummary),
		MatchedSkills: ms, Trace: trace,
		WeightProfileVersion: profileLabelOrDefault(res.WeightProfileVersion),
	}
}

func profileLabelOrDefault(v string) string {
	if v == "" {
		return engine.GlobalDefaultProfileVersion
	}
	return v
}

func slateMemberView(candidateID string, rank int, res engine.MatchResult) SlateMemberView {
	return SlateMemberView{
		CandidateID: candidateID, Rank: rank,
		Total: res.Total.StringFixed(2), Band: res.Band.Code(), BandLabel: res.Band.Label(),
		Explanation: res.Explanation, GapSummary: nonNilStrings(res.GapSummary),
	}
}

func candidateListView(c dbgen.Candidate) CandidateListView {
	return CandidateListView{
		ID: c.ID, FullName: c.FullName, ClearanceLevel: c.ClearanceLevel, ClearanceStatus: c.ClearanceStatus,
		YearsExperience: c.YearsExperience, Location: deref(c.Location), Available: c.Available,
	}
}

func requirementListView(r dbgen.Requirement) RequirementListView {
	return RequirementListView{
		ID: r.ID, Title: r.Title, RequiredLevel: r.RequiredLevel,
		CustomerAgency: deref(r.CustomerAgency), KeyPersonnel: r.KeyPersonnel,
	}
}

func nonNilStrings(s []string) []string {
	if s == nil {
		return []string{}
	}
	return s
}