shoc-backend/docs/work-orders/staff-review-findings.md

Staff Review Findings — Work Orders (Fase 2)

Adversarial reviews per delivery. Do not treat preliminary inventário notes as final.

---

Entrega A — Structured Service Notes / POC / Tech-Vendor

How it works

1. Create POST /api/workorders/board: FluentValidation → resolve primaryService/trade → serialize extraServices JSON → persist POC/service/tech/vendor on WorkOrder; if vendor/appt present, create Dispatch and store tech/vendor notes there instead of WO.
2. Patch PATCH .../board with pm | serviceNotes | extraServices.
3. Read: board projection prefers WO POC fields over WorkOrderContacts; tech phone = Dispatch.TechPhone → WO.TechPhone → Vendor.Phone. Detail exposes serviceNotes, extraServices, vendorNotes.

Domain invariants

• Extra services require a primary service on create.
• Tech/vendor notes live on dispatch when a vendor dispatch exists; otherwise on WO.
• Board POC free-text overrides linked contact projection.

Half-done

• No board PATCH for pocName / pocPhone / pocNotes / techPhone / vendorNotes (create-only for those).
• ParseExtraServices duplicated in board + detail services.
• Create validation file has excessive blank lines (noise).
• Test PatchField_ExtraServicesWithoutPrimary_Throws disagrees with promotion logic in ApplyExtraServices.

Findings

A1 — ExtraServices without primary: test vs promotion

• Severity: High
• File: SeaHaven.Services/Implementation/WorkOrderBoardUpdateService.cs (~294–298); test WorkOrderBoardUpdateServiceTests.cs (~331)
• Explanation: Create requires primary when extras exist; PATCH promotes first extra to Trade without auditing Trade. Test expects InvalidValue.
• Scenario: Legacy WO with empty Trade; FE patches extraServices only.
• Repro: PATCH extraServices=["Filter change"] on WO with null Trade.
• Fix: Reject when Trade empty (align create + test); do not promote silently.
• When: Now (blocks green CI / domain consistency).

A2 — ExtraServices JSON can exceed nvarchar(2000)

• Severity: High
• File: Create SerializeExtraServices; Update ApplyExtraServices
• Explanation: Per-item max 128; no check on serialized JSON length vs column 2000.
• Scenario: Many extras → DbUpdateException 500.
• Repro: PATCH/create with ~20×128-char labels.
• Fix: After serialize, throw InvalidValue if length > 2000.
• When: Now.

A3 — Create does not cap ExtraServices JSON length / per-item in serializer

• Severity: Medium
• File: WorkOrderBoardCreateService.SerializeExtraServices
• Explanation: FluentValidation caps each item at 128 but create serializer does not re-validate length or total JSON; update path has item length check, create does not.
• Fix: Share normalize helper; enforce item + JSON caps on create.
• When: Now (with A2).

A4 — POC / tech / vendor notes not patchable on board

• Severity: Medium
• File: WorkOrderBoardFieldNames.cs / UpdateService
• Explanation: Create persists structured POC/tech/vendor; no PATCH fields → FE cannot edit after create without another API.
• When: Later if FE has another edit path; otherwise before FE ship.

A5 — Dual POC sources can diverge

• Severity: Low
• File: CreateService + Projection
• Explanation: PocContactId + free-text both allowed; board prefers free-text; contact row may hold different notes.
• When: Later (document or clear contact notes when free-text set).

A6 — Duplicate ParseExtraServices

• Severity: Low
• File: WorkOrderBoardService.cs, WorkOrderDetailService.cs
• When: Later (extract helper).

Verdict A

Merge blocked until A1–A3 fixed. A4 is a product gap for FE edit flows.

---

Entrega B — Flag Color

How it works

PATCH flagColor → normalize #RRGGBB → whitelist palette → persist on WO → project on board/detail. Distinct from dispatcher avatar color.

Half-done

• None material. Migration + model + PATCH + tests present.

Findings

B1 — No finding Critical/High

Palette enforcement and clear semantics are consistent with tests.

B2 — Snapshot/model coupled with Entrega A

• Severity: Low (process)
• Explanation: Same WorkerOrder / snapshot file as service notes; branch split needs careful ordering.
• When: During organize.

Verdict B

OK to merge after A schema lands (or same branch ordered commits). No code blockers unique to B.

---

Entrega C — Search / overdue / paging

How it works

Advanced search: normalize page (≥0), pageSize≤100, resolve Mon–Fri presets, whitelist sortBy, apply type/overdue/unscheduled filters, project board rows. Board GET maps ArgumentException → 400.

Half-done / risks

• Shared PagedResult flipped to 0-based helpers while Location/Contact/etc. still use 1-based page defaults.

Findings

