zpan/docs/roadmap/v2.8.md

v2.8 — Admin Analytics & Dashboard

Build the first real operator dashboard for ZPan admins. This version should help an instance owner understand usage, growth, cost pressure, and reliability without querying the database by hand.

v2.8 intentionally stays focused. It does not bundle enterprise identity, desktop sync, webhooks, or native clients.

Product Boundary

• Pro and Business get the full admin analytics surface through the analytics feature gate.
• Pro keeps the existing operator features already shipped in v2.6, such as audit log, white-label, open registration, and higher free limits.
• Community keeps normal file workflows and can continue to see local, user-facing counters such as share views/downloads where already exposed.

No v2.8 feature requires a managed cloud runtime. ZPan Cloud only supplies the Business entitlement certificate.

Current Baseline

ZPan already records enough local data to build a useful first dashboard:

• activity_events for file, team, auth, admin, quota, share, and download-task actions
• shares.views and shares.downloads
• download_tasks, downloaders, and remote_download_usage_reports
• org_quotas, org_quota_entitlements, and cloud_traffic_reports
• background_jobs

v2.8 turns these into background-computed result rows. Dashboard requests must not reconstruct metrics from operational records.

Major Features

Admin Overview

Add a Pro+-gated analytics page under Admin.

Top-level cards:

• Total storage used, quota allocated, and quota utilization
• Download traffic issued by ZPan
• Active users, new signups, and user status
• Share views/downloads and top shared files
• Remote-download task volume, success rate, failure reasons, and downloader health
• Background job volume and failure rate

The page should be useful immediately on a small self-hosted instance, even when there is only one user and one storage backend.

Analytics Rollups

Use additive rollups for metrics that would otherwise become expensive.

Suggested storage:

• Hourly rollups by metric, org, declared dimension, and UTC time bucket
• Daily and longer-range charts are composed from UTC hourly rows at query time

Retention defaults:

• Hourly rollups are the only persisted aggregate and are retained until an explicit pruning policy is introduced
• Dashboard ranges use UTC calendar boundaries; no time-zone-specific aggregate is stored

The current open hour is excluded. Versioned completion markers distinguish full snapshot results from counter-only historical repairs. Missing coverage is shown to the operator and never falls back to request-time raw aggregation.

Usage And Cost Views

Operators need to understand where resource pressure comes from:

• Storage used by space and file type
• Quota allocation and utilization by space
• Upload/download volume by source and period
• Remote-download and background-job outcomes
• Over-quota or near-quota spaces

This is a dashboard, not a billing engine. Billing still belongs to Cloud and the quota-store flow already designed in v2.6.

Share And Public Access Analytics

The current share detail panel exposes simple counters. v2.8 turns them into an admin-operable view:

• Top shares by views and downloads
• Downloads and saves per 100 landing views, explicitly not a user funnel
• Expired, revoked, and download-limit-hit counts
• Anonymous vs signed-in access where known
• Top public user-homepage items where data is available

Avoid per-recipient behavioral analytics in this version.

Reliability Views

Give admins a place to diagnose operational health:

• Background-job outcomes and active backlog
• Remote-download outcomes and active backlog
• Current closed-hour downloader online/offline snapshot
• Cloud traffic-report backlog and outcomes
• Webhook failure snapshot

The goal is to answer "what is broken?" before adding deeper observability.

Read-only Dashboard Boundary

The browser queries completed result data and does not calculate metrics from detail rows. Request-time lookups are limited to hydrating the top eight result ids with display names. Report and CSV export are not part of v2.8.

Non-goals for v2.8

• Outbound event webhooks — future integrations work
• SAML, LDAP, SCIM, or other enterprise / legacy identity protocols
• Folder-level ACLs, custom roles, or complex team governance
• CLI, desktop sync, Flutter, or native client implementation
• Hosted analytics pipeline in ZPan Cloud
• Report, CSV, audit-event, task, downloader, quota, or entitlement export
• Content moderation, media transcoding, or managed large-file processing
• Replacing audit log; analytics summarizes behavior, audit log remains the record-level review surface

User Scenarios

Self-hosted operator:

I can see storage growth, active users, traffic, failed jobs, and near-quota spaces from the admin dashboard.

Paid self-hosted instance owner:

I know which teams are using the most capacity and which shares are consuming the most traffic before users ask for help.

Agency sharing files with clients:

I can inspect this month's share-link traffic and top downloads without running database queries or waiting for a large live aggregation.

v1 Issues Resolved

• #18 Purchasable storage — v2.6 ships quota purchases; v2.8 adds the reporting surface operators need to understand usage and cost.