Back
Super Admin: Admin Tab — Spec V1
Print Wireframe

Table of Contents

  1. 1) Goal & Preconditions
  2. 2) User Flow
  3. 3) Functional Requirements
  4. 4) Non‑Functional Requirements
  5. 5) Data & Validation Cheatsheet
  6. 6) API Stubs
  7. 7) UX Copy & Errors (EN/AR)
  8. 8) Edge Cases
  9. 9) Acceptance Criteria
  10. 10) Analytics (events)

Date: 31‑Aug‑2025

1) Goal & Preconditions

Goal. Enable Super Admin to manage Admin accounts (distinct from Tenant Admins).

  • Preconditions
    • Roles: super_admin, admin_super, admin_normal, tenant_admin, tenant_user.
    • Admins are created only by Super Admin.
    • Normal Admins can be scoped to IoT platform(s) and specific customers.

2) User Flow

Flow: Create → Invite → Accept (password+phone) → OTP verified → Assign customers/platforms → Active
States: pending_invite → accepted → phone_verified

3) Functional Requirements

3.1 Create Admin

  • Fields: name, email (unique), role = super_admin | normal_admin.
  • Normal Admin must be scoped:
    • Allowed IoT platform(s): 1..N
    • Customers to manage: multi‑select

3.2 Invitation & Onboarding

  • Invite email with secure one‑time link (24h).
  • First login: set password, add phone, OTP verification.
  • Status visible to Super Admin: Pending, Accepted, Phone Verified.

3.3 Permissions

  • Super Admin unchanged (all tabs).
  • Normal Admin: no IoT Platforms tab and no Users tab.
  • Data filtered to assigned customers. Can add/edit facilities, assets, devices for assigned customers only.
  • Cannot see/manage other admins/users.

3.4 Notifications

Email + in‑app popup when new customer assigned.

3.5 Visibility

Normal Admin sees BoQ, Assets, Devices, Dashboard, Alerts, Pricing, Facilities for assigned customers only.

4) Non‑Functional Requirements

  • RBAC: enforced server‑side.
  • Audit: admin creation, role changes, invitations, assignments, verifications.
  • Performance: Admin list p95 < 1.5s; status checks < 500ms.
  • Security: invitation links one‑time 24h; OTP rules same as Tenant.

5) Data & Validation Cheatsheet

Admin { adminId, name, email, role(super_admin|normal_admin), assignedPlatforms[], assignedCustomers[], status }
Status: pending_invite → accepted → phone_verified
Validation: email unique; role immutable post‑creation; assignedCustomers[] can be empty (see empty state)

6) API Stubs

POST /v1/superadmin/admins
{ name, email, role:"normal_admin"|"super_admin", platforms:["pl_1"], customers:["ten_1","ten_2"] }

GET /v1/superadmin/admins
→ 200 { items:[{ adminId, name, email, role, status, assignedCustomersCount, assignedPlatformsCount }] }

PATCH /v1/superadmin/admins/{id}/assign
{ customers:["ten_1","ten_3"], platforms?:["pl_1","pl_3"] }

GET /v1/superadmin/admins/{id}/status
→ 200 { accepted:true, phoneVerified:true }

POST /v1/auth/admin-invite/accept
{ token:"invite_123", password:"Strong!123", phone:"+971..." }

7) UX Copy & Errors (EN/AR)

  • EN: Invitation sent to {email}. · AR: تم إرسال الدعوة إلى {email}.
  • EN: Admin must accept invitation before assignment. · AR: يجب أن يقبل المشرف الدعوة قبل التعيين.
  • EN: You don’t have permission to view other admins. · AR: ليست لديك صلاحية لعرض مشرفين آخرين.

8) Edge Cases

  • Invite expired → Resend option.
  • Normal Admin assigned to no customer → empty dashboard with CTA “No customers assigned yet.”
  • Reassignment → instant email + in‑app popup.
  • No role upgrade/downgrade after creation.

9) Acceptance Criteria

  • Given Super Admin creates a Normal Admin, When invitation is sent, Then user receives email and status=Pending.
  • Given user accepts and sets password+phone, When OTP verified, Then status=Active.
  • Given Normal Admin logs in, When accessing dashboard, Then only assigned customers’ data is shown.
  • Given a new customer is assigned to a Normal Admin, When assignment is saved, Then email + popup notification are sent.

10) Analytics (events)

admin_created { adminId, role, createdBy }
admin_invite_sent { adminId, email }
admin_invite_accepted { adminId, verified }
admin_customer_assigned { adminId, customerId }
admin_login { adminId, role }