From 0768622a521f49c3a561eddf30cbf4b972d4c88e Mon Sep 17 00:00:00 2001 From: root Date: Fri, 24 Jul 2026 11:34:39 -0400 Subject: [PATCH] docs: define customer portal requirements --- CHANGELOG.md | 15 ++ PORTAL-GAP-ANALYSIS.md | 333 +++++++++++++++++++++++ PORTAL-REQUIREMENTS.md | 598 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 946 insertions(+) create mode 100644 PORTAL-GAP-ANALYSIS.md create mode 100644 PORTAL-REQUIREMENTS.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e27f0dd..2ac5e31 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # voipsimplicity.com — Migration CHANGELOG +## 2026-07-24 — Portal requirements documentation (revised v2.0) + +### Revised +- **[PORTAL-REQUIREMENTS.md](./PORTAL-REQUIREMENTS.md)** — replaced with comprehensive v1.0 covering all 7 owner-specified requirement areas: + 1. **My Dashboard:** per-customer stats, lists (extensions/DIDs/queues/attendants), music on hold, time frames, graphical topology (Phase 3). + 2. **Call History:** unified search (name + phone), direction/status/destination columns, recording playback (conditional), voicemail transcripts, CSV export (all + filtered), CDR data-source caveat (RingLogix CDR endpoints all return 404). + 3. **Marketplace:** plans/features catalog, cart, per-extension vs per-account distinction, one/multiple/all extension selection, immediate provisioning vs request-discussion choice, audit log + ticket + notification, approval boundaries, data-source caveat. + 4. **Billing:** plan/price summary, included + available features, prior invoices list (date/number/amount/status), inline framed invoice viewer (closeable), download individual/multiple/all, separate secure card update path, NEVER store card data in browser storage. + 5. **My Info:** view/update name/email/phone/address, separately update payment method, add/manage authorized users with RBAC/invitation/audit trail. + 6. **Site Login:** split-half login page, authenticate by domain ID/account email/authorized-user email, password reset, MFA/one-time token exploration (email/SMS) with rate limiting and recovery, order-services contact form. + 7. **Screenshot-informed features:** ViiBE seller-side (Accounts, Quotes, Products, LNP, Number Orders, CNAM, Mobile Connect, Reports) and NetSapiens customer/manager views (Home/Statistics, Domains, SIP Trunks, Phone Inventory, E911, Call History, Contacts, Answer Rules, Time Frames, Voicemail/Settings, Music/Messages, Call-Center Queues/Statistics, Auto Attendants). Staff-only vs customer views separated. Provider/API unknowns marked — does not claim RingLogix supports unsupported endpoints. +- Document includes sources section (owner screenshots + Obsidian notes), source-of-truth table with API availability, RBAC/tenant isolation rules, audit/compliance requirements, phased MVP sequence (4 phases), acceptance criteria, unknowns/caveats, and out-of-scope items. +- **[PORTAL-GAP-ANALYSIS.md](./PORTAL-GAP-ANALYSIS.md)** — replaced with v2.0, reorganized to map gap analysis directly to the 7 owner requirement areas. Includes source-of-truth data availability matrix (19 data categories with API status), screenshot-to-feature mapping for both Viirtue and Apollo screenshots, design/UX comparison, technical architecture gaps (backend DB, payment gateway, file storage), and P0–P4 priority matrix. References 22 owner-provided screenshots and Obsidian notes. +- No code or configuration changes — documentation only. Portal deployment, DNS, APIs, and credentials unchanged. + ## 2026-07-24 — Entity record started ### Added diff --git a/PORTAL-GAP-ANALYSIS.md b/PORTAL-GAP-ANALYSIS.md new file mode 100644 index 0000000..9d36cc9 --- /dev/null +++ b/PORTAL-GAP-ANALYSIS.md @@ -0,0 +1,333 @@ +# my.voipsimplicity.com — Portal Gap Analysis + +**Status:** Documentation-only analysis +**Version:** 2.0.0 (revised for owner requirement areas) +**Date:** July 24, 2026 +**References:** [PORTAL-REQUIREMENTS.md](./PORTAL-REQUIREMENTS.md) — canonical requirements doc; Viirtue/ViiBE seller portal (`voipsimplicity.viibewithus.com`, v2.8.0) and Apollo/NetSapiens manager+user portals (`portal.voipsimplicity.com`, v44.5.1) — 22 screenshots provided by owner Germaine Brown; [Obsidian notes](#sources) from owner. + +> **Purpose:** Map the 7 owner-specified requirement areas (Dashboard, Call History, Marketplace, Billing, My Info, Site Login, Screenshot Groups) against current portal state and identify what needs to be built, wired, or deferred. + +--- + +## Table of Contents + +1. [Sources](#sources) +2. [Gap Summary by Requirement Area](#gap-summary-by-requirement-area) +3. [Area 1: My Dashboard](#area-1-my-dashboard) +4. [Area 2: Call History](#area-2-call-history) +5. [Area 3: Marketplace](#area-3-marketplace) +6. [Area 4: Billing](#area-4-billing) +7. [Area 5: My Info](#area-5-my-info) +8. [Area 6: Site Login](#area-6-site-login) +9. [Area 7: Screenshot-Informed Features](#area-7-screenshot-informed-features) +10. [Source of Truth & Data Availability](#source-of-truth--data-availability) +11. [Technical Architecture Gaps](#technical-architecture-gaps) +12. [Implementation Priority Matrix](#implementation-priority-matrix) + +--- + +## Sources + +| Source | Type | Provider | Date | +|---|---|---|---| +| ViiBE/Viirtue seller portal | Screenshots (Accounts, Quotes, Products, LNP, Number Orders, CNAM, Mobile Connect, Reports) | Owner | July 2026 | +| Apollo/NetSapiens customer + manager portals | Screenshots (Home/Statistics, Domains, SIP Trunks, Phone Inventory, E911, Call History, Contacts, Answer Rules, Time Frames, Voicemail/Settings, Music/Messages, Call-Center Queues/Statistics, Auto Attendants) | Owner | July 2026 | +| Owner Obsidian notes | Design preferences, feature wishlist, operational constraints | Germaine Brown | July 2026 | +| Deployed portal | `/home/myvoip/htdocs/my.voipsimplicity.com/index.html` on app3 | Live system | July 2026 | +| `voip-portal-development` skill | 13 reference files covering API, patterns, deployment | Hermes skill repo | Ongoing | + +--- + +## Gap Summary by Requirement Area + +| # | Requirement Area | Current State | Gap Severity | Priority | +|---|---|---|---|---| +| 1 | **My Dashboard** | Stats + basic lists. No topology, MoH, or time frames. | Medium | Phase 1–3 | +| 2 | **Call History** | Unified search + export implemented. No recordings, no CDR data. | **High** | Phase 1–3 | +| 3 | **Marketplace** | Catalog + add-on request flow exists. No cart, no provisioning, no order tracking. | Medium | Phase 2 | +| 4 | **Billing** | Plan card + CC form (sessionStorage). No invoices, no gateway. | **High** | Phase 2 | +| 5 | **My Info** | Contact editing + CC form. No authorized users, no RBAC. | Medium | Phase 2 | +| 6 | **Site Login** | Split-half page + session restore. No MFA, no password reset, no contact form. | Medium | Phase 1–3 | +| 7 | **Screenshot Features** | 12+ feature sections visible in screenshots, 0 implemented. | **High** | Phase 1–4 | + +**Overall gap severity:** High. The portal is a functional skeleton — login, nav, dashboard stats, call history search, and marketplace add-on requests work. Everything beyond these (MFA, billing invoices, authorized users, device lists, answering rules, time frames, contacts, music on hold, quotes/orders, reports) is absent or placeholder. Refer to [PORTAL-REQUIREMENTS.md](./PORTAL-REQUIREMENTS.md) for the complete phased plan. + +--- + +## Area 1: My Dashboard + +### Legend + +| Symbol | Meaning | +|---|---| +| ✅ | Exists in current portal | +| 🟡 | Partially exists (skeleton, needs wiring) | +| ❌ | Missing entirely | +| ⬜ | Deferred (Phase 3+) | + +### Dashboard Feature Gap + +| Feature | Current | Required By | Gap Detail | +|---|---|---|---| +| Per-customer aggregate stats (extensions, queues, DIDs, attendants) | ✅ | Phase 1 | Wired via RingLogix API. Filter to 100–399 for real extensions. | +| Extension list (name, email, voicemail badge) | ✅ | Phase 1 | Implemented. System routes hidden by toggle. | +| DID inventory list | 🟡 | Phase 1 | `phonenumber/read` returns ALL DIDs — filter client-side by `dialrule_domain`. | +| Call queue list (name, strategy, members) | 🟡 | Phase 1 | `callqueue/read` wired. Members count not yet displayed. | +| Auto attendant list (name, schedule, prompt) | ✅ | Phase 1 | `attendant/read` wired. Menu options NOT available via API. | +| Subscribed plan display | 🟡 | Phase 1 | Hardcoded in billing card. Needs RingLogix catalog integration. | +| Music on Hold display | ❌ | Phase 3 | No confirmed RingLogix endpoint. Apollo screenshots show MoH UI. | +| Time Frames list | ❌ | Phase 1 (Apollo ref) | `timeframe/read` endpoint confirmed; not yet wired in portal. Apollo shows Name, Owner, When, Recurrence, Ends On columns. | +| Graphical phone-system topology | ❌ | Phase 3 | No current implementation. Requires Canvas/SVG rendering of DID→TF→AA→Queue→Ext routing graph. | + +**Dashboard gap assessment:** Current dashboard covers Phase 1 aggregate stats and basic lists. Missing: time frames (Phase 1 wiring needed), music on hold (blocked on API), topology graph (Phase 3 build), and plan display integration. + +--- + +## Area 2: Call History + +### Call History Feature Gap + +| Feature | Current | Required By | Gap Detail | +|---|---|---|---| +| Unified search (name + phone, single input) | ✅ | Phase 1 | `oninput` handler, real-time filtering, `data-search` attributes. | +| Direction indicators (↓ incoming, ↑ outgoing) | ✅ | Phase 1 | Teal/gold color scheme implemented. | +| Date/Time, Direction, Name, Phone, Destination, Duration columns | ✅ | Phase 1 | All implemented in call-history-pattern. | +| Status badges (Answered/Missed/Voicemail) | ✅ | Phase 1 | Color-coded badges implemented. | +| Date range filter (Today/Week/Month/All) | 🟡 | Phase 1 | Time period filter in skill; Apollo shows calendar date picker. Enhance to date-range picker. | +| CSV Export (All + Current View) | ✅ | Phase 1 | Both export buttons implemented. Arrow character cleanup. | +| Recording playback (inline, conditional on enabled) | 🟡 | Phase 3 | Play button UI exists. Blocked on Wasabi S3 signed-URL generation and per-domain recording-enabled check. | +| Voicemail transcript (inline modal) | 🟡 | Phase 3 | Transcript button + modal UI implemented. Blocked on CDR/vmail data availability. | +| **CDR data availability** | ❌ | Phase 1 | **CRITICAL BLOCKER.** `cdr`, `call_detail_record`, `callhistory` all return 404 from RingLogix API. All Call History features are placeholder until an alternative data source is found (NetSapiens CDR export, RingLogix reseller-level reporting, or direct PBX collection). | + +**Call History gap assessment:** The strongest area in the current portal — search, export, and rendering are well-implemented. The single critical blocker is CDR data availability. Without it, Call History can only show mock/placeholder data. Secondary gaps: recording playback (Wasabi integration), voicemail transcripts (data source), and date-range picker enhancement. + +--- + +## Area 3: Marketplace + +### Marketplace Feature Gap + +| Feature | Current | Required By | Gap Detail | +|---|---|---|---| +| Plans/features catalog browsing | ✅ | Phase 2 | Cards with name, description, price, perLine flag. 10 hardcoded items. | +| Per-extension vs per-account distinction | ✅ | Phase 2 | `perLine: true/false/'did'` flags. Event delegation pattern. | +| Extension selector modal (single extension) | ✅ | Phase 2 | Modal with dropdown (100-399). | +| **Multiple/all extensions selection** | ❌ | Phase 2 | Only single extension selection implemented. Need checkboxes + "Select All" for multi-extension add-ons. | +| Per-DID selector (SMS/Text Messaging) | ✅ | Phase 2 | DID dropdown from `extension_list` filtered by 10+ digit regex. | +| Cart metaphor | ❌ | Phase 2 | No cart — items processed one at a time. Need running cart before submission. | +| Immediate provisioning vs request-discussion choice | ❌ | Phase 2 | Only "Request Discussion" flow implemented. Immediate provisioning requires RingLogix write API (unconfirmed). | +| Audit log entries for all changes | ✅ | Phase 2 | `auditLog.push()` on every add-on request. | +| Staff-visible ticket/notification | 🟡 | Phase 2 | Audit entries logged; no separate ticket UI or email notification pipeline. | +| Approval boundaries / staff review workflow | ❌ | Phase 2 | No approval workflow. All requests go to manual review. | + +**Marketplace gap assessment:** Add-on request flow is functional. Missing: multiple/all extensions selection, cart metaphor, provisioning choice (blocked on write API), and formal approval/ticket workflow. The catalog is hardcoded — no confirmed RingLogix product catalog API. + +--- + +## Area 4: Billing + +### Billing Feature Gap + +| Feature | Current | Required By | Gap Detail | +|---|---|---|---| +| Plan/price summary card | 🟡 | Phase 2 | Hardcoded domain name + pricing. Needs RingLogix plan integration. | +| Included features display | 🟡 | Phase 2 | Not implemented. Teal "Active" badges for plan features. | +| Available but unsubscribed options | ❌ | Phase 2 | Not implemented. Gray "Available" badges with Marketplace link. | +| Prior invoices list (date, number, amount, status) | ❌ | Phase 2 | **BLOCKED.** No confirmed RingLogix billing API. RingOS billing "coming soon." | +| Inline framed invoice viewer (closeable) | ❌ | Phase 2 | **BLOCKED** on invoice data source. | +| Download individual/multiple/all invoices | ❌ | Phase 2 | **BLOCKED** on invoice data source. | +| Separate secure card update path | 🟡 | Phase 2 | CC form exists in billing view but uses `sessionStorage` — **NOT PCI-compliant.** Needs Stripe Elements or equivalent gateway. | +| Card data never in browser storage | ❌ | Phase 2 | Current implementation stores last-4 in sessionStorage. Must migrate to tokenized gateway. | +| Payment history | ❌ | Phase 2 | Viirtue shows Payments & Credits, Late Payers. Not in current portal. | +| Tax exemption / tax reports | ❌ | Phase 4 | Viirtue shows Tax Exemptions, Tax Liability, Tax Summary. Deferred. | +| Auto-pay toggle | ❌ | Phase 3 | Not in current portal. Requires payment gateway integration. | + +**Billing gap assessment:** The billing view is a skeleton. The critical blocker is RingLogix RingOS billing API availability ("coming soon"). Without it, invoices must be manually uploaded or sourced from Stripe. Payment method needs a full PCI-compliant overhaul (Stripe Elements). Viirtue's Revenue/Billing/Compliance reports are the target model. + +--- + +## Area 5: My Info + +### My Info Feature Gap + +| Feature | Current | Required By | Gap Detail | +|---|---|---|---| +| View/update account name | ✅ | Phase 2 | Editable contact form with toggle. | +| View/update account email | ✅ | Phase 2 | Editable. | +| View/update phone | ✅ | Phase 2 | Editable. | +| View/update address | ❌ | Phase 2 | Not in current form. Needs street/city/state/ZIP fields. | +| Company name (read-only) | 🟡 | Phase 2 | Displayed in billing but not in My Info view. | +| Domain ID (read-only) | ❌ | Phase 2 | Not displayed. | +| Separately update payment method | 🟡 | Phase 2 | CC form in same billing view, not isolated. Needs separate secure path. | +| Add/manage authorized users | ❌ | Phase 2 | Not implemented. Viirtue shows multiple accounts per seller; Apollo shows multi-user domains. | +| RBAC for authorized users | ❌ | Phase 2 | Need roles: Customer Admin, Authorized User, View-Only. | +| Invitation flow | ❌ | Phase 2 | No invitation email flow. | +| Audit trail for user management | ❌ | Phase 2 | No audit entries for user add/remove/role-change. | +| Password change (self-service) | ❌ | Phase 1 | Not implemented. Viirtue and Apollo both imply password management. | +| Notification preferences | ❌ | Phase 4 | Apollo shows voicemail email, missed call, mailbox full notifications. | + +**My Info gap assessment:** Basic contact editing exists. Major gaps: authorized user management with RBAC (entirely absent), address fields, payment method isolation, password self-service, and notification preferences. The Viirtue Account Detail page (with tabs: Details, Quotes, Number Orders, Notes, Storage) is the primary model for Phase 2+. + +--- + +## Area 6: Site Login + +### Site Login Feature Gap + +| Feature | Current | Required By | Gap Detail | +|---|---|---|---| +| Split-half login page (login left, help right) | ✅ | Phase 1 | Implemented. Navy gradient left, white right. Mobile stacks vertically. | +| Authenticate by domain ID | ✅ | Phase 1 | Domain ID → password. Customer→domain mapping hardcoded for demo. | +| Authenticate by account email | ✅ | Phase 1 | Email → password. | +| Authenticate by authorized-user email | ❌ | Phase 2 | Requires authorized user table + per-user credentials. | +| Staff login (`info@voipsimplicity.com`) | ✅ | Phase 1 | Hardcoded. Staff badge + domain selector on success. | +| Session persistence (refresh/back button) | ✅ | Phase 1 | `sessionStorage` — cleared on logout. | +| Password reset | ❌ | Phase 1 | Not implemented. Needs email-based token flow with rate limiting. | +| MFA / one-time token (email/SMS) | ❌ | Phase 3 | Not implemented. Exploration target: Twilio Verify, email OTP, TOTP apps. | +| Rate limiting on login attempts | ❌ | Phase 1 | No rate limiting in current implementation. | +| MFA recovery codes | ❌ | Phase 3 | Generated on enrollment, shown once. | +| Order-services contact form | ❌ | Phase 3 | Not implemented. Needs Name/Email/Phone/Company/Interest/Message fields on login page. | + +**Site Login gap assessment:** Core authentication (split-half page, domain ID/email login, staff login, session persistence) is solid. Missing: authorized-user email auth, password reset, MFA, rate limiting, and the order-services contact form. MFA is a Phase 3 exploration target due to SMS dependency on Twilio provisioning and A2P 10DLC registration. + +--- + +## Area 7: Screenshot-Informed Features + +The owner provided 22+ screenshots from Viirtue/ViiBE (seller-side) and Apollo/NetSapiens (customer + manager). These reveal 12+ feature sections not in the current portal. **Staff-only views are marked.** Provider/API data availability is noted — this document does NOT claim RingLogix supports endpoints that are unverified. + +### 7.1 ViiBE/Viirtue Seller-Side Screenshots (Staff-Only) + +| Screenshot Feature | Current Portal | Required By | API Availability | Gap Detail | +|---|---|---|---|---| +| **Accounts** (account list, tabs) | 🟡 | Phase 1 | `domain/read` ✅ | Admin Panel shows 14-domain roster. Missing: per-account detail with Details/Quotes/Number Orders/Notes/Storage tabs. | +| **Quotes** (Quote Name, Company, Owner, Status; create/edit) | ❌ | Phase 2 | ❌ No RingLogix quoting API | Need portal DB for quotes. Model: Viirtue table + line-item creation from product catalog. | +| **Products** (product catalog, per-seat/per-account pricing) | ❌ | Phase 2 | ❌ Unknown | Marketplace has hardcoded catalog. Staff need catalog management UI. | +| **LNP** (Port Date, Customer, Port Type, BTN, Status) | ❌ | Phase 4 | ❌ Unknown | Viirtue LNP integration. RingLogix porting API TBD. | +| **Number Orders** (Order No., Customer, Date, Description, Status) | ❌ | Phase 4 | ❌ Unknown | Viirtue number ordering. | +| **CNAM** (Order No., CNAM Value, Telephone No., Status) | ❌ | Phase 4 | ❌ Unknown | Viirtue CNAM tab. | +| **Mobile Connect** | ❌ | Deferred | ❌ Not available | Future: softphone/mobile app pairing. | +| **Reports** (Monthly Revenue, Recurring Revenue Growth, Revenue Projection) | ❌ | Phase 4 | ⚠️ Partial (stats available; CDR not) | Staff revenue dashboard. Viirtue Reports landing model. | +| **Account Notes** (staff-only timeline per account) | ❌ | Phase 4 | N/A (portal DB) | Staff notes per customer account. | +| **Document Storage** (file upload per account: LOAs, agreements) | ❌ | Phase 4 | N/A (portal DB + S3) | File upload/download per account. | + +### 7.2 Apollo/NetSapiens Customer + Manager Views + +| Screenshot Feature | Current | Required By | API Availability | Customer/Staff? | +|---|---|---|---|---| +| **Home / Statistics** | ✅ | Phase 1 | `subscriber/read`, `callqueue/read`, etc. ✅ | Customer + Staff | +| **Domains** | ✅ | Phase 1 | `domain/read` ✅ | Staff (domain selector) | +| **SIP Trunks** | ❌ | Phase 4 | ❌ Unknown — no confirmed endpoint | Customer/Staff | +| **Phone Inventory / Devices** | ❌ | Phase 4 | ⚠️ `mac/read` may exist — unverified | Customer | +| **E911 Inventory** | ❌ | Phase 4 | ❌ Unknown — no confirmed endpoint | Customer/Staff | +| **Call History** (date picker, recordings, blocked numbers) | 🟡 | Phase 1 | ❌ CDR endpoints return 404 | Customer | +| **Contacts** (Name, Number, Status, Department, Email; add/import/export) | ❌ | Phase 4 | ❌ Not available via RingLogix API | Customer | +| **Answer Rules** (Time Frame, Ring targets, Allow/Block, fallback) | ❌ | Phase 4 | ❌ Unknown | Customer | +| **Time Frames** (Name, Owner, When, Recurrence, Ends On; drag-to-reorder) | ❌ | Phase 1 | `timeframe/read` ✅ | Customer | +| **User Voicemail / Settings** (inbox, greetings, notifications, transcription) | 🟡 | Phase 3 | ⚠️ `vmail/read` may exist — unverified | Customer | +| **Music / Messages** (Add Music, Add Introduction, Add Message) | ❌ | Phase 3 | ❌ Unknown | Customer/Staff | +| **Call-Center Queues / Statistics** | 🟡 | Phase 1 | `callqueue/read` ✅ (list; real-time stats unknown) | Customer/Staff | +| **Auto Attendants** | ✅ | Phase 1 | `attendant/read` ✅ (menu detail NOT available) | Customer/Staff | + +### 7.3 Design & UX Comparison (from Screenshots) + +| Aspect | Current Portal | Reference Portals | Verdict | +|---|---|---|---| +| Theme | Light/neutral (teal, gold, navy) | Viirtue: dark sidebar, light content; Apollo: light all | Current matches owner intent. No dark mode needed. | +| Navigation | Vertical sidebar | Viirtue: sidebar; Apollo: horizontal icon bar | Sidebar is canonical — keep it. | +| Card layout | Stat cards, billing cards | Apollo: two-column card layout on Home | Consistent. | +| Data tables | Call logs, extensions | Both: tables with sort, search, pagination | Consistent. | +| Empty states | ✅ Canonical "No data available." | Viirtue: "Nothing to see here!"; Apollo: "No new messages." | Current canonical state is correct per skill rules. | +| Mobile | ✅ Hamburger menu, viewport meta | Reference portals appear desktop-only in screenshots | Current portal is *more* mobile-ready than references. | + +--- + +## Source of Truth & Data Availability + +| Data Category | Current Source | Required Source | Status | +|---|---|---|---| +| Extensions | RingLogix `subscriber/read` | Same | ✅ Wired | +| Domains | RingLogix `domain/read` | Same | ✅ Wired | +| DIDs | RingLogix `phonenumber/read` | Same (filter client-side) | ✅ Wired | +| Call Queues | RingLogix `callqueue/read` | Same | ✅ Wired | +| Auto Attendants | RingLogix `attendant/read` | Same | ✅ Wired | +| Time Frames | RingLogix `timeframe/read` | Same | ❌ Not yet wired | +| Call History (CDRs) | RingLogix | RingLogix / NetSapiens / alternative | ❌ **BLOCKED** — `cdr`, `call_detail_record`, `callhistory` all return 404 | +| Call Recordings | Wasabi S3 (RingLogix writes to it) | Wasabi S3 signed URLs | 🟡 Storage confirmed; signed-URL generation TBD | +| Voicemail | Not wired | RingLogix `vmail/read` (unverified) | ❌ Need API verification | +| Device Registration | Not wired | RingLogix `mac/read` (unverified) | ❌ Need API verification | +| Billing / Invoices | Not applicable | RingLogix RingOS (future) or Stripe | ❌ **BLOCKED** — RingOS billing "coming soon" | +| Payment Methods | `sessionStorage` only | Stripe Elements or equivalent | ❌ Need gateway integration | +| Quotes / Orders | Not applicable | Portal DB (new) or Viirtue API | ❌ Need backend DB | +| Notes / Documents | Not applicable | Portal DB + S3/disk | ❌ Need backend storage | +| Products Catalog | Hardcoded in portal JS | Portal DB or RingLogix catalog API | 🟡 Hardcoded works for MVP; need management UI | +| Customer Profiles | `sessionStorage` only | Portal DB | ❌ Need persistent storage | +| SIP Trunks | Not applicable | RingLogix (unverified) | ❌ Unknown endpoint | +| E911 | Not applicable | RingLogix (unverified) | ❌ Unknown endpoint | +| Answer Rules | Not applicable | RingLogix (unverified) | ❌ Unknown endpoint | +| CNAM | Not applicable | Viirtue (unverified) | ❌ Unknown endpoint | + +--- + +## Technical Architecture Gaps + +| Aspect | Current | Needed | Gap | +|---|---|---|---| +| **Architecture** | Single-file HTML SPA (no backend) | Backend for portal DB, payment gateway, file storage, API proxying | ❌ Major gap | +| **Data persistence** | `sessionStorage` only (volatile) | Server-side DB for quotes, orders, notes, products, customer profiles, authorized users | ❌ Need database | +| **API key protection** | Unknown — may be client-side | Server-side proxy to protect RingLogix credentials | 🟡 Needs audit | +| **File upload** | Not supported | Document storage (LOAs, agreements, MoH audio) | ❌ Need upload + storage | +| **Payment processing** | Not integrated | Tokenized payment gateway (Stripe Elements) | ❌ Need gateway | +| **Multi-user per domain** | Not supported | Authorized user management per customer account | ❌ Need user management | +| **PDF generation** | Not supported | Invoice PDF download | ❌ Need PDF gen or stored PDFs | +| **File size** | ~1,500 lines (July 2026) | Could grow to 5,000+ with full feature set | 🟡 Monitor; consider module splitting | +| **Build step** | None (single file) | May need build step if file grows too large | 🟡 Monitor | + +--- + +## Implementation Priority Matrix + +| Priority | What | Effort | Depends On | +|---|---|---|---| +| **P0 — Immediate (blocks everything)** | | | | +| P0 | CDR data source for Call History | Investigation | RingLogix support / NetSapiens CDR / alternative | +| P0 | Data isolation enforcement for all views | Low | RBAC infrastructure (exists) | +| **P1 — Phase 1: Foundation** | | | | +| P1 | Time Frames wiring (`timeframe/read` → portal) | Low | RingLogix API | +| P1 | Password reset flow | Medium | Email infrastructure | +| P1 | Call History date range filter (calendar picker) | Low | CDR data | +| P1 | Dashboard plan display integration | Low | RingLogix catalog or hardcoded | +| **P2 — Phase 2: Self-Service** | | | | +| P2 | Contact info (address fields, read-only domain ID) | Low | None | +| P2 | Authorized user management (add/remove/RBAC/invitation) | High | Backend DB + email | +| P2 | Marketplace: multi-extension selection + cart | Medium | None (frontend only) | +| P2 | Marketplace: provisioning choice UI | Low | Write API (for immediate; request-discussion needs no API) | +| P2 | Billing: invoice list + viewer (placeholder until API available) | Medium | Backend DB or manual invoice storage | +| P2 | Payment method: Stripe Elements integration | High | Stripe account + backend | +| P2 | Login: rate limiting | Medium | Backend auth | +| P2 | Login: authorized-user email authentication | Medium | Authorized user DB | +| **P3 — Phase 3: Advanced** | | | | +| P3 | Phone-system topology graph | High | All system objects wired | +| P3 | MFA / one-time token (email/SMS) | High | Backend auth + email/SMS infrastructure | +| P3 | Call recording playback (Wasabi S3) | Medium | Signed URL generation | +| P3 | Voicemail settings/inbox | Medium | `vmail/read` API verification | +| P3 | Music on Hold display | Medium | File upload + storage | +| P3 | Order-services contact form | Low | Email infrastructure | +| P3 | Auto-pay toggle | Medium | Payment gateway | +| **P4 — Phase 4: Feature Parity** | | | | +| P4 | Phones/Devices list | Medium | `mac/read` API verification | +| P4 | Contacts (CRUD + import/export) | High | Backend DB | +| P4 | Answering Rules | High | Backend DB or unverified API | +| P4 | E911 inventory | Medium | Unknown API | +| P4 | SIP trunk status | Medium | Unknown API | +| P4 | Quotes + Orders pipeline | High | Backend DB | +| P4 | Staff Reports | High | All data sources | +| P4 | CNAM management | Medium | Unknown API | +| P4 | LNP / Number Orders | High | Backend DB | +| P4 | Account Notes (staff) | Low | Backend DB | +| P4 | Document Storage | Medium | File storage | +| P4 | Notification preferences | Medium | Backend DB + email | + +--- + +*Gap analysis maintained in `/root/projects/voipsimplicity/PORTAL-GAP-ANALYSIS.md`. Companion requirements at [PORTAL-REQUIREMENTS.md](./PORTAL-REQUIREMENTS.md).* diff --git a/PORTAL-REQUIREMENTS.md b/PORTAL-REQUIREMENTS.md new file mode 100644 index 0000000..1f4d1e4 --- /dev/null +++ b/PORTAL-REQUIREMENTS.md @@ -0,0 +1,598 @@ +# my.voipsimplicity.com — Portal Requirements + +**Version:** 1.0 +**Date:** 2026-07-24 +**Status:** Pre-MVP documentation +**Owner:** Germaine Brown (VoIPSimplicity LLC) +**Platform:** RingLogix-powered, deployed on app3 (CloudPanel CE) +**Design:** Light, mobile-first, single-file HTML SPA (see [voip-portal-development skill](#sources--methodology)) + +--- + +## Table of Contents + +1. [Sources & Methodology](#sources--methodology) +2. [Source of Truth & Data Architecture](#source-of-truth--data-architecture) +3. [RBAC, Tenant Isolation & Security](#rbac-tenant-isolation--security) +4. [Audit & Compliance](#audit--compliance) +5. [Phased MVP Sequence](#phased-mvp-sequence) +6. [Requirement Areas](#requirement-areas) + - [1. My Dashboard](#1-my-dashboard) + - [2. Call History](#2-call-history) + - [3. Marketplace](#3-marketplace) + - [4. Billing](#4-billing) + - [5. My Info](#5-my-info) + - [6. Site Login](#6-site-login) + - [7. Screenshot-Informed Requirements](#7-screenshot-informed-requirements) +7. [Nav Organization (Expanded Canonical)](#nav-organization-expanded-canonical) +8. [Acceptance Criteria by Phase](#acceptance-criteria-by-phase) +9. [Unknowns & Caveats](#unknowns--caveats) +10. [Out of Scope (Deferred to Post-MVP)](#out-of-scope-deferred-to-post-mvp) + +--- + +## Sources & Methodology + +### Owner-Provided Materials +- **Owner screenshots:** ViiBE seller-side views (Accounts, Quotes, Products, LNP, Number Orders, CNAM, Mobile Connect, Reports) and NetSapiens customer/manager views (Home/Statistics, Domains, SIP Trunks, Phone Inventory, E911 Inventory, Call History, Contacts, Answer Rules, Time Frames, User Voicemail/Settings, Music/Messages, Call-Center Queues/Statistics, Auto Attendants). +- **Owner Obsidian notes:** Captured preferences, design constraints, competitive feature wishlist, and operational requirements from Germaine Brown. +- **Owner business records:** [ENTITY.md](./ENTITY.md) — verified phone assets and legal entity. + +### Existing Portal Artifacts +- **Deployed portal:** `/home/myvoip/htdocs/my.voipsimplicity.com/index.html` on app3 (533 lines production, 1,471 enhanced reference). +- **Skill documentation:** `voip-portal-development` skill in `~/.hermes/skills/devops/voip-portal-development/` with 13 reference files covering API integration, call patterns, marketplace flows, and deployment. +- **Domain roster:** 14 customer domains, 189 subscribers, 17 DIDs, 30 call queues, 19 auto attendants, 16 time frames — all on RingLogix. + +--- + +## Source of Truth & Data Architecture + +| Data Domain | Primary Source | API/Object | Notes | +|---|---|---|---| +| Subscribers/Extensions | RingLogix | `subscriber/read` | `domain` param required; filter to 100–399 for real users | +| DIDs/Phone Numbers | RingLogix | `phonenumber/read` | Ignores domain filter — filter client-side by `dialrule_domain` | +| Call Queues | RingLogix | `callqueue/read` | `domain` param required | +| Auto Attendants | RingLogix | `attendant/read` | NOT `autoattendant` (returns 404) | +| Time Frames | RingLogix | `timeframe/read` | `domain` param required | +| Music on Hold | RingLogix | **Unknown** — no confirmed endpoint | Screenshots show MOH config; API availability TBD | +| Call History / CDRs | RingLogix | **NOT AVAILABLE** — `cdr`, `call_detail_record`, `callhistory` all return 404 | Must use alternative source or NetSapiens CDR export | +| Call Recordings | RingLogix → Wasabi S3 | `s3:*` bucket policy for RingLogix IPs (192.92.8.0/24, 64.52.82.0/24, 64.52.83.0/24) | Portal would proxy through signed URLs | +| Billing / Invoices | RingLogix | **Unknown** — no confirmed billing API endpoint | Likely via RingLogix admin panel export or Stripe integration | +| Plans & Features | RingLogix / Manual | **Unknown** — no confirmed catalog API | Marketplace catalog maintained manually or via RingLogix reseller API | +| User Auth / RBAC | Custom (portal-local) | N/A — built in portal JS | No RingLogix customer-auth API; staff `info@voipsimplicity.com` hardcoded | +| E911 Inventory | RingLogix | **Unknown** — no confirmed endpoint | NetSapiens screenshots reference; API path TBD | +| SIP Trunks | RingLogix | **Unknown** — no confirmed endpoint | NetSapiens screenshots reference; API path TBD | +| Answer Rules | RingLogix | **Unknown** — no confirmed endpoint | NetSapiens screenshots reference; API path TBD | +| CNAM | RingLogix / ViiBE | **Unknown** — ViiBE screenshots show CNAM tab | API path and data model TBD | + +**API base URL:** `https://api.ringlogix.com/pbx/v1/` (all calls POST with `object` and `action` in body — NOT RESTful GET). + +**CRITICAL:** CDR/call-history, billing, and E911 endpoints are NOT available via the current RingLogix API. See [Unknowns & Caveats](#unknowns--caveats). + +--- + +## RBAC, Tenant Isolation & Security + +### Role Definitions + +| Role | Access Scope | Auth Mechanism | Login Identifier | +|---|---|---|---| +| **IT Staff** | All 14 domains, all views, admin panel, audit log, domain selector | Hardcoded credentials: `info@voipsimplicity.com` + password | Email | +| **Customer Admin** | Single domain, all customer views, billing, add/remove authorized users | Domain ID or registered email + password | Domain ID, account email, or authorized-user email | +| **Authorized User** | Single domain, subset of views (no billing, no user management) — configurable by Customer Admin | Email + password, invited by Customer Admin | Authorized-user email | +| **View-Only User** | Single domain, read-only dashboard + call history | Email + password, invited by Customer Admin | Authorized-user email | + +### Tenant Isolation Rules + +- Every data query is scoped to `currentDomain` (customer) or selected domain (staff). +- Staff domain selector changes `currentDomain` and re-renders the active view — never leaks cross-domain data. +- Customer sessions are locked to a single domain ID returned on login. +- Staff audit log entries include `performedBy` (staff email), `domain` (affected domain), and `impersonated` flag if acting as customer. + +### Security Constraints + +- **Card data:** Never stored in browser session storage, `localStorage`, or cookies. Card updates go through a separate, secure payment-gateway path (Stripe Elements or equivalent hosted iframe). +- **Session tokens:** `sessionStorage` only — cleared on logout (`sessionStorage.clear() + location.reload()`). +- **No JWTs in URL:** Auth state never appears in query strings or URL fragments. +- **MFA recovery codes:** Generated server-side, shown once, never stored in browser. +- **Rate limiting:** Login attempts, MFA token requests, and password-reset requests rate-limited per IP and per account (5 attempts / 15 min window). +- **Password reset tokens:** Single-use, time-limited (15 min), delivered via email only (SMS fallback TBD per provider availability). + +--- + +## Audit & Compliance + +### Audit Trail Requirements + +All state-changing operations produce immutable audit log entries: + +| Operation | Audit Fields | +|---|---| +| Login/logout | `ts`, `user`, `role`, `domain`, `action`, `ip` (if available) | +| Marketplace add-on request | `ts`, `user`, `action:'addon_request'`, `domain`, `detail` (item name, extension, choice) | +| Plan change / upgrade | `ts`, `user`, `action:'plan_change'`, `domain`, `detail` (from → to plan) | +| Authorized user add/remove | `ts`, `user`, `action:'user_add'|'user_remove'`, `domain`, `detail` (affected user email + role) | +| Contact info update | `ts`, `user`, `action:'contact_update'`, `domain`, `detail` (changed fields, not values) | +| Payment method change | `ts`, `user`, `action:'payment_update'`, `domain` (no card details logged) | +| Password reset | `ts`, `user`, `action:'password_reset'`, `domain` | +| Staff domain switch | `ts`, `user`, `action:'domain_switch'`, `detail` (from → to domain) | + +### Notification Rules + +- All marketplace orders produce a notification (ticket-like) visible to staff. +- Authorized-user invitation emails are sent with a time-limited registration link. +- Password reset and MFA token delivery produce notifications with delivery method noted. + +--- + +## Phased MVP Sequence + +### Phase 1: Foundation (MVP Launch) +- Site login (split-half page, domain ID / email auth, password reset) +- My Dashboard (per-customer stats + lists, no topology graph) +- Call History (searchable, exportable — mock/placeholder data if CDR API unavailable) +- Nav: Dashboard, Call History, Billing (read-only), My Info (read-only) + +### Phase 2: Self-Service +- My Info: editable contact info + payment method update (secure, separate path) +- Marketplace: catalog browsing, cart, per-extension vs per-account selection, immediate provisioning vs request-discussion choice +- Billing: invoice viewer, download, prior invoices list +- Authorized user management: add/remove with RBAC + +### Phase 3: Advanced +- Graphical phone-system topology in Dashboard +- MFA / one-time token delivery (email/SMS) +- Recording playback in Call History (only if enabled) +- Voicemail inline in Call History +- Music on Hold, Time Frames displays +- Order-services contact form on login page + +### Phase 4: Feature Parity +- E911 inventory display +- SIP trunk status +- Answer rules viewer +- CNAM management (if API available) +- Staff-only reports, LNP, number orders (ViiBE integration) + +--- + +## Requirement Areas + +### 1. My Dashboard + +#### 1.1 Per-Customer Aggregate View + +**Customer sees:** +| Metric | Data Source | Format | +|---|---|---| +| Total extensions | `subscriber/read` filtered to 100–399 | Large stat card: "12 Extensions" | +| Call queues | `callqueue/read` count | Stat card: "3 Queues" | +| DID inventory | `phonenumber/read` filtered by `dialrule_domain` | Stat card: "5 Phone Numbers" | +| Auto attendants | `attendant/read` count | Stat card: "2 Attendants" | +| Subscribed plan | Manual / RingLogix catalog (TBD) | Badge: "Business Pro" | + +**Staff sees (domain selector active):** +- Same metrics for the selected domain. +- Aggregate "All Domains" stats: total subscribers, DIDs, queues, attendants across all 14 domains. + +#### 1.2 Detail Lists (Expandable Under Stats) + +| List | Columns | Notes | +|---|---|---| +| Extensions | Name, Email, Extension #, Voicemail (badge) | Filtered to 100–399. System routes hidden by toggle. | +| DIDs | Phone Number (formatted), Domain, Assigned Extension | Full DID list for domain. | +| Call Queues | Queue Name, Extension, Strategy (Linear Hunt, etc.), Members count | From `callqueue/read`. | +| Auto Attendants | Extension, Name, Schedule, Prompt Type | From `attendant/read`. Menu options NOT available via API — show note to use RingLogix admin. | + +#### 1.3 Music on Hold + +- **Data source:** Unknown endpoint. Screenshots (NetSapiens) show MOH configuration per domain. +- **Fallback:** Display "Configured via RingLogix Admin Panel" with a note until API endpoint is confirmed. + +#### 1.4 Time Frames + +- **Data source:** `timeframe/read` per domain. +- **Display:** Table of time frame names, schedules, and associated objects (attendants, routes). +- **Staff view:** Full edit capability (if API supports write), otherwise read-only with admin-panel link. + +#### 1.5 Graphical Phone-System Topology (Phase 3) + +- **Requirement:** Visual graph/flowchart showing: + - Inbound DID → Time Frame → Auto Attendant → Call Queue → Extensions + - Nodes color-coded by type (DID=gold, Attendant=blue, Queue=teal, Extension=green) + - Connected edges show full routing path +- **Rendering:** Canvas or SVG-based, mobile-responsive (scrollable on small screens). +- **Data:** Built from `phonenumber/read` (matchrule, dialrule_domain), `attendant/read` (timeframes, menus), `callqueue/read` (connect_to), `subscriber/read` relationships. +- **Note:** Menu-level routing (specific attendant option → extension) is NOT available via current API. Graph shows attendant → connected queues/extensions at the object level, not per-menu-option. + +--- + +### 2. Call History + +#### 2.1 Unified View + +Single page merging incoming and outgoing calls — NOT separate "Call Logs" + "Recordings" tabs. Customers see one searchable list. + +#### 2.2 Search + +- **Searchable fields:** Caller name AND phone number. +- **Behavior:** `oninput` handler with no submit button. Real-time filtering across both inbound and outbound calls. +- **Implementation:** Single search box with `data-search` attribute on rows containing lowercase concatenation of caller name + phone number. + +#### 2.3 Table Columns + +| # | Column | Content | Notes | +|---|---|---|---| +| 1 | Date/Time | `YYYY-MM-DD HH:MM AM/PM` | Sortable | +| 2 | Direction | `↓ Incoming` (teal) or `↑ Outgoing` (gold) | Text label + arrow | +| 3 | Caller Name | Avatar circle + name | Unknown callers: gray "?" avatar + "Unknown" | +| 4 | Caller Phone | Formatted `(XXX) XXX-XXXX` | Muted secondary text | +| 5 | Destination | Extension number or queue name | Who handled the call | +| 6 | Status | Badge: Answered (teal), Missed (red), Voicemail (gray) | Color-coded | +| 7 | Voicemail | `📝 View Transcript` button or `—` | Opens modal with transcript text; only shown if call was missed → voicemail left | +| 8 | Recording | `▶ MM:SS` play button or `—` | **Only shown if recording is enabled for this domain/extension.** Inline playback. | +| 9 | Duration | `MM:SS` | Call duration | + +#### 2.4 Recording Playback + +- **Conditional:** Recording play button appears ONLY when recording is enabled. RingLogix recording toggle is per-domain or per-extension — portal must check this. +- **Playback:** Inline HTML5 `