C1 — PagedResult 0-based breaks 1-based APIs

• Severity: Critical
• File: SeaHaven.Services/DTOs/ContactDTOs.cs
• Explanation: HasPrevious/HasNext assume 0-based; Location etc. pass page=1 on first page → HasPrevious=true incorrectly; last-page HasNext wrong for 0-based search too if mixed.
• Scenario: Any paged Location/Contact/Vendor list UI using helpers.
• Fix: Restore 1-based helpers by default; opt-in 0-based for WO search only (PageBase or dedicated DTO).
• When: Now.

C2 — Unscheduled always included in date range

• Severity: High
• File: WorkOrderBoardQueryFilters.ApplyDateRangeFilter
• Explanation: Every advanced search with a date range also returns all unscheduled non-terminal WOs → unbounded result growth.
• Scenario: Narrow custom range + large backlog of undated WOs.
• Fix: Explicit includeUnscheduled or cap; confirm FE intent.
• When: Confirm with FE; fix before prod if unintentional.

C3 — WorkOrderType.Other = overdue sentinel

• Severity: High (domain)
• File: WorkOrderBoardQueryFilters.ApplyTypeAndOverdueFilter
• Explanation: Cannot filter real Other types via types=99.
• When: Document now; long-term separate isPastDue query param.

C4 — Label search label.Contains(s) matches short tokens broadly

• Severity: Medium
• File: WorkOrderBoardSearchFilter
• When: Later / monitor perf.

C5 — Overdue uses UTC date vs possibly local scheduled dates

• Severity: Medium
• File: QueryFilters / search filter
• When: Later if US sites report off-by-one day.

C6 — Search helper methods not EF-translatable (FIXED)

• Severity: Critical
• File: WorkOrderBoardSearchFilter.Apply
• Explanation: Refactor extracted Matches* private methods; EF Core InMemory/SQL cannot translate them → all text searches throw at runtime.
• Repro: Any search with length ≥ 2 on board/search.
• Fix: Inline predicates in the Where expression (applied).
• When: Now — fixed during Fase 2.

Verdict C

Merge blocked on C1 (fixed via PageBase) and C6 (fixed via inline predicates). C2 needs product confirmation. Prefer separate PR.

---

Entrega D — Comments edit + display names

How it works

GetDisplayNamesByIdsAsync → comment/audit projections. PATCH comment: author or Admin; General+WorkOrder only; read-only WO blocked.

Half-done

• Comment edit not written to audit log.

Findings

D1 — Comment updates leave no audit trail

• Severity: Medium
• File: WorkOrderCommentService.UpdateCommentAsync
• When: Later if compliance requires it; note in PR.

D2 — No max length on comment text on update

• Severity: Low (pre-existing on create)
• When: Later.

Verdict D

OK to merge with D1 noted. No Critical/High code defects found.

---

Entrega E — Sites + Vendor ContactName

How it works

GET /api/locations/sites?search= → Id/Code/City/State (Code ← Locations.Name). Vendor Dropdown adds contactName.

Findings

E1 — GetSites unbounded

• Severity: Medium
• File: LocationDataService.GetSiteOptionsAsync
• Explanation: No Take/limit; large Locations table → heavy payload.
• When: Later or add Take(500) if volume unknown.

E2 — No soft-delete filter

• Severity: Low
• Explanation: Locations inherit audit entity; if soft-delete used elsewhere, sites may include deleted.
• When: Later if soft-delete applies to Locations.

Verdict E

OK to merge independently.

---

Entrega F1 — Phase4 migration hardening

How it works

Before creating indexes, alter SiteCode/InternalWONumber to nvarchar(450).

Findings

F1-1 — Editing already-shipped migration

• Severity: High (ops)
• File: 20260624200000_Phase4_SearchIndexes.cs
• Explanation: Environments that already applied old Up will not re-run. Failed partial applies need manual repair or a new migration.
• When: Verify __EFMigrationsHistory per environment before merge. Prefer new corrective migration if any env already applied.

Verdict F1

Conditional merge after env check. Apply on feat/work-orders-phase-4 only.

---

Entrega F2 — Phase6 migration hardening

How it works

Idempotent SQL for Category column, CompletionDocTemplates, index; EF attributes for discovery.

Findings

F2-1 — Same applied-migration caveat as F1

• Severity: High (ops)
• When: Verify env history; idempotent SQL helps partial DBs if migration re-run manually, not if EF skips applied migrations.

Verdict F2

Conditional merge on slideover branch after env check.

---

Cross-cutting mandatory fixes before organize

1. A1 — ExtraServices without primary throws
2. A2/A3 — JSON length ≤ 2000
3. C1 — PagedResult 1-based default + WO search 0-based opt-in