بناء محرك احتساب اشتراكات التأمينات الاجتماعية ومطابقتها باستخدام TypeScript

// src/rates/types.ts
 
export type Scheme = "existing" | "new" | "non-saudi";
 
export interface RateComponents {
  /** مكوّن المعاشات / التقاعد */
  annuitiesEmployer: number;
  annuitiesEmployee: number;
  /** الأخطار المهنية — على صاحب العمل فقط */
  hazardsEmployer: number;
  /** ساند للتأمين ضد التعطل */
  sanedEmployer: number;
  sanedEmployee: number;
}
 
export interface RateBand {
  scheme: Scheme;
  /** بداية النطاق شاملة، بصيغة ISO */
  effectiveFrom: string;
  /** النهاية غير شاملة. null = مفتوح */
  effectiveTo: string | null;
  components: RateComponents;
  /** المصدر — أي تعميم أو نظام حدّد هذا النطاق */
  source: string;
}

// src/rates/table.ts
import type { RateBand } from "./types";
 
const NONE = {
  annuitiesEmployer: 0,
  annuitiesEmployee: 0,
  hazardsEmployer: 0,
  sanedEmployer: 0,
  sanedEmployee: 0,
};
 
export const RATE_TABLE: readonly RateBand[] = [
  {
    scheme: "existing",
    effectiveFrom: "2000-01-01",
    effectiveTo: null,
    components: {
      annuitiesEmployer: 0.09,
      annuitiesEmployee: 0.09,
      hazardsEmployer: 0.02,
      sanedEmployer: 0.0075,
      sanedEmployee: 0.0075,
    },
    source: "النظام القائم، دون تغيير لمن سُجّل قبل 2024-07-03",
  },
  {
    scheme: "new",
    effectiveFrom: "2024-07-03",
    effectiveTo: "2025-07-01",
    components: {
      annuitiesEmployer: 0.09,
      annuitiesEmployee: 0.09,
      hazardsEmployer: 0.02,
      sanedEmployer: 0.0075,
      sanedEmployee: 0.0075,
    },
    source: "نظام التأمينات الجديد، السنة الأولى (21.5% مجموعًا)",
  },
  {
    scheme: "new",
    effectiveFrom: "2025-07-01",
    effectiveTo: "2026-07-01",
    components: {
      annuitiesEmployer: 0.095,
      annuitiesEmployee: 0.095,
      hazardsEmployer: 0.02,
      sanedEmployer: 0.0075,
      sanedEmployee: 0.0075,
    },
    source: "النظام الجديد، الزيادة الأولى 0.5 نقطة (22.5% مجموعًا)",
  },
  {
    scheme: "new",
    effectiveFrom: "2026-07-01",
    effectiveTo: "2027-07-01",
    components: {
      annuitiesEmployer: 0.1,
      annuitiesEmployee: 0.1,
      hazardsEmployer: 0.02,
      sanedEmployer: 0.0075,
      sanedEmployee: 0.0075,
    },
    source: "النظام الجديد، الزيادة الثانية (23.5% مجموعًا)",
  },
  {
    scheme: "non-saudi",
    effectiveFrom: "2000-01-01",
    effectiveTo: null,
    components: { ...NONE, hazardsEmployer: 0.02 },
    source: "الأخطار المهنية فقط للمشتركين غير السعوديين",
  },
];

// src/rates/lookup.ts
import { RATE_TABLE } from "./table";
import type { RateBand, Scheme } from "./types";
 
export function resolveRateBand(scheme: Scheme, periodStart: string): RateBand {
  const band = RATE_TABLE.find(
    (b) =>
      b.scheme === scheme &&
      periodStart >= b.effectiveFrom &&
      (b.effectiveTo === null || periodStart < b.effectiveTo),
  );
 
  if (!band) {
    throw new Error(
      `لا يوجد نطاق نسب للتأمينات للنظام "${scheme}" بتاريخ ${periodStart}. ` +
        `الجدول يحتاج على الأرجح إلى تمديد — راجع جدول النِسَب المعتمد الحالي.`,
    );
  }
  return band;
}

// src/domain/employee.ts
import { z } from "zod";
 
