placementt-core 1.400.993 → 1.400.995

package/src/callables/surveys.ts

@@ -1,6 +1,6 @@
 import {z} from "zod";
 import {CallableGroup} from "./types";
-import {SURVEY_KINDS_LIST} from "../surveys/types";
+import {SURVEY_COHORT_SCOPES, SURVEY_KINDS_LIST} from "../surveys/types";
 
 /**
  * Contracts for the unified survey engine
@@ -12,6 +12,7 @@ import {SURVEY_KINDS_LIST} from "../surveys/types";
  */
 
 const surveyKind = z.enum(SURVEY_KINDS_LIST as [string, ...string[]]);
+const cohortScope = z.enum(SURVEY_COHORT_SCOPES as [string, ...string[]]);
 
 const raters = z.object({
     students: z.boolean().optional(),
@@ -25,7 +26,7 @@ export const surveyCallables = {
             oId: z.string(),
             kind: surveyKind,
             /** One cycle per year group. Omitted for institute-wide kinds. */
-            yearGroups: z.array(z.number()).optional(),
+            yearGroups: z.array(z.string()).optional(),
             scheduledSendDate: z.string(), // ISO
             /** Overrides the year derived from the send date — the leaver thread's
              * Christmas leg sends in the year after the cohort's own. */
@@ -49,10 +50,10 @@ export const surveyCallables = {
         response: z.object({
             created: z.array(z.object({
                 cycleId: z.string(),
-                yearGroup: z.number().optional(),
+                yearGroup: z.string().optional(),
                 invited: z.number(),
             })),
-            skippedEmpty: z.array(z.number()),
+            skippedEmpty: z.array(z.string()),
             skippedNoEmail: z.number(),
             academicYear: z.string(),
         }),
@@ -65,7 +66,7 @@ export const surveyCallables = {
         }),
         response: z.object({
             cycleId: z.string(),
-            yearGroup: z.number().optional(),
+            yearGroup: z.string().optional(),
             invited: z.number(),
             skippedNoEmail: z.number().optional(),
             alreadyScheduled: z.boolean().optional(),
@@ -116,6 +117,44 @@ export const surveyCallables = {
         request: z.object({cycleId: z.string(), jobId: z.string().optional()}),
         response: z.object({deleted: z.number()}),
     },
+    "surveys-saveSurveyCohortSetup": {
+        request: z.object({
+            oId: z.string(),
+            scope: cohortScope,
+            /** Year group ("9") or skills group id ("all", "yg9", a mapping id). */
+            cohort: z.string(),
+            /** JSON-serialised DataViewerSelectionBackend. */
+            studentSelection: z.string().optional(),
+            selectionSummary: z.string().optional(),
+            /** null clears the cohort's template and falls back to the default copy. */
+            emailTemplateId: z.string().nullable().optional(),
+            /** false → store the answer for future years only, leaving the cycles
+             * already provisioned alone. Defaults to true. */
+            applyToExisting: z.boolean().optional(),
+        }),
+        response: z.object({
+            saved: z.boolean(),
+            /** Cycles that picked the answer up, and how many people they now reach. */
+            updatedCycles: z.number(),
+            invited: z.number(),
+        }),
+    },
+    "surveys-provisionSurveysNow": {
+        request: z.object({
+            oId: z.string(),
+            /** Omit for every programme the institute runs. */
+            scope: cohortScope.optional(),
+            /** Provision the upcoming academic year rather than the current one. */
+            nextYear: z.boolean().optional(),
+        }),
+        response: z.object({
+            created: z.number(),
+            academicYear: z.string(),
+            /** True when the current year had nothing left to create and the next
+             * academic year was provisioned instead. */
+            rolledForward: z.boolean(),
+        }),
+    },
     "surveys-getMySurveyRequest": {
         request: z.object({requestId: z.string()}),
         // Shape varies by kind (see HYDRATE in surveys.ts), so left open.

package/src/constants.ts

@@ -980,6 +980,12 @@ export const emailTemplates:{[key: string]: EmailTemplateConfig} = {
         button: {text: "Connect with Employers", link: "/login"},
         sections: ["employerDatabaseSummarySection"],
     },
+    skillsInvite: {
+        description: "Sent to students, parents and employers inviting them to complete a skills assessment.",
+        params: ["studentForename", "instituteName"],
+        type: "skillsInvite",
+        button: {text: "Complete Assessment", link: "/institutes/surveys/skills/{{requestId}}"},
+    },
     aspirationInvite: {
         description: "Sent to students inviting them to complete the career aspirations survey.",
         params: ["studentForename", "instituteName"],
@@ -1513,3 +1519,13 @@ export const JOB_VALUES: string[] = [
     "Working with technology",
 ];
 
+
+/**
+ * The `UserData.details` key holding a student's year group tag.
+ *
+ * A defined standard key rather than one of the dynamic upload columns: the Wonde
+ * sync writes it, the manual spreadsheet upload always offers it, and every survey's
+ * recipient filter resolves a cohort by matching `details.year` against a tag from
+ * `InstituteData.yearGroups`. The tag is opaque — matched as a string, never parsed.
+ */
+export const STUDENT_YEAR_FIELD = "year";

package/src/portfolioAggregate.ts

@@ -21,7 +21,7 @@ import {
     StudentPlacementData,
     UserData,
 } from "./typeDefinitions";
-import {skillLabelColours} from "./constants";
+import {skillColour} from "./constants";
 
 // ── Brand ────────────────────────────────────────────────────────────────────
 // The portfolio uses the CareerThread platform palette, which is distinct from
@@ -120,7 +120,10 @@ export const ACTIVITY_TYPE_TO_PFA: Record<StudentActivity["activityType"], PfaPa
 // Self-Management would naturally sit under Independent living and Attitude &
 // Resilience under Good health, but those pathways aren't rendered yet, so they
 // are folded into the two reported ones so no skill silently disappears.
-export const SKILL_CATEGORY_TO_PFA: Record<SkillLabel["category"], PfaPathway> = {
+// Categories a framework brings with it are mapped here too — anything unmapped
+// (e.g. a school's own category) falls back to PFA_DEFAULT_PATHWAY.
+export const SKILL_CATEGORY_TO_PFA: Record<string, PfaPathway> = {
+    // Platform categories.
     ["Communication"]: "communityInclusion",
     ["Teamwork"]: "communityInclusion",
     ["Self-Management"]: "employmentAndFurtherLearning",
@@ -128,6 +131,10 @@ export const SKILL_CATEGORY_TO_PFA: Record<SkillLabel["category"], PfaPathway> =
     ["Attitude & Resilience"]: "communityInclusion",
     ["Work Readiness"]: "employmentAndFurtherLearning",
     ["Career Development"]: "employmentAndFurtherLearning",
+    // SDS meta-skills wheel pillars ("Self-Management" is shared with the platform
+    // set above and maps the same way).
+    ["Social Intelligence"]: "communityInclusion",
+    ["Innovation"]: "employmentAndFurtherLearning",
 };
 
 // ── Aggregate output shape ────────────────────────────────────────────────────
@@ -316,7 +323,7 @@ function buildSkill(
         skillId,
         label: label.label,
         category: label.category,
-        color: skillLabelColours[label.category],
+        color: skillColour(label),
         latestScore: latestStudent,
         firstScore,
         distanceTravelled: Math.round((latestStudent - firstScore) * 100) / 100,

package/src/surveys/types.ts

@@ -94,8 +94,9 @@ export type SurveyCycle = {
      * Legacy leaverGroups used the slash form ("2026/27") and are converted on migration. */
     academicYear: string,
     /** The single year group this cycle targets. Absent for alumni check-in cycles,
-     * which are institute-wide. Replaces AspirationCycle.yearGroupsIncluded. */
-    yearGroup?: number,
+     * which are institute-wide. Replaces AspirationCycle.yearGroupsIncluded. Opaque:
+     * whatever tag the school's import wrote to details.year, matched as a string. */
+    yearGroup?: string,
     /** SkillsMapping.id ("all" for the All students group) — skills cycles only. */
     groupId?: string,
     /** Chains the cycles of one journey: the three leaver kinds for a cohort share
@@ -186,7 +187,7 @@ export type SurveyRequest = {
     email: string,
     /** Post-leaving contact address; where invites go once the school email dies. */
     personalEmail?: string,
-    yearGroup?: number,
+    yearGroup?: string,
     status: SurveyRequestStatus,
     completed: boolean,
     /** ISO — when the invite was emailed. */
@@ -221,3 +222,84 @@ export type SurveyRequest = {
     parentToken?: string,
     parentTokenExpiry?: string,
 };
+
+// ─── Per-cohort setup ─────────────────────────────────────────────────────────
+
+/**
+ * The two questions a school can only answer once per cohort — who is in it, and
+ * which email its invitations use.
+ *
+ * A survey's SCHEDULE holds for every year to come, so setup asks for it once. Its
+ * COHORT does not: no school's student records agree on how a year group is written,
+ * so provisioning cannot resolve "Year 9" on its own, and until someone says who
+ * Year 9 is, that year group's surveys have nobody to send to. Rather than ask again
+ * every time a survey is provisioned, the answer is stored here and every later
+ * survey for that cohort inherits it — including next year's, whose cohort is the
+ * same query against a new set of students.
+ *
+ * Stored on institutes/{oId}.surveyCohorts, keyed by surveyCohortKey().
+ */
+export type SurveyCohortSetup = {
+    /** JSON-serialised DataViewerSelectionBackend — a FILTER, not a frozen list, so
+     * it re-resolves against whoever is in the year group at each send. */
+    studentSelection?: string,
+    /** Human summary of the selection ("All students matching Year group: 9"), for
+     * the setup screens — the JSON is not readable enough to show staff. */
+    selectionSummary?: string,
+    /** How many students it resolved to when it was saved. Indicative only. */
+    resolvedCount?: number,
+    /** emailTemplates doc id used for this cohort's invitations. Absent = the
+     * platform's default copy for the kind. */
+    emailTemplateId?: string,
+    savedAt?: string,
+    /** uid of the staff member who answered. */
+    savedBy?: string,
+};
+
+/**
+ * A cohort's scope. Kinds that share a cohort share a scope, so answering once for
+ * Year 11 leavers covers all three legs of their journey.
+ */
+export type SurveyCohortScope = "aspirations"|"leavers"|"skills";
+
+/** Every scope as a runtime array — for validation. */
+export const SURVEY_COHORT_SCOPES: SurveyCohortScope[] = ["aspirations", "leavers", "skills"];
+
+/**
+ * The key one cohort's setup is stored under: the scope plus the cohort within it —
+ * a year group for aspirations and leavers ("aspirations_y9"), a skills group id for
+ * skills ("skills_all", "skills_yg9", "skills_<mappingId>").
+ *
+ * @param {SurveyCohortScope} scope which programme the cohort belongs to.
+ * @param {string} cohort the year group tag, or the skills group id.
+ * @return {string} the storage key.
+ */
+export const surveyCohortKey = (scope: SurveyCohortScope, cohort: string): string =>
+    `${scope}_${surveyCohortSlug(cohort)}`;
+
+/**
+ * A year group tag reduced to characters that are safe in a Firestore field path and
+ * document id.
+ *
+ * A tag is whatever the school's MIS calls it — "9", "Year 9", "Yr 9 (KS4)" — and it
+ * is never parsed or renumbered. But a key segment can't hold a slash or a dot, so
+ * anything outside [A-Za-z0-9_-] collapses to a hyphen for id purposes only. The tag
+ * itself is stored and matched verbatim.
+ *
+ * @param {string} tag the year group tag or group id.
+ * @return {string} the tag as a key segment.
+ */
+export const surveyCohortSlug = (tag: string): string =>
+    String(tag).trim().replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
+
+/** The scope a survey kind's cohorts are keyed under. */
+export const SURVEY_KIND_COHORT_SCOPE: {[k in SurveyKind]?: SurveyCohortScope} = {
+    aspirations: "aspirations",
+    skills: "skills",
+    leaverIntentions: "leavers",
+    leaverResults: "leavers",
+    leaverChristmas: "leavers",
+};
+
+/** Every cohort's setup, as stored on the institute. */
+export type SurveyCohortSetupMap = {[key: string]: SurveyCohortSetup};

package/src/typeDefinitions.ts

@@ -1,8 +1,8 @@
 import {DocumentData, DocumentReference, OrderByDirection, Timestamp, WhereFilterOp} from "firebase/firestore";
 import {Descendant} from "slate";
-import {emailTemplates, skillLabelColours} from "./constants";
+import {emailTemplates} from "./constants";
 import type {ChecklistItem, GiftHistory} from "./customerCareConfig";
-import type {SurveyKind, SurveySlot} from "./surveys/types";
+import type {SurveyCohortSetupMap, SurveyKind, SurveySlot} from "./surveys/types";
 
 export type FilterObject = {
     [key: string]: {
@@ -847,6 +847,12 @@ export type InstituteData = {
     students: number,
     staff: number,
     studentsFields: string[],
+    /** The year group tags present in this school's student records, in order, as
+     * written by whichever importer put them there (the Wonde sync, or a manual
+     * spreadsheet upload). Opaque strings — a tag is whatever the school calls it.
+     * Every year-group picker offers this list, and a selected tag resolves students
+     * by an exact string match on details.year. */
+    yearGroups?: string[],
     staffFields: string[],
     employerFields?: string[],
     studentsActive: number,
@@ -934,6 +940,10 @@ export type InstituteData = {
     // Written by the setup wizard (aspirations-saveDestinationsConfig); read by
     // destinationsProvisionCron each September to create that year's surveys/groups.
     destinationsConfig?: DestinationsConfig,
+    /** Who is in each survey cohort, and which email template it uses — the two
+     * answers a schedule can't supply on its own. Keyed by surveyCohortKey(); read
+     * by provisioning so every year's surveys inherit the answer. */
+    surveyCohorts?: SurveyCohortSetupMap,
     acceptingAlumni?: boolean,
     approveAlumni?: boolean,
     shareAlumni?: boolean
@@ -976,6 +986,11 @@ export type InstituteData = {
     /** Annual survey schedule for the default "All students" group. Auto-provisioned
      * into each academic year by the daily cron. */
     skillsSurveys?: SkillsSurveySlot[],
+    /** Which of the school's year group tags (InstituteData.yearGroups) take part in
+     * skills surveys. Provisioning creates one cycle per tag from `skillsSurveys`, so
+     * staff chase Year 9 separately from Year 10. Empty/absent = one survey for
+     * everyone. Tags are matched against details.year, never parsed. */
+    skillsYearGroups?: string[],
     scheduledSkillsAssessments?: {
         [key in "yearStart" | "yearEnd" | "eachTerm" | "preWorkExperience" | "postWorkExperience" | "employerInteraction" | "extracurricularActivity"]?: {
             students?: boolean,
@@ -1532,7 +1547,7 @@ export type EmailTemplateConfig = {
         button?: {text: string, link: string},
         secondaryButton?: {text: string, link: string},
         optionalButtons?: {text: string, link: string}[],
-        type: "workflow"|"feedback"|"event"|"campaign"|"database"|"onboarding"|"aspirationInvite"|"leaverInvite"|"leaverResultsInvite"|"leaverChristmasInvite",
+        type: "workflow"|"feedback"|"event"|"campaign"|"database"|"onboarding"|"skillsInvite"|"aspirationInvite"|"leaverInvite"|"leaverResultsInvite"|"leaverChristmasInvite",
         sections?: EmailSectionNames[],
 }
 
@@ -2053,7 +2068,8 @@ export type DestinationsConfig = {
     // ── Aspirations (Form A) ──
     aspirations: {
         enabled: boolean,
-        yearGroups: number[],                   // e.g. [7,8,9,10,11]
+        /** Year group tags from InstituteData.yearGroups. Matched, never parsed. */
+        yearGroups: string[],
         /** Shared schedule applied to every selected year group. Any number of sends
          * per year — a school running one a term is as valid as one a year. */
         surveys: AspirationSurveySlot[],
@@ -2067,7 +2083,8 @@ export type DestinationsConfig = {
     // ── Leavers (Form B + checkpoints) ──
     leavers: {
         enabled: boolean,
-        yearGroups: number[],                   // subset of [11, 13]
+        /** Year group tags from InstituteData.yearGroups. Matched, never parsed. */
+        yearGroups: string[],
         // Each leg is scheduled by relative rule with the MM-DD as its materialised
         // fallback, the same pair aspiration and skills slots use.
         intentionsSendMMDD: string,             // Form B, before they leave — default "06-15"
@@ -2872,7 +2889,12 @@ export type SkillsFrameworkKey = "custom" | "skillsBuilder" | "sdsMetaskills";
 export type SkillLabel = {
     label: string,
     description: string,
-    category: keyof typeof skillLabelColours,
+    /** The group this skill sits under, stored on the document — pickers and reports
+     * head skills by it. A framework brings its own set (the SDS meta-skills wheel has
+     * exactly three: Self-Management, Social Intelligence, Innovation); generic and
+     * school-created labels use the platform set in `skillLabelColours`. Free text, so
+     * a framework is never forced into the platform categories. */
+    category: string,
     /** Display colour stored on the document. Seeded via the admin
      * "Seed skill labels & colours" action (framework labels carry their own
      * scheme, e.g. the SDS meta-skills wheel pillars). Read via skillColour(),