placementt-core 1.400.1236 → 1.400.1237

package/src/pricing.ts

@@ -59,6 +59,10 @@ export type PricingConfig = {
     },
     /** Careers hubs are a flat platform fee plus a fee for each school. */
     hub: {baseFee: number, perSchoolFee: number},
+    /** Taken off a returning school's placement fee for each student who was on
+     * work experience last year and didn't get a placement, as a fraction of
+     * that placement's price (0.5 = those placements are half price). */
+    returningUnplacedDiscount: number,
 };
 
 /** The pricing sheet's figures, as agreed for 2026. */
@@ -74,6 +78,7 @@ export const DEFAULT_PRICING_CONFIG: PricingConfig = {
     fullPlatformDiscount: 0.1,
     trust: {threshold: 10, discount: 0.05, largeDiscount: 0.1},
     hub: {baseFee: 2000, perSchoolFee: 150},
+    returningUnplacedDiscount: 0.5,
 };
 
 /** Where the adjustable copy of the config lives. */
@@ -103,6 +108,9 @@ export type SchoolPricingInput = {
     /** A price agreed with the customer, which replaces everything above it —
      * the discounts, the minimum fee and the total the products came to. */
     quoteOverride?: number,
+    /** Students on work experience last year who never got a placement. That
+     * many of this year's placements are charged at the returning discount. */
+    returningUnplaced?: number,
 };
 
 export type PricingLineKey =
@@ -113,8 +121,10 @@ export type PricingLine = {
     label: string,
     /** What the product costs after any partial-product discount. */
     amount: number,
-    /** The fee before its partial-product discount, when one was applied. */
+    /** The fee before its partial-product or returning discount, when one was applied. */
     undiscounted?: number,
+    /** Placements on this line charged at the returning discount. */
+    returningPlacements?: number,
     /** How the amount was reached, band by band. Empty for the base fee. */
     bands: PricingBand[],
 };
@@ -224,6 +234,44 @@ export function trustDiscountRate(
     return count >= config.trust.threshold ? config.trust.largeDiscount : config.trust.discount;
 }
 
+/**
+ * Charge last year's unplaced students' placements at the returning discount.
+ *
+ * A school that paid for students who never got a placement shouldn't pay full
+ * price for them again. Those placements are spread across the year groups in
+ * proportion to each one's placements, and priced at that year group's average
+ * rate per placement, so the graduated bands still decide what a placement is
+ * worth. Never more placements than this year's quote has.
+ *
+ * @param {Array} lines the fees so far; the work experience ones are changed in place.
+ * @param {object} input the quote's inputs.
+ * @param {object} config the figures to price with.
+ */
+function applyReturningDiscount(lines: PricingLine[], input: SchoolPricingInput, config: PricingConfig) {
+    const wexLines = lines.filter((l) => l.key === "wexY10" || l.key === "wexY12");
+    const placements = sum(wexLines.map((l) => sum(l.bands.map((b) => b.quantity))));
+    const unplaced = Math.min(Math.max(Math.floor(input.returningUnplaced || 0), 0), placements);
+    const rate = clampFraction(config.returningUnplacedDiscount);
+    if (!unplaced || !rate) return;
+
+    let remaining = unplaced;
+    wexLines.forEach((line, index) => {
+        const linePlacements = sum(line.bands.map((b) => b.quantity));
+        if (!linePlacements || !line.amount) return;
+        // The last year group takes whatever rounding left over, so the
+        // placements discounted always add up to the unplaced count.
+        const share = index === wexLines.length - 1 ?
+            Math.min(remaining, linePlacements) :
+            Math.min(Math.round(unplaced * linePlacements / placements), linePlacements, remaining);
+        if (!share) return;
+        remaining -= share;
+        const undiscounted = line.amount;
+        line.amount = undiscounted - share * (undiscounted / linePlacements) * rate;
+        line.undiscounted = undiscounted;
+        line.returningPlacements = share;
+    });
+}
+
 /**
  * Price a school, trust or hub-school quote.
  *
@@ -257,6 +305,7 @@ export function calculateSchoolPrice(
     };
     addWex("wexY10", "Work experience: Y10", input.wexY10);
     addWex("wexY12", "Work experience: Y12", input.wexY12);
+    applyReturningDiscount(lines, input, config);
 
     const addPerStudent = (key: "events"|"destinations", label: string, taken?: boolean, discounted?: boolean) => {
         if (!taken) return;
@@ -339,6 +388,7 @@ export function mergePricingConfig(stored?: Partial<PricingConfig>): PricingConf
         tiers: stored.tiers?.length ? stored.tiers.map((t, i) => ({...(d.tiers[i] || d.tiers[d.tiers.length - 1]), ...t})) : d.tiers,
         partialProductDiscount: {...d.partialProductDiscount, ...stored.partialProductDiscount},
         fullPlatformDiscount: stored.fullPlatformDiscount ?? d.fullPlatformDiscount,
+        returningUnplacedDiscount: stored.returningUnplacedDiscount ?? d.returningUnplacedDiscount,
         trust: {...d.trust, ...stored.trust},
         hub: {...d.hub, ...stored.hub},
     };
@@ -379,12 +429,19 @@ export type InstitutePricing = {
     discountReason?: string,
     /** A price agreed with the customer, which replaces the calculated one. */
     quoteOverride?: number,
+    /** Students on last year's work experience cohorts who never got a placement,
+     * charged at the returning discount this year. One school's, for a trust. */
+    returningUnplaced?: number,
     /** Schools in the trust, which set its discount. Trust accounts only. */
     schools?: number,
     /** Schools on the hub. Hub accounts only. */
     hubSchools?: number,
     /** The quote as last saved, for the customer to see. */
     quote?: InstituteQuoteSnapshot,
+    /** Academic years ("2026-27") an admin marked as invoiced outside the panel,
+     * for a customer billed some other way (old pricing, an invoice that can't
+     * be matched to them in Xero). Admin-only. */
+    markedInvoiced?: {[year: string]: {at: string, note?: string}},
 };
 
 /** A priced institute: the same shape for a school, a trust and a hub. */
@@ -550,6 +607,7 @@ export function instituteQuote(
         fullPlatformDiscount: pricing?.fullPlatformDiscount,
         bespokeDiscount: pricing?.bespokeDiscount,
         quoteOverride: pricing?.quoteOverride,
+        returningUnplaced: wex ? pricing?.returningUnplaced : undefined,
     }, config);
 }