export const EmployeeSchema = z.object({
  employeeId: z.string().min(1),
  /** رقم الهوية الوطنية (سعودي) أو رقم الإقامة (غير سعودي) */
  identityNumber: z.string().regex(/^[12]\d{9}$/, "يجب أن يكون 10 أرقام تبدأ بـ 1 أو 2"),
  nationality: z.enum(["saudi", "non-saudi"]),
  /** تاريخ أول تسجيل في التأمينات على الإطلاق — لا تاريخ العقد الحالي */
  gosiRegistrationDate: z.string().date(),
  basicSalary: z.number().nonnegative(),
  housingAllowance: z.number().nonnegative(),
  joinedOn: z.string().date(),
  leftOn: z.string().date().nullable(),
});
 
export type Employee = z.infer<typeof EmployeeSchema>;

// src/domain/scheme.ts
import type { Employee } from "./employee";
import type { Scheme } from "../rates/types";
 
const NEW_SCHEME_START = "2024-07-03";
 
export function resolveScheme(employee: Employee): Scheme {
  if (employee.nationality === "non-saudi") return "non-saudi";
  return employee.gosiRegistrationDate >= NEW_SCHEME_START ? "new" : "existing";
}

// src/domain/wage.ts
import type { Employee } from "./employee";
 
/** 45,000 ريال معبَّرًا عنها بالهللات */
export const CONTRIBUTORY_WAGE_CEILING = 4_500_000;
 
export function toHalalas(riyals: number): number {
  return Math.round(riyals * 100);
}
 
export interface ContributoryWage {
  /** بالهللات، قبل السقف */
  declared: number;
  /** بالهللات، بعد السقف */
  capped: number;
  ceilingApplied: boolean;
}
 
export function contributoryWage(employee: Employee): ContributoryWage {
  const declared = toHalalas(employee.basicSalary) + toHalalas(employee.housingAllowance);
  const capped = Math.min(declared, CONTRIBUTORY_WAGE_CEILING);
  return { declared, capped, ceilingApplied: capped < declared };
}

// src/domain/proration.ts
import type { Employee } from "./employee";
 
export interface Period {
  /** أول يوم في شهر الرواتب، ISO */
  start: string;
  /** آخر يوم في شهر الرواتب، ISO */
  end: string;
}
 
export function daysInPeriod(period: Period): number {
  const [y, m] = period.start.split("-").map(Number);
  return new Date(Date.UTC(y, m, 0)).getUTCDate();
}
 
/** أيام تغطية التأمينات لهذا الموظف داخل الفترة. */
export function coveredDays(employee: Employee, period: Period): number {
  const total = daysInPeriod(period);
  const from = employee.joinedOn > period.start ? employee.joinedOn : period.start;
  const to =
    employee.leftOn !== null && employee.leftOn < period.end ? employee.leftOn : period.end;
 
  if (from > to) return 0;
 
  const fromDay = Number(from.slice(8, 10));
  const toDay = Number(to.slice(8, 10));
  return Math.min(toDay - fromDay + 1, total);
}
 
export function prorationFactor(employee: Employee, period: Period): number {
  return coveredDays(employee, period) / daysInPeriod(period);
}

// src/engine/calculate.ts
import { resolveRateBand } from "../rates/lookup";
import { resolveScheme } from "../domain/scheme";
import { contributoryWage } from "../domain/wage";
import { prorationFactor, type Period } from "../domain/proration";
import type { Employee } from "../domain/employee";
 
export interface ContributionBreakdown {
  annuitiesEmployer: number;
  annuitiesEmployee: number;
  hazardsEmployer: number;
  sanedEmployer: number;
  sanedEmployee: number;
}
 
export interface ContributionResult {
  employeeId: string;
  period: string;
  scheme: string;
  contributoryWage: number;
  ceilingApplied: boolean;
  prorationFactor: number;
  breakdown: ContributionBreakdown;
  employerTotal: number;
  employeeTotal: number;
  grandTotal: number;
  rateSource: string;
}
 
/** حتمي: تقريب النصف بعيدًا عن الصفر، بالهللات. */
function applyRate(wageHalalas: number, rate: number, factor: number): number {
  return Math.round(wageHalalas * rate * factor);
}
 
