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 OpenedAt string `json:"opened_at"` 56 TargetFillDate string `json:"target_fill_date,omitempty"` 57 ClosedAt string `json:"closed_at,omitempty"` 58 OnHoldSince string `json:"on_hold_since,omitempty"` 59 60 AgeDays float64 `json:"age_days"` 61 WorkingDays float64 `json:"working_days"` 62 HeldDays float64 `json:"held_days"` 63 // DaysToTarget is negative when the target fill date has passed. Nil when no target was set, which 64 // is different from zero and must not be rendered as "due today". 65 DaysToTarget *int `json:"days_to_target,omitempty"` 66 67 CreatedAt string `json:"created_at"` 68 // UpdatedAt doubles as the optimistic concurrency token. 69 UpdatedAt string `json:"updated_at"` 70} 71 72// RequisitionList is an envelope so the caller learns the total without a second query. 73type RequisitionList struct { 74 Requisitions []Requisition `json:"requisitions"` 75 Limit int `json:"limit"` 76 Offset int `json:"offset"` 77 Total int `json:"total"` 78} 79 80// RequisitionEvent is one status change. Append only, and the source of every duration Phase 17 reports. 81type RequisitionEvent struct { 82 ID string `json:"id"` 83 FromStatus string `json:"from_status,omitempty"` 84 ToStatus string `json:"to_status"` 85 DaysInFrom float64 `json:"days_in_from"` 86 Note string `json:"note,omitempty"` 87 ActorUserID string `json:"actor_user_id,omitempty"` 88 ActorUserName string `json:"actor_user_name,omitempty"` 89 OccurredAt string `json:"occurred_at"` 90} 91 92// RequisitionDetail is an order with its history, which is how the detail screen reads it. 93type RequisitionDetail struct { 94 Requisition 95 Events []RequisitionEvent `json:"events"` 96} 97 98// CreateRequisitionInput. Only a title is required. A job order is usually opened from a phone call 99// with the rate and the manager still unknown, and demanding them up front makes people type 100// placeholders that are worse than a blank. 101type CreateRequisitionInput struct { 102 ClientID string `json:"client_id"` 103 HiringManagerID string `json:"hiring_manager_id"` 104 RequirementID string `json:"requirement_id"` 105 Title string `json:"title"` 106 Description string `json:"description"` 107 LaborCategory string `json:"labor_category"` 108 Openings int `json:"openings"` 109 Priority string `json:"priority"` 110 EmploymentType string `json:"employment_type"` 111 Status string `json:"status"` 112 RequiredLevel string `json:"required_level"` 113 RequiredPoly string `json:"required_poly"` 114 WorkLocation string `json:"work_location"` 115 RemoteAllowed bool `json:"remote_allowed"` 116 BillRateMin string `json:"bill_rate_min"` 117 BillRateMax string `json:"bill_rate_max"` 118 PayRateMin string `json:"pay_rate_min"` 119 PayRateMax string `json:"pay_rate_max"` 120 SalaryMin string `json:"salary_min"` 121 SalaryMax string `json:"salary_max"` 122 TargetFillDate string `json:"target_fill_date"` 123} 124 125// UpdateRequisitionInput carries the editable fields plus the concurrency token. Pointers so an omitted 126// field means leave it alone, which is different from an empty string meaning clear it. 127// 128// Status is deliberately absent. A status change moves clocks and writes an event, so it goes through 129// ChangeStatus, where the transition graph decides whether it is legal. Allowing it here would let a 130// PATCH write any status directly and bypass the entire lifecycle. 131type UpdateRequisitionInput struct { 132 ExpectedUpdatedAt string `json:"expected_updated_at"` 133 ClientID *string `json:"client_id,omitempty"` 134 HiringManagerID *string `json:"hiring_manager_id,omitempty"` 135 Title *string `json:"title,omitempty"` 136 Description *string `json:"description,omitempty"` 137 LaborCategory *string `json:"labor_category,omitempty"` 138 Openings *int `json:"openings,omitempty"` 139 Priority *string `json:"priority,omitempty"` 140 EmploymentType *string `json:"employment_type,omitempty"` 141 RequiredLevel *string `json:"required_level,omitempty"` 142 RequiredPoly *string `json:"required_poly,omitempty"` 143 WorkLocation *string `json:"work_location,omitempty"` 144 RemoteAllowed *bool `json:"remote_allowed,omitempty"` 145 BillRateMin *string `json:"bill_rate_min,omitempty"` 146 BillRateMax *string `json:"bill_rate_max,omitempty"` 147 PayRateMin *string `json:"pay_rate_min,omitempty"` 148 PayRateMax *string `json:"pay_rate_max,omitempty"` 149 SalaryMin *string `json:"salary_min,omitempty"` 150 SalaryMax *string `json:"salary_max,omitempty"` 151 TargetFillDate *string `json:"target_fill_date,omitempty"` 152} 153 154// ChangeStatusInput. The note is what makes the event trail readable a year later: "client froze the 155// program" and "candidate accepted elsewhere" are the same transition and different stories. 156type ChangeStatusInput struct { 157 ExpectedUpdatedAt string `json:"expected_updated_at"` 158 Status string `json:"status"` 159 Note string `json:"note"` 160} 161 162const dateLayout = "2006-01-02" 163 164// dateStr renders a Postgres date. Only the date part, because a target fill date has no time of day and 165// showing one would imply a precision the field does not have. 166func dateStr(t *time.Time) string { 167 if t == nil { 168 return "" 169 } 170 return t.UTC().Format(dateLayout) 171} 172