placementt-core 1.400.966 → 1.400.968

package/lib/typeDefinitions.d.ts

@@ -3348,4 +3348,136 @@ export type LeaverGroup = {
         };
     };
 };
+/** Keys identifying each importable LMI source. Used for lmiMeta/status and
+ * for addressing individual sync callables from the admin cards. */
+export type LmiSourceKey = "socDescriptions" | "asheNational" | "asheRegional" | "nomisEmployment" | "standards" | "titleAliases";
+/** One searchable job-title alias pointing into a 4-digit SOC profile, from the
+ * ONS SOC 2020 Volume 2 coding index (~30k titles). Stored in lmiTitleAliases
+ * so a student searching "physiotherapist" or "ethical hacker" resolves to the
+ * right occupation even though those aren't SOC unit-group names. */
+export type LmiTitleAlias = {
+    title: string;
+    search: string;
+    keywords: string[];
+    soc: string;
+};
+/** National full-time gross annual pay percentiles for an occupation (whole
+ * pounds). Any percentile ONS suppressed ("x" / "..") is stored as null. */
+export type LmiSalaryPercentiles = {
+    p10: number | null;
+    p25: number | null;
+    median: number | null;
+    p75: number | null;
+    p90: number | null;
+};
+/** Median full-time gross annual pay for an occupation within one ONS work
+ * region / UK nation (ASHE Table 15). */
+export type LmiRegionalSalary = {
+    median: number | null;
+    regionName: string;
+};
+/** Employment (job count) for an occupation within one region, from the Nomis
+ * Annual Population Survey. Keyed by the parent 2-digit SOC. */
+export type LmiRegionalEmployment = {
+    jobs: number | null;
+    regionName: string;
+};
+/** A linked apprenticeship standard (IfATE / Skills England). Doubles as
+ * "routes in" content for the future student-facing career profile. */
+export type LmiApprenticeshipStandard = {
+    name: string;
+    level: number;
+    reference: string;
+};
+/** One document per 4-digit SOC 2020 occupation: lmiOccupations/{soc4Code}.
+ * Each source owns and merge-writes only its own fields, so a partial sync
+ * never clobbers data written by another source. */
+export type LmiOccupation = {
+    soc: string;
+    title: string;
+    description: string;
+    entryRoutes?: string;
+    salary?: {
+        year: number;
+        national: LmiSalaryPercentiles;
+        byRegion: {
+            [regionCode: string]: LmiRegionalSalary;
+        };
+    };
+    employment?: {
+        year: number;
+        soc2: string;
+        byRegion: {
+            [regionCode: string]: LmiRegionalEmployment;
+        };
+    };
+    skills?: string[];
+    apprenticeshipStandards?: LmiApprenticeshipStandard[];
+    lastUpdated: string;
+};
+/** Editable per-source configuration (lmiMeta/config) so next year's refresh
+ * needs only a URL/edition change in the admin card — no redeploy. */
+export type LmiMetaConfig = {
+    sources: {
+        asheTable14: {
+            url: string;
+            edition: number;
+        };
+        asheTable15: {
+            url: string;
+            edition: number;
+        };
+        socVolume1: {
+            url: string;
+        };
+        nomis: {
+            datasetId: string;
+            geography: string;
+        };
+        standards?: {
+            url: string;
+        };
+        titleAliases?: {
+            url: string;
+        };
+    };
+    /** Optional per-source note surfaced in the admin card, e.g. to flag a URL
+     * that could not be verified and should be checked/corrected by an admin. */
+    notes?: {
+        [K in LmiSourceKey]?: string;
+    };
+};
+export type LmiSyncState = "idle" | "running" | "success" | "error";
+/** Per-source sync state read by the admin status cards (lmiMeta/status). */
+export type LmiSyncStatus = {
+    lastRun: string;
+    lastSuccess?: string;
+    state: LmiSyncState;
+    error?: string;
+    counts?: {
+        occupationsWritten: number;
+        rowsParsed: number;
+    };
+};
+/** lmiMeta/status document shape — one LmiSyncStatus per source key. */
+export type LmiMetaStatus = Partial<Record<LmiSourceKey, LmiSyncStatus>>;
+/** Phase 3 — proposed title-based matches between apprenticeship standards and
+ * occupations, written to lmiMeta/standardsMatchReview for human review when
+ * the standards data carries no SOC code to link on directly. */
+export type LmiStandardsMatchReview = {
+    generatedAt: string;
+    unmatchedStandards?: {
+        reference: string;
+        name: string;
+        level: number;
+    }[];
+    proposedMatches: {
+        soc: string;
+        occupationTitle: string;
+        standardReference: string;
+        standardName: string;
+        standardLevel: number;
+        confidence: number;
+    }[];
+};
 export {};

package/package.json

@@ -2,7 +2,7 @@
   "private": false,
   "name": "placementt-core",
   "author": "Placementt",