export function calculateContribution(
  employee: Employee,
  period: Period,
): ContributionResult {
  const scheme = resolveScheme(employee);
  const band = resolveRateBand(scheme, period.start);
  const wage = contributoryWage(employee);
  const factor = prorationFactor(employee, period);
  const c = band.components;
 
  const breakdown: ContributionBreakdown = {
    annuitiesEmployer: applyRate(wage.capped, c.annuitiesEmployer, factor),
    annuitiesEmployee: applyRate(wage.capped, c.annuitiesEmployee, factor),
    hazardsEmployer: applyRate(wage.capped, c.hazardsEmployer, factor),
    sanedEmployer: applyRate(wage.capped, c.sanedEmployer, factor),
    sanedEmployee: applyRate(wage.capped, c.sanedEmployee, factor),
  };
 
  const employerTotal =
    breakdown.annuitiesEmployer + breakdown.hazardsEmployer + breakdown.sanedEmployer;
  const employeeTotal = breakdown.annuitiesEmployee + breakdown.sanedEmployee;
 
  return {
    employeeId: employee.employeeId,
    period: period.start.slice(0, 7),
    scheme,
    contributoryWage: wage.capped,
    ceilingApplied: wage.ceilingApplied,
    prorationFactor: factor,
    breakdown,
    employerTotal,
    employeeTotal,
    grandTotal: employerTotal + employeeTotal,
    rateSource: band.source,
  };
}

// src/access/port.ts
 
export interface GosiStatementLine {
  identityNumber: string;
  contributoryWage: number;
  employerAmount: number;
  employeeAmount: number;
}
 
export interface GosiStatement {
  establishmentId: string;
  period: string;
  lines: GosiStatementLine[];
  totalBilled: number;
}
 
/**
 * السطح الوحيد الذي يعتمد عليه النطاق. قد تكون التطبيقات واجهة وسيط،
 * أو تصديرًا من مزوّد نظام موارد بشرية معتمد، أو تنزيلًا محلَّلًا من البوابة.
 */
export interface GosiAccessPort {
  fetchStatement(establishmentId: string, period: string): Promise<GosiStatement>;
}

// src/access/csv-adapter.ts
import { parse } from "csv-parse/sync";
import { toHalalas } from "../domain/wage";
import type { GosiAccessPort, GosiStatement } from "./port";
 
export class CsvStatementAdapter implements GosiAccessPort {
  constructor(private readonly loadFile: (period: string) => Promise<string>) {}
 
  async fetchStatement(establishmentId: string, period: string): Promise<GosiStatement> {
    const raw = await this.loadFile(period);
    const rows = parse(raw, { columns: true, skip_empty_lines: true, bom: true });
 
    const lines = rows.map((r: Record<string, string>) => ({
      identityNumber: r["identity_number"].trim(),
      contributoryWage: toHalalas(Number(r["contributory_wage"])),
      employerAmount: toHalalas(Number(r["employer_amount"])),
      employeeAmount: toHalalas(Number(r["employee_amount"])),
    }));
 
    return {
      establishmentId,
      period,
      lines,
      totalBilled: lines.reduce(
        (sum, l) => sum + l.employerAmount + l.employeeAmount,
        0,
      ),
    };
  }
}

// src/recon/reconcile.ts
import type { ContributionResult } from "../engine/calculate";
import type { GosiStatement } from "../access/port";
import type { Employee } from "../domain/employee";
 
export type VarianceCode =
  | "MISSING_FROM_STATEMENT"
  | "MISSING_FROM_PAYROLL"
  | "WAGE_MISMATCH"
  | "SCHEME_MISMATCH"
  | "AMOUNT_MISMATCH"
  | "ROUNDING_ONLY";
 
export interface Variance {
  code: VarianceCode;
  identityNumber: string;
  employeeId: string | null;
  calculated: number | null;
  billed: number | null;
  deltaHalalas: number;
  explanation: string;
}
 
/** الفروق عند هذا الحد أو دونه ضجيج، لا نتائج. */
const ROUNDING_TOLERANCE = 2;
 
