بناء مُدقِّق كتالوج المنتجات قبل التقديم على سابر باستخدام TypeScript

mkdir saber-validator && cd saber-validator
npm init -y
npm install zod csv-parse date-fns
npm install -D typescript tsx @types/node vitest
npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

{
  "type": "module",
  "scripts": {
    "validate": "tsx src/cli.ts",
    "test": "vitest run"
  }
}

mkdir -p src/{rules,data,report} tests

// src/types.ts
import { z } from "zod";
 
export const ProductRecordSchema = z.object({
  /** رقم الصنف الداخلي — مفتاح الربط لكل شيء */
  sku: z.string().min(1),
 
  /** اسم المنتج كما سيظهر على الشهادة والفاتورة */
  nameEn: z.string().min(1),
  nameAr: z.string().optional(),
 
  /** العلامة التجارية والموديل يجب أن يطابقا البضاعة الفعلية والفاتورة */
  brand: z.string().min(1),
  model: z.string().min(1),
 
  /** الرمز الجمركي السعودي بـ 12 خانة، كنص للحفاظ على الأصفار البادئة */
  hsCode: z.string(),
 
  /** بلد الصنع، ISO 3166-1 alpha-2 */
  countryOfOrigin: z.string().length(2),
 
  /** الاسم النظامي للمصنّع، كما هو مطبوع على تقرير الاختبار */
  manufacturer: z.string().min(1),
 
  /** رقم شهادة مطابقة المنتج، إن صدرت */
  pcocNumber: z.string().optional(),
  pcocExpiry: z.coerce.date().optional(),
});
 
export type ProductRecord = z.infer<typeof ProductRecordSchema>;

// src/types.ts (تكملة)
 
export type Severity = "blocker" | "warning" | "info";
 
/**
 * قابلية الإصلاح تحدد تجميع التقرير. مسؤول الامتثال لا يريد المشكلات
 * مرتبة حسب رقم الصف — يريد أن يعرف ما يمكنه إصلاحه اليوم مقابل ما
 * يتطلب تقرير اختبار جديدًا ومهلة ستة أسابيع.
 */
export type Fixability =
  | "data-entry"        // إصلاح في نظامك أنت، دقائق
  | "documentation"     // طلب مستند من المورّد، أيام
  | "certification";    // تقويم مطابقة جديد، أسابيع
 
export interface ValidationIssue {
  sku: string;
  code: string;
  severity: Severity;
  fixability: Fixability;
  message: string;
  /** القيمة الملاحَظة، ليكون التقرير قابلًا للتنفيذ دون فتح الملف المصدر */
  observed?: string;
  /** الشكل الصحيح المتوقع */
  expected?: string;
}

// src/rules/hs-code.ts
import type { ProductRecord, ValidationIssue } from "../types.js";
 
const DIGITS_ONLY = /^\d+$/;
 
export function validateHsCode(product: ProductRecord): ValidationIssue[] {
  const issues: ValidationIssue[] = [];
  const raw = product.hsCode.trim();
 
  // Excel هو العدو هنا. تصل الرموز كـ "8516.60.00" أو "851660"
  // أو كعدد عشري فقد صفره البادئ.
  const normalised = raw.replace(/[.\s-]/g, "");
 
  if (!DIGITS_ONLY.test(normalised)) {
    issues.push({
      sku: product.sku,
      code: "HS_NON_NUMERIC",
      severity: "blocker",
      fixability: "data-entry",
      message: "الرمز الجمركي يحتوي على محارف غير رقمية بعد التوحيد.",
      observed: raw,
      expected: "12 خانة، مثال: 851660100000",
    });
    return issues; // لا جدوى من فحص الطول على قيمة تالفة
  }
 
  if (normalised.length === 12) {
    return issues; // صحيح
  }
 
  if (normalised.length < 12) {
    // الحالة الشائعة: رمز دولي من 6 أو 8 خانات استُورد
    // ولم يمدّه أحد إلى المستوى الوطني السعودي.
    issues.push({
      sku: product.sku,
      code: "HS_TOO_SHORT",
      severity: "blocker",
      fixability: "data-entry",
      message:
        `الرمز الجمركي فيه ${normalised.length} خانة. سابر يستنتج اللوائح ` +
        "الفنية على 12 خانة؛ الرمز الأقصر لا يمكن ربطه بلائحة.",
      observed: normalised,
      expected: `${normalised.padEnd(12, "0")} (تحقّق — لا تُكمل بالأصفار عشوائيًا)`,
    });
  } else {
    issues.push({
      sku: product.sku,
      code: "HS_TOO_LONG",
      severity: "blocker",
      fixability: "data-entry",
      message: `الرمز الجمركي فيه ${normalised.length} خانة، والمتوقع 12.`,
      observed: normalised,
    });
  }
 
  return issues;
}

