Créer un suivi de conformité des licences Balady en TypeScript

mkdir balady-tracker && cd balady-tracker
npm init -y
npm install zod
npm install -D typescript tsx vitest @types/node
npx tsc --init

import { z } from 'zod';
 
/** Le calendrier dans lequel l'expiration est juridiquement exprimée. */
export type CalendarSystem = 'hijri' | 'gregorian';
 
export const LicenceKind = z.enum([
  'commercial_activity', // رخصة نشاط تجاري
  'building_permit',     // رخصة بناء
  'safety_permit',       // تصريح السلامة
  'signage',             // رخصة لوحة
  'mobile_cart',         // رخصة عربة متنقلة
]);
export type LicenceKind = z.infer<typeof LicenceKind>;
 
/** Date hégirienne (Umm al-Qura) : une date civile, pas un horodatage. */
export const HijriDate = z.object({
  year: z.number().int().min(1300).max(1600),
  month: z.number().int().min(1).max(12),
  day: z.number().int().min(1).max(30),
});
export type HijriDate = z.infer<typeof HijriDate>;
 
/**
 * Registre de commerce saoudien : 10 chiffres.
 * Le premier chiffre encode le groupe de villes émetteur.
 */
export const CommercialRegistration = z
  .string()
  .regex(/^[12347]\d{9}$/, 'Le RC compte 10 chiffres commençant par 1, 2, 3, 4 ou 7');
 
/** Les numéros de licence Balady sont des chaînes de 10 chiffres. */
export const LicenceNumber = z
  .string()
  .regex(/^\d{10}$/, 'Le numéro de licence Balady compte exactement 10 chiffres');
 
export const Licence = z.object({
  id: z.string().uuid(),
  kind: LicenceKind,
  licenceNumber: LicenceNumber,
  commercialRegistration: CommercialRegistration,
 
  /** Libellé de la succursale et municipalité émettrice. */
  branchName: z.string().min(1),
  municipality: z.string().min(1), // ex. "أمانة منطقة الرياض"
 
  /** Le calendrier dans lequel la date d'expiration est imprimée. */
  authoritativeCalendar: z.enum(['hijri', 'gregorian']),
 
  /** Toujours renseignés tous les deux. L'un dérive de l'autre. */
  expiresOnHijri: HijriDate,
  expiresOnGregorian: z.string().date(), // ISO YYYY-MM-DD
 
  /** Dernière confirmation de la licence auprès de la plateforme. */
  lastVerifiedAt: z.string().datetime().nullable(),
 
  /** Qui relance le renouvellement. Une expiration sans responsable devient une amende. */
  ownerEmail: z.string().email(),
});
export type Licence = z.infer<typeof Licence>;

const UMALQURA = 'en-u-ca-islamic-umalqura-nu-latn';
const RIYADH = 'Asia/Riyadh';
const DAY_MS = 86_400_000;
 
const partsFormatter = new Intl.DateTimeFormat(UMALQURA, {
  year: 'numeric',
  month: 'numeric',
  day: 'numeric',
  timeZone: RIYADH,
});
 
export interface HijriParts {
  year: number;
  month: number;
  day: number;
}
 
/** Convertit un instant grégorien en date civile Umm al-Qura à Riyad. */
export function toHijri(date: Date): HijriParts {
  const parts = Object.fromEntries(
    partsFormatter
      .formatToParts(date)
      .filter((p) => p.type !== 'literal')
      .map((p) => [p.type, p.value]),
  );
 
  return {
    year: Number(parts.year),
    month: Number(parts.month),
    day: Number(parts.day),
  };
}
 
function compareHijri(a: HijriParts, b: HijriParts): number {
  return a.year - b.year || a.month - b.month || a.day - b.day;
}

/**
 * Trouve la date grégorienne dont la date Umm al-Qura vaut exactement `target`.
 * Renvoie null si la date n'existe pas (ex. jour 30 d'un mois de 29 jours).
 */
