shoc-frontend-new/docs/work-orders/pending-be-contract.md

Pending BE contract (WO design parity gaps)

Local checklist for FE branches off dev. Confirm with backend before shipping PR3/PR5 to production. Until confirmed, FE may use typed clients + mocks.

Board row / PATCH

Field	Needed by	Notes
completedDate on GET /board and /board/search rows	PR1, PR4	PATCH field: "completedDate" expected; confirm GET includes ISO date
severity (1–5 | null) on row, create, PATCH	PR2, PR5	Required for Emergency/Reactive; PATCH field: "severity"
upliftSummary on row	PR3, PR4, PR5	{ hasUplift, pendingCount, primaryStatus?, amount? } — implemented (SH-196 BE)
hasPendingUplift on row/detail	PR4	Prefer server 422 on Completed / completion-doc when pending
additionalContacts[]	PR6	{ name, phone, notes? }[] on create/detail/PATCH
isAddOn	PR5 (filter)	Indicator, not a WO type (SH-126)

Proposed WO-scoped uplift endpoints (SH-196 — landed on backend dev)

Method	Path	Body	Status
GET	workorders/{id}/uplifts	—	Implemented (SH-196 BE)
POST	workorders/{id}/uplifts	{ amount, notes, attachments? }	Implemented (attachments still FE stub)
POST	workorders/{id}/uplifts/{upliftId}/cancel	—	Implemented
POST	workorders/{id}/uplifts/{upliftId}/revoke	{ reason? }	Implemented

Board row upliftSummary ({ hasUplift, pendingCount, primaryStatus?, amount? }) is returned on GET /board and /board/search rows (SH-196 BE).

Statuses (design): pending | approved | auto_approved | rejected | cancelled | revoked.

SH-196 producer invariants (backend #64):

• One open (pending) request per work order at a time — cancel-and-refile to submit another.
• Auto-approval cap is cumulative per WO: $500, or $5,000 for Emergency. Consumed = sum of current auto_approved amounts (revoked amounts are freed).
• Amount ≤ remaining allowance → auto_approved; otherwise pending (admin queue).
• Cancelling a WO withdraws any pending uplift in the same action.

Search query params (GET workorders/board/search)

Param	Meaning
severities	multi 1–5
rescheduled / carriedOver	boolean (≥2 counters)
addOn	boolean (isAddOn)
flagColors	multi #RRGGBB
internalOnly	WO# starts with SH
avetaOnly	if avetaRequired exists
hasUplift + upliftStatuses	uplift filters

Already documented in board-search-api.md: datePreset, sites, types, overdue, dispatchers, statuses, pmTypes, vendorIds, docStatuses.

Comments

Field	Needed by
POST { text, mentions?: string[] }	PR9
Response includes mentions for highlight	PR9

Vendor

Item	Needed by
Create technician under company (confirm existing vendors API)	PR7

Optional

Item	Needed by
422 on duplicate WO number (global)	PR8 (FE dialog works without it)