1. 1) Purpose
2. 2) Scope
3. 3) Key Concepts & Definitions
4. 4) User Stories
5. 5) UI/UX
6. 6) Data Model (proposed)
7. 7) Permissions & Visibility
8. 8) API (illustrative)
9. 9) Business Rules
10. 10) Audit & Logging
11. 11) Edge Cases
12. 12) Acceptance Criteria

Date: 31‑Aug‑2025

Add a Customer Details capability under Super Admin → Customers to manage per‑facility onboarding defaults for a customer. During facility onboarding, the operator can:

• Attach a Facility Template (per facility).
• Attach an Off‑Time policy (per facility) using a reusable template.
• Super Admin can see all facilities for any customer they are assigned to.

• Who: Super Admin (full), Admin (only for customers explicitly assigned).
• Where: Super Admin → Customers → Customer Profile → Customer Details tab; Facility onboarding flow; Facility settings.
• What: Templates management (Facility Template, Off‑Time Template), assignment at onboarding and later edits; visibility of all facilities for that customer.

Facility Template. Reusable JSON config applied per facility at onboarding (or later): widgets, KPIs, device table columns, alert prefs, thresholds, locale/timezone defaults, certification display rules.

Off‑Time Template. Reusable policy defining when the facility is considered off (e.g., nights/weekends/maintenance). Supports timezones, recurrence rules (RRULE), exceptions.

Assigned Customer Visibility. Super Admin sees all facilities for customers they manage; Admins see only facilities/customers assigned.

• As a Super Admin, I can create/edit Facility Templates and Off‑Time Templates at the customer level.
• As a Super Admin, when I onboard a new facility, I can select a Facility Template and an Off‑Time Template to apply.
• As an Admin (assigned), I can onboard a facility for my assigned customer(s) using available templates.
• As a Super Admin, I can view all facilities of a customer and filter by template usage and Off‑Time policy.
• As a Tenant Admin/User, I can view (read‑only) which template and Off‑Time policy are applied to my facility.

5.1 Customer Profile → Customer Details tab

• Facility Templates — Table: Template Name, Version, Scope (Customer/Global), Last Updated, Assigned Facilities (#), Actions (View, Duplicate, Edit, Archive). New Template drawer: Name, Base (Global/Blank), Description, Version tag, JSON editor (schema validation), Preview.
• Off‑Time Templates — Table: Template Name, Timezone, Recurrence (RRULE summary), Exceptions (#), Assigned Facilities (#), Actions (View, Duplicate, Edit, Archive). New Off‑Time Template drawer: Name, Timezone, Builder (weekday selectors + hours), Recurrence (RRULE), Exceptions (dates), Effective From/To.
• Facilities (Read & Manage) — Grid/Table: Facility Name, Location, Status, Template, Off‑Time, Last Updated, Actions (Open Facility, Change Templates).

5.2 Facility Onboarding Flow

Step: Defaults

• Facility Template select: [None] + searchable list + JSON preview.
• Off‑Time Template select: [None] + searchable list + human‑readable summary (e.g., Mon–Fri 20:00–06:00; Sat–Sun All Day).
• Info note: “Templates can be changed later from Facility Settings.”

5.3 Facility Settings → Policies sub‑tab

Read current assignments; Change action (role‑gated) with audit note prompt.

FacilityTemplate {
  id: UUID,
  name: string,
  scope: enum[global, customer],
  customer_id: UUID | null,
  version: string,
  description: string,
  payload: jsonb,    // KPI layout, device columns, alerts prefs, etc.
  created_by: user_id,
  created_at: timestamp,
  updated_at: timestamp,
  status: enum[active, archived]
}

OffTimeTemplate {
  id: UUID,
  name: string,
  customer_id: UUID | null,
  timezone: IANA_tz,
  rrule: string,     // e.g., RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR
  daily_windows: [ { day: MON, start: "20:00", end: "06:00+1" } ],
  exceptions: [ { date: "2025-09-12", include: false } ],
  effective_from: date,
  effective_to: date | null,
  created_by: user_id,
  created_at: timestamp,
  updated_at: timestamp,
  status: enum[active, archived]
}

FacilitySettings {
  facility_id: UUID (PK/FK),
  facility_template_id: UUID | null,
  off_time_template_id: UUID | null,
  overrides: jsonb,  // per-facility deviations from template
  updated_by: user_id,
  updated_at: timestamp
}

Summary matrix:

• Super Admin: Create/Edit Facility & Off‑Time templates; assign at onboarding; change post‑onboarding; view all facilities.
• Admin (assigned): Same within assigned customers.
• Tenant Admin/User: Read‑only view of applied templates on their facilities.

GET  /customers/{id}/templates/facility
POST /customers/{id}/templates/facility
PATCH /templates/facility/{templateId}

GET  /customers/{id}/templates/offtime
POST /customers/{id}/templates/offtime
PATCH /templates/offtime/{templateId}

GET  /customers/{id}/facilities            // includes template bindings
POST /facilities                            // includes facility_template_id, off_time_template_id
PATCH /facilities/{id}/settings             // update bindings/overrides

Response embed example:
{
  "facility_id": "...",
  "facility_template": {"id": "...", "name": "Retail‑Lite v1"},
  "off_time": {"id": "...", "summary": "Mon–Fri 20:00–06:00, Weekend all‑day"}
}

• If no template chosen at onboarding, defaults remain None; facility uses platform defaults.
• Off‑Time affects alerting, certification scheduling, and optional KPI smoothing (see existing specs).
• Changing a template prompts confirmation and impact summary; applies prospectively; historical data not mutated.
• Archived templates cannot be newly assigned but remain visible where previously applied.
• Timezone is required on Off‑Time Templates; evaluate schedules in facility’s timezone.

Log create/update/archive on templates and any facility template re‑assignment with: actor, timestamp, reason, previous → new values. Expose in Facility Settings → Policies → History.

• Cross‑region customers: validate Off‑Time templates against local timezone.
• DST changes: compute using IANA tz; RRULE expansions must respect DST.
• Facility deletion/unassignment: retain historical audit; orphaned templates remain available unless archived.

• AC1: During facility onboarding, operator can select Facility Template and Off‑Time Template from dropdowns; both save successfully.
• AC2: Super Admin can create/edit templates from Customer Details and see live counts of assigned facilities.
• AC3: Super Admin/Admin can search and filter facilities by assigned templates.
• AC4: Tenant users can see (read‑only) which templates apply to their facility.
• AC5: All actions are captured in audit logs.