// src/data/regulations.ts
export interface RegulationEntry {
  /** رمز من 12 خانة، أو بادئة للمطابقة على نطاق */
  hsPrefix: string;
  regulationCode: string;
  regulationNameEn: string;
  /** هل تتطلب هذه اللائحة شهادة منتج قبل إصدار شهادة الإرسالية؟ */
  requiresPcoc: boolean;
  /** الفئات عالية الخطورة تخضع لتدقيق إضافي ومهل أطول */
  riskLevel: "low" | "medium" | "high";
}
 
/**
 * مجموعة توضيحية مصغّرة. املأ الجدول الحقيقي من بيانات الهيئة المنشورة
 * وأصدر له نسخًا — اللوائح تتغير، وتحتاج أن تعرف أي مجموعة قواعد
 * جرى التحقق السابق وفقها.
 */
export const REGULATIONS: RegulationEntry[] = [
  {
    hsPrefix: "8516",
    regulationCode: "SASO-TR-ELEC-01",
    regulationNameEn: "Technical Regulation for Low Voltage Electrical Equipment",
    requiresPcoc: true,
    riskLevel: "high",
  },
  {
    hsPrefix: "9503",
    regulationCode: "SASO-TR-TOYS-01",
    regulationNameEn: "Technical Regulation for Toys",
    requiresPcoc: true,
    riskLevel: "high",
  },
  {
    hsPrefix: "6109",
    regulationCode: "SASO-TR-TEX-01",
    regulationNameEn: "Technical Regulation for Textile Products",
    requiresPcoc: true,
    riskLevel: "medium",
  },
];

// src/rules/regulation.ts
import { REGULATIONS, type RegulationEntry } from "../data/regulations.js";
import type { ProductRecord, ValidationIssue } from "../types.js";
 
export function resolveRegulation(hsCode: string): RegulationEntry | undefined {
  const normalised = hsCode.replace(/[.\s-]/g, "");
 
  // أطول بادئة تفوز: قاعدة محددة بـ 12 خانة تسبق قاعدة فصل بـ 4 خانات.
  let best: RegulationEntry | undefined;
  for (const entry of REGULATIONS) {
    if (!normalised.startsWith(entry.hsPrefix)) continue;
    if (!best || entry.hsPrefix.length > best.hsPrefix.length) {
      best = entry;
    }
  }
  return best;
}
 
