Waafir
هذه الصفحة ترجمة آلية في انتظار المراجعة البشرية. قد تحتوي على أخطاء.

التحقق من التحميل بالتشغيل التجريبي قبل اعتماد البيانات

توضّح هذه الوصفة كيفية استخدام نقطة نهاية الاستيراد غير المتزامن أداةَ تحقق خالية من الآثار الجانبية قبل اعتماد البيانات. التدفق مطابق لـ وصفة الاستيراد المجمّع — بدء، ورفع، واعتماد، واستطلاع — مع تغيير معامل واحد: dryRun: true. يشغّل العامل مسار التحقق الكامل، ويحتسب الصفوف التي اجتازت التحقق ضمن إجمالي النجاح، ولا يكتب أي صف.

متى تستخدم هذا

التشغيل التجريبي هو الأداة المناسبة عندما تريد معرفة ما إذا كان ملف أنشأته صحيح البنية قبل أن تأتمنه على إرسال يومي. ومن الاستخدامات المعتادة:

  • المرة الأولى التي تربط فيها تصدير شريط القروض لديك وتريد التأكد من أن بنية JSON تطابق ما تتوقعه Waafir.
  • تشغيل استطلاعي ليلي (canary) على أول 100 صف من ملف جديد قبل إرسال البقية.
  • بعد تغيير داخلي في المخطط لديك، للتحقق من أن بنية البيانات المُرسلة لا تزال تُحلَّل بسلاسة.

يشغّل التشغيل التجريبي أدوات التحقق نفسها التي يستخدمها مسار الاستيعاب الحقيقي، لذا فإن اجتياز التشغيل التجريبي ضمان قوي بأن الملف نفسه سيصل بنجاح عند إرساله فعليًا. أما وجه عدم التماثل: فالتشغيل التجريبي لا يختبر قيود التفرّد في قاعدة البيانات (إذ لا تُكتب أي صفوف)، لذا قد يفشل التشغيل الحقيقي رغم ذلك بسبب معرّفات خارجية مكرّرة قبلها التشغيل التجريبي. طابِق بالمعرّف الخارجي بعد التشغيل الحقيقي إذا كنت بحاجة إلى هذا الضمان.

الوصفة

# curl — dry-run validation
set -euo pipefail

PAT="${WAAFIR_PAT}"
BASE_URL="${WAAFIR_BASE_URL:-https://app.waafir.io}"
NDJSON_FILE="loans-canary.ndjson"

# Step 1 — start an import with dryRun=true. The query parameter and
# the body field are both accepted; the query is the curl-friendly form.
START=$(curl -fsS -X POST "${BASE_URL}/api/v1/monitoring/loan/imports?dryRun=true" \
  -H "Authorization: Bearer ${PAT}" \
  -H "Content-Type: application/json" \
  -d "$(cat <<JSON
{
  "kind": "loan",
  "filename": "${NDJSON_FILE}",
  "sizeBytes": $(stat -c%s "${NDJSON_FILE}")
}
JSON
)")

IMPORT_ID=$(echo "$START" | jq -r .importId)
UPLOAD_URL=$(echo "$START" | jq -r .uploadUrl)

# Step 2 — upload the file, applying the signed-in headers the start
# response returned (same shape as a real import — see the
# async-import recipe for the full rationale).
HEADER_ARGS=$(echo "$START" | jq -r '.headers | to_entries[] | "-H \"\(.key): \(.value)\""')
eval curl -fsS -X PUT --data-binary @"\"${NDJSON_FILE}\"" $HEADER_ARGS "\"${UPLOAD_URL}\""

# Step 3 — commit; the worker enqueues but the row processor short-circuits.
curl -fsS -X POST "${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}/commit" \
  -H "Authorization: Bearer ${PAT}"

# Step 4 — poll. Terminal status + dryRun:true means the file is structurally valid.
while :; do
  BODY=$(curl -fsS "${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}" \
    -H "Authorization: Bearer ${PAT}")
  STATUS=$(echo "$BODY" | jq -r .status)
  echo "dry-run ${IMPORT_ID}: ${STATUS}"
  case "${STATUS}" in
    succeeded|partial|failed|cancelled) break ;;
  esac
  sleep 5
done

# At terminal, inspect the row counts. `dryRun: true` should be present.
echo "$BODY" | jq '{status, dryRun, rowCountProcessed, rowCountSucceeded, rowCountFailed}'
// TypeScript — dry-run validation
import { readFileSync, statSync } from "node:fs";

const PAT = process.env.WAAFIR_PAT!;
const BASE_URL = process.env.WAAFIR_BASE_URL ?? "https://app.waafir.io";
const NDJSON_FILE = "loans-canary.ndjson";

const auth = { Authorization: `Bearer ${PAT}` };

