Tenant User — Assets Module (Full Spec)
Section

Climacert‑X — Tenant User: Assets Module (FULL)

Build‑ready specification • Generated on August 19, 2025
Back to Requirements
Table of Contents

1) Goal & Preconditions

Goal

Provide tenant users a complete, secure, and localized experience to view and manage facilities’ assets (Facility → Location → Space → Subspace) including certification status, scoring insights, alerts, and reports — while enforcing permissions and reflecting onboarding, subscription, maintenance, and billing states.

Preconditions

  • Assets are created by Super Admin only, after BoQ payment.
  • Devices sync from Alef into Climacert (device data source), while Asset hierarchy and all metadata live in Climacert.
  • Tenant user has explicit access to one or more facilities (RBAC).
  • Localization: English and Arabic (including RTL).
  • Authentication & session policies follow platform defaults (OTP, password strength, refresh tokens).

2) User Flow (diagram)

Mermaid (placeholder)
flowchart TD
  A[Login / OTP] --> B[Facility List]
  B --> C[Facility View]
  C --> C1[Overview]
  C --> C2[Hierarchy]
  C --> C3[Certification Widget]
  C --> C4[Devices & Status]
  C --> C5[Scoring Details]
  C --> C6[Alerts]
  C --> C7[Reports]
  C --> C8[Settings → Notifications]
  C --> C9[Image Manager]

3) Functional Requirements

3.1 Asset Model & Creation

  • Hierarchy is fixed: Facility → Location → Space → Subspace.
  • Creation is Super Admin only, post‑BoQ payment; created from BoQ‑derived structure.
  • Required facility fields: name, city, country, type, floors ≥1, area >0 (with unit), building age ≥0, image (JPG/PNG ≤10MB).
  • Device inventory syncs from Alef into Climacert. Assets do not exist in Alef; only devices do.

3.2 Facility List

  • Default view: table; card view available via toggle.
  • Columns: Facility ID, Name, Type, Location, Created At, Certification Status, Subscription Status (reflects onboarding, pause, billing).
  • Search, sort, filter, and export (CSV).

3.3 Facility View (Tabs / Sections)

  • Overview: key attributes; certification & subscription badges; activation banners.
  • Hierarchy: tree view of Facility → Location → Space → Subspace.
  • Certification widget: current level, validity period, days remaining, history, QR + 'View Certificate' button.
  • Devices & status: linked devices, last reading, online/offline.
  • Scoring details (separate section): averages and last readings only; calculated score; contributing parameters; no raw data stream stored.
  • Alerts: last 3 months by default; filters by type/date; downgrade reasons, device offline, expiry windows (90/30/7 days).
  • Reports: Audit Report (PDF/CSV) including scoring, level, alerts, and facility structure.
  • Settings → Notifications: toggle notifications per facility; choose recipients from users with access; channels: email, phone, or both.
  • Image manager: tenant can add/replace JPG/PNG ≤10MB; all changes logged (user, timestamp, previous hash).

3.4 Permissions

  • Tenant with facility access: view entire facility, download reports, see subscription end date.
  • Invoices and prices are not in Assets; they live in Billing (separate permission).
  • Tenant cannot delete any asset; only allowed edit is facility image.
  • All actions are server‑side authorized (RBAC).

3.5 Activation & Maintenance

  • Activation requires AND: Super Admin onboarding complete + Tenant confirmation of devices received/installed.
  • If tenant selects 'Not yet', show Help/Contact page; activation remains pending.
  • Pause (tenant‑requested): sets status to 'Paused for Maintenance'; scoring pauses starting at the first day of the next month; intermediate 'Resume scheduled' status appears after unpause request.

3.6 Billing Impact

  • Payment Due (Grace): renewal failure triggers grace countdown; UI shows banner and status; core viewing allowed.
  • Billing Hold (Suspended): grace expires unpaid; certificate and QR hidden; report downloads disabled; alerts visible; image changes still allowed.
  • Reactivation Pending: payment succeeded; awaiting provider webhook; on success, status returns to Active (or remains Resume scheduled if unpause is queued).

4) Non‑Functional Requirements

  • Security & RBAC: server‑side checks; audit logs on sensitive actions (image updates, confirmation, pause/unpause).
  • Performance: facility list load < 2s p95; facility view < 2s p95; scoring compute < 1s p95 (cached).
  • Localization & Accessibility: EN/AR including RTL; keyboard navigation; ARIA for widgets; readable contrasts.