export function validateRegulationCoverage(
  product: ProductRecord,
): ValidationIssue[] {
  const issues: ValidationIssue[] = [];
  const regulation = resolveRegulation(product.hsCode);
 
  if (!regulation) {
    // المنتجات غير المنظّمة موجودة فعلًا. لكن الرمز غير المطابق يكون
    // رمزًا خاطئًا أكثر بكثير من كونه منتجًا معفى — لذا حذّر، ولا تُمرّر.
    issues.push({
      sku: product.sku,
      code: "REG_UNMATCHED",
      severity: "warning",
      fixability: "data-entry",
      message:
        "لم تُطابق أي لائحة فنية هذا الرمز الجمركي. تأكد أن المنتج معفى " +
        "فعلًا وليس مصنّفًا تصنيفًا خاطئًا قبل الشحن.",
      observed: product.hsCode,
    });
    return issues;
  }
 
  if (regulation.requiresPcoc && !product.pcocNumber) {
    issues.push({
      sku: product.sku,
      code: "PCOC_MISSING",
      severity: "blocker",
      // هذه هي المكلفة: تحتاج جهة تقويم مطابقة وتقارير اختبار
      // وأسابيع من الوقت التقويمي.
      fixability: "certification",
      message:
        `${regulation.regulationNameEn} (${regulation.regulationCode}) تتطلب ` +
        "شهادة مطابقة منتج. لا توجد شهادة مسجلة لهذا الصنف.",
    });
  }
 
  if (regulation.riskLevel === "high") {
    issues.push({
      sku: product.sku,
      code: "REG_HIGH_RISK",
      severity: "info",
      fixability: "documentation",
      message:
        `مشمول بلائحة عالية الخطورة (${regulation.regulationCode}). ` +
        "توقّع تدقيقًا إضافيًا ومهل تقويم أطول.",
    });
  }
 
  return issues;
}

// src/rules/certificate.ts
import { addDays, differenceInDays, isBefore } from "date-fns";
import type { ProductRecord, ValidationIssue } from "../types.js";
 
export interface ExpiryOptions {
  /** الأيام من وقت التحقق حتى التخليص الجمركي المتوقع */
  transitLeadDays: number;
  /** هامش إضافي لطلب شهادة الإرسالية نفسه */
  bufferDays: number;
  /** مُحقَن ليكون الاختبار حتميًا */
  now?: Date;
}
 
export function validateCertificateValidity(
  product: ProductRecord,
  options: ExpiryOptions,
): ValidationIssue[] {
  const issues: ValidationIssue[] = [];
  if (!product.pcocNumber) return issues; // تعالجها قاعدة تغطية اللوائح
 
  const now = options.now ?? new Date();
  const requiredValidUntil = addDays(
    now,
    options.transitLeadDays + options.bufferDays,
  );
 
  if (!product.pcocExpiry) {
    issues.push({
      sku: product.sku,
      code: "PCOC_NO_EXPIRY",
      severity: "blocker",
      fixability: "documentation",
      message:
        `الشهادة ${product.pcocNumber} مسجلة بلا تاريخ انتهاء. ` +
        "لا يمكن تأكيد صلاحيتها.",
    });
    return issues;
  }
 
  if (isBefore(product.pcocExpiry, now)) {
    issues.push({
      sku: product.sku,
      code: "PCOC_EXPIRED",
      severity: "blocker",
      fixability: "certification",
      message: `الشهادة ${product.pcocNumber} منتهية الصلاحية بالفعل.`,
      observed: product.pcocExpiry.toISOString().slice(0, 10),
    });
    return issues;
  }
 
  if (isBefore(product.pcocExpiry, requiredValidUntil)) {
    const daysShort = differenceInDays(requiredValidUntil, product.pcocExpiry);
    issues.push({
      sku: product.sku,
      code: "PCOC_EXPIRES_IN_TRANSIT",
      severity: "blocker",
      fixability: "certification",
      message:
        `الشهادة ${product.pcocNumber} تنتهي قبل التخليص الجمركي المتوقع ` +
        `بـ ${daysShort} يومًا. جدّدها قبل الشحن.`,
      observed: product.pcocExpiry.toISOString().slice(0, 10),
      expected: `صالحة حتى ${requiredValidUntil.toISOString().slice(0, 10)}`,
    });
  }
 
  return issues;
}

// src/rules/reconcile.ts
import type { ProductRecord, ValidationIssue } from "../types.js";
 
