Feature Package PK-03 — Engineering & Maintenance

Status: Package Specification
Domain: Buildings / Assets / Engineering
Maps to: Process 8 (Asset Maintenance & Remediation), Playbook H-3
External integration: OpenMAINT (CMMS), MinIO (evidence photos)

1. What This Package Does

Gives a hotel's engineering team one auditable system for faults, preventive maintenance, work orders, parts consumption, and expert sign-off — replacing paper logbooks, WhatsApp fault reports, and spreadsheets.

2. Features & Functionality

Feature	What it does	Who uses it	What stands behind it
Fault intake	Guest or staff reports a fault (HVAC, plumbing, lift, lighting, room amenity) with photo evidence; a work-order claim is created	Front desk, guest, housekeeping attendant	`cns://operations/incident` claim; photo hash stored on claim; MinIO storage
Work-order creation	Fault claim is converted into an OpenMAINT work order; work-order ID is mirrored back to the hotel record	Engineering supervisor	Camel adapter → OpenMAINT `openmaint.v1.cmd.workorder.create`; `integration_entity` mirror
Technician dispatch	Work order is assigned to a technician by skill, location, and priority; status syncs back over NATS	Engineering supervisor, technician	Solver-gateway proposes dispatch sequence (optional); engineering lead confirms
Parts consumption	Technician logs parts used; parts are deducted from the maintenance budget pool	Technician, storekeeper	`resource:budget_maintenance` deduction on work-order close
Expert sign-off	A qualified expert (different from the technician) must sign off before the work order closes — enforced by separation of duties	Maintenance expert, engineering supervisor	`lookup.claims.sod.v1` (inspector ≠ doer); `fn::poce::record_step`
Preventive maintenance schedule	Recurring work orders (lift inspection, HVAC filter, fire alarm test) are generated on a cadence	Engineering supervisor	Recurring `cns://operations/work_order` claims; Kestra-driven schedule
Evidence pack	Every closed work order carries photo evidence, technician notes, parts list, and expert sign-off in one receipt	Auditor, insurer, GM	PoCE finalized session; cryptographic receipt

3. Workflow (Step by Step)

Fault reported → incident claim created with photo (MinIO)
Claim → OpenMAINT work order; ID mirrored in integration_entity
Work order assigned to technician (solver proposes, lead confirms)
Technician completes work, logs parts, uploads completion photo
Parts deducted from resource:budget_maintenance
Expert signs off (SoD: expert ≠ technician)
fn::poce::finalize_session — work order closed; PoCE receipt issued
Status visible to front desk (room back in service) and finance (parts cost)

4. Guard Rails

No auto-close without expert sign-off
No parts deduction without work-order close
No synthetic technician/vendor IDs
OpenMAINT owns asset specification and depreciation; Sovereign owns booking availability and sign-off
If OpenMAINT is unreachable → 502 fail-closed; no invented work-order numbers

5. Evidence & Audit

Work-order claim, OpenMAINT work-order reference, parts log, technician photo, expert signature, PoCE receipt
Receipt verifiable offline by an auditor or insurer against the hotel's public keys