Phase 4 — SFMS Core Modules

Status: Shipped ✅ · Owner: SFMS Lead · Duration: 4 weeks · Gate: G4

1. Overview

Phase 4 turns the Data Platform into a real Smart FM application. It implements the operational modules that an FM team actually uses daily: Asset Management (with the Atlas canonical model from Phase 3), Work Orders (planned + reactive, with the full lifecycle), Location & Floor visualisation (ceiling-plan overlay from the KTC fixture), Maintenance scheduling, Documents, Notifications, Reports / exports, and Search.

Phase 4 stays UI-light beyond what the modules need; the rich dashboard studio is Phase 5.

2. Objectives

O4.1 — Full Asset Management module (CRUD, hierarchy, attributes, attachments, history, classification).
O4.2 — Full Work Order module (lifecycle, scheduling, assignment, escalation, history, costs, SLA tracking).
O4.3 — Location module with floor / ceiling-plan visual overlay (using KTC ceiling-plan fixture as proof).
O4.4 — Maintenance scheduling (planned recurring + reactive intake) with calendar view.
O4.5 — Document module (upload, versioning, attach to any entity, preview, OCR optional later).
O4.6 — Notification module (in-app, email, push, webhook) with per-user preferences.
O4.7 — Reports & exports (CSV / Excel / PDF) with templates.
O4.8 — Full-text search across all entities.
O4.9 — Smart FM PDCA baseline KPIs visible (KPI cards on each module landing page).

3. Scope

3.1 In-scope

Asset CRUD UI + advanced search + saved views.
Asset bulk operations (move, retire, reassign).
Asset relationships (parent system, child sub-assets, attached docs).
Work Order full lifecycle (Open → Assigned → In Progress → On Hold → Completed → Verified → Closed).
Work Order types: planned periodic, planned one-off, reactive, inspection, audit.
Recurrence (RRULE) for planned work.
Assignment to user or team; escalation chains.
SLA tracking (response, resolution; calculated automatically).
Work Order checklists / sub-tasks.
Costs (labour, parts, vendor) — placeholder rate cards.
Location hierarchy (Site / Building / Floor / Zone / Room).
Ceiling-plan visual layer: PNG/SVG background per floor, overlay equipment markers at coordinates from the ceiling-plan fixture; clickable to asset detail.
Maintenance calendar (month / week / day).
Document upload (S3) + per-entity attach + versioning.
Notification preferences (per channel, per category) + delivery.
Reports framework + first-set templates (Asset register, Work order summary, KPI report, MTTR/MTBF).
Search (Atlas Search or Meilisearch; ADR-017).

3.2 Out-of-scope

Inventory / spare parts (post-launch).
Vendor portal / external contractor access (post-launch).
AI auto-categorisation of work orders (Phase 6).
Workflow automation beyond simple status flows (Phase 7).

4. Dependencies

Phase 3 complete (entities, ingestion, time-series, tagging).

5. Architecture & Design

5.1 Module structure (apps/web)

/app
  /(app)
    /assets
      page.tsx                   list
      [id]/page.tsx              detail
      [id]/edit/page.tsx
      new/page.tsx
    /work-orders
      page.tsx                   list (Kanban + table views)
      [id]/page.tsx              detail with timeline
      new/page.tsx
      calendar/page.tsx
    /locations
      page.tsx
      [id]/page.tsx              with ceiling-plan overlay
    /documents
      page.tsx
    /reports
      page.tsx
      templates/[id]/page.tsx
    /search
      page.tsx
    /settings/notifications/page.tsx

5.2 Work order lifecycle (state machine)

[Open] ─assign─▶ [Assigned] ─start─▶ [In Progress] ─hold─▶ [On Hold] ─resume─▶ [In Progress]
                                                ─complete─▶ [Completed] ─verify─▶ [Verified] ─close─▶ [Closed]
                                                ─cancel─▶ [Cancelled]

State machine is data-driven and reused by the future Workflow Studio (Phase 7) — same engine, but Phase 4 wires the SFMS-default flow.

5.3 Ceiling-plan visual layer