5) Data & Validation Cheatsheet

Facility Fields

  • name: string (2–80)
  • city: string, required
  • country: string, required
  • type: enum { Retail, School, Villa, Office }
  • floors: int ≥ 1
  • area: number > 0 (store unit)
  • age: int ≥ 0
  • image: JPG/PNG ≤ 10MB

IDs & Hierarchy

facilityId, locationId, spaceId, subspaceId: generated by Climacert; stable GUIDs.

Status Values

  • Onboarding: In Progress, Ready for Certification, Pending Tenant Confirmation, Active Certification, Change Required
  • Maintenance: Paused for Maintenance, Resume scheduled (unpause at next month start)
  • Billing: Payment Due (Grace), Billing Hold (Suspended), Reactivation Pending

6) API Stubs (shapes)

GET    /v1/facilities                                  → list facilities (table/card data)
GET    /v1/facilities/{id}                             → facility detail (attributes, devices, certification, alerts)
PATCH  /v1/facilities/{id}/image                       → upload/replace facility image (JPG/PNG ≤10MB)
POST   /v1/facilities/{id}/confirm-install             → { receivedInstalled: true|false } → tenant confirmation
POST   /v1/facilities/{id}/pause                       → { reason?: string } → set Paused for Maintenance
GET    /v1/facilities/{id}/alerts                      → list alerts (default 3 months; filters)
GET    /v1/facilities/{id}/reports/audit               → download report (PDF/CSV) (403 if billing_hold)
GET    /v1/facilities/{id}/billing-status              → { status, graceEndsAt }
POST   /v1/billing/webhooks/payment-updated            → provider events: payment_failed, payment_succeeded
POST   /v1/facilities/{id}/notifications/settings      → set notification recipients and channels

7) UX Copy & Errors (EN/AR)

Banners and CTAs

  • EN: "Shipping and onboarding done. Did you receive and install the devices?" [Yes] [Not yet]
  • AR: «تم الشحن وإنهاء التجهيز. هل استلمت الأجهزة وتم تركيبها؟» [نعم] [ليس بعد]
  • EN: "Payment issue detected. Your subscription renewal failed. X days left in grace period."
  • AR: «مشكلة في الدفع. فشل تجديد الاشتراك. تبقّى X يوم في فترة السماح.»
  • EN: "Certification suspended due to non‑payment. Resolve billing to restore access."
  • AR: «تم إيقاف الشهادة بسبب عدم السداد. الرجاء تسوية الفاتورة لاستعادة الوصول.»

Errors and Tooltips

  • EN: "Image upload failed — must be JPG or PNG under 10 MB."
  • AR: «فشل رفع الصورة — يجب أن تكون JPG أو PNG وأقل من 10 ميغابايت.»
  • EN: "Cannot download while certification is suspended due to billing."
  • AR: «لا يمكن التحميل أثناء إيقاف الشهادة بسبب الفواتير.»
  • EN: "Unpause scheduled. Certification resumes at the start of next month."
  • AR: «تم جدولة إعادة التفعيل. ستستأنف الشهادة مع بداية الشهر القادم.»

8) Edge Cases

  • Tenant selects Not yet at confirmation: show Help/Contact; keep PTC status.
  • Auto‑retry during grace: exponential backoff (e.g., 1h, 12h, 24h) until graceEndsAt.
  • Device offline > threshold hours triggers alert even in billing states (view‑only).
  • Image update allowed during Billing Hold but logged (user, timestamp, previous hash).

9) Acceptance Criteria (Given/When/Then)

  • Given a facility In Progress, When Super Admin completes onboarding, Then status becomes Ready for Certification.
  • Given Ready for Certification, When tenant confirms devices received and installed, Then subscription activates and status becomes Active Certification.
  • Given Active Certification, When tenant requests pause, Then status becomes Paused for Maintenance and scoring pauses at next month start; if unpause requested, status becomes Resume scheduled until the boundary.
  • Given Active Certification, When renewal payment fails, Then status becomes Payment Due (Grace) and grace banner shows countdown.
  • Given Payment Due, When grace expires unpaid, Then status becomes Billing Hold (Suspended); certificate/QR hidden; report downloads return 403.
  • Given Billing Hold, When payment succeeds and webhook is processed, Then status becomes Active Certification (or remains Resume scheduled if an unpause was queued).
  • Given Paused with Resume scheduled and Billing Hold active, When month boundary arrives but billing not Active, Then resume does not occur; remain Resume scheduled until billing Active.