// Step 1 — start with dryRun=true via the body. (?dryRun=true is also accepted.)
const startRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports`, {
    method: "POST",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({
        kind: "loan",
        filename: NDJSON_FILE,
        sizeBytes: statSync(NDJSON_FILE).size,
        dryRun: true,
    }),
});
if (!startRes.ok) throw new Error(`start failed: ${startRes.status} ${await startRes.text()}`);
const { importId, uploadUrl, headers: uploadHeaders } = (await startRes.json()) as {
    importId: string;
    uploadUrl: string;
    headers: Record<string, string>;
};

// Step 2 — upload, applying the signed-in headers.
const putRes = await fetch(uploadUrl, {
    method: "PUT",
    headers: uploadHeaders,
    body: readFileSync(NDJSON_FILE),
});
if (!putRes.ok) throw new Error(`upload failed: ${putRes.status}`);

// Step 3 — commit.
const commitRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports/${importId}/commit`, {
    method: "POST",
    headers: auth,
});
if (!commitRes.ok) throw new Error(`commit failed: ${commitRes.status} ${await commitRes.text()}`);

// Step 4 — poll until terminal.
const TERMINAL = new Set(["succeeded", "partial", "failed", "cancelled"]);
let final: { status: string; dryRun: boolean; rowCountProcessed: number; rowCountSucceeded: number; rowCountFailed: number };
while (true) {
    const statusRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports/${importId}`, { headers: auth });
    final = (await statusRes.json()) as typeof final;
    console.log(`dry-run ${importId}: ${final.status}`);
    if (TERMINAL.has(final.status)) break;
    await new Promise((r) => setTimeout(r, 5_000));
}

console.log({
    status: final.status,
    dryRun: final.dryRun,
    rowCountProcessed: final.rowCountProcessed,
    rowCountSucceeded: final.rowCountSucceeded,
    rowCountFailed: final.rowCountFailed,
});
# python — dry-run validation
import os
import time
import requests
from pathlib import Path

PAT = os.environ["WAAFIR_PAT"]
BASE_URL = os.environ.get("WAAFIR_BASE_URL", "https://app.waafir.io")
NDJSON_FILE = Path("loans-canary.ndjson")

auth = {"Authorization": f"Bearer {PAT}"}

# Step 1 — start with dryRun=True. The body field is the structured form;
# `?dryRun=true` on the query string is equivalent for curl ergonomics.
start = requests.post(
    f"{BASE_URL}/api/v1/monitoring/loan/imports",
    headers={**auth, "Content-Type": "application/json"},
    json={
        "kind": "loan",
        "filename": NDJSON_FILE.name,
        "sizeBytes": NDJSON_FILE.stat().st_size,
        "dryRun": True,
    },
    timeout=30,
)
start.raise_for_status()
payload = start.json()
import_id = payload["importId"]
upload_url = payload["uploadUrl"]
upload_headers = payload["headers"]

# Step 2 — upload, applying the signed-in headers.
with NDJSON_FILE.open("rb") as fh:
    requests.put(upload_url, data=fh, headers=upload_headers, timeout=300).raise_for_status()

# Step 3 — commit.
requests.post(
    f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}/commit",
    headers=auth,
    timeout=30,
).raise_for_status()

# Step 4 — poll until terminal.
terminal = {"succeeded", "partial", "failed", "cancelled"}
while True:
    body = requests.get(
        f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}",
        headers=auth,
        timeout=30,
    ).json()
    print(f"dry-run {import_id}: {body['status']}")
    if body["status"] in terminal:
        break
    time.sleep(5)

print({
    "status": body["status"],
    "dryRun": body["dryRun"],
    "rowCountProcessed": body["rowCountProcessed"],
    "rowCountSucceeded": body["rowCountSucceeded"],
    "rowCountFailed": body["rowCountFailed"],
})

ما يجب التحقق منه

يحمل كائن الحالة النهائية dryRun: true لتتمكن من التأكد من أن العامل عمل في وضع التشغيل التجريبي. ولأعداد الصفوف معنى محدد في التشغيل التجريبي:

  • rowCountSucceeded هو عدد الصفوف التي اجتازت التحقق — وهو بالضبط العدد الذي كان سيصل كصفوف حيّة في تشغيل حقيقي.
  • rowCountFailed هو عدد الصفوف التي أخفقت في التحقق. تصفّحها عبر وصفة فحص الإخفاق الجزئي — إذ تعمل نقطة نهاية الأخطاء المقسّمة إلى صفحات بالطريقة نفسها في التشغيل التجريبي.
  • rowCountProcessed هو المجموع: كل صف نظر فيه العامل.

إذا لم يكن في ملفك أي صف مُخفق في التشغيل التجريبي، فإن الملف نفسه عند إرساله فعليًا (دون dryRun: true) سيصل بسلاسة، مع مراعاة عدم التماثل المتعلق بتفرّد قاعدة البيانات المذكور أعلاه.