apps/backend/src/common/place-event-learning/place-event-learning.service.tsTypeScript
import { Injectable } from '@nestjs/common';
import { createHash } from 'node:crypto';
export interface PlaceEventScenario {
scenarioId: string;
placeType: string;
eventType?: string;
attendance: number;
stockUnits: number;
staffingUnits: number;
prepUnits: number;
/** Optional contribution margin in minor currency units from canonical event economics. */
contributionMinor?: number;
}
export interface PlaceEventLearningInput {
current: Omit<PlaceEventScenario, 'scenarioId'>;
historical: PlaceEventScenario[];
}
export interface PlaceEventLearningRecommendation {
/** Stable, non-secret fingerprint for correlating a recommendation with its evidence. */
decisionFingerprint: string;
comparableScenarioIds: string[];
forecast: {attendance: number; stockUnits: number; staffingUnits: number; prepUnits: number; contributionMinor?: number};
evidence: {scenarioCount: number; match: 'exact_event' | 'place_fallback' | 'broad_fallback'; confidence: 'high' | 'medium' | 'low'};
explanation: string;
requiresHumanConfirmation: true;
}
@Injectable()
export class PlaceEventLearningService {
prepare(input: PlaceEventLearningInput): PlaceEventLearningRecommendation {
if (!input || typeof input !== 'object' || !input.current || !Array.isArray(input.historical)) throw new Error('place_event_learning.invalid');
const current = this.validate(input.current, false);
const historical = input.historical.map((scenario) => this.validate(scenario, true));
const scenarioIds = historical.map((scenario) => scenario.scenarioId);
const normalizedScenarioIds = scenarioIds.map((scenarioId) => scenarioId.toLowerCase());
if (new Set(normalizedScenarioIds).size !== normalizedScenarioIds.length) throw new Error('place_event_learning.duplicate_scenario');
const comparable = historical.filter((scenario) => scenario.placeType === current.placeType && (!current.eventType || scenario.eventType === current.eventType));
const source = comparable.length ? comparable : historical.filter((scenario) => scenario.placeType === current.placeType);
const baseline = source.length ? source : historical;
if (!baseline.length) throw new Error('place_event_learning.no_comparable_scenarios');
const match = comparable.length ? 'exact_event' : source.length ? 'place_fallback' : 'broad_fallback';
const confidence = match === 'exact_event' && baseline.length >= 3 ? 'high' : match === 'exact_event' || match === 'place_fallback' ? 'medium' : 'low';
const average = (key: keyof Pick<PlaceEventScenario, 'attendance'|'stockUnits'|'staffingUnits'|'prepUnits'>): number => Math.ceil(baseline.reduce((sum, scenario) => sum + scenario[key], 0) / baseline.length);
const contributionMinor = baseline.every((scenario) => scenario.contributionMinor !== undefined)
? Math.ceil(baseline.reduce((sum, scenario) => sum + (scenario.contributionMinor ?? 0), 0) / baseline.length)
: undefined;
const decisionFingerprint = createHash('sha256').update(JSON.stringify({
current,
historical: [...historical].sort((left, right) => left.scenarioId.localeCompare(right.scenarioId)),
match,
})).digest('hex').slice(0, 24);
return {
decisionFingerprint,
comparableScenarioIds: baseline.map((scenario) => scenario.scenarioId).sort((left, right) => left.localeCompare(right)),
forecast: {attendance: average('attendance'), stockUnits: average('stockUnits'), staffingUnits: average('staffingUnits'), prepUnits: average('prepUnits'), ...(contributionMinor === undefined ? {} : {contributionMinor})},
evidence: {scenarioCount: baseline.length, match, confidence},
explanation: comparable.length ? `Based on ${comparable.length} comparable Place/event scenario${comparable.length === 1 ? '' : 's'}.` : 'No exact event match was found; the Place history is used as a fallback.',
requiresHumanConfirmation: true,
};
}
private validate(input: Omit<PlaceEventScenario, 'scenarioId'> | PlaceEventScenario, historical: boolean): PlaceEventScenario {
if (!input || typeof input !== 'object' || typeof input.placeType !== 'string' || (historical && (!('scenarioId' in input) || typeof input.scenarioId !== 'string')) || (input.eventType !== undefined && typeof input.eventType !== 'string')) throw new Error('place_event_learning.invalid');
const scenarioId = historical && 'scenarioId' in input ? input.scenarioId.trim() : 'current';
const placeType = input.placeType.trim();
const eventType = input.eventType?.trim() || undefined;
const values = [input.attendance, input.stockUnits, input.staffingUnits, input.prepUnits];
if (!scenarioId || !placeType || values.some((value) => !Number.isSafeInteger(value) || value < 0) || (input.contributionMinor !== undefined && !Number.isSafeInteger(input.contributionMinor))) throw new Error('place_event_learning.invalid');
return {scenarioId, placeType, eventType, attendance: input.attendance, stockUnits: input.stockUnits, staffingUnits: input.staffingUnits, prepUnits: input.prepUnits, ...(input.contributionMinor === undefined ? {} : {contributionMinor: input.contributionMinor})};
}
}