export interface ShipmentLine {
  sku: string;
  /** الوصف كما هو مطبوع تمامًا على الفاتورة التجارية */
  invoiceDescription: string;
  invoiceBrand: string;
  invoiceModel: string;
  hsCode: string;
  quantity: number;
}
 
/** توحيد حالة الأحرف والمسافات وإسقاط الترقيم — قارن المعنى لا التنسيق. */
function canonical(value: string): string {
  return value
    .toLowerCase()
    .replace(/[^\p{L}\p{N}\s]/gu, " ")
    .replace(/\s+/g, " ")
    .trim();
}
 
export function reconcileShipment(
  lines: ShipmentLine[],
  catalogue: Map<string, ProductRecord>,
): ValidationIssue[] {
  const issues: ValidationIssue[] = [];
 
  for (const line of lines) {
    const product = catalogue.get(line.sku);
 
    if (!product) {
      issues.push({
        sku: line.sku,
        code: "SHIP_SKU_UNREGISTERED",
        severity: "blocker",
        fixability: "certification",
        message:
          "بند الإرسالية يشير إلى صنف بلا سجل منتج مسجل. " +
          "لا يمكن أن تغطيه شهادة مطابقة منتج قائمة.",
      });
      continue;
    }
 
    if (canonical(line.invoiceBrand) !== canonical(product.brand)) {
      issues.push({
        sku: line.sku,
        code: "SHIP_BRAND_MISMATCH",
        severity: "blocker",
        fixability: "documentation",
        message:
          "العلامة التجارية في الفاتورة لا تطابق العلامة في المنتج المسجل. " +
          "ستَرفض جهة تقويم المطابقة شهادة الإرسالية.",
        observed: line.invoiceBrand,
        expected: product.brand,
      });
    }
 
    if (canonical(line.invoiceModel) !== canonical(product.model)) {
      issues.push({
        sku: line.sku,
        code: "SHIP_MODEL_MISMATCH",
        severity: "blocker",
        fixability: "documentation",
        message:
          "الموديل في الفاتورة لا يطابق الموديل المسجل. هذا هو السبب " +
          "الأكثر شيوعًا لرفض شهادة الإرسالية.",
        observed: line.invoiceModel,
        expected: product.model,
      });
    }
 
    const lineHs = line.hsCode.replace(/[.\s-]/g, "");
    const productHs = product.hsCode.replace(/[.\s-]/g, "");
    if (lineHs !== productHs) {
      issues.push({
        sku: line.sku,
        code: "SHIP_HS_MISMATCH",
        severity: "blocker",
        fixability: "data-entry",
        message:
          "الرمز الجمركي في الفاتورة يختلف عن رمز المنتج المسجل. " +
          "ستستنتج الجمارك وسابر لوائح مختلفة للبضاعة نفسها.",
        observed: lineHs,
        expected: productHs,
      });
    }
 
    if (line.quantity <= 0) {
      issues.push({
        sku: line.sku,
        code: "SHIP_QUANTITY_INVALID",
        severity: "blocker",
        fixability: "data-entry",
        message: "كمية بند الإرسالية يجب أن تكون أكبر من صفر.",
        observed: String(line.quantity),
      });
    }
  }
 
  return issues;
}

// src/pipeline.ts
import { validateHsCode } from "./rules/hs-code.js";
import { validateRegulationCoverage } from "./rules/regulation.js";
import { validateCertificateValidity, type ExpiryOptions } from "./rules/certificate.js";
import { reconcileShipment, type ShipmentLine } from "./rules/reconcile.js";
import { ProductRecordSchema, type ProductRecord, type ValidationIssue } from "./types.js";
 
export interface ValidationInput {
  rawProducts: unknown[];
  shipmentLines?: ShipmentLine[];
  expiry: ExpiryOptions;
}
 
export interface ValidationResult {
  issues: ValidationIssue[];
  validProducts: ProductRecord[];
  parseFailures: number;
}
 