-  "version": "1.400.966",
+  "version": "1.400.968",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {

package/src/typeDefinitions.ts

@@ -3319,4 +3319,132 @@ export type LeaverGroup = {
         resultsDay?: {sentAt?: string, reminderSentAt?: string, totalSent?: number, totalResponded?: number},
         christmas?: {sentAt?: string, reminderSentAt?: string, totalSent?: number, totalResponded?: number},
     },
+}
+
+/* ------------------------------------------------------------------------- *
+ * Labour Market Information (LMI)                                            *
+ *                                                                           *
+ * Free, open-data occupation intelligence used to power career             *
+ * recommendations. Populated server-side by the lmiImport callables from   *
+ * ONS (ASHE Tables 14 & 15, SOC 2020 Volume 1), the Nomis API and          *
+ * (Phase 3) IfATE / Skills England apprenticeship standards.               *
+ * Firestore: lmiOccupations/{soc4}, lmiMeta/config, lmiMeta/status.        *
+ * ------------------------------------------------------------------------- */
+
+/** Keys identifying each importable LMI source. Used for lmiMeta/status and
+ * for addressing individual sync callables from the admin cards. */
+export type LmiSourceKey =
+    "socDescriptions"|"asheNational"|"asheRegional"|"nomisEmployment"|
+    "standards"|"titleAliases";
+
+/** One searchable job-title alias pointing into a 4-digit SOC profile, from the
+ * ONS SOC 2020 Volume 2 coding index (~30k titles). Stored in lmiTitleAliases
+ * so a student searching "physiotherapist" or "ethical hacker" resolves to the
+ * right occupation even though those aren't SOC unit-group names. */
+export type LmiTitleAlias = {
+    title: string,          // display title, natural word order
+    search: string,         // sanitised lowercase title for prefix search
+    keywords: string[],     // sanitised tokens for word (array-contains) search
+    soc: string,            // 4-digit SOC 2020 the title codes to
+}
+
+/** National full-time gross annual pay percentiles for an occupation (whole
+ * pounds). Any percentile ONS suppressed ("x" / "..") is stored as null. */
+export type LmiSalaryPercentiles = {
+    p10: number|null,
+    p25: number|null,
+    median: number|null,
+    p75: number|null,
+    p90: number|null,
+}
+
+/** Median full-time gross annual pay for an occupation within one ONS work
+ * region / UK nation (ASHE Table 15). */
+export type LmiRegionalSalary = {
+    median: number|null,
+    regionName: string,
+}
+
+/** Employment (job count) for an occupation within one region, from the Nomis
+ * Annual Population Survey. Keyed by the parent 2-digit SOC. */
+export type LmiRegionalEmployment = {
+    jobs: number|null,
+    regionName: string,
+}
+
+/** A linked apprenticeship standard (IfATE / Skills England). Doubles as
+ * "routes in" content for the future student-facing career profile. */
+export type LmiApprenticeshipStandard = {
+    name: string,
+    level: number,
+    reference: string,
+}
+
+/** One document per 4-digit SOC 2020 occupation: lmiOccupations/{soc4Code}.
+ * Each source owns and merge-writes only its own fields, so a partial sync
+ * never clobbers data written by another source. */
+export type LmiOccupation = {
+    soc: string,                    // "2236" — 4-digit SOC 2020, also the doc id
+    title: string,
+    description: string,
+    entryRoutes?: string,           // qualifications / entry text from SOC vol 1
+    salary?: {
+        year: number,               // ASHE edition year
+        national: LmiSalaryPercentiles,
+        byRegion: {[regionCode: string]: LmiRegionalSalary},
+    },
+    employment?: {
+        year: number,
+        soc2: string,               // parent 2-digit code the stats are keyed on
+        byRegion: {[regionCode: string]: LmiRegionalEmployment},
+    },
+    skills?: string[],              // Phase 3 — condensed IfATE/SE KSB skill names
+    apprenticeshipStandards?: LmiApprenticeshipStandard[], // Phase 3
+    lastUpdated: string,            // ISO timestamp
+}
+
+/** Editable per-source configuration (lmiMeta/config) so next year's refresh
+ * needs only a URL/edition change in the admin card — no redeploy. */
+export type LmiMetaConfig = {
+    sources: {
+        asheTable14: {url: string, edition: number},
+        asheTable15: {url: string, edition: number},
+        socVolume1: {url: string},
+        nomis: {datasetId: string, geography: string},
+        standards?: {url: string},  // Phase 3 — IfATE/Skills England endpoint
+        titleAliases?: {url: string}, // ONS SOC 2020 Vol 2 coding index
+    },
+    /** Optional per-source note surfaced in the admin card, e.g. to flag a URL
+     * that could not be verified and should be checked/corrected by an admin. */
+    notes?: {[K in LmiSourceKey]?: string},
+}
+
+export type LmiSyncState = "idle"|"running"|"success"|"error";
+
+/** Per-source sync state read by the admin status cards (lmiMeta/status). */
+export type LmiSyncStatus = {
+    lastRun: string,
+    lastSuccess?: string,
+    state: LmiSyncState,
+    error?: string,
+    counts?: {occupationsWritten: number, rowsParsed: number},
+}
+
+/** lmiMeta/status document shape — one LmiSyncStatus per source key. */
+export type LmiMetaStatus = Partial<Record<LmiSourceKey, LmiSyncStatus>>;
+
+/** Phase 3 — proposed title-based matches between apprenticeship standards and
+ * occupations, written to lmiMeta/standardsMatchReview for human review when
+ * the standards data carries no SOC code to link on directly. */
+export type LmiStandardsMatchReview = {
+    generatedAt: string,
+    unmatchedStandards?: {reference: string, name: string, level: number}[],
+    proposedMatches: {
+        soc: string,
+        occupationTitle: string,
+        standardReference: string,
+        standardName: string,
+        standardLevel: number,
+        confidence: number,        // 0-1 heuristic score
+    }[],
 }