placementt-core 1.400.1073 → 1.400.1074

package/lib/benchmarkAggregate.d.ts

@@ -0,0 +1,249 @@
+import { CoverageBand, GatsbyBenchmarkNumber } from "./benchmarkEvidenceRules";
+import { CareersRecordEntry, ExternalEvent, ExternalEventStudent, StudentActivity, StudentPlacementData, UserData } from "./typeDefinitions";
+import { SurveyCycle } from "./surveys/types";
+/** The evidence sources, counted. Used for the scheduled half of a benchmark's stat. */
+export type EvidenceCounts = {
+    events: number;
+    attendances: number;
+    activities: number;
+    placements: number;
+    guidanceEntries: number;
+};
+/** Per-student, per-benchmark evidence rolled up for the overview + matrix. */
+export type BenchmarkStat = {
+    benchmark: GatsbyBenchmarkNumber;
+    /**
+     * Tagged events providing evidence, which have already taken place. Counted over
+     * this academic year for annual benchmarks and over all time for cumulative ones
+     * (BM6/7/8), matching whichever window that benchmark's coverage is measured on.
+     * Same rule for the counts below.
+     */
+    events: number;
+    /** Student attendances across those events (joined/confirmed event-student records). */
+    attendances: number;
+    /** Logged student activities classified to this benchmark. */
+    activities: number;
+    /** Work-experience placements (BM6 only; 0 otherwise). */
+    placements: number;
+    /** Careers record entries evidencing this benchmark (BM3 and BM8; 0 otherwise). */
+    guidanceEntries: number;
+    /**
+     * The same evidence, for items dated after today: an event already in the calendar
+     * with pupils invited or signed up, a placement arranged for next term, a guidance
+     * meeting already booked. Planned delivery, not evidence.
+     */
+    scheduled: EvidenceCounts;
+    /** Distinct on-roll students with ≥1 qualifying evidence item that has happened. */
+    coveredStudents: number;
+    /**
+     * Distinct on-roll students who either hold evidence already or are booked onto
+     * something that would give them some — what the school reaches if every planned
+     * activity goes ahead.
+     */
+    projectedCoveredStudents: number;
+    /** On-roll student roster size (denominator). */
+    rosterTotal: number;
+    /** coveredStudents / rosterTotal, 0-1. */
+    coverage: number;
+    /** projectedCoveredStudents / rosterTotal, 0-1. Always ≥ coverage. */
+    projectedCoverage: number;
+    band: CoverageBand;
+    projectedBand: CoverageBand;
+    /** Year group with the lowest delivered coverage (the biggest gap), if any roster exists. */
+    biggestGap?: {
+        yearGroup: number;
+        missingFraction: number;
+        missingCount: number;
+        scheduledCount: number;
+    };
+    /** Coverage per year group: yearGroup → {covered, projected, total}. */
+    byYearGroup: {
+        [yearGroup: number]: {
+            covered: number;
+            projected: number;
+            total: number;
+        };
+    };
+    /** Contributing events, so the drill-down can link back to each one. */
+    eventRefs: {
+        id: string;
+        name: string;
+        startDate?: string;
+        scheduled: boolean;
+    }[];
+    /**
+     * Coverage at each period this benchmark is judged over — the age checkpoints for
+     * BM7/8 ("by 16… and a further one by 18"), the Key Stages for BM2/6 (Compass asks
+     * each Key Stage as its own question). Absent for the annual benchmarks, which have
+     * no periodised denominator.
+     *
+     * `dueCoverage` is the headline: the proportion of the year group at which the duty
+     * has actually fallen due (Y9, Y11, Y13) holding evidence THAT PERIOD accepts — i.e.
+     * evidence gained while the pupil was in one of its `accumulatingYearGroups`. The
+     * age-18 figure therefore only counts post-16 experiences, because the benchmark asks
+     * for a further one after 16; and the Key Stage 4 figure counts nothing from Key
+     * Stage 3, because CEC asks about the two separately.
+     *
+     * Spreading this across all year groups instead — which is what measuring these
+     * annually does — asks what proportion of Year 7 has had a guidance meeting, and
+     * that measures nothing.
+     */
+    byPeriod?: {
+        id: string;
+        label: string;
+        dueYearGroup: number;
+        dueCovered: number;
+        dueTotal: number;
+        dueCoverage: number;
+        /** The same figure once everything already booked for this period is delivered. */
+        projectedDueCovered: number;
+        projectedDueCoverage: number;
+        band: CoverageBand;
+        projectedBand: CoverageBand;
+        /**
+         * The pupils in the due year group with no evidence this period accepts —
+         * a coverage percentage turned back into a list of names.
+         *
+         * This is what a careers leader actually needs from the number: "84% of Year
+         * 11 have had a personal guidance meeting" is a figure to report, and "here
+         * are the 29 who have not" is the thing they can act on. It is the inversion
+         * of the covered set against the roster, which is why it costs nothing.
+         *
+         * `scheduled` separates the two very different names on that list: the pupil
+         * already booked onto next term's guidance week, and the pupil nobody has
+         * planned anything for. Only the second needs a decision.
+         */
+        missing: {
+            uid: string;
+            name: string;
+            scheduled: boolean;
+        }[];
+    }[];
+};
+export type PalPhaseStat = {
+    phase: 1 | 2 | 3;
+    label: string;
+    /** Distinct PAL-compliant provider encounters (events) touching this phase. */
+    compliantEncounters: number;
+    /** Encounters in the calendar for this phase that haven't happened yet. */
+    scheduledEncounters: number;
+    target: number;
+};
+export type BenchmarkData = {
+    academicYear: string;
+    rosterTotal: number;
+    /** Year groups present in the roster, ascending. */
+    yearGroups: number[];
+    byBenchmark: {
+        [benchmark: number]: BenchmarkStat;
+    };
+    pal: PalPhaseStat[];
+    /** BM3: aspiration-survey response coverage (data-collection health). */
+    destinationsHealth: {
+        surveyed: number;
+        responded: number;
+        responseRate: number;
+    };
+};
+/**
+ * Everything the aggregation reads, as the collections come back.
+ *
+ * Keyed maps rather than arrays because that is the shape both callers already have:
+ * the client's `getDocsWhere` returns one, and the cron builds one off its snapshot.
+ * All seven are scoped to a single school by `oId` before they get here.
+ */
+export type BenchmarkEvidenceInput = {
+    /** The year the ANNUAL benchmarks are measured over. The cumulative ones (BM6/7/8)
+     * read every year, which is why most of these collections arrive unfiltered. */
+    academicYear: string;
+    events: {
+        [id: string]: ExternalEvent;
+    };
+    /** One doc per pupil per event, carrying their uid. NOT externalEventAttendees,
+     * which is the employer side and holds document ids rather than uids. */
+    eventStudents: {
+        [id: string]: ExternalEventStudent;
+    };
+    activities: {
+        [id: string]: StudentActivity;
+    };
+    placements: {
+        [id: string]: StudentPlacementData;
+    };
+    /** On-roll, active students only. This is the denominator of every figure here. */
+    students: {
+        [uid: string]: UserData;
+    };
+    /** This year's aspiration cycles, for the BM3 data-collection health figure. */
+    aspirationCycles: {
+        [id: string]: SurveyCycle;
+    };
+    /** Deliberately unfiltered by year: BM8 is a cumulative "by 16 / by 18" duty, so a
+     * meeting held in Year 9 still evidences the duty in Year 11. */
+    careersRecord: {
+        [id: string]: CareersRecordEntry;
+    };
+    /** The instant "scheduled" is measured against. Defaults to now; passed explicitly
+     * by the cron so one run stamps every school with the same clock, and by tests. */
+    now?: Date | string;
+};
+/**
+ * One school's evidence coverage, from the documents behind it.
+ *
+ * Pure: same input, same output. Nothing in here reads a clock except through `now`,
+ * which is why a rollup can be trusted to say what the browser would have said at the
+ * moment it was written.
+ *
+ * @param {BenchmarkEvidenceInput} input the school's documents and the year to measure.
+ * @return {BenchmarkData} the coverage.
+ */
+export declare function computeBenchmarkData(input: BenchmarkEvidenceInput): BenchmarkData;
+/** The collection the rollups live in. */
+export declare const BENCHMARK_AGGREGATES = "benchmarkAggregates";
+/**
+ * A benchmark's stat as the rollup stores it: everything except the two per-pupil
+ * lists.
+ *
+ * `missing` is a name per uncovered pupil and `eventRefs` one per contributing event,
+ * so on a large secondary they are most of the payload — and they are only ever read
+ * on a school's own page, which computes live anyway. Dropping them is what keeps a
+ * school's year comfortably inside the 1MB document limit.
+ */
+export type BenchmarkAggregateStat = Omit<BenchmarkStat, "eventRefs" | "byPeriod"> & {
+    byPeriod?: Omit<NonNullable<BenchmarkStat["byPeriod"]>[number], "missing">[];
+};
+/** One school-year in the rollup. */
+export type BenchmarkAggregateYear = Omit<BenchmarkData, "byBenchmark"> & {
+    byBenchmark: {
+        [benchmark: number]: BenchmarkAggregateStat;
+    };
+    /** When this year was last recomputed, ISO. The UI shows it: a figure from a
+     * rollup has to say how old it is, or it reads as live and isn't. */
+    computedAt: string;
+};
+export type BenchmarkAggregateDoc = {
+    oId: string;
+    years: {
+        [academicYear: string]: BenchmarkAggregateYear;
+    };
+};
+/**
+ * A computed year, trimmed to what the rollup stores.
+ *
+ * Drops the per-pupil lists, and drops `undefined` outright rather than writing it:
+ * Firestore rejects an undefined field value, and `biggestGap`, `byPeriod` and an
+ * event's `startDate` are all legitimately absent.
+ *
+ * @param {BenchmarkData} data the computed year.
+ * @param {string} computedAt when it was computed, ISO.
+ * @return {BenchmarkAggregateYear} the document body for this year.
+ */
+export declare function benchmarkRollupYear(data: BenchmarkData, computedAt: string): BenchmarkAggregateYear;
+/**
+ * How stale a rollup year is, in hours.
+ *
+ * @param {BenchmarkAggregateYear} [year] the stored year.
+ * @param {Date|string} [now] the instant to measure from.
+ * @return {number|undefined} hours since it was computed, absent when it never was.
+ */
+export declare function benchmarkRollupAgeHours(year?: Pick<BenchmarkAggregateYear, "computedAt">, now?: Date | string): number | undefined;