بناء نظام متابعة رخص بلدي والامتثال البلدي بلغة 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';
 
/** التقويم الذي يُعبَّر به نظاميًا عن تاريخ انتهاء الرخصة. */
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>;
 
/** تاريخ هجري بتقويم أم القرى — تاريخ مدني وليس طابعًا زمنيًا. */
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>;
 
/**
 * السجل التجاري السعودي: عشرة أرقام.
 * الرقم الأول يرمز إلى مجموعة المدينة المُصدِرة.
 */
export const CommercialRegistration = z
  .string()
  .regex(/^[12347]\d{9}$/, 'السجل التجاري عشرة أرقام تبدأ بـ 1 أو 2 أو 3 أو 4 أو 7');
 
/** أرقام رخص بلدي سلاسل رقمية من عشر خانات. */
export const LicenceNumber = z
  .string()
  .regex(/^\d{10}$/, 'رقم رخصة بلدي عشرة أرقام بالضبط');
 
export const Licence = z.object({
  id: z.string().uuid(),
  kind: LicenceKind,
  licenceNumber: LicenceNumber,
  commercialRegistration: CommercialRegistration,
 
  /** اسم الفرع مع الأمانة أو البلدية التي أصدرت الرخصة. */
  branchName: z.string().min(1),
  municipality: z.string().min(1), // مثل "أمانة منطقة الرياض"
 
  /** التقويم الذي طُبع به تاريخ الانتهاء. */
  authoritativeCalendar: z.enum(['hijri', 'gregorian']),
 
  /** الحقلان مملوءان دائمًا، وأحدهما مشتق من الآخر. */
  expiresOnHijri: HijriDate,
  expiresOnGregorian: z.string().date(), // ISO YYYY-MM-DD
 
  /** آخر مرة تأكدنا فيها من الرخصة مقابل المنصة. */
  lastVerifiedAt: z.string().datetime().nullable(),
 
  /** من يتابع التجديد. الرخص بلا مالك هي سبب الغرامات. */
  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;
}
 
/** تحويل لحظة ميلادية إلى تاريخها المدني بأم القرى بتوقيت الرياض. */
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;
}

/**
 * إيجاد التاريخ الميلادي الذي يوافق تاريخ أم القرى `target` بالضبط.
 * يُعيد null إذا كان التاريخ غير موجود (مثل اليوم 30 في شهر من 29 يومًا).
 */
export function fromHijri(target: HijriParts): Date | null {
  // نقطة بداية من بدء التقويم الهجري (622-07-19م) ومتوسط طول السنة.
  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;
}
 
/**
 * إضافة سنوات هجرية كاملة إلى تاريخ ميلادي مع الحفاظ على اليوم الهجري.
 * يُخفَّض اليوم 30 إلى 29 عندما يكون الشهر الهدف قصيرًا.
 */
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;
 
  // اليوم 30 غير موجود في كل شهر هجري — نرجع إلى 29.
  const clamped = fromHijri({ ...wanted, day: 29 });
  if (!clamped) {
    throw new Error(
      `تعذّر تحديد التاريخ الهجري ${wanted.year}-${wanted.month}-${wanted.day}`,
    );
  }
  return clamped;
}
 
/** صيغة ISO YYYY-MM-DD، وهي ما تخزّنه وتفهرس عليه. */
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 صفر 1448هـ
 
console.log(toIsoDate(addHijriYears(issued, 1)));
// 2027-08-02   — وليس 2027-08-12
 
console.log(toIsoDate(addHijriYears(issued, 5)));
// 2031-06-19   — وليس 2031-08-12

import { z } from 'zod';
import { addHijriYears, fromHijri, toHijri, toIsoDate } from './hijri';
import { HijriDate, Licence, LicenceKind, LicenceNumber } from './domain';
 
/** ما يعطينا إياه موظف العمليات أو ملف الاستيراد فعليًا. */
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,
    'يجب تزويد تاريخ انتهاء واحد على الأقل',
  );
 
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;
 
  // التقويم الذي زوّدنا به المستخدم هو التقويم النظامي للرخصة.
  const authoritativeCalendar = input.expiresOnHijri ? 'hijri' : 'gregorian';
 
  if (hijri && !gregorian) {
    const resolved = fromHijri(hijri);
    if (!resolved) {
      throw new Error(
        `التاريخ الهجري ${hijri.year}-${hijri.month}-${hijri.day} غير موجود في أم القرى`,
      );
    }
    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,
  };
}
 