export function validateCatalogue(input: ValidationInput): ValidationResult {
  const issues: ValidationIssue[] = [];
  const validProducts: ProductRecord[] = [];
  let parseFailures = 0;
 
  for (const raw of input.rawProducts) {
    const parsed = ProductRecordSchema.safeParse(raw);
 
    if (!parsed.success) {
      parseFailures++;
      // حاول استخراج رقم الصنف للتقرير حتى من صف مشوّه،
      // وإلا لن يستطيع المشغّل إيجاد السطر المخالف.
      const sku =
        typeof raw === "object" && raw !== null && "sku" in raw
          ? String((raw as Record<string, unknown>).sku)
          : "unknown";
 
      for (const issue of parsed.error.issues) {
        issues.push({
          sku,
          code: "SCHEMA_INVALID",
          severity: "blocker",
          fixability: "data-entry",
          message: `الحقل "${issue.path.join(".")}": ${issue.message}`,
        });
      }
      continue;
    }
 
    const product = parsed.data;
    validProducts.push(product);
 
    issues.push(...validateHsCode(product));
    issues.push(...validateRegulationCoverage(product));
    issues.push(...validateCertificateValidity(product, input.expiry));
  }
 
  if (input.shipmentLines?.length) {
    const catalogue = new Map(validProducts.map((p) => [p.sku, p]));
    issues.push(...reconcileShipment(input.shipmentLines, catalogue));
  }
 
  return { issues, validProducts, parseFailures };
}

// src/report/summarise.ts
import type { Fixability, ValidationIssue } from "../types.js";
 
export interface ReportSection {
  fixability: Fixability;
  headline: string;
  leadTime: string;
  blockers: number;
  affectedSkus: string[];
  issues: ValidationIssue[];
}
 
const SECTION_META: Record<Fixability, { headline: string; leadTime: string }> = {
  "data-entry": {
    headline: "أصلحها في نظامك أنت",
    leadTime: "دقائق إلى ساعات",
  },
  documentation: {
    headline: "اطلب مستندات مصححة من المورّد",
    leadTime: "أيام",
  },
  certification: {
    headline: "تتطلب تقويم مطابقة — ابدأ الآن",
    leadTime: "أسابيع؛ هذا مسارك الحرج",
  },
};
 
const ORDER: Fixability[] = ["certification", "documentation", "data-entry"];
 
export function buildReport(issues: ValidationIssue[]): ReportSection[] {
  return ORDER.map((fixability) => {
    const scoped = issues.filter((i) => i.fixability === fixability);
    const meta = SECTION_META[fixability];
 
    return {
      fixability,
      headline: meta.headline,
      leadTime: meta.leadTime,
      blockers: scoped.filter((i) => i.severity === "blocker").length,
      affectedSkus: [...new Set(scoped.map((i) => i.sku))],
      issues: scoped,
    };
  }).filter((section) => section.issues.length > 0);
}

// src/cli.ts
import { readFileSync } from "node:fs";
import { parse } from "csv-parse/sync";
import { validateCatalogue } from "./pipeline.js";
import { buildReport } from "./report/summarise.js";
 
const [, , cataloguePath, transitDaysArg] = process.argv;
 
if (!cataloguePath) {
  console.error("Usage: npm run validate -- <catalogue.csv> [transitDays]");
  process.exit(1);
}
 
const rows = parse(readFileSync(cataloguePath, "utf8"), {
  columns: true,
  skip_empty_lines: true,
  trim: true,
});
 
const result = validateCatalogue({
  rawProducts: rows,
  expiry: {
    transitLeadDays: Number(transitDaysArg ?? 28),
    bufferDays: 14,
  },
});
 
const report = buildReport(result.issues);
 
console.log(`\nValidated ${rows.length} rows`);
console.log(`Parse failures: ${result.parseFailures}`);
console.log(`Total issues: ${result.issues.length}\n`);
 
