feat(report): types, data computation, formatters, executive summary
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
fahed
@@ -0,0 +1,232 @@
|
|||||||
|
import { filterDataByDateRange, calculateMetrics, groupByMuseum, groupByChannel, umrahData } from '../../services/dataService';
|
||||||
|
import { shiftYear } from '../../lib/dateHelpers';
|
||||||
|
import type { MuseumRecord, Metrics } from '../../types';
|
||||||
|
|
||||||
|
// ─── config ───────────────────────────────────────────────────────
|
||||||
|
export interface ReportConfig {
|
||||||
|
title: string;
|
||||||
|
clientName: string;
|
||||||
|
contactName: string;
|
||||||
|
clientLogoBase64: string | null;
|
||||||
|
accentColor: string;
|
||||||
|
startDate: string;
|
||||||
|
endDate: string;
|
||||||
|
selectedMuseums: string[];
|
||||||
|
selectedChannels: string[];
|
||||||
|
includeVAT: boolean;
|
||||||
|
includeComparison: boolean;
|
||||||
|
showExecutiveSummary: boolean;
|
||||||
|
showMetricsTable: boolean;
|
||||||
|
showTrendChart: boolean;
|
||||||
|
showMuseumBreakdown: boolean;
|
||||||
|
showChannelBreakdown: boolean;
|
||||||
|
showPilgrimCapture: boolean;
|
||||||
|
language: 'en' | 'ar';
|
||||||
|
confidentiality: 'Confidential' | 'Internal' | 'Public';
|
||||||
|
orientation: 'portrait' | 'landscape';
|
||||||
|
}
|
||||||
|
|
||||||
|
export const DEFAULT_CONFIG: ReportConfig = {
|
||||||
|
title: '',
|
||||||
|
clientName: '',
|
||||||
|
contactName: '',
|
||||||
|
clientLogoBase64: null,
|
||||||
|
accentColor: '#2563eb',
|
||||||
|
startDate: new Date(new Date().getFullYear(), new Date().getMonth(), 1).toISOString().slice(0, 10),
|
||||||
|
endDate: new Date(new Date().getFullYear(), new Date().getMonth() + 1, 0).toISOString().slice(0, 10),
|
||||||
|
selectedMuseums: [],
|
||||||
|
selectedChannels: [],
|
||||||
|
includeVAT: true,
|
||||||
|
includeComparison: true,
|
||||||
|
showExecutiveSummary: true,
|
||||||
|
showMetricsTable: true,
|
||||||
|
showTrendChart: true,
|
||||||
|
showMuseumBreakdown: true,
|
||||||
|
showChannelBreakdown: true,
|
||||||
|
showPilgrimCapture: true,
|
||||||
|
language: 'en',
|
||||||
|
confidentiality: 'Confidential',
|
||||||
|
orientation: 'portrait',
|
||||||
|
};
|
||||||
|
|
||||||
|
// ─── computed report data ─────────────────────────────────────────
|
||||||
|
export interface BreakdownItem { name: string; value: number; }
|
||||||
|
|
||||||
|
export interface ReportData {
|
||||||
|
config: ReportConfig;
|
||||||
|
metrics: Metrics;
|
||||||
|
prevMetrics: Metrics | null;
|
||||||
|
trendLabels: string[];
|
||||||
|
trendCurrent: number[];
|
||||||
|
trendPrevious: number[] | null;
|
||||||
|
museumBreakdown: BreakdownItem[];
|
||||||
|
channelBreakdown: BreakdownItem[];
|
||||||
|
pilgrimCapture: { current: number; previous: number | null } | null;
|
||||||
|
generatedAt: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
// ─── data computation ─────────────────────────────────────────────
|
||||||
|
function applyDimFilters(rows: MuseumRecord[], cfg: ReportConfig): MuseumRecord[] {
|
||||||
|
let d = rows;
|
||||||
|
if (cfg.selectedMuseums.length) d = d.filter(r => cfg.selectedMuseums.includes(r.museum_name));
|
||||||
|
if (cfg.selectedChannels.length) d = d.filter(r => cfg.selectedChannels.includes(r.channel));
|
||||||
|
return d;
|
||||||
|
}
|
||||||
|
|
||||||
|
function estimatePilgrims(start: string, end: string): number | null {
|
||||||
|
const sd = new Date(start), ed = new Date(end);
|
||||||
|
let total = 0, has = false;
|
||||||
|
for (let y = sd.getFullYear(); y <= ed.getFullYear(); y++) {
|
||||||
|
for (let q = 1; q <= 4; q++) {
|
||||||
|
const qs = new Date(y, (q - 1) * 3, 1), qe = new Date(y, q * 3, 0);
|
||||||
|
if (qe < sd || qs > ed) continue;
|
||||||
|
const p = (umrahData as any)[y]?.[q];
|
||||||
|
if (!p) continue;
|
||||||
|
const os = new Date(Math.max(qs.getTime(), sd.getTime()));
|
||||||
|
const oe = new Date(Math.min(qe.getTime(), ed.getTime()));
|
||||||
|
total += p * ((oe.getTime() - os.getTime()) / 86400000 + 1) /
|
||||||
|
((qe.getTime() - qs.getTime()) / 86400000 + 1);
|
||||||
|
has = true;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return has ? Math.round(total) : null;
|
||||||
|
}
|
||||||
|
|
||||||
|
function buildTrend(rows: MuseumRecord[], start: string, cfg: ReportConfig): { labels: string[]; values: number[] } {
|
||||||
|
const s = new Date(start);
|
||||||
|
const acc: Record<number, MuseumRecord[]> = {};
|
||||||
|
rows.forEach(r => {
|
||||||
|
if (!r.date) return;
|
||||||
|
const diff = Math.floor((new Date(r.date).getTime() - s.getTime()) / 86400000);
|
||||||
|
const key = Math.floor(diff / 7) + 1;
|
||||||
|
if (!acc[key]) acc[key] = [];
|
||||||
|
acc[key].push(r);
|
||||||
|
});
|
||||||
|
const maxK = Math.max(...Object.keys(acc).map(Number), 1);
|
||||||
|
const labels = Array.from({ length: maxK }, (_, i) => `W${i + 1}`);
|
||||||
|
const values = labels.map((_, i) => {
|
||||||
|
const group = acc[i + 1] || [];
|
||||||
|
const revenueField = cfg.includeVAT ? 'revenue_gross' : 'revenue_net';
|
||||||
|
return group.reduce((s, r) => s + parseFloat(String((r as any)[revenueField] || 0)), 0);
|
||||||
|
});
|
||||||
|
return { labels, values };
|
||||||
|
}
|
||||||
|
|
||||||
|
export function computeReportData(allData: MuseumRecord[], cfg: ReportConfig): ReportData {
|
||||||
|
const currRows = applyDimFilters(filterDataByDateRange(allData, cfg.startDate, cfg.endDate, {}), cfg);
|
||||||
|
const metrics = calculateMetrics(currRows, cfg.includeVAT);
|
||||||
|
|
||||||
|
const prevStart = shiftYear(cfg.startDate);
|
||||||
|
const prevEnd = shiftYear(cfg.endDate);
|
||||||
|
const prevRows = cfg.includeComparison
|
||||||
|
? applyDimFilters(filterDataByDateRange(allData, prevStart, prevEnd, {}), cfg)
|
||||||
|
: [];
|
||||||
|
const prevMetrics = cfg.includeComparison ? calculateMetrics(prevRows, cfg.includeVAT) : null;
|
||||||
|
|
||||||
|
const currTrend = buildTrend(currRows, cfg.startDate, cfg);
|
||||||
|
const prevTrend = cfg.includeComparison ? buildTrend(prevRows, prevStart, cfg) : null;
|
||||||
|
const maxLen = Math.max(currTrend.labels.length, prevTrend?.values.length ?? 0);
|
||||||
|
const trendLabels = Array.from({ length: maxLen }, (_, i) => `W${i + 1}`);
|
||||||
|
const trendCurrent = Array.from({ length: maxLen }, (_, i) => currTrend.values[i] ?? 0);
|
||||||
|
const trendPrevious = prevTrend
|
||||||
|
? Array.from({ length: maxLen }, (_, i) => prevTrend.values[i] ?? 0)
|
||||||
|
: null;
|
||||||
|
|
||||||
|
const musG = groupByMuseum(currRows, cfg.includeVAT);
|
||||||
|
const museumBreakdown: BreakdownItem[] = Object.entries(musG)
|
||||||
|
.map(([name, g]) => ({ name, value: g.revenue }))
|
||||||
|
.sort((a, b) => b.value - a.value)
|
||||||
|
.slice(0, 10);
|
||||||
|
|
||||||
|
const chanG = groupByChannel(currRows, cfg.includeVAT);
|
||||||
|
const channelBreakdown: BreakdownItem[] = Object.entries(chanG)
|
||||||
|
.map(([name, g]) => ({ name, value: g.visitors }))
|
||||||
|
.sort((a, b) => b.value - a.value);
|
||||||
|
|
||||||
|
const currPilgrims = estimatePilgrims(cfg.startDate, cfg.endDate);
|
||||||
|
const prevPilgrims = cfg.includeComparison ? estimatePilgrims(prevStart, prevEnd) : null;
|
||||||
|
const pilgrimCapture = currPilgrims && metrics.visitors
|
||||||
|
? {
|
||||||
|
current: parseFloat(((metrics.visitors / currPilgrims) * 100).toFixed(2)),
|
||||||
|
previous: prevPilgrims && prevMetrics
|
||||||
|
? parseFloat(((prevMetrics.visitors / prevPilgrims) * 100).toFixed(2))
|
||||||
|
: null,
|
||||||
|
}
|
||||||
|
: null;
|
||||||
|
|
||||||
|
return {
|
||||||
|
config: cfg,
|
||||||
|
metrics,
|
||||||
|
prevMetrics,
|
||||||
|
trendLabels,
|
||||||
|
trendCurrent,
|
||||||
|
trendPrevious,
|
||||||
|
museumBreakdown,
|
||||||
|
channelBreakdown,
|
||||||
|
pilgrimCapture,
|
||||||
|
generatedAt: new Date().toLocaleDateString('en-GB'),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
// ─── formatters ───────────────────────────────────────────────────
|
||||||
|
export function formatCurrency(n: number, inclVAT: boolean): string {
|
||||||
|
return `SAR ${n.toLocaleString('en-SA', { maximumFractionDigits: 0 })}${inclVAT ? '' : ' (ex-VAT)'}`;
|
||||||
|
}
|
||||||
|
|
||||||
|
export function formatPct(change: number): string {
|
||||||
|
return `${change >= 0 ? '+' : ''}${change.toFixed(1)}%`;
|
||||||
|
}
|
||||||
|
|
||||||
|
export function formatPeriodLabel(start: string, end: string, lang: 'en' | 'ar'): string {
|
||||||
|
const months = lang === 'en'
|
||||||
|
? ['January','February','March','April','May','June','July','August','September','October','November','December']
|
||||||
|
: ['يناير','فبراير','مارس','أبريل','مايو','يونيو','يوليو','أغسطس','سبتمبر','أكتوبر','نوفمبر','ديسمبر'];
|
||||||
|
const s = new Date(start), e = new Date(end);
|
||||||
|
const sm = months[s.getMonth()], em = months[e.getMonth()];
|
||||||
|
const sy = s.getFullYear(), ey = e.getFullYear();
|
||||||
|
if (sy === ey && sm === em) return `${sm} ${sy}`;
|
||||||
|
if (sy === ey) return `${sm} – ${em} ${sy}`;
|
||||||
|
return `${sm} ${sy} – ${em} ${ey}`;
|
||||||
|
}
|
||||||
|
|
||||||
|
// ─── executive summary ────────────────────────────────────────────
|
||||||
|
export function generateExecutiveSummary(data: ReportData): string {
|
||||||
|
const { config: cfg, metrics, prevMetrics, channelBreakdown } = data;
|
||||||
|
const lang = cfg.language;
|
||||||
|
const period = formatPeriodLabel(cfg.startDate, cfg.endDate, lang);
|
||||||
|
const revenue = formatCurrency(metrics.revenue, cfg.includeVAT);
|
||||||
|
const topChannel = channelBreakdown[0]?.name ?? '';
|
||||||
|
const totalVisitors = channelBreakdown.reduce((s, i) => s + i.value, 0);
|
||||||
|
const topPct = totalVisitors > 0 && channelBreakdown[0]
|
||||||
|
? Math.round((channelBreakdown[0].value / totalVisitors) * 100)
|
||||||
|
: 0;
|
||||||
|
const museumLabel = cfg.selectedMuseums.length > 0
|
||||||
|
? cfg.selectedMuseums.join(', ')
|
||||||
|
: (lang === 'en' ? 'all museums' : 'جميع المتاحف');
|
||||||
|
|
||||||
|
if (lang === 'en') {
|
||||||
|
let s = `During ${period}, ${museumLabel} recorded ${metrics.visitors.toLocaleString()} visitors and ${revenue} in revenue.`;
|
||||||
|
if (prevMetrics && prevMetrics.revenue > 0) {
|
||||||
|
const chg = Math.round(((metrics.revenue - prevMetrics.revenue) / prevMetrics.revenue) * 100);
|
||||||
|
s += ` This represents a ${formatPct(chg)} change in revenue versus the same period last year.`;
|
||||||
|
}
|
||||||
|
if (topChannel) s += ` The top-performing channel was ${topChannel} with ${topPct}% of total visitors.`;
|
||||||
|
return s;
|
||||||
|
} else {
|
||||||
|
let s = `خلال ${period}، سجّلت ${museumLabel} ${metrics.visitors.toLocaleString()} زائراً وإيرادات بلغت ${revenue}.`;
|
||||||
|
if (prevMetrics && prevMetrics.revenue > 0) {
|
||||||
|
const chg = Math.round(((metrics.revenue - prevMetrics.revenue) / prevMetrics.revenue) * 100);
|
||||||
|
s += ` يمثّل ذلك تغيّراً بنسبة ${formatPct(chg)} في الإيرادات مقارنةً بالفترة ذاتها من العام الماضي.`;
|
||||||
|
}
|
||||||
|
if (topChannel) s += ` كانت ${topChannel} أعلى القنوات أداءً بنسبة ${topPct}% من إجمالي الزوار.`;
|
||||||
|
return s;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ─── page count estimator ─────────────────────────────────────────
|
||||||
|
export function estimatePageCount(cfg: ReportConfig): number {
|
||||||
|
let pages = 2; // cover + first content page
|
||||||
|
if (cfg.showMuseumBreakdown) pages += 1;
|
||||||
|
if (cfg.showChannelBreakdown) pages += 1;
|
||||||
|
return pages;
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user