/** * Payslip bulk-upload auto-match (AK-P17b). Pure function — no DB, no IO — so it * is unit-testable in isolation. Given an uploaded file name and the tenant's * employees, it classifies the match confidence: * - `hard`: the file name contains the employee's personal number as a token. * - `soft`: the file name contains the employee's (last) name but no personal * number hit, OR more than one employee matches by name. * - `none`: nothing matched. * The admin confirms/overrides before any payslip is created. This module maps a * file name to a single best classification plus the ambiguous candidate set. */ export type PayslipMatchConfidence = "hard" | "soft" | "none"; export interface PayslipMatchEmployee { readonly userId: string; readonly personalNumber: string | null; /** Display name (e.g. "Alex Doe"); matched token-wise, case-insensitive. */ readonly name: string; } export interface PayslipMatchResult { readonly fileName: string; readonly confidence: PayslipMatchConfidence; /** The single matched employee when unambiguous; null for none/ambiguous. */ readonly employeeUserId: string | null; /** All plausible candidates (length > 1 ⇒ ambiguous ⇒ soft). */ readonly candidateUserIds: readonly string[]; } /** Lowercased alphanumeric tokens of length ≥ 2 (drops the file extension). */ function tokenize(value: string): string[] { const withoutExt = value.replace(/\.[a-z0-9]{1,5}$/i, ""); return withoutExt .toLowerCase() .split(/[^a-z0-9]+/i) .filter((token) => token.length >= 2); } /** Normalised digits of a personal number (so "PN-0042" matches "0042"). */ function digitsOf(value: string): string { return value.replace(/\D+/g, ""); } export function matchPayslipFile(fileName: string, employees: readonly PayslipMatchEmployee[]): PayslipMatchResult { const tokens = tokenize(fileName); const tokenSet = new Set(tokens); const haystackDigits = digitsOf(fileName); // 1. Hard match on personal number (unique digit token in the file name). const hardHits = employees.filter((employee) => { const pn = employee.personalNumber ? digitsOf(employee.personalNumber) : ""; return pn.length >= 2 && haystackDigits.includes(pn); }); if (hardHits.length === 1) { return { fileName, confidence: "hard", employeeUserId: hardHits[0]!.userId, candidateUserIds: [hardHits[0]!.userId] }; } if (hardHits.length > 1) { // Multiple personal-number hits ⇒ ambiguous, downgrade to soft. return { fileName, confidence: "soft", employeeUserId: null, candidateUserIds: hardHits.map((e) => e.userId) }; } // 2. Soft match on name tokens (every name token present in the file name). const nameHits = employees.filter((employee) => { const nameTokens = tokenize(employee.name); return nameTokens.length > 0 && nameTokens.every((token) => tokenSet.has(token)); }); if (nameHits.length === 1) { return { fileName, confidence: "soft", employeeUserId: nameHits[0]!.userId, candidateUserIds: [nameHits[0]!.userId] }; } if (nameHits.length > 1) { return { fileName, confidence: "soft", employeeUserId: null, candidateUserIds: nameHits.map((e) => e.userId) }; } return { fileName, confidence: "none", employeeUserId: null, candidateUserIds: [] }; }