apps/backend/src/common/intelligence/recommendation-outcome.service.tsTypeScript
import { Injectable } from '@nestjs/common';
export interface RecommendationOutcomeInput {
recommendationId: string;
requestedUnits: number;
allocatedUnits: number;
fulfilledUnits: number;
overrideUsed?: boolean;
}
export interface RecommendationOutcome {
recommendationId: string;
requestedUnits: number;
allocatedUnits: number;
fulfilledUnits: number;
fulfillmentRate: number;
outcome: 'fulfilled' | 'partial' | 'not_fulfilled';
overrideUsed: boolean;
explanation: string;
}
export interface RecommendationOutcomeSummary {
recommendationCount: number;
allocatedUnits: number;
fulfilledUnits: number;
fulfillmentRate: number;
overrideCount: number;
confidence: 'high' | 'medium' | 'low';
}
@Injectable()
export class RecommendationOutcomeService {
evaluate(input: RecommendationOutcomeInput): RecommendationOutcome {
if (!input || typeof input !== 'object' || typeof input.recommendationId !== 'string') throw new Error('recommendation_outcome.invalid');
const recommendationId = input.recommendationId.trim();
if (!recommendationId || !Number.isSafeInteger(input.requestedUnits) || input.requestedUnits < 0 || !Number.isSafeInteger(input.allocatedUnits) || input.allocatedUnits < 0 || input.allocatedUnits > input.requestedUnits || !Number.isSafeInteger(input.fulfilledUnits) || input.fulfilledUnits < 0 || input.fulfilledUnits > input.allocatedUnits || (input.overrideUsed !== undefined && typeof input.overrideUsed !== 'boolean')) {
throw new Error('recommendation_outcome.invalid');
}
const fulfillmentRate = input.allocatedUnits === 0 ? 0 : input.fulfilledUnits / input.allocatedUnits;
const outcome = fulfillmentRate === 1 ? 'fulfilled' : fulfillmentRate > 0 ? 'partial' : 'not_fulfilled';
return {recommendationId, requestedUnits: input.requestedUnits, allocatedUnits: input.allocatedUnits, fulfilledUnits: input.fulfilledUnits, fulfillmentRate, outcome, overrideUsed: input.overrideUsed === true, explanation: outcome === 'fulfilled' ? 'Allocated demand was fulfilled.' : outcome === 'partial' ? 'Only part of the allocated demand was fulfilled.' : 'No allocated demand was fulfilled.'};
}
summarize(outcomes: RecommendationOutcome[]): RecommendationOutcomeSummary {
if (!Array.isArray(outcomes) || outcomes.length === 0 || outcomes.some((outcome) => {
if (!outcome || typeof outcome.recommendationId !== 'string' || !outcome.recommendationId.trim() || !Number.isSafeInteger(outcome.requestedUnits) || outcome.requestedUnits < 0 || !Number.isSafeInteger(outcome.allocatedUnits) || outcome.allocatedUnits < 0 || outcome.allocatedUnits > outcome.requestedUnits || !Number.isSafeInteger(outcome.fulfilledUnits) || outcome.fulfilledUnits < 0 || outcome.fulfilledUnits > outcome.allocatedUnits || !Number.isFinite(outcome.fulfillmentRate) || outcome.fulfillmentRate < 0 || outcome.fulfillmentRate > 1 || typeof outcome.overrideUsed !== 'boolean' || typeof outcome.explanation !== 'string' || !outcome.explanation.trim()) return true;
const expectedOutcome = outcome.fulfillmentRate === 1 ? 'fulfilled' : outcome.fulfillmentRate > 0 ? 'partial' : 'not_fulfilled';
return outcome.outcome !== expectedOutcome;
})) throw new Error('recommendation_outcome.summary_invalid');
const ids = outcomes.map((outcome) => outcome.recommendationId.trim().toLowerCase());
if (new Set(ids).size !== ids.length) throw new Error('recommendation_outcome.duplicate');
const allocatedUnits = outcomes.reduce((total, outcome) => total + outcome.allocatedUnits, 0);
const fulfilledUnits = outcomes.reduce((total, outcome) => total + outcome.fulfilledUnits, 0);
if (!Number.isSafeInteger(allocatedUnits) || !Number.isSafeInteger(fulfilledUnits)) throw new Error('recommendation_outcome.summary_invalid');
const overrideCount = outcomes.filter((outcome) => outcome.overrideUsed).length;
const fulfillmentRate = allocatedUnits === 0 ? 0 : fulfilledUnits / allocatedUnits;
return {recommendationCount: outcomes.length, allocatedUnits, fulfilledUnits, fulfillmentRate, overrideCount, confidence: outcomes.length >= 10 ? 'high' : outcomes.length >= 3 ? 'medium' : 'low'};
}
}