Janady13/missionmatch / internal/modules/recruiting/placement_math.go

1package recruiting 2 3import ( 4 "time" 5 6 "github.com/shopspring/decimal" 7) 8 9// Money arithmetic for offers and placements. 10// 11// Every figure here is exact decimal on values that arrived from Postgres numeric as text. None of it 12// touches float64. A bill rate is multiplied by hours and by a wrap rate downstream, and binary floating 13// point cannot represent 0.1, so a margin computed through a float would not reconcile with an invoice. 14// 15// What this file deliberately does NOT compute is projected revenue. Annualising an hourly rate requires 16// assuming a full time, full year assignment that nobody has agreed to, and a number like that is 17// indistinguishable on a screen from one that was actually contracted. Only quantities that follow from 18// recorded facts appear here. 19 20var ( 21 offerStatuses = map[string]bool{ 22 "extended": true, "accepted": true, "declined": true, "rescinded": true, "expired": true, 23 } 24 placementStatuses = map[string]bool{ 25 "pending_start": true, "active": true, "completed": true, "terminated": true, "fell_off": true, 26 } 27 interviewKinds = map[string]bool{ 28 "phone_screen": true, "technical": true, "client": true, "panel": true, "final": true, 29 } 30 interviewOutcomes = map[string]bool{ 31 "scheduled": true, "passed": true, "failed": true, "no_show": true, "cancelled": true, "rescheduled": true, 32 } 33) 34 35// offerTransitions mirrors rm_offer_transition in migration 0055. The database is the authority; this 36// exists so the interface can offer only the moves that will be accepted. 37var offerTransitions = map[string][]string{ 38 "extended": {"accepted", "declined", "rescinded", "expired"}, 39 "accepted": {"rescinded"}, 40 // declined and expired are terminal. Re offering is a NEW offer so the history keeps both. 41 "declined": {}, 42 "rescinded": {}, 43 "expired": {}, 44} 45 46func offerCanMove(from, to string) bool { 47 for _, t := range offerTransitions[from] { 48 if t == to { 49 return true 50 } 51 } 52 return false 53} 54 55// placementEnded reports whether a status closes an assignment. An ended placement must carry an end 56// date, which the database enforces, and stops being counted as live. 57func placementEnded(status string) bool { 58 return status == "completed" || status == "terminated" || status == "fell_off" 59} 60 61// Margin is the economics of one placement or offer, all exact. 62type Margin struct { 63 // GrossPerHour is bill minus pay. Present only for rate priced work. 64 GrossPerHour *decimal.Decimal `json:"gross_per_hour,omitempty"` 65 // Pct is gross as a share of bill, to four places. Absent when the bill rate is zero, because a 66 // share of nothing is undefined rather than zero, and rendering 0.00 would read as a real margin of 67 // nothing rather than as an unanswerable question. 68 Pct *decimal.Decimal `json:"margin_pct,omitempty"` 69 // Fee is the direct hire fee: an explicit amount when one was agreed, otherwise salary times the 70 // percentage. Present only for direct hire. 71 Fee *decimal.Decimal `json:"fee,omitempty"` 72} 73 74// marginOf computes the economics from whichever pricing shape applies. 75// 76// The two shapes are never blended. A contract placement earns a spread per hour and a direct hire earns 77// a one time fee, and averaging them or summing them into one revenue number produces a figure that 78// describes neither. Migration 0048 already requires the right columns per employment type, so this 79// reads whichever pair is populated rather than guessing. 80func marginOf(employmentType string, bill, pay, salary, feePct, feeAmount *decimal.Decimal) Margin { 81 var m Margin 82 if employmentType == "direct_hire" { 83 switch { 84 case feeAmount != nil: 85 f := *feeAmount 86 m.Fee = &f 87 case salary != nil && feePct != nil: 88 // fee_pct is stored as a fraction (0 to 1), so 0.20 of a 150000 salary is 30000. 89 f := salary.Mul(*feePct).Round(2) 90 m.Fee = &f 91 } 92 return m 93 } 94 if bill == nil || pay == nil { 95 return m 96 } 97 g := bill.Sub(*pay) 98 m.GrossPerHour = &g 99 if bill.IsZero() { 100 // Undefined, not zero. Returning nil is what stops a divide by zero and what stops a screen 101 // claiming a zero percent margin on a rate nobody set. 102 return m 103 } 104 p := g.Div(*bill).Mul(decimal.NewFromInt(100)).Round(4) 105 m.Pct = &p 106 return m 107} 108 109// Guarantee is the clawback position on a placement. 110// 111// A staffing guarantee means that if the person leaves within N days of starting, the fee is returned or 112// the seat is refilled free. It is the single largest correction to reported revenue in this industry, so 113// it is computed from recorded dates rather than tracked by hand. 114type Guarantee struct { 115 Days int `json:"days"` 116 // EndsOn is the last day covered. Inclusive: a 90 day guarantee on a placement starting the 1st 117 // covers through day 90, so the boundary case is a real day and not an off by one. 118 EndsOn string `json:"ends_on,omitempty"` 119 // DaysRemaining is negative once the guarantee has run out. Absent for an ended placement, where the 120 // question is no longer about time remaining but about whether it fell inside. 121 DaysRemaining *int `json:"days_remaining,omitempty"` 122 // Breached is true when the assignment ended inside the guarantee window in a way that triggers it. 123 // A completed assignment never breaches, however short: completing early is the client's call. 124 Breached bool `json:"breached"` 125} 126 127// guaranteeOf computes the clawback position. 128// 129// Only fell_off and terminated breach. completed does not, because an assignment that ran its course is 130// not a failure to deliver, and counting it as one would understate a recruiter's performance for work 131// the client ended on its own terms. 132func guaranteeOf(days int, start time.Time, end *time.Time, status string, today time.Time) Guarantee { 133 g := Guarantee{Days: days} 134 if days <= 0 { 135 return g 136 } 137 // Inclusive of the start day: a 90 day guarantee starting on the 1st ends on day 90, which is 138 // start + 89 days, not start + 90. 139 endsOn := start.AddDate(0, 0, days-1) 140 g.EndsOn = endsOn.Format(dateLayout) 141 142 if end != nil { 143 if (status == "fell_off" || status == "terminated") && !end.After(endsOn) { 144 g.Breached = true 145 } 146 return g 147 } 148 rem := int(endsOn.Sub(today).Hours() / 24) 149 g.DaysRemaining = &rem 150 return g 151} 152 153// interviewRoundOK bounds the round number against the CHECK in migration 0048. 154func interviewRoundOK(r int) bool { return r >= 1 && r <= 20 } 155 156// interviewConcluded reports whether an outcome requires a completed_at, mirroring interviews_completed_chk. 157func interviewConcluded(outcome string) bool { 158 return outcome == "passed" || outcome == "failed" || outcome == "no_show" 159} 160