Janady13/missionmatch / internal/modules/bidoutcomes/service.go

1package bidoutcomes 2 3import ( 4 "context" 5 "encoding/json" 6 "errors" 7 "time" 8 9 "github.com/google/uuid" 10 "github.com/jackc/pgx/v5" 11 12 "github.com/missionworkforce/missionmatch/internal/platform/audit" 13 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 14) 15 16// ErrNoDatabase is returned when no pool is configured. ErrNotFound when an update matches nothing in the 17// caller's org. ErrInvalidResult when the result enum is outside the allowed set. ErrInvalidID when a 18// supplied link or row id is not a UUID. 19var ( 20 ErrNoDatabase = errors.New("bidoutcomes: no database configured") 21 ErrNotFound = errors.New("bidoutcomes: bid outcome not found") 22 ErrInvalidResult = errors.New("bidoutcomes: result must be one of win, loss, no_bid, pending") 23 ErrInvalidID = errors.New("bidoutcomes: an id field must be a uuid") 24) 25 26// Service records and updates bid outcomes under RLS, and writes an append only AEDT audit event with NO 27// PII (the org from the validated session, the result, and which of opportunity, requirement, and slate 28// were set, never the notes text and never the awardee). 29type Service struct { 30 db *tenant.DB 31 aud *audit.Writer 32} 33 34// NewService builds the service. db may be nil (then calls return ErrNoDatabase). The audit writer records 35// the recorded and updated events on the same tenant transaction as the work. 36func NewService(db *tenant.DB, aud *audit.Writer) *Service { return &Service{db: db, aud: aud} } 37 38// RecordBidOutcome inserts a new bid outcome, or upserts an existing one when input.ID is set, under the 39// caller's tenant transaction (RLS). It validates the result enum (defaulting an empty result to pending), 40// parses the optional uuid links and the optional timestamps, and on success writes an append only 41// aedt.bid_outcome.recorded audit event carrying NO PII. RLS plus the composite FKs guarantee a link can 42// only ever point at the caller's own opportunity, requirement, or slate. 43func (s *Service) RecordBidOutcome(ctx context.Context, in RecordInput) (BidOutcome, error) { 44 // Validate the input BEFORE touching the database so a bad result enum, a malformed link uuid, or a bad 45 // timestamp is a clean typed error regardless of whether a pool is configured. 46 result := in.Result 47 if result == "" { 48 result = ResultPending 49 } 50 if !IsValidResult(result) { 51 return BidOutcome{}, ErrInvalidResult 52 } 53 rowID, oppID, reqID, slateID, err := parseLinks(in.ID, in.OpportunityID, in.RequirementID, in.SlateID) 54 if err != nil { 55 return BidOutcome{}, err 56 } 57 submittedAt, err := parseTime(in.SubmittedAt) 58 if err != nil { 59 return BidOutcome{}, err 60 } 61 awardDate, err := parseDate(in.AwardDate) 62 if err != nil { 63 return BidOutcome{}, err 64 } 65 if !s.db.Ready() { 66 return BidOutcome{}, ErrNoDatabase 67 } 68 69 var out BidOutcome 70 err = s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 71 // An UPSERT keyed on the row id when provided; otherwise a plain insert with a generated id. The 72 // ON CONFLICT path only ever updates a row already visible to this tenant under RLS, so an id from 73 // another org cannot be overwritten (the WITH CHECK and the composite FKs both hold). 74 row := tx.QueryRow(ctx, insertOrUpsertOutcomeSQL, rowID, oppID, reqID, slateID, submittedAt, result, awardDate, in.AwardeeUEI, in.Notes) 75 scanned, scanErr := scanOutcome(row) 76 if scanErr != nil { 77 return scanErr 78 } 79 out = scanned 80 return s.audit(ctx, tx, "aedt.bid_outcome.recorded", out) 81 }) 82 if err != nil { 83 return BidOutcome{}, err 84 } 85 return out, nil 86} 87 88// UpdateBidOutcome updates the result and award fields of an existing outcome in the caller's org once they 89// are known. It validates the result enum, parses the optional timestamps, and on a row that this tenant 90// can see (RLS) writes an append only aedt.bid_outcome.recorded audit event with NO PII. A row id that this 91// tenant cannot see returns ErrNotFound, never another org's row. 92func (s *Service) UpdateBidOutcome(ctx context.Context, id uuid.UUID, in UpdateInput) (BidOutcome, error) { 93 // Validate the input BEFORE touching the database so a bad result enum or a bad timestamp is a clean 94 // typed error regardless of whether a pool is configured. 95 result := in.Result 96 if result == "" { 97 result = ResultPending 98 } 99 if !IsValidResult(result) { 100 return BidOutcome{}, ErrInvalidResult 101 } 102 submittedAt, err := parseTime(in.SubmittedAt) 103 if err != nil { 104 return BidOutcome{}, err 105 } 106 awardDate, err := parseDate(in.AwardDate) 107 if err != nil { 108 return BidOutcome{}, err 109 } 110 if !s.db.Ready() { 111 return BidOutcome{}, ErrNoDatabase 112 } 113 114 var out BidOutcome 115 err = s.db.RunInTenantTx(ctx, func(ctx context.Context, tx pgx.Tx) error { 116 // COALESCE keeps the existing submitted_at and award_date when the update omits them (a null bind), 117 // so a partial update never wipes a known timestamp. The UPDATE is RLS scoped, so a row in another 118 // org is invisible and matches zero rows. 119 row := tx.QueryRow(ctx, updateOutcomeSQL, id, result, submittedAt, awardDate, in.AwardeeUEI, in.Notes) 120 scanned, scanErr := scanOutcome(row) 121 if errors.Is(scanErr, pgx.ErrNoRows) { 122 return ErrNotFound 123 } 124 if scanErr != nil { 125 return scanErr 126 } 127 out = scanned 128 return s.audit(ctx, tx, "aedt.bid_outcome.recorded", out) 129 }) 130 if err != nil { 131 return BidOutcome{}, err 132 } 133 return out, nil 134} 135 136// audit writes one append only AEDT event for a bid outcome write, carrying NO PII: the result and which of 137// opportunity, requirement, and slate were set, never the notes, the awardee UEI, or any link id value. The 138// actor is taken from the validated session, never a caller argument. 139func (s *Service) audit(ctx context.Context, tx pgx.Tx, action string, out BidOutcome) error { 140 if s.aud == nil { 141 return nil 142 } 143 payload, _ := json.Marshal(map[string]any{ 144 "result": out.Result, 145 "has_opportunity": out.OpportunityID != "", 146 "has_requirement": out.RequirementID != "", 147 "has_slate": out.SlateID != "", 148 "submitted": out.SubmittedAt != "", 149 "award_decision_set": out.AwardDate != "", 150 }) 151 e := audit.Event{Action: action, EntityType: "bid_outcome", EntityID: out.ID, NewValues: payload} 152 if p, ok := tenant.UserFromContext(ctx); ok { 153 if uid, perr := uuid.Parse(p.UserID); perr == nil { 154 e.ActorUserID = &uid 155 } 156 } 157 return s.aud.OnTx(ctx, tx, e) 158} 159 160// scanOutcome scans a returned bid_outcomes row into the DTO, mapping nullable links and timestamps to 161// empty strings so the JSON omits them. 162func scanOutcome(row pgx.Row) (BidOutcome, error) { 163 var ( 164 id uuid.UUID 165 oppID *uuid.UUID 166 reqID *uuid.UUID 167 slateID *uuid.UUID 168 submittedAt *time.Time 169 result string 170 awardDate *time.Time 171 awardeeUEI string 172 notes string 173 createdAt time.Time 174 updatedAt time.Time 175 ) 176 if err := row.Scan(&id, &oppID, &reqID, &slateID, &submittedAt, &result, &awardDate, &awardeeUEI, &notes, &createdAt, &updatedAt); err != nil { 177 return BidOutcome{}, err 178 } 179 return BidOutcome{ 180 ID: id.String(), 181 OpportunityID: uuidStr(oppID), 182 RequirementID: uuidStr(reqID), 183 SlateID: uuidStr(slateID), 184 SubmittedAt: timeStr(submittedAt), 185 Result: result, 186 AwardDate: dateStr(awardDate), 187 AwardeeUEI: awardeeUEI, 188 Notes: notes, 189 CreatedAt: createdAt.Format(time.RFC3339), 190 UpdatedAt: updatedAt.Format(time.RFC3339), 191 }, nil 192} 193 194// parseLinks parses the optional row id and the three optional link ids, returning typed uuid pointers that 195// bind to NULL when empty. A non empty value that is not a uuid is rejected with ErrInvalidID so a bad link 196// is a clean 422, never a raw bind error. 197func parseLinks(rowID, oppID, reqID, slateID string) (row, opp, req, slate *uuid.UUID, err error) { 198 if row, err = parseOptUUID(rowID); err != nil { 199 return 200 } 201 if opp, err = parseOptUUID(oppID); err != nil { 202 return 203 } 204 if req, err = parseOptUUID(reqID); err != nil { 205 return 206 } 207 slate, err = parseOptUUID(slateID) 208 return 209} 210 211// parseOptUUID parses an optional uuid: an empty string is a nil pointer (NULL), a valid uuid is its 212// pointer, and anything else is ErrInvalidID. 213func parseOptUUID(s string) (*uuid.UUID, error) { 214 if s == "" { 215 return nil, nil 216 } 217 id, err := uuid.Parse(s) 218 if err != nil { 219 return nil, ErrInvalidID 220 } 221 return &id, nil 222} 223 224// parseTime parses an optional RFC3339 timestamp; empty is a nil pointer (NULL). 225func parseTime(s string) (*time.Time, error) { 226 if s == "" { 227 return nil, nil 228 } 229 t, err := time.Parse(time.RFC3339, s) 230 if err != nil { 231 return nil, err 232 } 233 return &t, nil 234} 235 236// parseDate parses an optional award date, accepting either a bare date (2006-01-02) or a full RFC3339 237// timestamp; empty is a nil pointer (NULL). The DB column is a date, so a parsed time is truncated to its 238// day at bind time by pgx. 239func parseDate(s string) (*time.Time, error) { 240 if s == "" { 241 return nil, nil 242 } 243 if t, err := time.Parse("2006-01-02", s); err == nil { 244 return &t, nil 245 } 246 t, err := time.Parse(time.RFC3339, s) 247 if err != nil { 248 return nil, err 249 } 250 return &t, nil 251} 252 253func uuidStr(id *uuid.UUID) string { 254 if id == nil { 255 return "" 256 } 257 return id.String() 258} 259 260func timeStr(t *time.Time) string { 261 if t == nil { 262 return "" 263 } 264 return t.Format(time.RFC3339) 265} 266 267func dateStr(t *time.Time) string { 268 if t == nil { 269 return "" 270 } 271 return t.Format("2006-01-02") 272} 273