export function fromHijri(target: HijriParts): Date | null {
  // Amorce : époque hégirienne (19/07/622) et longueur moyenne de l'année.
  const seed = Date.UTC(622, 6, 19) + (target.year - 1) * 354.367 * DAY_MS;
 
  let lo = seed - 60 * DAY_MS;
  let hi = seed + 420 * DAY_MS;
 
  while (hi - lo > DAY_MS) {
    const mid = lo + Math.floor((hi - lo) / 2 / DAY_MS) * DAY_MS;
    if (compareHijri(toHijri(new Date(mid)), target) < 0) {
      lo = mid;
    } else {
      hi = mid;
    }
  }
 
  const candidate = new Date(hi);
  return compareHijri(toHijri(candidate), target) === 0 ? candidate : null;
}
 
/**
 * Ajoute des années hégiriennes entières en préservant le quantième hégirien.
 * Ramène le jour 30 à 29 lorsque le mois cible est court.
 */
export function addHijriYears(date: Date, years: number): Date {
  const current = toHijri(date);
  const wanted: HijriParts = {
    year: current.year + years,
    month: current.month,
    day: current.day,
  };
 
  const exact = fromHijri(wanted);
  if (exact) return exact;
 
  // Le jour 30 n'existe pas dans tous les mois hégiriens — repli sur le 29.
  const clamped = fromHijri({ ...wanted, day: 29 });
  if (!clamped) {
    throw new Error(
      `Impossible de résoudre la date hégirienne ${wanted.year}-${wanted.month}-${wanted.day}`,
    );
  }
  return clamped;
}
 
/** ISO YYYY-MM-DD, ce que vous stockez et indexez. */
export function toIsoDate(date: Date): string {
  return date.toISOString().slice(0, 10);
}

const issued = new Date('2026-08-12T00:00:00Z');
 
console.log(toHijri(issued));
// { year: 1448, month: 2, day: 29 }  → 29 Safar 1448 AH
 
console.log(toIsoDate(addHijriYears(issued, 1)));
// 2027-08-02   — et non 2027-08-12
 
console.log(toIsoDate(addHijriYears(issued, 5)));
// 2031-06-19   — et non 2031-08-12

import { z } from 'zod';
import { addHijriYears, fromHijri, toHijri, toIsoDate } from './hijri';
import { HijriDate, Licence, LicenceKind, LicenceNumber } from './domain';
 
/** Ce que fournit réellement un utilisateur des opérations ou un import. */
export const LicenceInput = z
  .object({
    kind: LicenceKind,
    licenceNumber: LicenceNumber,
    commercialRegistration: z.string(),
    branchName: z.string().min(1),
    municipality: z.string().min(1),
    ownerEmail: z.string().email(),
    expiresOnHijri: HijriDate.optional(),
    expiresOnGregorian: z.string().date().optional(),
  })
  .refine(
    (input) => input.expiresOnHijri || input.expiresOnGregorian,
    "Fournissez au moins une date d'expiration",
  );
 
export type LicenceInput = z.infer<typeof LicenceInput>;
 
export function normaliseLicence(
  raw: unknown,
  id: string,
): Omit<Licence, 'lastVerifiedAt'> & { lastVerifiedAt: null } {
  const input = LicenceInput.parse(raw);
 
  let hijri = input.expiresOnHijri;
  let gregorian = input.expiresOnGregorian;
 
  // Le calendrier fourni par l'utilisateur est celui qui fait foi.
  const authoritativeCalendar = input.expiresOnHijri ? 'hijri' : 'gregorian';
 
  if (hijri && !gregorian) {
    const resolved = fromHijri(hijri);
    if (!resolved) {
      throw new Error(
        `La date hégirienne ${hijri.year}-${hijri.month}-${hijri.day} n'existe pas dans Umm al-Qura`,
      );
    }
    gregorian = toIsoDate(resolved);
  }
 
  if (gregorian && !hijri) {
    hijri = toHijri(new Date(`${gregorian}T00:00:00Z`));
  }
 
  return {
    id,
    kind: input.kind,
    licenceNumber: input.licenceNumber,
    commercialRegistration: input.commercialRegistration,
    branchName: input.branchName,
    municipality: input.municipality,
    ownerEmail: input.ownerEmail,
    authoritativeCalendar,
    expiresOnHijri: hijri!,
    expiresOnGregorian: gregorian!,
    lastVerifiedAt: null,
  };
}
 
