Feature Package PK-04 — Maintenance & Facilities (Common Areas)
Status: Package Specification
Domain: Common Areas / Assets / Maintenance
Maps to: Process 8 (Asset Maintenance & Remediation), Playbook (common-area work orders)
External integration: OpenMAINT (CMMS), MinIO (evidence photos)
1. What This Package Does
Gives the facilities team one auditable system for common-area maintenance — lifts, landscaping, pools, security lighting, corridors — plus unit defect/snag remediation. Replaces WhatsApp fault reports, paper logs, and uncoordinated vendor management.
2. Features & Functionality
| Feature | What it does | Who uses it | What stands behind it |
|---|---|---|---|
| Defect / snag reporting | Resident or staff reports a common-area or unit defect with photo; work-order claim created | Resident, concierge, facilities | cns://claim/type/real-estate/defect; photo hash in claim.evidence; MinIO |
| Work-order creation | Defect claim converted to OpenMAINT work order; WO id mirrored back | Facilities manager | Camel → OpenMAINT; integration_entity (system: "openmaint") |
| Contractor dispatch | Work order assigned to vendor/contractor by skill, location, priority | Facilities manager | Solver-gateway proposes sequence (optional); facilities lead confirms |
| Parts consumption | Contractor logs parts used; charged to service-charge fund or maintenance budget | Contractor, facilities | resource:budget_maintenance deduction on close |
| Expert sign-off | Qualified inspector (different from contractor) signs off before close | Facilities inspector | lookup.claims.sod.v1 (inspector ≠ doer); fn::poce::record_step |
| Preventive maintenance | Recurring work orders (lift certification, pool water test, lift inspection) on cadence | Facilities manager | Recurring cns://operations/work_order; Kestra-driven schedule |
| Common-area status | Lift, pool, gym status (operational/under maintenance/closed) visible to residents | Residents, concierge | resource:common-area status; NATS streaming |
3. Workflow (Defect to Closure)
- Defect reported (lift out of order) → claim with photo; bound to common-area resource
- Claim → OpenMAINT work order; ID mirrored in
integration_entity - Work order assigned to lift vendor (solver proposes, lead confirms)
- Vendor completes work, logs parts, uploads completion photo
- Parts charged to service-charge maintenance fund
- Independent inspector signs off (SoD);
fn::poce::finalize_session; work order closed - Lift status →
OPERATIONAL; residents notified via NATS stream
4. Guard Rails
- No auto-close without expert sign-off
- No parts deduction without work-order close
- No synthetic contractor/vendor IDs
- OpenMAINT owns asset spec/depreciation; Sovereign owns booking availability and sign-off
- If OpenMAINT is unreachable →
502fail-closed; no invented work-order numbers
5. Evidence & Audit
- Defect claim, OpenMAINT work-order ref, parts log, contractor photo, inspector signature, PoCE receipt