Background asset: PNG or SVG per floor, uploaded by admin.
Coordinate system: percent-based or pixel-based per floor.
Equipment markers loaded from assets with locationGeometry.
Click marker → asset detail drawer.
Hover marker → asset summary tooltip.
Read-only initially; edit mode in Phase 5 dashboard widgets.

5.4 Notifications

Channels: in-app (always), email, push (FCM/APNs via Phase 8 PWA), webhook.
Categories: work order assigned, work order overdue, SLA breach, anomaly detected, document shared, system alert.
User preferences: per-channel × per-category opt-in/out.
Delivery worker on BullMQ with retry + dead letter.
Admin can configure tenant-level templates.

5.5 Reports framework

Templates defined in YAML/JSON (data sources, columns, filters, group-by, totals).
Output formats: CSV, XLSX, PDF (via headless Chrome / Puppeteer).
Scheduled reports (daily, weekly, monthly) emailed to subscribers.
Manual run from UI; report download archive per tenant.

5.6 Search

Atlas Search (MongoDB-native) or Meilisearch (separate service) — decision in ADR-017.
Indexes: assets, workOrders, locations, documents, users, tags.
Per-tenant index scoping; permission filter applied at query time.

6. Detailed Specifications

6.1 API surface (Phase 4 additions)

# Work Orders
GET    /api/v1/work-orders                  (list, filter, sort, paginate)
POST   /api/v1/work-orders
GET    /api/v1/work-orders/:id
PATCH  /api/v1/work-orders/:id
POST   /api/v1/work-orders/:id/transitions  (state machine transitions)
POST   /api/v1/work-orders/:id/comments
POST   /api/v1/work-orders/:id/attachments
GET    /api/v1/work-orders/:id/history

# Maintenance plans
GET    /api/v1/maintenance-plans
POST   /api/v1/maintenance-plans            (RRULE-based)
PATCH  /api/v1/maintenance-plans/:id

# Locations (ceiling-plan)
POST   /api/v1/locations/:id/floor-plan     (upload SVG/PNG)
GET    /api/v1/locations/:id/equipment      (asset markers)

# Documents
POST   /api/v1/documents                    (multipart upload to S3)
GET    /api/v1/documents
GET    /api/v1/documents/:id/download

# Notifications
GET    /api/v1/notifications                (per-user)
PATCH  /api/v1/notifications/:id            (mark read)
GET    /api/v1/notification-prefs
PATCH  /api/v1/notification-prefs

# Reports
GET    /api/v1/reports                      (templates list)
POST   /api/v1/reports/:id/run              (synchronous or async)
GET    /api/v1/reports/runs/:id

# Search
GET    /api/v1/search?q=…&types=…

6.2 Permissions added

workorder.read workorder.create workorder.update workorder.transition workorder.delete
maintenance.read maintenance.write
location.geometry.write
document.read document.upload document.share document.delete
notification.read notification.send notification.config
report.read report.run report.schedule
search.read

6.3 KPI catalogue (initial)

KPI	Definition	Module
MTTR	Mean Time to Repair	Work Order
MTBF	Mean Time Between Failures	Work Order × Asset
First-time fix rate	Closed without re-open / total	Work Order
SLA compliance	On-time resolution / total	Work Order
Planned vs reactive ratio	planned% : reactive%	Work Order
Asset uptime	(planned-up – downtime) / planned-up	Asset × Telemetry
Open work orders by priority	bucketed counts	Work Order
Cost per asset / per sqm	summed	Work Order + Location

7. Implementation Tasks

Epic 4.A — Asset Management

4.A.1 Asset list (table + filters + saved views).
4.A.2 Asset detail (info, attachments, related work orders, telemetry preview, history).
4.A.3 Asset create/edit with classification picker.
4.A.4 Bulk operations (move, retire, reassign).

Epic 4.B — Work Orders

4.B.1 Work Order list (table + Kanban switch + filters).
4.B.2 Work Order detail (timeline, comments, checklist, attachments, costs).
4.B.3 State machine engine (reusable; Phase 7 plugs in).
4.B.4 Assignment + escalation chain config.
4.B.5 SLA computation + indicators.
4.B.6 Recurrence editor (RRULE).
4.B.7 Calendar view.
4.B.8 Smart FM PDCA-style "this month" KPI cards on landing page.

