Service Layer Progress

Service Layer — progress tracker

Rollout status of the service-layer refactor: collapsing each module's duplicated UI + REST API write logic into one shared service, module by module, behind a before/after parity harness.

Strategy: prove the pattern on the smallest, lowest-risk module first; do tickets last (biggest, most integrations). Each module is its own revertable commit; nothing ships unless the harness proves the API is byte-identical.

Per-module status

Module	Status	Adapter lines removed	Parity	Notes
Service Status	✅ Done (#718)	474 removed / 75 kept (9 files)	✅ byte-identical	Pilot. Established the primitives + pattern. Display-UTC fix #719.
Morning Checks	✅ Done (#720)	424 removed / 94 kept (10 files)	✅ byte-identical	Unified documented UI/API drift. Added ActorContext.actorName + shared apiFailFromService().
Software	✅ Done (#722)	175 removed / 40 kept (3 files)	✅ byte-identical	Only licences overlap UI+API; inventory is read-only and widgets/apikeys are UI-only (no twin), so left untouched.
Calendar	✅ Done (#723)	302 removed / 70 kept (5 files)	✅ byte-identical	Events overlap UI+API; UI-only categories folded in. Naïve-local datetime contract preserved (not converted to UTC).
Forms	✅ Done (#724)	722 removed / 55 kept (6 files)	✅ byte-identical	Largest so far. Positional field sync + version chains + the form.submitted workflow dispatch all in one write path.
Contracts	✅ Done (#725)	462 removed / 56 kept (6 files)	✅ byte-identical	Contracts + suppliers + term upsert. Lookup settings (UI-only) and supplier contacts (UI-flat vs API-nested mismatch) left on their own code.
Knowledge	⬜ Planned	—	—
Tasks	⬜ Planned	—	—
CMDB	⬜ Planned	—	—
Network Mapper	⬜ Planned	—	—
Assets	⬜ Planned	—	—
Changes	⬜ Planned	—	—
Problems	⬜ Planned	—	—
Service Status settings	✅ folded into pilot	—	n/a	Incident-statuses + impact-levels are UI-only; moved into the service.
Tickets	⬜ Last	—	—	Biggest payoff, most integrations — deliberately last.

Line savings — the honest picture

The first module is roughly line-neutral: it pays a one-time cost (the shared ActorContext + ServiceError primitives, ~105 lines) and its service includes UI-only logic that was never duplicated. The thousands of lines of net removal arrive as the larger, heavily-mirrored modules migrate — tickets above all.

	Lines
One-time primitives (includes/service_context.php + apiFailFromService)	+122 (paid once, for all modules)
Service Status: adapter logic removed	−474
Service Status: adapters kept (thin)	+75
Service Status: service (incl. UI-only ops)	+390
Morning Checks: adapter logic removed	−424
Morning Checks: adapters kept (thin)	+94
Morning Checks: service (incl. UI-only ops)	+310
Software: adapter logic removed	−175
Software: adapters kept (thin)	+40
Software: service (licences only)	+168
Calendar: adapter logic removed	−302
Calendar: adapters kept (thin)	+70
Calendar: service (events + UI-only categories)	+251
Forms: adapter logic removed	−722
Forms: adapters kept (thin)	+55
Forms: service (forms + versions + submissions + dispatch)	+445
Contracts: adapter logic removed	−462
Contracts: adapters kept (thin)	+56
Contracts: service (contracts + suppliers + terms)	+341

Convergence log

Where a module's UI and API already behaved differently, we converge to the API's behaviour (the API is the external contract; it stays identical, the UI shifts to match). Record each convergence here so nothing is a silent surprise.

Service Status (#718):

• Create timestamps: server-local → UTC (SLA-correct; same bug class as Forms #701).
• Empty description: "" → null.
• Affected-service validation: silently-skip unknowns → strict 422.
• Incident status: name-only → name or id.
• UI deletes: idempotent → 404 on missing (matches the API).

Morning Checks (#720):

• Result date: malformed silently-swapped-for-today → strict 422.
• Unknown check id on a result: raw FK 500 → 422 with a clear message.
• Result CreatedBy: left NULL by the UI → the recording analyst's name (attribution; the API already did this).
• Check validation messages align with the API wording; updating/deleting a missing check → 404 (was a silent no-op).

Software (#722):

• Licence app id: no check (raw FK error on a bad id) → the app must exist, 422 with a clear message.
• Quantity / cost / dates: silently coerced → validated (422) — a negative quantity, a non-numeric cost or a malformed date is rejected.
• Empty optional fields (licence_key, portal_url, vendor_contact, notes): stored as "" → null; missing currency/status fall back to GBP / Active.
• Saving or deleting a missing licence: silent success → "Licence not found." (matches the API's 404).

Calendar (#723):

• Event category id: no check (raw FK error on a bad id) → the category must exist, 422.
• Event times: no check → end_at before start_at is rejected (422); naive-datetime format is validated (Z/offset rejected) — the naive-local contract is kept, not converted to UTC.
• Generated events (source = 'asset_warranty' etc.): the UI let you edit/delete one, only for it to reappear on the next sync → now refused (409) on both edit and delete, matching the API.
• Saving or deleting a missing event: silent success → "Event not found." (matches the API's 404).
• Categories are a UI-only operation (no API twin) — moved into the service with behaviour preserved verbatim (name required, #RRGGBB colour check, in-use delete guard).

Forms (#724):

• Field validation: a blank label was silently dropped, an unrecognised field type blindly stored → both now 422.
• Submission with an unknown field id: raw FK error → 422 with a clear message.
• Editing a frozen (non-leaf) version → 409; deleting a form that still has newer versions → 409 (was a raw FK error). Whole-chain delete stays an API-only option (?chain=true).
• Submitting to an inactive form → 409 (the UI merged not-found + inactive into one message; now split into 404 / 409).
• Saving/deleting a missing form or submission → 404 (was a silent success).
• The form.submitted workflow dispatch now fires from the shared write path, so UI and API submissions trigger workflows identically — the first webhook-relevant side effect to land on a service (see the eventing note above).

Contracts (#725):

• A contract now needs a contract_number + title; its supplier / status / schedule / owner id must exist (were raw FK errors); dates are validated; the value must be numeric and the currency a 3-letter code.
• A duplicate contract_number is refused (409) on create and update — the raw UI allowed duplicates.
• Deleting a supplier cleanly unlinks every referrer (assets, contacts, contracts, RFP invites/scores) before the delete, and created timestamps are stamped UTC (the UI relied on the server-local column default).
• Scope: only the cleanly-duplicated overlaps (contracts, suppliers, term values) were migrated. The lookup settings (contract/supplier statuses, supplier types, payment schedules, term tabs) are UI-only (the API exposes them read-only) and stay on their own endpoints; supplier contacts are modelled flat by the UI (a supplier_id in the body, movable) but nested under a supplier by the API — a structural mismatch not worth forcing into one shape — so they stay separate too.

Deferred / follow-up work

• Display-layer UTC parsing — storage is now consistently UTC, but module JS parses "Y-m-d H:i:s" as local (new Date(...)), so UTC data can render an hour off. Fix is a small per-module parseUtc() helper (mark the naive string UTC before toLocale*). Done for service-status (#719); still to do on calendar, morning-checks and other timestamp-rendering modules. See Watch out for #2.
• Webhook events from the write path — once a module is on its service, emitting lifecycle events (for outbound webhooks) is one line from the single write path, firing identically for UI, API and automation. This is the webhooks "wider event catalogue" phase.

How each module is done

1. Read the complete surface — every UI endpoint and the API resource for the module.
2. Enumerate the UI-vs-API divergences; agree the convergence.
3. Build/adapt the parity harness; capture golden-before on untouched code.
4. Extract <Module>Service; repoint the API write handlers + the UI endpoints at it.
5. Run the harness after; require the API byte-identical, UI converged as designed.
6. Ship as one commit. Update this page.

See Service Layer — architecture for the conventions and the full "Watch out for…" list.