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

1package recruiting 2 3import ( 4 "time" 5 6 "github.com/shopspring/decimal" 7) 8 9// Requisition is a job order: a role a client has asked this organization to fill. 10// 11// Money is carried as decimal and rendered as a JSON string, never a float. A bill rate is multiplied by 12// hours and by a wrap rate downstream, and binary floating point cannot represent 0.1 exactly, so a rate 13// that survived a round trip through a JSON number would not necessarily be the rate that was agreed. 14// 15// The three clocks are reported separately because they answer different questions. AgeDays is the wall 16// clock a client sees. WorkingDays removes time the order spent on hold, which is the number that says 17// how fast this organization actually works. HeldDays is the difference, shown so neither number has to 18// be taken on trust. 19type Requisition struct { 20 ID string `json:"id"` 21 22 ClientID string `json:"client_id,omitempty"` 23 ClientName string `json:"client_name,omitempty"` 24 // The hiring manager is constrained by the database to be a contact AT this client, so a submittal 25 // cannot be addressed to someone at a different company. 26 HiringManagerID string `json:"hiring_manager_id,omitempty"` 27 HiringManagerName string `json:"hiring_manager_name,omitempty"` 28 // Ownership is the lock, the same rule clients use. An unowned order is claimable by anyone with 29 // write capability; an owned one is edited by its holder or an admin. 30 OwnerUserID string `json:"owner_user_id,omitempty"` 31 OwnerName string `json:"owner_name,omitempty"` 32 // RequirementID bridges to the federal capture side when a job order came from a solicitation. 33 RequirementID string `json:"requirement_id,omitempty"` 34 35 Title string `json:"title"` 36 Description string `json:"description,omitempty"` 37 LaborCategory string `json:"labor_category,omitempty"` 38 Openings int `json:"openings"` 39 Priority string `json:"priority"` 40 EmploymentType string `json:"employment_type"` 41 Status string `json:"status"` 42 // Clearance is a self reported indicator throughout this product, never a verified status. 43 RequiredLevel string `json:"required_level"` 44 RequiredPoly string `json:"required_poly"` 45 WorkLocation string `json:"work_location,omitempty"` 46 RemoteAllowed bool `json:"remote_allowed"` 47 48 BillRateMin *decimal.Decimal `json:"bill_rate_min,omitempty"` 49 BillRateMax *decimal.Decimal `json:"bill_rate_max,omitempty"` 50 PayRateMin *decimal.Decimal `json:"pay_rate_min,omitempty"` 51 PayRateMax *decimal.Decimal `json:"pay_rate_max,omitempty"` 52 SalaryMin *decimal.Decimal `json:"salary_min,omitempty"` 53 SalaryMax *decimal.Decimal `json:"salary_max,omitempty"` 54 55 // WHERE THIS REQUISITION CAME FROM, which changes how it is worked. A vendor management system 56 // distributes one req to a preferred vendor list, and most of those run five to ten agencies competing on 57 // the same role against a hard deadline. A desk that treats that identically to a client phone call loses 58 // the first kind. 59 IntakeSource string `json:"intake_source"` 60 VMSName string `json:"vms_name,omitempty"` 61 VMSRequisitionRef string `json:"vms_requisition_ref,omitempty"` 62 SubmissionDeadline string `json:"submission_deadline,omitempty"` 63 CompetingVendors *int `json:"competing_vendors,omitempty"` 64 MaxSubmissions *int `json:"max_submissions,omitempty"` 65 // HoursToDeadline is negative once it has passed. It is computed rather than left to the browser because 66 // the deadline is the single most operationally important field on a VMS req and the most often missed, 67 // and a screen that has to work out urgency itself is a screen that will work it out differently. 68 HoursToDeadline *float64 `json:"hours_to_deadline,omitempty"` 69 70 OpenedAt string `json:"opened_at"` 71 TargetFillDate string `json:"target_fill_date,omitempty"` 72 ClosedAt string `json:"closed_at,omitempty"` 73 OnHoldSince string `json:"on_hold_since,omitempty"` 74 75 AgeDays float64 `json:"age_days"` 76 WorkingDays float64 `json:"working_days"` 77 HeldDays float64 `json:"held_days"` 78 // DaysToTarget is negative when the target fill date has passed. Nil when no target was set, which 79 // is different from zero and must not be rendered as "due today". 80 DaysToTarget *int `json:"days_to_target,omitempty"` 81 82 CreatedAt string `json:"created_at"` 83 // UpdatedAt doubles as the optimistic concurrency token. 84 UpdatedAt string `json:"updated_at"` 85} 86 87// RequisitionList is an envelope so the caller learns the total without a second query. 88type RequisitionList struct { 89 Requisitions []Requisition `json:"requisitions"` 90 Limit int `json:"limit"` 91 Offset int `json:"offset"` 92 Total int `json:"total"` 93} 94 95// RequisitionEvent is one status change. Append only, and the source of every duration Phase 17 reports. 96type RequisitionEvent struct { 97 ID string `json:"id"` 98 FromStatus string `json:"from_status,omitempty"` 99 ToStatus string `json:"to_status"` 100 DaysInFrom float64 `json:"days_in_from"` 101 Note string `json:"note,omitempty"` 102 ActorUserID string `json:"actor_user_id,omitempty"` 103 ActorUserName string `json:"actor_user_name,omitempty"` 104 OccurredAt string `json:"occurred_at"` 105} 106 107// RequisitionDetail is an order with its history, which is how the detail screen reads it. 108type RequisitionDetail struct { 109 Requisition 110 Events []RequisitionEvent `json:"events"` 111} 112 113// CreateRequisitionInput. Only a title is required. A job order is usually opened from a phone call 114// with the rate and the manager still unknown, and demanding them up front makes people type 115// placeholders that are worse than a blank. 116type CreateRequisitionInput struct { 117 ClientID string `json:"client_id"` 118 HiringManagerID string `json:"hiring_manager_id"` 119 RequirementID string `json:"requirement_id"` 120 Title string `json:"title"` 121 Description string `json:"description"` 122 LaborCategory string `json:"labor_category"` 123 Openings int `json:"openings"` 124 Priority string `json:"priority"` 125 EmploymentType string `json:"employment_type"` 126 Status string `json:"status"` 127 RequiredLevel string `json:"required_level"` 128 RequiredPoly string `json:"required_poly"` 129 WorkLocation string `json:"work_location"` 130 RemoteAllowed bool `json:"remote_allowed"` 131 BillRateMin string `json:"bill_rate_min"` 132 BillRateMax string `json:"bill_rate_max"` 133 PayRateMin string `json:"pay_rate_min"` 134 PayRateMax string `json:"pay_rate_max"` 135 SalaryMin string `json:"salary_min"` 136 SalaryMax string `json:"salary_max"` 137 TargetFillDate string `json:"target_fill_date"` 138 139 IntakeSource string `json:"intake_source"` 140 VMSName string `json:"vms_name"` 141 VMSRequisitionRef string `json:"vms_requisition_ref"` 142 SubmissionDeadline string `json:"submission_deadline"` 143 CompetingVendors *int `json:"competing_vendors"` 144 MaxSubmissions *int `json:"max_submissions"` 145} 146 147// UpdateRequisitionInput carries the editable fields plus the concurrency token. Pointers so an omitted 148// field means leave it alone, which is different from an empty string meaning clear it. 149// 150// Status is deliberately absent. A status change moves clocks and writes an event, so it goes through 151// ChangeStatus, where the transition graph decides whether it is legal. Allowing it here would let a 152// PATCH write any status directly and bypass the entire lifecycle. 153type UpdateRequisitionInput struct { 154 ExpectedUpdatedAt string `json:"expected_updated_at"` 155 ClientID *string `json:"client_id,omitempty"` 156 HiringManagerID *string `json:"hiring_manager_id,omitempty"` 157 Title *string `json:"title,omitempty"` 158 Description *string `json:"description,omitempty"` 159 LaborCategory *string `json:"labor_category,omitempty"` 160 Openings *int `json:"openings,omitempty"` 161 Priority *string `json:"priority,omitempty"` 162 EmploymentType *string `json:"employment_type,omitempty"` 163 RequiredLevel *string `json:"required_level,omitempty"` 164 RequiredPoly *string `json:"required_poly,omitempty"` 165 WorkLocation *string `json:"work_location,omitempty"` 166 RemoteAllowed *bool `json:"remote_allowed,omitempty"` 167 BillRateMin *string `json:"bill_rate_min,omitempty"` 168 BillRateMax *string `json:"bill_rate_max,omitempty"` 169 PayRateMin *string `json:"pay_rate_min,omitempty"` 170 PayRateMax *string `json:"pay_rate_max,omitempty"` 171 SalaryMin *string `json:"salary_min,omitempty"` 172 SalaryMax *string `json:"salary_max,omitempty"` 173 TargetFillDate *string `json:"target_fill_date,omitempty"` 174} 175 176// ChangeStatusInput. The note is what makes the event trail readable a year later: "client froze the 177// program" and "candidate accepted elsewhere" are the same transition and different stories. 178type ChangeStatusInput struct { 179 ExpectedUpdatedAt string `json:"expected_updated_at"` 180 Status string `json:"status"` 181 Note string `json:"note"` 182} 183 184const dateLayout = "2006-01-02" 185 186// dateStr renders a Postgres date. Only the date part, because a target fill date has no time of day and 187// showing one would imply a precision the field does not have. 188func dateStr(t *time.Time) string { 189 if t == nil { 190 return "" 191 } 192 return t.UTC().Format(dateLayout) 193} 194