export function reconcile(
  employees: Employee[],
  calculated: ContributionResult[],
  statement: GosiStatement,
): Variance[] {
  const calcByIdentity = new Map<string, ContributionResult>();
  for (const c of calculated) {
    const emp = employees.find((e) => e.employeeId === c.employeeId);
    if (emp) calcByIdentity.set(emp.identityNumber, c);
  }
 
  const variances: Variance[] = [];
  const seen = new Set<string>();
 
  for (const line of statement.lines) {
    seen.add(line.identityNumber);
    const calc = calcByIdentity.get(line.identityNumber);
 
    if (!calc) {
      variances.push({
        code: "MISSING_FROM_PAYROLL",
        identityNumber: line.identityNumber,
        employeeId: null,
        calculated: null,
        billed: line.employerAmount + line.employeeAmount,
        deltaHalalas: line.employerAmount + line.employeeAmount,
        explanation:
          "التأمينات تفوتر مشتركًا غائبًا عن مسير الرواتب هذا. " +
          "غالبًا موظف غادر ولم يُلغَ تسجيله، أو تسجيل تحت منشأة خاطئة.",
      });
      continue;
    }
 
    if (calc.contributoryWage !== line.contributoryWage) {
      variances.push({
        code: "WAGE_MISMATCH",
        identityNumber: line.identityNumber,
        employeeId: calc.employeeId,
        calculated: calc.contributoryWage,
        billed: line.contributoryWage,
        deltaHalalas: calc.contributoryWage - line.contributoryWage,
        explanation:
          "الأجر الخاضع للاشتراك مختلف. التأمينات تحتفظ بآخر أجر بُلّغت به؛ " +
          "والزيادة المطبَّقة في الرواتب ولم تُرفع إلى التأمينات تظهر بهذا الشكل تمامًا.",
      });
      continue;
    }
 
    const billed = line.employerAmount + line.employeeAmount;
    const delta = calc.grandTotal - billed;
 
    if (delta === 0) continue;
 
    if (Math.abs(delta) <= ROUNDING_TOLERANCE) {
      variances.push({
        code: "ROUNDING_ONLY",
        identityNumber: line.identityNumber,
        employeeId: calc.employeeId,
        calculated: calc.grandTotal,
        billed,
        deltaHalalas: delta,
        explanation: "ضمن حدود التقريب. لا إجراء مطلوبًا.",
      });
      continue;
    }
 
    // الأجر نفسه ومبلغ مختلف جوهريًا: النسبة المطبَّقة مختلفة،
    // وهذا يعني غالبًا أن الطرفين يختلفان حول النظام.
    variances.push({
      code: "SCHEME_MISMATCH",
      identityNumber: line.identityNumber,
      employeeId: calc.employeeId,
      calculated: calc.grandTotal,
      billed,
      deltaHalalas: delta,
      explanation:
        `أجر خاضع للاشتراك متطابق مع فرق قدره ${(delta / 100).toFixed(2)} ريال. ` +
        `احتُسب تحت نظام "${calc.scheme}" — تحقق من تاريخ أول تسجيل في التأمينات.`,
    });
  }
 
  for (const calc of calculated) {
    const emp = employees.find((e) => e.employeeId === calc.employeeId);
    if (!emp || seen.has(emp.identityNumber)) continue;
    if (calc.grandTotal === 0) continue;
 
    variances.push({
      code: "MISSING_FROM_STATEMENT",
      identityNumber: emp.identityNumber,
      employeeId: calc.employeeId,
      calculated: calc.grandTotal,
      billed: null,
      deltaHalalas: calc.grandTotal,
      explanation:
        "احتُسب اشتراك لشخص لا تفوتره التأمينات. " +
        "عادةً موظف جديد غير مسجَّل — وهذه مخاطرة تسجيل متأخر، لا وفر.",
    });
  }
 
  return variances;
}

// src/engine/calculate.test.ts
import { describe, it, expect } from "vitest";
import { calculateContribution } from "./calculate";
import type { Employee } from "../domain/employee";
 
const base: Employee = {
  employeeId: "E-001",
  identityNumber: "1012345678",
  nationality: "saudi",
  gosiRegistrationDate: "2020-01-15",
  basicSalary: 10_000,
  housingAllowance: 2_500,
  joinedOn: "2020-01-15",
  leftOn: null,
};
 