/** Projette le prochain renouvellement en respectant le calendrier faisant foi. */
export function nextExpiry(licence: Licence, terms = 1): string {
  const current = new Date(`${licence.expiresOnGregorian}T00:00:00Z`);
 
  if (licence.authoritativeCalendar === 'hijri') {
    return toIsoDate(addHijriYears(current, terms));
  }
 
  const projected = new Date(current);
  projected.setUTCFullYear(projected.getUTCFullYear() + terms);
  return toIsoDate(projected);
}

import type { Licence } from './domain';
 
export type Severity = 'none' | 'low' | 'medium' | 'high' | 'critical';
 
export interface Stage {
  id: string;
  severity: Severity;
  /** Borne supérieure incluse, en jours restants. */
  withinDays: number;
  action: string;
}
 
/**
 * Ordonné du plus étroit au plus large. Un renouvellement Balady demande
 * réellement trois à quatre semaines lorsqu'une contre-visite de sécurité
 * est requise : le stade 'urgent' commence donc bien avant l'échéance.
 */
export const STAGES: Stage[] = [
  { id: 'grace',    severity: 'critical', withinDays: 7,  action: "Escalader au responsable des opérations aujourd'hui" },
  { id: 'urgent',   severity: 'high',     withinDays: 30, action: 'Déposer le renouvellement et réserver la visite de sécurité' },
  { id: 'due',      severity: 'medium',   withinDays: 60, action: 'Vérifier la validité du bail et du registre de commerce' },
  { id: 'upcoming', severity: 'low',      withinDays: 90, action: 'Ajouter au prochain lot de renouvellement' },
];
 
export interface Assessment {
  licenceId: string;
  branchName: string;
  daysRemaining: number;
  stage: string;
  severity: Severity;
  action: string;
  ownerEmail: string;
}
 
const DAY_MS = 86_400_000;
 
export function daysRemaining(licence: Licence, now: Date): number {
  const expiry = Date.parse(`${licence.expiresOnGregorian}T00:00:00Z`);
  const today = Date.parse(`${now.toISOString().slice(0, 10)}T00:00:00Z`);
  return Math.round((expiry - today) / DAY_MS);
}
 
export function assess(licence: Licence, now: Date): Assessment {
  const remaining = daysRemaining(licence, now);
 
  const base = {
    licenceId: licence.id,
    branchName: licence.branchName,
    daysRemaining: remaining,
    ownerEmail: licence.ownerEmail,
  };
 
  if (remaining < 0) {
    return {
      ...base,
      stage: 'expired',
      severity: 'critical',
      action: 'Exploitation sans licence valide — revue immédiate requise',
    };
  }
 
  const stage = STAGES.find((s) => remaining <= s.withinDays);
 
  return stage
    ? { ...base, stage: stage.id, severity: stage.severity, action: stage.action }
    : { ...base, stage: 'ok', severity: 'none', action: 'Aucune action' };
}

import type { Licence } from './domain';
import { assess, type Assessment } from './escalation';
 
const DAY_MS = 86_400_000;
 
export interface ReconciliationFlag {
  licenceId: string;
  branchName: string;
  reason: 'never_verified' | 'stale_verification' | 'expired_unverified';
  detail: string;
}
 
/**
 * Demi-vie de la vérification. Une licence contrôlée il y a 120 jours n'est
 * plus une preuve mais un souvenir. À resserrer pour les sites à risque.
 */
const STALE_AFTER_DAYS = 120;
 