for (const section of report) {
  console.log(`── ${section.headline} (${section.leadTime})`);
  console.log(
    `   ${section.blockers} blockers across ${section.affectedSkus.length} SKUs\n`,
  );
 
  for (const issue of section.issues.slice(0, 20)) {
    console.log(`   [${issue.code}] ${issue.sku}`);
    console.log(`     ${issue.message}`);
    if (issue.observed) console.log(`     observed: ${issue.observed}`);
    if (issue.expected) console.log(`     expected: ${issue.expected}`);
    console.log();
  }
 
  if (section.issues.length > 20) {
    console.log(`   ... and ${section.issues.length - 20} more\n`);
  }
}
 
// خروج بقيمة غير صفرية ليتمكن هذا من حجب مهمة CI أو خط ما قبل الشحن
const hasBlockers = result.issues.some((i) => i.severity === "blocker");
process.exit(hasBlockers ? 1 : 0);

npm run validate -- ./data/catalogue.csv 35

// tests/certificate.test.ts
import { describe, expect, it } from "vitest";
import { validateCertificateValidity } from "../src/rules/certificate.js";
import type { ProductRecord } from "../src/types.js";
 
const base: ProductRecord = {
  sku: "LED-9W-E27",
  nameEn: "LED Bulb 9W E27",
  brand: "Lumina",
  model: "LX-9W-E27",
  hsCode: "851660100000",
  countryOfOrigin: "CN",
  manufacturer: "Lumina Lighting Co Ltd",
  pcocNumber: "PC-2026-004411",
  pcocExpiry: new Date("2026-09-01"),
};
 
describe("certificate validity", () => {
  const now = new Date("2026-08-09");
 
  it("flags a certificate that expires while goods are in transit", () => {
    const issues = validateCertificateValidity(base, {
      transitLeadDays: 28,
      bufferDays: 14,
      now,
    });
 
    expect(issues).toHaveLength(1);
    expect(issues[0]?.code).toBe("PCOC_EXPIRES_IN_TRANSIT");
    expect(issues[0]?.fixability).toBe("certification");
  });
 
  it("passes a certificate valid beyond arrival plus buffer", () => {
    const issues = validateCertificateValidity(
      { ...base, pcocExpiry: new Date("2027-01-01") },
      { transitLeadDays: 28, bufferDays: 14, now },
    );
 
    expect(issues).toHaveLength(0);
  });
});

// tests/reconcile.test.ts
import { describe, expect, it } from "vitest";
import { reconcileShipment } from "../src/rules/reconcile.js";
import type { ProductRecord } from "../src/types.js";
 
const product: ProductRecord = {
  sku: "LED-9W-E27",
  nameEn: "LED Bulb 9W E27",
  nameAr: "مصباح ليد ٩ واط",
  brand: "Lumina",
  model: "LX-9W-E27",
  hsCode: "851660100000",
  countryOfOrigin: "CN",
  manufacturer: "Lumina Lighting Co Ltd",
};
 
describe("shipment reconciliation", () => {
  const catalogue = new Map([[product.sku, product]]);
 
  it("treats punctuation and case differences as equivalent", () => {
    const issues = reconcileShipment(
      [
        {
          sku: "LED-9W-E27",
          invoiceDescription: "LED Bulb 9W",
          invoiceBrand: "LUMINA",
          invoiceModel: "LX 9W E27",
          hsCode: "8516.60.10.0000",
          quantity: 500,
        },
      ],
      catalogue,
    );
 
    expect(issues).toHaveLength(0);
  });
 
  it("catches a superseded model number", () => {
    const issues = reconcileShipment(
      [
        {
          sku: "LED-9W-E27",
          invoiceDescription: "LED Bulb 9W",
          invoiceBrand: "Lumina",
          invoiceModel: "LX-9W-E27-V2",
          hsCode: "851660100000",
          quantity: 500,
        },
      ],
      catalogue,
    );
 
    expect(issues.map((i) => i.code)).toContain("SHIP_MODEL_MISMATCH");
  });
});

npm test