/** إسقاط موعد التجديد التالي مع احترام التقويم المرجعي. */
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;
  /** الحد الأعلى شاملًا، بالأيام المتبقية. */
  withinDays: number;
  action: string;
}
 
/**
 * مرتبة من الأضيق. تجديدات بلدي تحتاج واقعيًا ثلاثة إلى أربعة أسابيع
 * عندما يتطلب الأمر إعادة معاينة السلامة، لذا تبدأ حالة 'urgent'
 * قبل الموعد بوقت كافٍ لا عنده.
 */
export const STAGES: Stage[] = [
  { id: 'grace',    severity: 'critical', withinDays: 7,  action: 'تصعيد إلى مدير العمليات اليوم' },
  { id: 'urgent',   severity: 'high',     withinDays: 30, action: 'قدّم التجديد الآن واحجز معاينة السلامة' },
  { id: 'due',      severity: 'medium',   withinDays: 60, action: 'تأكد من سريان عقد الإيجار والسجل التجاري' },
  { id: 'upcoming', severity: 'low',      withinDays: 90, action: 'أضفها إلى دفعة التجديد القادمة' },
];
 
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: 'مزاولة نشاط برخصة منتهية — مراجعة عاجلة لوقف الخسارة',
    };
  }
 
  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: 'لا إجراء' };
}

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;
}
 
/**
 * عمر النصف للتحقق. الرخصة التي تم التحقق منها قبل 120 يومًا ليست دليلًا،
 * بل ذكرى. شدّد هذه القيمة للفروع عالية المخاطر.
 */
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: 'أُدخلت ولم يتم تأكيدها قط مقابل منصة بلدي',
      });
      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: `مسجّلة كمنتهية منذ ${Math.abs(verdict.daysRemaining)} يومًا — تأكد أنها لم تُجدَّد خارج النظام`,
      });
    } else if (ageDays > STALE_AFTER_DAYS) {
      flags.push({
        licenceId: licence.id,
        branchName: licence.branchName,
        reason: 'stale_verification',
        detail: `آخر تحقق قبل ${ageDays} يومًا`,
      });
    }
  }
 
  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');
 
  // التجميع حسب المالك حتى لا يتلقى أحدهم أربعين رسالة منفصلة.
  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
      ? `[عاجل] ${critical} رخصة بلدي تحتاج إجراءً اليوم`
      : `${items.length} رخصة بلدي تقترب من التجديد`;
 
    const body = items
      .sort((a, b) => a.daysRemaining - b.daysRemaining)
      .map((i) => `${i.branchName}: ${i.daysRemaining} يومًا — ${i.action}`)
      .join('\n');
 
    await notify.send(owner, subject, body);
  }
 
  if (flags.length > 0) {
    console.warn(`[balady] رُفعت ${flags.length} علامة مطابقة`);
  }
}

import { describe, expect, it } from 'vitest';
import { addHijriYears, fromHijri, toHijri, toIsoDate } from './hijri';
 
describe('محرك أم القرى', () => {
  it('يحوّل تاريخًا معروفًا', () => {
    expect(toHijri(new Date('2026-08-12T00:00:00Z'))).toEqual({
      year: 1448,
      month: 2,
      day: 29,
    });
  });
 
  it('يعود ذهابًا وإيابًا كل أسبوع على مدى إحدى عشرة سنة', () => {
    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, `لا تحويل عكسي لـ ${JSON.stringify(hijri)}`).not.toBeNull();
      expect(toHijri(back!)).toEqual(hijri);
    }
  });
 
  it('يتأخر عشرة أيام عن الذكرى الميلادية', () => {
    const issued = new Date('2026-08-12T00:00:00Z');
    expect(toIsoDate(addHijriYears(issued, 1))).toBe('2027-08-02');
  });
 
  it('يراكم الانحراف على مدى خمس سنوات', () => {
    const issued = new Date('2026-08-12T00:00:00Z');
    expect(toIsoDate(addHijriYears(issued, 5))).toBe('2031-06-19');
  });
 
  it('يعيد null ليوم غير موجود', () => {
    // نمسح سنة كاملة بحثًا عن الشهور القصيرة ونتأكد أننا لا نخترع تاريخًا.
    for (let month = 1; month <= 12; month++) {
      const resolved = fromHijri({ year: 1448, month, day: 30 });
      if (resolved) expect(toHijri(resolved).day).toBe(30);
    }
  });
});