export function reconcile(licences: Licence[], now: Date): {
  assessments: Assessment[];
  flags: ReconciliationFlag[];
} {
  const assessments = licences.map((l) => assess(l, now));
  const flags: ReconciliationFlag[] = [];
 
  for (const licence of licences) {
    const verdict = assessments.find((a) => a.licenceId === licence.id)!;
 
    if (!licence.lastVerifiedAt) {
      flags.push({
        licenceId: licence.id,
        branchName: licence.branchName,
        reason: 'never_verified',
        detail: 'Importée mais jamais confirmée auprès de la plateforme Balady',
      });
      continue;
    }
 
    const ageDays = Math.floor(
      (now.getTime() - Date.parse(licence.lastVerifiedAt)) / DAY_MS,
    );
 
    if (verdict.stage === 'expired') {
      flags.push({
        licenceId: licence.id,
        branchName: licence.branchName,
        reason: 'expired_unverified',
        detail: `Enregistrée comme expirée depuis ${Math.abs(verdict.daysRemaining)} jours — vérifier qu'elle n'a pas été renouvelée hors système`,
      });
    } else if (ageDays > STALE_AFTER_DAYS) {
      flags.push({
        licenceId: licence.id,
        branchName: licence.branchName,
        reason: 'stale_verification',
        detail: `Dernière vérification il y a ${ageDays} jours`,
      });
    }
  }
 
  return { assessments, flags };
}

// src/job.ts
import { reconcile } from './reconcile';
import type { Licence } from './domain';
 
interface Notifier {
  send(to: string, subject: string, body: string): Promise<void>;
}
 
export async function runDailyComplianceJob(
  licences: Licence[],
  notify: Notifier,
  now = new Date(),
): Promise<void> {
  const { assessments, flags } = reconcile(licences, now);
 
  const actionable = assessments.filter((a) => a.severity !== 'none');
 
  // Regrouper par responsable pour éviter quarante e-mails distincts.
  const byOwner = new Map<string, typeof actionable>();
  for (const item of actionable) {
    const bucket = byOwner.get(item.ownerEmail) ?? [];
    bucket.push(item);
    byOwner.set(item.ownerEmail, bucket);
  }
 
  for (const [owner, items] of byOwner) {
    const critical = items.filter((i) => i.severity === 'critical').length;
    const subject = critical
      ? `[URGENT] ${critical} licence(s) Balady à traiter aujourd'hui`
      : `${items.length} licence(s) Balady approchent du renouvellement`;
 
    const body = items
      .sort((a, b) => a.daysRemaining - b.daysRemaining)
      .map((i) => `${i.branchName} : ${i.daysRemaining} j — ${i.action}`)
      .join('\n');
 
    await notify.send(owner, subject, body);
  }
 
  if (flags.length > 0) {
    console.warn(`[balady] ${flags.length} signalement(s) de réconciliation`);
  }
}

import { describe, expect, it } from 'vitest';
import { addHijriYears, fromHijri, toHijri, toIsoDate } from './hijri';
 
describe('Moteur Umm al-Qura', () => {
  it('convertit une date connue', () => {
    expect(toHijri(new Date('2026-08-12T00:00:00Z'))).toEqual({
      year: 1448,
      month: 2,
      day: 29,
    });
  });
 
  it('fait un aller-retour chaque semaine sur onze ans', () => {
    const start = Date.UTC(2018, 0, 1);
    for (let i = 0; i < 4000; i += 7) {
      const gregorian = new Date(start + i * 86_400_000);
      const hijri = toHijri(gregorian);
      const back = fromHijri(hijri);
 
      expect(back, `pas d'inverse pour ${JSON.stringify(hijri)}`).not.toBeNull();
      expect(toHijri(back!)).toEqual(hijri);
    }
  });
 
  it("décale de dix jours par rapport à l'anniversaire grégorien", () => {
    const issued = new Date('2026-08-12T00:00:00Z');
    expect(toIsoDate(addHijriYears(issued, 1))).toBe('2027-08-02');
  });
 
  it('accumule le décalage sur cinq ans', () => {
    const issued = new Date('2026-08-12T00:00:00Z');
    expect(toIsoDate(addHijriYears(issued, 5))).toBe('2031-06-19');
  });
 
  it("renvoie null pour un jour qui n'existe pas", () => {
    // Balayer une année pour trouver les mois courts sans inventer de date.
    for (let month = 1; month <= 12; month++) {
      const resolved = fromHijri({ year: 1448, month, day: 30 });
      if (resolved) expect(toHijri(resolved).day).toBe(30);
    }
  });
});