Epic 4.C — Locations & ceiling plan

4.C.1 Hierarchy CRUD.
4.C.2 Floor-plan upload + viewer.
4.C.3 Marker overlay (clickable; tooltip on hover).
4.C.4 Asset placement editor (drag marker on plan).

Epic 4.D — Documents

4.D.1 Upload to S3 with virus scan (ClamAV optional).
4.D.2 Attach to entity (asset, work order, location, system).
4.D.3 Versioning (auto on re-upload).
4.D.4 Preview for common types (PDF, image, Office via cloud renderer).
4.D.5 Share link (token-based, expiring).

Epic 4.E — Notifications

4.E.1 Delivery worker; channel adapters (in-app, email via SES/SendGrid, webhook).
4.E.2 Per-user preference UI.
4.E.3 Tenant templates (admin).
4.E.4 In-app drawer + unread count.

Epic 4.F — Reports

4.F.1 Template loader (YAML).
4.F.2 Runner (CSV, XLSX via exceljs, PDF via Puppeteer).
4.F.3 Run history + downloads.
4.F.4 Scheduling.
4.F.5 First-set templates: Asset Register, Work Order Summary, KPI Report, MTTR/MTBF.

Epic 4.G — Search

4.G.1 Index pipeline.
4.G.2 Search API + UI.
4.G.3 Permission filter at query time.

Epic 4.H — Smart FM PDCA cards

4.H.1 KPI service producing the catalogue in §6.3.
4.H.2 Landing-page cards on Asset, Work Order, Location modules.

8. Acceptance Criteria

AC4.1 — KTC Asset Ledger fully usable: filter, sort, view detail, see related work orders + telemetry.
AC4.2 — A planned maintenance plan ("monthly chiller inspection") generates work orders on schedule; reactive intake creates a work order from a UI form.
AC4.3 — Work order moves through the full lifecycle with audit; SLA indicator turns red on breach.
AC4.4 — Ceiling-plan view shows KTC floor (using fixture); clicking a marker opens the asset.
AC4.5 — Uploading a document and attaching to an asset works; the asset detail shows it; share link generates and expires.
AC4.6 — Notification preferences enforced; user receives email when assigned a work order (configurable).
AC4.7 — Running the "Work Order Summary" report produces an XLSX that matches the KTC 2024 fixture totals (97% planned vs 3% reactive).
AC4.8 — Search for "chiller" returns assets + work orders + documents from KTC with permission filter respected.
AC4.9 — Landing-page KPI cards compute correctly against fixtures.

9. Test Requirements

Unit: ≥80% on services.
Integration: state machine, RRULE generator, SLA engine, notification delivery (mock channels).
e2e: full work-order lifecycle, ceiling-plan visualisation, document upload + share, report run.
Load: 100 concurrent users browsing assets + work orders; p95 < 500 ms.
Accessibility: WCAG 2.2 AA on every new screen.
Internationalisation: every label translated (English + Japanese).

10. Documentation Requirements

docs/modules/asset.md, work-order.md, location.md, document.md, notification.md, report.md, search.md.
docs/fixtures/ktc_fixture_guide.md (how the KTC sample data is used in tests).
ADR-017: Search engine choice.
Updated OpenAPI spec.
Updated SDK.

11. Sign-off Criteria (Gate G4)

All Acceptance Criteria met.
Product Owner accepts a live walkthrough using the KTC fixture as the demo dataset.
SFMS Lead, Engineering Lead, Product Owner sign _gates/Gate_G4_signoff.md.
Tagged phase-4-v1.0.

12. Risks & Mitigations

Risk	L	I	Mitigation
Ceiling-plan coordinate system inconsistent across floors	3	2	Admin tool to recalibrate; fallback grid editor.
Email deliverability issues	3	3	Verified domain, SPF/DKIM/DMARC; transactional provider.
Report generation slow at scale	2	3	Async runner with progress; size limits per template.
Search query latency	2	3	Atlas Search (managed) with proper indexes; cache hot queries.