const june2026 = { start: "2026-06-01", end: "2026-06-30" };
const july2026 = { start: "2026-07-01", end: "2026-07-31" };
 
describe("اختيار النظام", () => {
  it("يبقي من سُجّل قبل 2024-07-03 على النظام القائم عبر الزيادة", () => {
    const june = calculateContribution(base, june2026);
    const july = calculateContribution(base, july2026);
    expect(june.grandTotal).toBe(july.grandTotal);
    expect(july.scheme).toBe("existing");
    // 12,500 ريال × 21.5% = 2,687.50 ريال
    expect(july.grandTotal).toBe(268_750);
  });
 
  it("يطبّق زيادة يوليو 2026 على تسجيلات النظام الجديد", () => {
    const newJoiner = { ...base, gosiRegistrationDate: "2025-03-01" };
    const june = calculateContribution(newJoiner, june2026);
    const july = calculateContribution(newJoiner, july2026);
    // من 22.5% إلى 23.5% على 12,500 ريال = 125 ريالًا زيادة
    expect(july.grandTotal - june.grandTotal).toBe(12_500);
    expect(july.grandTotal).toBe(293_750);
  });
 
  it("يعامل 2024-07-03 نفسه كنظام جديد", () => {
    const boundary = { ...base, gosiRegistrationDate: "2024-07-03" };
    expect(calculateContribution(boundary, july2026).scheme).toBe("new");
  });
 
  it("يحمّل غير السعوديين الأخطار المهنية فقط", () => {
    const expat = { ...base, nationality: "non-saudi" as const, identityNumber: "2012345678" };
    const r = calculateContribution(expat, july2026);
    expect(r.employeeTotal).toBe(0);
    expect(r.employerTotal).toBe(25_000); // 12,500 × 2%
  });
});
 
describe("السقف والتوزيع النسبي", () => {
  it("يحدّ الأجر الخاضع للاشتراك عند 45,000 ريال", () => {
    const exec = { ...base, basicSalary: 60_000, housingAllowance: 15_000 };
    const r = calculateContribution(exec, july2026);
    expect(r.ceilingApplied).toBe(true);
    expect(r.contributoryWage).toBe(4_500_000);
  });
 
  it("يوزّع من التحق منتصف الشهر توزيعًا شاملًا للطرفين", () => {
    const joiner = { ...base, joinedOn: "2026-07-17" };
    const r = calculateContribution(joiner, july2026);
    expect(r.prorationFactor).toBeCloseTo(15 / 31); // من 17 إلى 31 شاملًا
  });
 
  it("يُرجع صفرًا لمن غادر قبل الفترة", () => {
    const leaver = { ...base, leftOn: "2026-05-30" };
    expect(calculateContribution(leaver, july2026).grandTotal).toBe(0);
  });
});

// src/run.ts
import { readFile } from "node:fs/promises";
import { calculateContribution } from "./engine/calculate";
import { CsvStatementAdapter } from "./access/csv-adapter";
import { reconcile } from "./recon/reconcile";
import { EmployeeSchema, type Employee } from "./domain/employee";
 
export async function runMonthlyReconciliation(
  establishmentId: string,
  period: { start: string; end: string },
  rawEmployees: unknown[],
) {
  const employees: Employee[] = rawEmployees.map((r) => EmployeeSchema.parse(r));
 
  const calculated = employees.map((e) => calculateContribution(e, period));
 
  const adapter = new CsvStatementAdapter((p) =>
    readFile(`./statements/${establishmentId}-${p}.csv`, "utf8"),
  );
  const statement = await adapter.fetchStatement(establishmentId, period.start.slice(0, 7));
 
  const variances = reconcile(employees, calculated, statement);
 
  const calculatedTotal = calculated.reduce((s, c) => s + c.grandTotal, 0);
  const actionable = variances.filter((v) => v.code !== "ROUNDING_ONLY");
 
  return {
    period: period.start.slice(0, 7),
    headcount: employees.length,
    calculatedTotal,
    billedTotal: statement.totalBilled,
    difference: calculatedTotal - statement.totalBilled,
    actionable,
    summary: actionable.reduce<Record<string, number>>((acc, v) => {
      acc[v.code] = (acc[v.code] ?? 0) + 1;
      return acc;
    }, {}),
  };
}